Design Language

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.

DTCG conformance gate

Target the stable DTCG 2025.10 format and declare "$schema": "https://www.designtokens.org/schemas/2025.10/format.json" when producing token JSON.

• Every token must have a resolved $type; do not infer type from its value.
• A color value is a structured object with colorSpace and components, not a bare hex string.
• A dimension value is { "value": number, "unit": "px" | "rem" }.
• A duration value is { "value": number, "unit": "ms" | "s" }, not a number or CSS string.
• Put project metadata under a reverse-domain key inside $extensions, not as ad hoc token properties.
• Run a schema validator when available. Otherwise run and preserve a deterministic structural checker for the types used, clearly label its coverage as partial, and do not claim full schema conformance.

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.
• Separate frozen product truth from proposals. When the source context does not specify a spacing scale, type ramp, control height, breakpoint, or motion value, mark the token proposed or unresolved in metadata instead of calling it canonical.

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.
• Keep units explicit: 14pt bold is about 18.66 CSS px at 96 dpi. Bold text at 14 CSS px is normal text and requires 4.5: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.

Run an existing contrast tool or a small deterministic checker. Preserve the exact command and captured stdout or machine-readable result in the evidence packet. The acceptance check must cover every selected semantic foreground/background assignment and exit successfully. Record deliberately tested failing inherited pairs in a separate diagnostic section; do not let them masquerade as accepted assignments or make the acceptance command fail. A hand-written ratio table without executable proof is a proposal, not verified contrast evidence. Sampled checks are not evidence for untested token pairs.

Interaction safety

Keyboard access must not create accidental high-impact actions. Reuse established product shortcuts when they exist. Otherwise prefer an explicit modifier or command surface, suppress shortcuts in editable contexts, and require confirmation for destructive actions. Do not promise undo, reversibility, or permission behavior that the product context does not establish; mark it proposed or unresolved. Document focus movement, concurrent-update recovery, and what happens when the action is not permitted.

Model error states at each material asynchronous boundary. Do not collapse a timeline load failure into an empty timeline, or a metrics request failure into stale data, when recovery and user meaning differ.

Visual comparison pin

For every planned baseline/candidate comparison, pin viewport dimensions, browser and version, OS, device pixel ratio, zoom, loaded fonts, theme, locale, reduced-motion setting, deterministic data fixture, clock, and animation state. If the implementation or product reference is unavailable, record the missing values as unresolved inputs to the future capture harness instead of implying that screenshots are already reproducible.

Component contract

For each material component record:

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.