---
name: design-language
description: Derive or extend a product design system from real context, producing semantic design tokens, component contracts, states, accessibility rules, and implementation mappings. Use for design-system creation or substantial UI work. Do not use to generate an arbitrary trendy palette.
license: Apache-2.0
metadata:
  compatibility: Codex, Kimi Code, and Grok Build; can emit DTCG token JSON and platform mappings.
  author: Lei Huang
  version: "0.2.0"
  status: experimental
---

# Design Language

Build a visual grammar that explains repeated decisions. Do not confuse a palette with a system.

## Workflow

1. Inspect existing tokens, components, styles, typography, assets, screen patterns, brand materials, and platform conventions.
2. Inventory inconsistencies and preserve intentional product signatures.
3. If no visual target exists for greenfield work, stop and route to `prototype-interface` for exactly three image-based directions and user selection.
4. Define principles tied to audience, content, density, interaction, and brand character.
5. Create primitive and semantic tokens for color, typography, space, size, radius, border, elevation, motion, and breakpoints as applicable.
6. Define component anatomy, variants, states, content constraints, keyboard behavior, accessibility, and responsive adaptation.
7. Map tokens and components to the target stack. Avoid parallel sources of truth.
8. Validate representative screens, edge states, contrast, focus, zoom, localization, and theme behavior.

## Token policy

Use the stable Design Tokens Community Group JSON format for new portable token sources when compatible with the toolchain. Prefer semantic names such as `color.text.muted` over presentation names such as `gray.500` in component contracts. References must resolve without cycles.

### Extension gate

Classify every proposed primitive as `inherited`, `derived`, or `new`.

- Reuse inherited product primitives before adding colors, radii, shadows, typefaces, or motion.
- A derived token must name its source primitive and transformation.
- A new primitive needs a semantic gap that existing tokens cannot fill, a named consumer, interaction-state coverage, and measured accessibility evidence.
- Do not invent hover, active, success, or warning values merely to make the table look complete. If a needed value is unverified, mark it unresolved instead of presenting it as system truth.

## Contrast gate

Calculate contrast from the exact rendered foreground and background values. Do not claim a pair passes from visual intuition.

- Normal text under 18pt, or under 14pt bold, requires at least 4.5:1.
- Large text requires at least 3:1.
- Focus indicators and meaningful non-text UI boundaries require at least 3:1 against adjacent colors.
- Report the tested pair, role, ratio, threshold, and result. If a pair fails, select a verified existing token or leave the design state unresolved.

Preserve the command or calculation output in the evidence packet. Sampled contrast checks are not evidence for untested token pairs.

## Component contract

For each material component record:

```yaml
purpose: user job
anatomy: named parts
variants: meaningful choices
states: default, hover, focus, active, disabled, loading, error, empty
content: limits, truncation, localization
behavior: pointer, keyboard, touch, motion
tokens: semantic references
accessibility: role, name, state, focus, contrast, target size
responsive: changes by available space
do_not: misuse patterns
```

## Quality rules

- Minimize arbitrary one-off values.
- Use typography and space for hierarchy before boxes and decoration.
- Do not erase an existing product’s character to impose a generic system.
- Do not use gradients, glassmorphism, excessive cards, or neon dark styling as defaults.
- Treat documentation examples and implementation mappings as part of the system.
- Produce one canonical artifact. Keep the final response to its path, decisions, verified checks, and open exceptions rather than duplicating the artifact body.

## Evidence packet

Return context inspected, principles, token source, component contracts, implementation mapping, representative validation, accessibility results, known exceptions, and migration steps.