# Design Language > 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. - Skill: `leihuang23/design-language-3` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add leihuang23/design-language-3` - Raw SKILL.md: https://api.skillmd.com/api/skills/leihuang23/design-language-3/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Design & Media - License: Apache-2.0 - Author: leihuang23 (https://skillmd.com/u/leihuang23) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/leihuang23/design-language-3 --- # 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](https://www.designtokens.org/TR/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: ```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.