Best Practices for Capturing and Applying Design Systems #

Summary #

Capturing a design system involves three phases: extraction (auditing existing visuals to identify patterns), documentation (recording decisions in machine-readable and human-readable formats), and application (using that documentation to drive consistent output from both human developers and AI tools).

The W3C Design Tokens Community Group released their first stable specification (2025.10) in October 2025, providing a standardized JSON format that major tools like Figma, Tokens Studio, and Style Dictionary now support. For AI/LLM workflows, combining design tokens with structured markdown documentation creates "guardrails" that direct AI agents toward on-brand, consistent results.

Your existing Tailwind theme in global.css is a good foundation—the next step is formalizing it into a portable, tool-agnostic format that AI editors can consume.

Project Context #

This project uses:

• Astro for static site generation
• Tailwind CSS v4 with a custom @theme block defining colors (paper, void, rand-blue, etc.) and fonts (Inter, Courier Prime)
• React components
• Custom CSS effects (halftone, CRT scanlines, Bell Labs photo filters)

The design language has a distinct "retro-tech" aesthetic that needs to be captured systematically.

Detailed Findings #

Phase 1: Extraction — The Visual Audit Process #

What it is: A systematic inventory of every visual element in your product to identify patterns, inconsistencies, and opportunities for standardization.

Why consider it: You can't document what you haven't identified. Companies like UXPin discovered 116 color variables with 62 shades of gray before conducting an audit—massive redundancy that slowed development.

How to implement:

1. Define scope: Start with core screens or the "happy path" user journey
2. Screenshot everything: Capture unique instances of typography, colors, buttons, icons, spacing, navigation
3. Use automated tools: CSS Stats can extract colors, spacing, and typography from existing stylesheets
4. Organize by category:
   • Foundations: Colors, typography, spacing, icons, motion
   • Components: Buttons, forms, cards, navigation, tables
   • Patterns: Functional (reusable UI), perceptual (brand aesthetics), platform-specific

1# For web projects, CSS Stats can help
2# Visit https://cssstats.com and paste your URL or CSS
3
4# Or inspect programmatically with browser tools:
5# - DevTools > Elements > Computed styles
6# - Look for repeated values in padding, margin, font-size

What to capture for each element:

Trade-offs:

• Pro: Reveals hidden inconsistencies and bloat
• Con: Time-intensive for large products (budget 1-2 weeks for comprehensive audit)

Phase 2: Documentation — The W3C Design Tokens Format #

What it is: A standardized JSON format for expressing design decisions as portable, tool-agnostic data.

Why consider it: The October 2025 stable release means major tools (Figma, Sketch, Tokens Studio, Style Dictionary, Penpot) now support or are implementing this standard. One file works everywhere.

How to implement:

Design token files use .tokens or .tokens.json extensions with this structure:

 1{
 2  "$description": "Design tokens for the AI Engineering Summit site",
 3
 4  "color": {
 5    "$type": "color",
 6    "paper": {
 7      "$value": "#f3f2ea",
 8      "$description": "Primary background - warm off-white"
 9    },
10    "void": {
11      "$value": "#1a1a1a",
12      "$description": "Primary text and dark elements"
13    },
14    "rand-blue": {
15      "$value": "#0055aa",
16      "$description": "Accent color for links and highlights"
17    },
18    "alert-red": {
19      "$value": "#d93025",
20      "$description": "Error states and warnings"
21    },
22    "surface": {
23      "$value": "#e6e4dc",
24      "$description": "Secondary background surfaces"
25    },
26    "terminal-green": {
27      "$value": "#00ff41",
28      "$description": "CRT terminal effect accent"
29    }
30  },
31
32  "fontFamily": {
33    "$type": "fontFamily",
34    "sans": {
35      "$value": ["Inter", "Helvetica", "Arial", "sans-serif"],
36      "$description": "Primary text font"
37    },
38    "mono": {
39      "$value": ["Courier Prime", "monospace"],
40      "$description": "Code and terminal styling"
41    }
42  },
43
44  "fontSize": {
45    "$type": "dimension",
46    "xs": { "$value": { "value": 12, "unit": "px" } },
47    "sm": { "$value": { "value": 14, "unit": "px" } },
48    "base": { "$value": { "value": 16, "unit": "px" } },
49    "lg": { "$value": { "value": 18, "unit": "px" } },
50    "xl": { "$value": { "value": 20, "unit": "px" } },
51    "2xl": { "$value": { "value": 24, "unit": "px" } },
52    "3xl": { "$value": { "value": 30, "unit": "px" } },
53    "4xl": { "$value": { "value": 36, "unit": "px" } }
54  },
55
56  "spacing": {
57    "$type": "dimension",
58    "1": { "$value": { "value": 4, "unit": "px" } },
59    "2": { "$value": { "value": 8, "unit": "px" } },
60    "3": { "$value": { "value": 12, "unit": "px" } },
61    "4": { "$value": { "value": 16, "unit": "px" } },
62    "6": { "$value": { "value": 24, "unit": "px" } },
63    "8": { "$value": { "value": 32, "unit": "px" } },
64    "12": { "$value": { "value": 48, "unit": "px" } },
65    "16": { "$value": { "value": 64, "unit": "px" } }
66  }
67}

