design-system

---
name: design-system
description: Use when a user wants a project's brand — colors, fonts, style — captured or reset before producing branded HTML, a report, or slides.
category: Formatting
version: 1.0.0
tools: []
---

# Design System — Brand Onboarding

Capture a user's brand identity once, in conversation, then apply the same tokens to every document, report, or deck produced afterward. Run this before any branded output; skip it only if the user already gave brand colors and fonts earlier in this conversation.

## When to run onboarding
- First time in a conversation the user asks for a branded document/HTML/deck.
- User asks to "set up the brand," "reset the design system," or "re-onboard."
- User wants a one-off per-project override instead of their standing brand.

## The 10 onboarding questions
Ask conversationally rather than as ten sequential prompts. Sensible defaults exist for everything so a user in a hurry can say "use defaults."

| # | Field | Choices / format | Default |
|---|---|---|---|
| 1 | Output location/description | free text (a folder name, a doc title) | "this project" |
| 2 | Primary brand color | HEX `#RRGGBB` | `#0A1628` |
| 3 | Accent color | HEX, or "derive it" | derived from primary |
| 4 | Heading font | any Google Font name | `Inter` |
| 5 | Body font | any Google Font name | `Inter` |
| 6 | Design style | editorial / technical / minimal / playful | `technical` |
| 7 | Code/syntax theme | light / dark / auto | `auto` |
| 8 | Table-of-contents behavior | sticky-sidebar / collapsible-top / inline / none | `sticky-sidebar` |
| 9 | Company name | free text, may be blank | blank |
| 10 | Logo | a URL or description, may be blank | blank |

Once captured, restate the brand as a short confirmed summary and keep using it for the rest of the session — there's no config file to persist it in, so re-confirm at the start of a new conversation.

## Hard rule: WCAG AA contrast
Body text on background, and links on background, must both reach a 4.5:1 contrast ratio (WCAG 2.2 §1.4.3). Reason about this via relative luminance: a lighter background with darker text (or vice versa) increases the ratio; two similarly-light or similarly-dark colors fail. If the user's chosen primary would fail as body text or as a link color, say so and offer to: pick a darker/lighter variant of the same hue, use a near-black/near-white neutral for body text instead, or keep the primary as an accent (buttons, headers) rather than as running text or background. Never hand back a "designed" palette that fails this floor.

## Design-style meanings
- **Technical** — specs, engineering reports; dense, high-contrast, minimal ornamentation.
- **Editorial** — long-read narratives; generous whitespace, larger type, pull quotes.
- **Minimal** — sparse reference docs; the least styling that still reads as designed.
- **Playful** — marketing/landing content; more color, rounder shapes, more personality.

Recommend technical for specs/reports, editorial for narratives, minimal for short references, playful for marketing copy — style should serve the rhetorical purpose (Ellen Lupton, *Thinking with Type*).

## TOC guidance
Recommend sticky-sidebar for documents over roughly 800 words, inline for short reads (Nielsen-Norman, "Table of Contents Best Practices," 2023).

## Deriving a full palette from one brand color
Once you have a primary (and optionally an accent), derive the rest of the palette by reasoning about lightness/hue shifts rather than picking arbitrary colors:

| Role | Purpose | How to derive |
|---|---|---|
| Background | Page/document background | Primary if already dark; otherwise a near-neutral |
| Surface | Card / callout / blockquote background | Background shifted ±4–6% in luminance |
| Border | Hairlines, table borders | Background shifted ±8–12% in luminance |
| Text | Body copy | Off-white on a dark background, near-black on a light one |
| Muted text | Captions, metadata | Text color at roughly 68% opacity |
| Accent | CTAs, callout headers, link emphasis | Primary if vibrant enough; otherwise lighter and hue-shifted |
| Accent-soft | Accent backgrounds, hover states | Accent at roughly 14% opacity |
| Code background | Inline code, fenced blocks | Background shifted ±4–5% in luminance |
| Link | Hyperlinks | Walk the accent's lightness until it clears 4.5:1 against the background |
| Link-hover | Hover state | Link shifted ±6–8% in luminance |
| Success | Approved / passed states | A green hue-matched to the palette's luminance |
| Warning | Caution / TODO states | An amber hue-matched to the palette's luminance |

Present this back as a short labeled list of hex values (or descriptive color names) the user can hand to a developer or paste into CSS variables — there's no file to write it into.

## Precedence when brand info conflicts
A per-project brand the user states now overrides one set earlier in the conversation; otherwise fall back to whatever standing brand they already described. There's no config persisted across separate conversations — always reconfirm at the start of a new one rather than assuming it carried over.

## Forcing questions (ask one at a time, each with a recommendation)
1. **What's your brand primary color?** Recommend a HEX already used in their product or docs, not a generic stock blue (Aarron Walter, *Designing for Emotion*).
2. **Derive the accent, or set it explicitly?** Recommend deriving on a first pass; set explicitly only if a brand kit already specifies one (Adobe Spectrum, *Color Foundations*).
3. **Which design style?** Match style to the content's purpose (Lupton).
4. **Sticky sidebar or inline TOC?** Use the ~800-word threshold above.

## Non-goals
Not a full design-token system — a dozen roles, not a hundred. Not a custom-font hosting solution — Google Fonts by name only. Not an accessibility audit suite — this enforces color contrast only; a full audit needs dedicated tooling. AAA contrast (7:1) is out of scope; the floor is AA (4.5:1 body text, 3:1 large text/UI).

## Anti-patterns
- Skipping the brand conversation and defaulting silently — the output looks generic and the user won't know why.
- Using a vibrant brand primary directly as a background behind body text — check contrast first, or use it as an accent instead.
- Inventing new palette roles beyond the twelve above without a deliberate name, purpose, and derivation rule.