design-spec
design-spec is a guide to creating DESIGN.md, the single source of truth for a project's visual language. It covers the YAML token schema (colors, typography, spacing, rounded, components), type system, token references, and canonical section order—all required before writing any UI code. Use it when defining design tokens or establishing a design source-of-truth for web or mobile projects.
design-spec teaches you how to author a DESIGN.md file—the machine-readable design-token format that must exist before any UI is built.
AI-generated summary based on this skill's SKILL.md
Install
vudovn/ag-kit/design-spec · repository language: TypeScript
git clone https://github.com/vudovn/ag-kit
cp -r ag-kit/.agents/skills/design-spec ~/.claude/skills/design-specFrequently asked questions
AI-generated answers based on this skill's SKILL.md and metadata
How do I write a design.md file for my project?
design-spec teaches you to create a DESIGN.md file as your project's single source of truth for visual language. Start by structuring it with canonical sections: colors, typography, spacing, rounded, and components. Use YAML front matter to define design tokens with their type, value, and optional description. This machine-readable format lets you establish all design decisions before writing UI code, ensuring consistency across web and mobile projects.
What is the design token schema for YAML front matter?
design-spec defines a YAML token schema covering colors, typography, spacing, rounded, and components. Each token has a type (like color or dimension), a value (hex code, pixel size, or reference), and optional metadata. The schema supports token references—using one token's value inside another—and composite values for complex design decisions. This structured format makes your design tokens machine-readable and exportable to tools like Tailwind or Figma.
What should the file structure and canonical section order be?
design-spec specifies a canonical section order for DESIGN.md: colors first, then typography, spacing, rounded, and finally components. Each section contains tokens defined in YAML with consistent naming conventions. This standardized structure ensures all team members follow the same organization, making the design source of truth predictable and easy to navigate when defining or referencing design tokens across your project.
How can design-spec help create a machine-readable design source?
design-spec enables you to build a machine-readable design source of truth by encoding all visual language decisions in DESIGN.md's YAML token schema. Once structured this way, your design tokens can be linted, exported, or converted to formats like JSON or Tailwind config files. This approach eliminates manual sync between design and code, making your design language authoritative and programmatically accessible before you build any UI components.
What design token naming conventions does design-spec recommend?
design-spec provides canonical naming conventions for design tokens to keep your design language consistent and discoverable. Token names should reflect their purpose and category—for example, color tokens might use descriptive names, typography tokens should indicate scale or role, and spacing tokens should follow a predictable pattern. Following these conventions makes token references clearer and helps teams collaborate on the same design source of truth.
Can design-spec tokens be converted to Figma variables or Tailwind?
design-spec's YAML token schema is designed to be exportable and convertible to other formats. Tokens defined in your DESIGN.md can be transformed into JSON, Tailwind config files, or synced with Figma variables through linters and exporters. This flexibility means you define your design tokens once in design-spec format and reuse them across your entire design and development workflow for web and mobile projects.
SKILL.md
rendered from the published skill — quoted content, verbatim
DESIGN.md Specification
> A DESIGN.md is the single source of truth for a project's visual language. Create it BEFORE building UI.
> Two layers: machine-readable design tokens (YAML front matter) + human-readable rationale (markdown body).
> Tokens are normative; prose gives context. Prose may use descriptive names ("Midnight Forest Green") that map to systematic token names (primary).
>
> _Format adapted from the DESIGN.md spec (Google Labs, Apache-2.0). A linter/exporter exists: `npx
(truncated - see the full file via the links below)
Read as markdown · JSON record · Browse the source repository
File tree — 2 files
.agents/skills/design-spec/SKILL.md
.agents/skills/design-spec/collection.md