Agent-friendly design system playbook

agent-design-system-gist.md

Agent-Friendly Design System Playbook

This is a lightweight pattern for helping agents build faster while keeping product design consistent. It works best for small apps, prototypes, landing pages, and isolated product surfaces where the design system should live close to the implementation.

Core Idea

Give agents a small, explicit design contract before they touch UI code.

The goal is not to create a full enterprise design system. The goal is to remove ambiguity around colors, spacing, radii, motion, layout, and repeatable UI patterns so agents can iterate quickly without inventing a new visual language every turn.

What To Create

Add a short design-system file to the repo, usually something like:

• DESIGN_SYSTEM.md
• src/DESIGN_SYSTEM.md
• docs/design-system.md
• app/DESIGN_SYSTEM.md

Keep it close to the UI it governs.

At the top, define scope clearly:

Scope: applies only to [path/to/surface]. Other app areas may use separate design rules.

This prevents agents from overgeneralizing and refactoring unrelated parts of the codebase.

What The File Should Contain

1. Philosophy

Write 4-6 rules that describe how the UI should feel and how agents should make tradeoffs.

Example:

- fix primitives before patching individual components
- use semantic tokens instead of raw colors
- keep one dominant action per screen
- prefer reusable patterns once they appear multiple times
- preserve spatial continuity with consistent transitions

2. Semantic Tokens

Document tokens by purpose, not by visual value.

Good:

--text-primary
--text-secondary
--surface-page
--surface-card
--border-subtle
--shadow-card
--radius-control
--motion-fast

Avoid:

--gray-500
--blue-700
--spacing-large-ish
--random-card-radius

Agents are better at preserving intent when tokens describe meaning.

3. Spacing And Radius Scales

List the allowed spacing and radius tokens. Keep the set small.

Example:

Spacing:
- --space-4
- --space-8
- --space-12
- --space-16
- --space-24
- --space-32

Radius:
- --radius-control
- --radius-card
- --radius-pill
- --radius-circle

Add a rule:

Do not introduce one-off spacing or radius values unless the token scale is updated first.

4. Pattern Inventory

List the reusable UI patterns and where they are used.

Example:

### Primary Action

Used by:
- submit button
- next-step button

Rules:
- one high-emphasis CTA per view
- hover, active, disabled, loading, and focus-visible states are required
- use the standard action surface, radius, shadow, and motion tokens

Useful patterns to document:

• primary action
• secondary action
• form control
• card
• sheet or modal
• segmented control
• tooltip
• status message
• metric/value display
• empty state
• navigation item

5. Interaction Rules

Agents often miss interaction consistency unless it is written down.

Include rules for:

• :hover
• :active
• :focus-visible
• disabled states
• loading states
• reduced motion
• mobile touch behavior

Example:

Any interactive control with hover or active styles must also define :focus-visible.

6. Anti-Patterns

This is one of the highest-value sections for agents.

Example:

Do not:
- add raw neutral colors in component CSS
- create new spacing values without updating the scale
- duplicate visual recipes for cards, inputs, or buttons
- add hover styles without focus-visible styles
- use static inline styles for reusable UI behavior
- import design tokens from a different product surface

Agent Workflow

Tell agents to follow this order:

1. Read the design-system file before changing UI.
2. Identify the existing primitive or pattern that matches the change.
3. Reuse existing tokens first.
4. If a new primitive is needed, document it before or alongside the code change.
5. If a visual rule appears three or more times, promote it to the design-system file.
6. Run the UI/design lint or visual check before finishing.

Enforcement

The design-system file is useful. Enforcement makes it durable.

Add repo instructions for agents:

For UI work in [surface], read [DESIGN_SYSTEM.md] first.
Scope changes to [surface] unless explicitly told otherwise.
Use semantic tokens instead of raw colors, ad hoc spacing, or ad hoc radii.
Any interactive control with hover or active styles must also have :focus-visible.
Avoid static inline styles in markup.

If possible, add a small lint script that catches the most common drift:

• raw hex/rgb neutral colors
• static style= attributes
• missing :focus-visible
• unsupported spacing or radius values
• duplicated component recipes

This does not need to be perfect. Even a narrow lint catches enough drift to keep agents honest.

Why This Works Well For Agents

Agents are good at applying local rules when those rules are explicit, scoped, and close to the files being edited.

They are less reliable when asked to infer a design system from visual taste, scattered CSS, or broad brand language.

The practical move is to turn taste into a short contract:

• semantic tokens
• small scales
• named patterns
• interaction requirements
• anti-patterns
• local enforcement

That gives agents enough structure to move quickly without turning every UI change into a new design direction.

Minimal Template

# [Surface] Design System

Scope: applies only to [path/to/surface].

## Philosophy

- [rule]
- [rule]
- [rule]

## Tokens

### Text
- --text-primary:
- --text-secondary:
- --text-muted:

### Surfaces
- --surface-page:
- --surface-card:
- --surface-control:

### Borders
- --border-subtle:
- --border-focus:

### Motion
- --motion-fast:
- --motion-base:
- --ease-standard:

## Spacing

- --space-4
- --space-8
- --space-12
- --space-16
- --space-24

## Radius

- --radius-control
- --radius-card
- --radius-pill

## Patterns

### [Pattern Name]

Used by:
- [component]

Rules:
- [rule]

## Interaction Rules

- Hover/active controls must also define :focus-visible.
- Disabled and loading states must be visually distinct.
- Reduced-motion behavior must be considered for major transitions.

## Anti-Patterns

- raw colors in component CSS
- one-off spacing/radius values
- duplicate button/input/card recipes
- static inline styles for reusable UI
- cross-surface token imports unless explicitly allowed