Design System Documentation — AI Prompt Templates (Starter Kit)
Updated
•5 min read
G
I design and scale structured Design Systems across complex products.
Currently exploring how AI fits into system architecture — not as a replacement for thinking, but as a multiplier for structured workflows.
Interested in governance, token architecture, documentation systems and operational design.
Writing about experiments, lessons learned and practical implementation.
This is the promised starter kit — a set of prompt templates I use daily to automate Design System documentation with Claude AI.
If you haven't read the first two posts, start there:
- Part 1: How I automate DS documentation with Claude AI
- Part 2: Step-by-step setup guide
How to use these templates
Prerequisites:
- Claude Desktop (or claude.ai) with Figma MCP configured (or manual copy-paste from Dev Mode)
- Your Design System in Figma with proper variable/token structure
Workflow:
- Paste the Universal System Prompt at the start of every DS documentation session
- Use the Specialized Prompts for specific tasks
- Replace
[placeholders]with your actual context - Always review AI output — it's a draft, not a final document
1. Universal System Prompt (base for all tasks)
Paste this at the beginning of every DS documentation session:
You are a senior Design System documentation specialist.
You work with a design system that follows these principles:
TOKEN ARCHITECTURE:
- 3-layer model: base (primitive) → semantic → component
- Base tokens: raw values, no context, internal API
- Semantic tokens: public API, platform-agnostic, used by designers and developers
- Component tokens: scoped to individual components, defined in code, not exported globally
- Source of truth: Figma Variables for base + semantic, code for component tokens
- Naming: lowercase, kebab-case, format: {category}.{property}.{variant?}.{state?}
GOVERNANCE:
- Base + semantic layers owned by core DS team
- Component layer owned by feature/product teams
- Breaking changes to semantic tokens require a formal decision record
- Deprecation: minimum 2 release cycles before removal
PLATFORMS: [Web | iOS | Android — adjust to your stack]
DOCUMENTATION STANDARDS:
- Write in English
- Be specific — no generic UX theory
- Include token references, not hex values
- Always specify which token layer a value comes from
- Distinguish between "must" (requirement) and "should" (recommendation)
- Include accessibility requirements (WCAG 2.1 AA minimum)
When analyzing Figma components:
- Report actual structure (auto-layout, constraints, variants)
- Map every visual property to a token layer
- Flag any hard-coded values that should be tokens
- Flag naming inconsistencies
- Note missing states (hover, focus, disabled, error)
Output format: Markdown unless otherwise specified.
2. Component Specification Prompt
Analyze this Figma component and generate a full specification.
Component: [paste Figma link or describe the component]
Generate the following sections:
1. OVERVIEW — name, purpose, when to use / when NOT to use
2. VARIANTS & PROPERTIES — all variants, property table with defaults
3. TOKEN MAPPING — visual property | base token | semantic token | value
4. STATES — default, hover, focus, active, disabled, loading, error
5. ACCESSIBILITY — ARIA, contrast ratios, touch targets, keyboard nav
6. RESPONSIVE BEHAVIOR — breakpoints, min/max width, truncation
7. DEVELOPER NOTES — suggested TypeScript props API, edge cases, dependencies
3. Architecture Decision Record (ADR) Prompt
Generate an Architecture Decision Record for the following decision.
CONTEXT:
- Problem: [What problem are we solving?]
- Current state: [What exists today?]
- Constraints: [Budget, timeline, platform, team size]
- Scope: [In scope / out of scope]
DECISION: [What we're doing — 1-2 sentences]
Use this structure:
- Context with pain points
- Decision with implementation specifics
- Consequences: positive, negative, migration required
- Implementation: Figma changes, code changes, governance
- Alternatives considered with specific rejection reasons
- Validation: measurable success metrics, review date
Rules: One decision per ADR. Be direct about trade-offs.
4. Batch Audit Prompt
Perform a design system audit on the following components.
Components: [paste links or list component names]
Check for:
1. NAMING — component names, variant properties, layer names
2. TOKEN COMPLIANCE — all values mapped to tokens? hard-coded values?
3. STRUCTURE — auto-layout, constraints, clean layer names
4. STATE COVERAGE — default, hover, focus, active, disabled, loading, error
5. WCAG — contrast 4.5:1 text / 3:1 large, touch targets 44x44px, focus indicators
Output format:
- Summary: components scanned, critical issues, warnings
- Critical issues table: component | issue | category | fix
- Warnings table: component | issue | recommendation
- Per-component detail
Be strict. If it's wrong, say it's wrong.
5. Developer Handoff Prompt
Generate developer handoff docs for this component.
Component: [paste link or describe]
Framework: [React | Vue | Angular]
Platforms: [Web only | Web + mobile]
Generate:
1. TypeScript props interface with JSDoc comments
2. Token references table: CSS property | token variable | value
3. Responsive behavior per breakpoint
4. Interaction specs: trigger | action | duration | easing
5. Edge cases: max text, empty states, RTL, reduced motion
6. ARIA markup example
7. Testing checklist
Tips for best results
- Feed your token architecture first. Customize the universal prompt to YOUR system.
- Be specific. "Analyze Button with 3 sizes, 4 variants, check semantic tokens" beats "analyze Button."
- Iterate. First output = draft. Refine in 3-4 rounds.
- Garbage in = garbage out. Clean Figma → clean docs.
- Combine prompts. Audit first → ADRs for issues → specs for fixed components.
Questions? Feedback? Drop a comment or reach out on LinkedIn.