Key specification rules:

• All spec properties use $ prefix ($value, $type, $description)
• Token names cannot contain $, {, }, or .
• Types inherit downward through groups
• References use {group.token} syntax: "$value": "{color.rand-blue}"

Trade-offs:

• Pro: Tool-agnostic, emerging industry standard, supported by major design tools
• Con: Still evolving; some tools have partial support

Phase 3: Application — Structuring for AI/LLM Consumption #

What it is: Formatting your design system documentation so AI code editors (Cursor, Windsurf, Claude Code) can use it as context for generating consistent code.

Why consider it: Without design context, LLMs produce generic output. With proper context, AI "provides code that better aligns to your design system in both design and code quality."

How to implement:

Option A: MCP Server Connection (Recommended for Figma users) #

Figma's Dev Mode MCP server connects directly to AI editors, providing real-time access to:

• Component structures and naming
• Design variables and tokens
• Style definitions

1# In Cursor/Windsurf/Claude Code settings, add MCP server:
2# Figma Dev Mode MCP provides live design context

Option B: Structured Markdown Documentation (Universal) #

Create a DESIGN_SYSTEM.md file that AI tools can reference:

 1# Design System Reference
 2
 3## Brand Voice
 4Retro-tech aesthetic inspired by Bell Labs and early computing.
 5Professional but approachable. Technical precision with warmth.
 6
 7## Color Palette
 8
 9| Token | Hex | Usage |
10|-------|-----|-------|
11| `paper` | #f3f2ea | Page backgrounds |
12| `void` | #1a1a1a | Primary text, dark UI |
13| `rand-blue` | #0055aa | Links, accents, CTAs |
14| `alert-red` | #d93025 | Errors, warnings |
15| `surface` | #e6e4dc | Cards, secondary backgrounds |
16| `terminal-green` | #00ff41 | CRT/terminal effects only |
17
18## Typography
19
20- **Sans (Inter)**: All body text, headings, UI elements
21- **Mono (Courier Prime)**: Code blocks, terminal styling, data
22
23### Scale
24- H1: 36px / font-bold
25- H2: 30px / font-bold
26- H3: 24px / font-semibold
27- Body: 16px / font-normal
28- Small: 14px / font-normal
29
30## Spacing System
31Base unit: 4px. Use multiples: 4, 8, 12, 16, 24, 32, 48, 64px
32
33## Component Patterns
34
35### Buttons
36- Primary: bg-rand-blue text-paper rounded px-4 py-2
37- Secondary: border border-void text-void rounded px-4 py-2
38
39### Cards
40- bg-surface rounded-lg p-6 shadow-sm
41
42## Effects (Use Sparingly)
43- `.halftone`: Subtle dot pattern overlay for images
44- `.bell-labs-photo`: Grayscale + contrast filter for speaker photos
45- `.scanlines`: CRT monitor effect for terminal sections
46
47## DO NOT
48- Use terminal-green outside of CRT/terminal contexts
49- Mix Inter and Courier Prime in the same text block
50- Use pure white (#ffffff) backgrounds—always use paper

Option C: Embedding in AI Prompts #

For one-off tasks, embed guidelines directly:

1You are generating code for a site with these brand guidelines:
2- Colors: paper (#f3f2ea) for backgrounds, void (#1a1a1a) for text, rand-blue (#0055aa) for accents
3- Fonts: Inter for UI, Courier Prime for code
4- Style: Retro-tech Bell Labs aesthetic
5- Use Tailwind CSS classes
6
7Generate a card component for displaying speaker information.

Trade-offs:

• MCP: Pro (live sync), Con (Figma-specific, requires setup)
• Markdown: Pro (universal, version-controlled), Con (manual updates)
• Inline prompts: Pro (quick), Con (not scalable, repetitive)

Tools for Extraction and Management #

Recommendation #

For this project specifically:

1. Formalize your existing Tailwind theme into a .tokens.json file using W3C format
2. Create a DESIGN_SYSTEM.md in your project root with the structured documentation above
3. Add design context to your Claude Code skills (you already have focus-ai-brand and theme-factory skills—extend these with specific token references)

This gives you:

• A portable source of truth (JSON tokens)
• Human-readable documentation (Markdown)
• AI-consumable context for consistent code generation

When NOT to Use This #

• Rapid prototyping phase: Don't formalize until visual direction is stable. Premature documentation creates maintenance burden.
• Solo projects with no handoff: If you're the only one touching the code and there's no AI assistance, the overhead may not pay off.
• Highly dynamic brands: Some brands intentionally break consistency for creative effect. A rigid system can constrain this.
• Legacy systems without refactor budget: Documenting a system you can't change creates frustration. Audit first, then decide if formalization is worth it.

Sources #

• Design Tokens Community Group - W3C
• Design Tokens Specification 2025.10
• Design System Checklist - UXPin
• How to Create an Interface Inventory - Mainmatter
• Design Systems with AI - James Carleton
• Visual Design Audit Guide - Design Shack
• Design System Audit - Ramotion
• Best Design System Examples 2025 - UXPin
• Enterprise Design Systems Best Practices - Softkraft
• Markdown Prompting in AI - Applied AI Tools
• Prompt Design Strategies - Google AI