🎓
Session 4•
4 min read

Your Design System Files

Session 4: Your Design System Files

Duration: 2 hours
Prerequisites: Sessions 1-3 completed, CLAUDE.md written
You'll need: Your Figma file with design tokens/variables

Part 1: From Figma to Markdown (30 min)

The Gap

Your design tokens exist. They're in Figma—as variables, styles, or documented in your component library. You've been using them for years.

Claude can read your Figma files through MCP. But there's a gap: Claude sees the usage of tokens in your designs, but doesn't have a clean reference of all tokens and when to use each.

The Bridge

A simple markdown file—design-tokens.md—bridges this gap. It's not a new system. It's your existing system, written in a format Claude can reference.

What you're NOT doing:

  • Creating a new design system
  • Defining new tokens
  • Learning a token specification format

What you ARE doing:

  • Exporting what's already in Figma
  • Adding usage context ("use this for X, not Y")
  • Making your implicit knowledge explicit

Why Markdown?

  • Claude reads markdown natively
  • Easy to write and maintain
  • Lives in your repo (versioned with code)
  • Human-readable too

Part 2: Creating design-tokens.md (45 min)

Start With Your Figma Variables

Open your Figma file. Go to your variables panel (or wherever you've defined tokens).

You're going to translate these into markdown. Not every single value—just the ones Claude needs to make decisions.

Colors

Export your color tokens with semantic names and actual values:

# Design Tokens

## Colors

### Backgrounds
| Token | Value | Usage |
|-------|-------|-------|
| --bg-primary | #FAF9F7 | Main page background |
| --bg-secondary | #F5F3F0 | Subtle sections |
| --bg-card | #FFFFFF | Card surfaces |
| --bg-input | #FFFFFF | Form inputs |
| --bg-hover | #F0EEEB | Hover states |

### Text
| Token | Value | Usage |
|-------|-------|-------|
| --text-primary | #1A1A1A | Body text, headings |
| --text-secondary | #6B6B6B | Supporting text |
| --text-muted | #9B9B9B | Placeholders, disabled |
| --text-inverse | #FFFFFF | Text on dark backgrounds |

### Accents
| Token | Value | Usage |
|-------|-------|-------|
| --color-primary | #6366F1 | Primary actions, links |
| --color-success | #22C55E | Success states |
| --color-warning | #F59E0B | Warning states |
| --color-error | #EF4444 | Error states |

Key insight: The "Usage" column is where your expertise goes. Claude knows #6366F1 is purple. Only you know it's for "primary actions, links."

Typography

## Typography

### Font Family
- Primary: Inter, system-ui, sans-serif
- Mono: JetBrains Mono, monospace (code only)

### Font Sizes
| Token | Value | Usage |
|-------|-------|-------|
| --text-xs | 12px | Labels, captions |
| --text-sm | 14px | Secondary text, inputs |
| --text-base | 16px | Body text |
| --text-lg | 18px | Lead paragraphs |
| --text-xl | 20px | Section headings |
| --text-2xl | 24px | Page headings |
| --text-3xl | 32px | Hero headings |

### Font Weights
| Token | Value | Usage |
|-------|-------|-------|
| --font-normal | 400 | Body text |
| --font-medium | 500 | Emphasis, labels |
| --font-semibold | 600 | Headings, buttons |

Spacing

## Spacing

Based on 4px grid.

| Token | Value | Usage |
|-------|-------|-------|
| --spacing-1 | 4px | Tight gaps (icon to text) |
| --spacing-2 | 8px | Related elements |
| --spacing-3 | 12px | Form field gaps |
| --spacing-4 | 16px | Standard padding |
| --spacing-5 | 20px | Card padding |
| --spacing-6 | 24px | Section gaps |
| --spacing-8 | 32px | Major sections |
| --spacing-12 | 48px | Page sections |

Other Tokens

## Border Radius

| Token | Value | Usage |
|-------|-------|-------|
| --radius-sm | 4px | Small elements, tags |
| --radius-md | 8px | Buttons, inputs |
| --radius-lg | 12px | Cards, modals |
| --radius-full | 9999px | Pills, avatars |

## Shadows

| Token | Value | Usage |
|-------|-------|-------|
| --shadow-sm | 0 1px 2px rgba(0,0,0,0.05) | Subtle depth |
| --shadow-card | 0 1px 3px rgba(0,0,0,0.05), 0 4px 12px rgba(0,0,0,0.05) | Cards (compound) |
| --shadow-dropdown | 0 4px 16px rgba(0,0,0,0.1), 0 1px 3px rgba(0,0,0,0.05) | Dropdowns, popovers |
| --shadow-modal | 0 8px 32px rgba(0,0,0,0.15), 0 2px 8px rgba(0,0,0,0.05) | Modals |

Usage Rules

Add explicit rules at the end:

## Rules

### DO
- Always use tokens from this file
- Use semantic names (--color-error, not --red)
- Use compound shadows for elevated surfaces

### DON'T
- Never hardcode color values
- Never use single-layer shadows
- Never invent spacing values outside the scale

Part 3: Creating component-patterns.md (30 min)

Patterns vs. Components

You have many components. You don't need to document all of them.

Document patterns—the reusable structures that appear across components. If Claude understands the pattern, it can apply it correctly to new components.

Example: Card Pattern

# Component Patterns

## Card

The standard container for grouped content.

### Structure

div.card div.card-header (optional) h3.card-title div.card-actions (optional) div.card-body div.card-footer (optional)


### Styles
- Background: --bg-card
- Border radius: --radius-lg
- Shadow: --shadow-card
- Padding: --spacing-5
- Gap between header/body/footer: --spacing-4

### Variants
- Default: White background, compound shadow
- Flat: No shadow (for nested cards)
- Interactive: Add hover state (--bg-hover, --shadow-dropdown)

Example: Button Pattern

## Button

### Structure

button.btn.btn-{variant} span.btn-icon (optional, left) span.btn-label span.btn-icon (optional, right)


### Variants
| Variant | Background | Text | Border |
|---------|-----------|------|--------|
| primary | --color-primary | white | none |
| secondary | transparent | --text-primary | 1px --border-default |
| ghost | transparent | --text-secondary | none |
| destructive | --color-error | white | none |

### States
- Hover: Darken background 10%
- Focus: 2px ring, --color-primary, 2px offset
- Disabled: 50% opacity, no pointer events

### Sizes
| Size | Height | Padding | Font |
|------|--------|---------|------|
| sm | 32px | --spacing-3 | --text-sm |
| md | 40px | --spacing-4 | --text-base |
| lg | 48px | --spacing-5 | --text-lg |

Example: Form Pattern

## Form Field

### Structure

div.form-field label.form-label input.form-input / select.form-select / textarea.form-textarea span.form-hint (optional) span.form-error (optional, shown on error)


### Styles
- Label: --text-sm, --font-medium, --text-secondary
- Input: --bg-input, 1px border --border-default, --radius-md
- Focus: border --color-primary, ring
- Error: border --color-error, --text-error for message
- Hint: --text-xs, --text-muted

### Spacing
- Label to input: --spacing-2
- Input to hint/error: --spacing-1
- Between fields: --spacing-4

What to Document

Prioritize patterns that:

  • Appear frequently (cards, buttons, forms)
  • Have specific rules (modals, dropdowns)
  • Are often done wrong (shadows, spacing)

Skip patterns that:

  • Are obvious (paragraphs, simple lists)
  • Only appear once
  • Have no special rules

Figma Style Mapping

When Claude reads from Figma via MCP, it sees Figma's style names. Add a mapping table so Claude knows which CSS variable corresponds to which Figma style:

---

## Figma Style Mapping

When reading from Figma, use this mapping:

| Figma Style | CSS Variable |
|-------------|--------------|
| bg-primary | `var(--bg-primary)` |
| bg-secondary | `var(--bg-secondary)` |
| bg-tertiary | `var(--bg-tertiary)` |
| text-primary | `var(--text-primary)` |
| text-secondary | `var(--text-secondary)` |
| text-tertiary | `var(--text-tertiary)` |
| accent-purple | `var(--accent-purple)` |
| accent-green | `var(--accent-green)` |
| accent-red | `var(--accent-red)` |
| border-primary | `var(--border-primary)` |
| border-secondary | `var(--border-secondary)` |

This ensures that when Claude sees bg-primary in your Figma design, it uses var(--bg-primary) in the code—not a hardcoded value.

Part 4: Verify Token Alignment (15 min)

The Test

Generate the same component using both paths. They should produce identical styling.

Exercise: Two-Path Test

Path 1: Figma → Claude

  1. Select a component in your Figma file (e.g., a card)
  2. Ask Claude:
Implement this card from Figma.

Path 2: Prompt → Claude

  1. In a new conversation, ask:
Create a card component with a title, description, and action button.

Compare:

  • Same colors?
  • Same spacing?
  • Same shadows?
  • Same border radius?

If They Don't Match

Problem: Path 1 uses different values than Path 2.

Likely cause: Your Figma file and design-tokens.md are out of sync.

Fix:

  • Check which values are in Figma
  • Update design-tokens.md to match
  • Or update Figma to match the documented tokens

Goal: Both paths produce identical results because they reference the same documented system.

Session 4 Checklist

  • [ ] Exported colors to design-tokens.md
  • [ ] Exported typography to design-tokens.md
  • [ ] Exported spacing scale to design-tokens.md
  • [ ] Exported shadows, radii, borders
  • [ ] Added usage context for each token
  • [ ] Added Figma style mapping table
  • [ ] Created component-patterns.md with key patterns
  • [ ] Documented card, button, and form patterns
  • [ ] Verified both paths produce consistent output

What's Next

Session 5: Killing the AI Slop

Your tokens and patterns are documented. But Claude might still generate generic output that technically follows the rules but lacks your system's distinctive character. Session 5 teaches you how to write anti-slop directives that capture what makes your system yours.

Session 4 of 10 • The Shipping AI Designer Course
Next: Session 5 — Killing the AI Slop

PreviousBriefing Your AI Colleague
NextKilling the AI Slop

Discussion

Loading comments...