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
Decision gist · record as of 2026-07-26
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. 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.
Use it when
- design-spec defines a YAML token schema covering colors, typography, spacing, rounded, and components.
- design-spec specifies a canonical section order for DESIGN.md: colors first, then typography, spacing, rounded, and finally components.
Verify before relying
Read SKILL.md below before installing (2 files). Open directory: indexed for reading, not audited.
Install
vudovn/ag-kit/design-spec · repository language: TypeScript
Open directory. Skills are indexed for reading, not audited. Review a skill's body before installing it.
Frequently 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)
File tree — 2 files
.agents/skills/design-spec/SKILL.md
.agents/skills/design-spec/collection.md
Let your AI agent find skills like this
Example. Real query, live index.
You found this page by searching. An agent finds it by wishing: SkillFed indexes 56,283 agent skills by what they can do, searchable in plain language.
wish › “Learn how to author and structure a DESIGN.md file before building UI”
Give your agent the search over MCP, or paste the wish link into any chat. No install? Search from any chat →
Related skills
design-md lets you create and validate DESIGN.md files—Google's open spec for encoding design systems as machine-readable tokens plus human-readable rationale. The included CLI lints structure, checks WCAG color contrast, diffs versions for regressions, and exports to Tailwind or W3C DTCG JSON formats.
Design Spec Extraction converts visual inputs—screenshots, mockups, and design exports—into structured JSON specifications following W3C Design Tokens standards. The skill uses a 7-pass serial architecture to extract layout, colors, typography, components, spacing, accessibility data, and state information, writing each phase to disk for validation and resumption.
design-md helps you create and maintain formal design token specifications using Google's open DESIGN.md format. Write machine-readable tokens in YAML paired with human-readable guidance, then lint for WCAG contrast compliance, diff versions for regressions, and export to Tailwind or W3C DTCG JSON formats.
Design System converts visual references into two synchronized outputs: a YAML token spec in Google's design.md format for coding agents, and a self-contained HTML style guide for human review. Reads imagery, derives tokens for color, typography, spacing, and components, then generates both files as a single source of truth that never drifts.
Design Tokens manages design token files using the DTCG 2025.10 standard with a dependency-free Python core. It scaffolds token sets, validates them against the spec, merges project overrides with global brand bases, resolves aliases, and exports to CSS custom properties. The skill also generates preview pages, design documentation, and generation prompts for on-brand image creation.
This skill validates DESIGN.md files using Google's @google/design.md specification, catching structural errors, broken token references, and design-system quality issues. It runs a bundled Node script to lint YAML front matter, component properties, and WCAG contrast ratios, then reports findings with actionable fixes. Use it to verify design tokens before shipping or to compare versions for regressions.