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.

Bounded surface-extension contract

For a single surface extending an existing product language, finish the smallest complete design-system extension. Do not expand the task into a general-purpose design system.

Create only these four evidence artifacts unless the request explicitly needs more:

1. design/tokens.json - no more than 32 DTCG tokens needed by the surface.
2. design/contrast-pairs.json - no more than 16 accepted semantic foreground/background assignments plus optional diagnostics.
3. design/validation.txt - captured output from the bundled validator.
4. design/incident-detail.md or an equivalently named canonical artifact - principles, up to four material component contracts, required state matrix, stack mapping, pinned visual plan, exceptions, and migration steps.

For the incident-detail surface, the four contracts must collectively cover every requested route responsibility: status, impact, owner, timeline, affected services, live metrics, and remediation actions. A useful grouping is summary header, timeline, impact/services, and metrics/actions. Do not omit a fixture field merely to satisfy the component cap.

Write the canonical artifact skeleton first, including every required field and state, so a later validation correction cannot crowd out the primary deliverable. The state matrix must contain explicit rows for loading, empty timeline, empty metrics, timeline error, metrics error, stale data, permission denied, concurrent conflict, success, focus, long or multilingual content, and narrow viewport. Keep distinct asynchronous failures distinct.

Run the bundled validator instead of writing another checker:

python3 .agents/skills/design-language/scripts/validate_design.py \
  design/tokens.json design/contrast-pairs.json | tee design/validation.txt

The validator intentionally covers color, dimension, and duration tokens for this bounded workflow. Record typography families, weights, content constraints, and unresolved product decisions in the canonical artifact rather than inventing a comprehensive token taxonomy. Do not perform extended manual contrast derivations before running the validator: select the closest justified candidate, run it, and revise only failed assignments. Once the four artifacts meet the request, stop. Do not build a second artifact, a bespoke validator, a generalized token library, or a duplicate final-response copy.

Do not narrate token-by-token luminance arithmetic. Let the bundled validator calculate it. Run the validator once, then make at most one focused correction pass for reported failures.

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.
• Do not repeat a member name within the same JSON object. Names at different paths, such as color.border and a top-level border dimension group, are distinct and valid. The bundled validator rejects actual same-object duplicates.
• 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.

Use ordinary document and tab order for non-interactive timeline content. Use roving tabindex only for a true composite widget with interactive descendants and defined arrow-key behavior.

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.

Turn unresolved runtime details into a capture preflight, not blank fields: the future command must record the actual browser version, OS, loaded font faces, DPR, and clock before taking expected and actual captures. Pin all controllable inputs now, including 1280px and 390px viewports, 100% zoom, DPR 1, light theme, en-US, reduced motion, deterministic fixture data, frozen clock, and disabled animation after settling. A visual plan is incomplete if it names only viewports.

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.