Design System Consistency with AI
AI is a useful consistency enforcer for design systems — it can audit code for hardcoded values that should be tokens, flag components that deviate from your naming conventions, and generate token names that follow your established patterns. It is not a designer: it cannot decide what your design system should be, only whether code conforms to what you have already decided.
Token Compliance Audit
The most common design system drift is hardcoded values — hex colours, pixel sizes, and font weights written directly in components instead of using the token system. AI catches these reliably in code review.
Audit the following component for design token compliance. Flag any hardcoded values that should use a design token instead.
Our token system uses: [DESCRIBE YOUR TOKEN FORMAT — e.g., "CSS custom properties: --color-primary-500, --spacing-4, --radius-md, --font-size-sm"]
Component code:
[PASTE COMPONENT CODE]
For each hardcoded value found:
1. The hardcoded value and where it appears
2. The token it should be replaced with (match our naming convention)
3. If no matching token exists: note it as a gap and suggest what the token should be named
After the audit: is this component fully token-compliant, partially compliant, or needs significant rework?
The "gap identification" step is valuable — it surfaces missing tokens in your system rather than silently leaving hardcoded values in place.
Token Naming Consistency
Token naming conventions become inconsistent over time as multiple people add tokens. AI can apply your established patterns to new token names and flag deviations.
I need to name design tokens for new components. Apply our existing naming convention to generate consistent token names.
Our existing token naming pattern:
- Structure: [e.g., "--[category]-[variant]-[scale] — e.g., --color-brand-500, --spacing-component-md"]
- Categories we use: [LIST — e.g., color / spacing / radius / shadow / typography / motion]
- Scale convention: [e.g., "numeric 100-900 for colours; t-shirt sizes sm/md/lg/xl for spacing"]
I need tokens for:
[LIST WHAT YOU NEED — e.g., "a new warning colour palette (5 steps), a tooltip border radius, a card drop shadow"]
Generate token names only. Do not assign values — that is a design decision.
Flag any naming decision where our convention is ambiguous and you had to make an assumption.
The explicit "names only, no values" constraint is important — token values are design decisions that require visual judgement. Token names are structural decisions AI can help with.
Documenting Design Decisions
The most time-consuming part of design system work is not building components — it is documenting when and how to use them. AI drafts this documentation from a description of the component's intent.
Write design system documentation for the following component. The audience is designers and developers who will use it — not people building it.
Component: [NAME]
What it is: [DESCRIBE]
Available variants: [LIST VARIANTS]
Existing similar components: [e.g., "we have an Alert component for errors; this Badge is for status labels only"]
Documentation must include:
1. When to use this component (3 concrete use cases)
2. When NOT to use it (and what to use instead)
3. Variant guide: when each variant applies
4. Accessibility notes: anything the implementer must handle (ARIA, colour contrast)
5. Do and Don't examples (2 of each, text descriptions — not code)
The "when NOT to use" section is the most valuable and most often skipped. It prevents the most common design system failure: using the wrong component for the job.
Design System Audit Prompt for a Component Library
Audit these components for consistency issues across our design system.
Components to review:
[PASTE 2-4 RELATED COMPONENT CODE FILES]
Check for:
1. Inconsistent prop naming: same concept named differently across components (e.g., 'isDisabled' in one, 'disabled' in another)
2. Inconsistent event handler naming (onClick vs handleClick vs onPress)
3. Hardcoded values that should be tokens
4. Inconsistent size variant naming (sm/md/lg vs small/medium/large vs s/m/l)
5. Missing variants: if Button has a 'ghost' variant, should Input also support it?
Output: a table of inconsistencies with the affected components and a recommended standard.
Paste 2-4 components at a time for the most useful audit. Larger batches spread AI attention and produce less actionable output.
What AI Cannot Do
AI can enforce and generate
- Finding hardcoded values that deviate from token system
- Naming new tokens that match your convention
- Flagging inconsistent prop naming across components
- Drafting "when to use" documentation from intent descriptions
- Suggesting missing component variants based on existing patterns
AI cannot make design decisions
- What your colour palette should look like
- Whether your spacing scale is appropriate for your brand
- Whether two colours have sufficient contrast in context
- Which components belong in a shared library vs page-specific
- Whether your design system architecture (single package vs monorepo) is correct
Checklist: Do You Understand This?
- What is design token drift, and why does it happen even in teams with an established design system?
- Why should you ask AI for token names only — not token values?
- What is the most important section in design system documentation that teams most often skip?
- Write a token compliance audit prompt for a Button component that may contain hardcoded colours.
- How many components should you paste in a single consistency audit prompt — and why?
- Name two design system decisions that require human visual judgement and cannot be delegated to AI.