AGENT SKILL

design-md

Author/validate/export Google's DESIGN.md token spec files.

License 许可
MIT
最近更新
2026-08-31
Stars
★ 0
Forks
0

01 前言 Front Matter

name
design-md
author
Hermes Agent
license
MIT
version
1.0.0
metadata
{ "hermes": { "tags": [ "design", "design-system", "tokens", "ui", "accessibility", "wcag", "tailwind", "dtcg", "google" ], "related_skills": [ "popular-web-designs", "claude-design", "excalidraw", "architecture-diagram" ] } }
platforms
[ "linux", "macos", "windows" ]
description
Author/validate/export Google's DESIGN.md token spec files.

02 资源文件 1

03 SKILL.md 正文

DESIGN.md Skill

DESIGN.md is Google's open spec (Apache-2.0, google-labs-code/design.md) for describing a visual identity to coding agents. One file combines:

  • YAML front matter — machine-readable design tokens (normative values)
  • Markdown body — human-readable rationale, organized into canonical sections

Tokens give exact values. Prose tells agents why those values exist and how to apply them. The CLI (npx @google/design.md) lints structure + WCAG contrast, diffs versions for regressions, and exports to Tailwind or W3C DTCG JSON.

When to use this skill

  • User asks for a DESIGN.md file, design tokens, or a design system spec
  • User wants consistent UI/brand across multiple projects or tools
  • User pastes an existing DESIGN.md and asks to lint, diff, export, or extend it
  • User asks to port a style guide into a format agents can consume
  • User wants contrast / WCAG accessibility validation on their color palette

For purely visual inspiration or layout examples, use popular-web-designs instead. For process and taste when designing a one-off HTML artifact from scratch (prototype, deck, landing page, component lab), use claude-design. This skill is for the formal spec file itself.

File anatomy

---
version: alpha
name: Heritage
description: Architectural minimalism meets journalistic gravitas.
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 3rem
    fontWeight: 700
    lineHeight: 1.1
    letterSpacing: "-0.02em"
  body-md:
    fontFamily: Public Sans
    fontSize: 1rem
rounded:
  sm: 4px
  md: 8px
  lg: 16px
spacing:
  sm: 8px
  md: 16px
  lg: 24px
components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "#FFFFFF"
    rounded: "{rounded.sm}"
    padding: 12px
  button-primary-hover:
    backgroundColor: "{colors.primary}"
---

## Overview

Architectural Minimalism meets Journalistic Gravitas...

## Colors

