designseeddocs

Editor

Component patterns

2 min read

Tokens encode the building blocks. Patterns encode the rules for how those blocks combine into UI. The Components panel adds a Patterns section to your DESIGN.md so the agent reads "here's how this brand assembles a button" instead of guessing from primitives.

What goes in a pattern

A typical pattern reads like this:

## Patterns
 
### Buttons
- Primary: bg=`--primary`, fg=`readableText(--primary)`, radius=`--radius-md`,
  padding=`--space-2 --space-4`, font-weight=600, focus-visible adds 2px ring
  in `--primary`.
- Secondary: bg=transparent, border=`1px solid --line`, fg=`--ink`, otherwise
  identical to primary.
- Destructive: bg=`--danger`, fg=white, otherwise identical to primary.
- Hover: 4% darken on bg via color-mix(); never animate scale.
 
### Cards
- bg=`--surface`, border=`1px solid --line`, radius=`--radius-lg`,
  padding=`--space-6`, shadow=`--shadow-1` resting / `--shadow-2` hover.
- Interactive cards animate `transform: translateY(-1px)` on hover, 150ms ease-out.
 
### Inputs
- height 40px, radius=`--radius-md`, border=`1px solid --line`,
  focus-visible adds 2px ring in `--primary` and removes the border.
- Error state: border switches to `--danger`, label color matches.

That's enough for an agent to generate a coherent button, card, or input without having to invent details.

Why patterns matter more than tokens

A token like --primary: #635BFF tells the agent the value. A pattern tells it the rules of usage: which token applies where, how interactive states differ, what the focus ring looks like, what motion is allowed.

Without patterns, agents fall back on their training prior — which is "shadcn-flavored Tailwind" most of the time. With patterns, they ground every component in your brand's actual rules.

What to include

At minimum cover buttons, cards, and form fields — those drive most UI. Add additional patterns when you have specific opinions:

  • Navigation (sticky, transparent, full-width, etc.)
  • Tabs (underlined, pill, segmented)
  • Modals (overlay color, padding, close affordance)
  • Empty states (illustration vs. icon, copy posture)