- **Primary (#1A1C1E):** Deep ink for headlines and core text.
- **Tertiary (#B8422E):** "Boston Clay" — the sole driver for interaction.

## Typography

Public Sans for everything except small all-caps labels...

## Components

`button-primary` is the only high-emphasis action on a page...

Token types

Type Format Example
Color # + hex (sRGB) "#1A1C1E"
Dimension number + unit (px, em, rem) 48px, -0.02em
Token reference {path.to.token} {colors.primary}
Typography object with fontFamily, fontSize, fontWeight, lineHeight, letterSpacing, fontFeature, fontVariation see above

Component property whitelist: backgroundColor, textColor, typography, rounded, padding, size, height, width. Variants (hover, active, pressed) are separate component entries with related key names (button-primary-hover), not nested.

Canonical section order

Sections are optional, but present ones MUST appear in this order. Duplicate headings reject the file.

  1. Overview (alias: Brand & Style)
  2. Colors
  3. Typography
  4. Layout (alias: Layout & Spacing)
  5. Elevation & Depth (alias: Elevation)
  6. Shapes
  7. Components
  8. Do's and Don'ts

Unknown sections are preserved, not errored. Unknown token names are accepted if the value type is valid. Unknown component properties produce a warning.

Workflow: authoring a new DESIGN.md

  1. Ask the user (or infer) the brand tone, accent color, and typography direction. If they provided a site, image, or vibe, translate it to the token shape above.
  2. Write DESIGN.md in their project root using write_file. Always include name: and colors:; other sections optional but encouraged.
  3. Use token references ({colors.primary}) in the components: section instead of re-typing hex values. Keeps the palette single-source.
  4. Lint it (see below). Fix any broken references or WCAG failures before returning.
  5. If the user has an existing project, also write Tailwind or DTCG exports next to the file (tailwind.theme.json, tokens.json).

Workflow: lint / diff / export

The CLI is @google/design.md (Node). Use npx — no global install needed.

# Validate structure + token references + WCAG contrast
npx -y @google/design.md lint DESIGN.md

# Compare two versions, fail on regression (exit 1 = regression)
npx -y @google/design.md diff DESIGN.md DESIGN-v2.md

# Export to Tailwind theme JSON
npx -y @google/design.md export --format tailwind DESIGN.md > tailwind.theme.json

# Export to W3C DTCG (Design Tokens Format Module) JSON
npx -y @google/design.md export --format dtcg DESIGN.md > tokens.json

# Print the spec itself — useful when injecting into an agent prompt
npx -y @google/design.md spec --rules-only --format json

All commands accept - for stdin. lint returns exit 1 on errors. Use the --format json flag and parse the output if you need to report findings structurally.

Lint rule reference (what the 7 rules catch)

  • broken-ref (error) — {colors.missing} points at a non-existent token
  • duplicate-section (error) — same ## Heading appears twice
  • invalid-color, invalid-dimension, invalid-typography (error)
  • wcag-contrast (warning/info) — component textColor vs backgroundColor ratio against WCAG AA (4.5:1) and AAA (7:1)
  • unknown-component-property (warning) — outside the whitelist above

When the user cares about accessibility, call this out explicitly in your summary — WCAG findings are the most load-bearing reason to use the CLI.

Pitfalls

  • Don't nest component variants. button-primary.hover is wrong; button-primary-hover as a sibling key is right.
  • Hex colors must be quoted strings. YAML will otherwise choke on # or truncate values like #1A1C1E oddly.
  • Negative dimensions need quotes too. letterSpacing: -0.02em parses as a YAML flow — write letterSpacing: "-0.02em".
  • Section order is enforced. If the user gives you prose in a random order, reorder it to match the canonical list before saving.
  • version: alpha is the current spec version (as of Apr 2026). The spec is marked alpha — watch for breaking changes.
  • Token references resolve by dotted path. {colors.primary} works; {primary} does not.

Spec source of truth

04 同仓库更多 Skills

lzy18001500226
lzy18001500226/MoSim

skill-installer

Install Codex skills into $CODEX_HOME/skills from a curated list or a GitHub repo path. Use when a user asks to list installable skills, install a curated skill, or install a skill from another repo (including private repos).

★ 0
lzy18001500226
lzy18001500226/MoSim

skill-creator

Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Codex's capabilities with specialized knowledge, workflows, or tool integrations.

★ 0
lzy18001500226
lzy18001500226/MoSim

openai-docs

Use for Codex models/pricing, scheduled tasks, skills, settings, setup, troubleshooting, customization, automations, and self-knowledge—including 'you,' 'your,' 'this app,' or 'this coding agent' when they refer to Codex—and for OpenAI APIs/products and ChatGPT Work. Also use for model choice/migration, prompting, SDKs, Responses, Realtime, agents, evals, and Chat/Work/Codex comparisons. Do not use for generic app/software tasks that merely mention Codex.

★ 0
lzy18001500226
lzy18001500226/MoSim

imagegen

Generate or edit raster images when the task benefits from AI-created bitmap visuals such as photos, illustrations, textures, sprites, mockups, or transparent-background cutouts. Use when Codex should create a brand-new image, transform an existing image, or derive visual variants from references, and the output should be a bitmap asset rather than repo-native code or vector. Do not use when the task is better handled by editing existing SVG/vector/code-native assets, extending an established icon or logo system, or building the visual directly in HTML/CSS/canvas.

★ 0
lzy18001500226
lzy18001500226/MoSim

skill-creator-cc

Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, update or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.

★ 0
lzy18001500226
lzy18001500226/MoSim

prd-writing-guide

Write complete, unambiguous PRDs that development teams can implement without guesswork. Includes requirement discovery framework, structured documentation methodology, completeness checklists, and common pitfall avoidance. Use when: writing new PRDs, reviewing PRD drafts, validating requirement completeness, preparing for engineering handoff. Triggers: 'write PRD', '写PRD', '产品需求文档', '需求文档', '需求规格', '需求评审', '完善需求', 'create requirements doc', 'product requirements', 'feature spec', 'requirements document'. Anti-triggers: 'technical design doc', 'architecture design', 'implementation plan', 'API design', '架构设计', '技术方案', '实现方案', '接口设计'.

★ 0