design-md

Files (15)

• SKILL.md
• CHANGELOG.md · references/
• INDEX.md · references/
• LESSONS_LEARNED.md · references/
• authoring-guide.md · references/
• cli-guide.md · references/
• css-custom-properties.md · references/conversions/
• design-tokens-json.md · references/conversions/
• tailwind.md · references/conversions/
• component-patterns.md · references/examples/
• full-system.md · references/examples/
• minimal.md · references/examples/
• spec-quickref.md · references/
• spec-source.md · references/
• wcag-contrast.md · references/

SKILL.md (first lines)

# DESIGN.md Skill

DESIGN.md is a plain-text design system spec: **YAML front matter** (machine-readable tokens) +
**Markdown body** (human-readable rationale). Tokens are normative values. Prose explains intent.

## Mode Selection

Pick one mode based on task. Each mode has its own workflow below.

| Mode | Trigger Phrases | Start Here |
|------|----------------|------------|
| **consume** | "build UI", "style this", "apply design", "use the design system" | Consume Mode below |
| **create** | "create design system", "make a DESIGN.md", "design tokens for my project" | → [references/authoring-guide.md](references/authoring-guide.md) |
| **validate** | "lint", "check contrast", "validate design", "diff design" | CLI Tooling below |
| **convert** | "tailwind config", "css variables", "tokens.json", "style dictionary" | → [references/INDEX.md](references/INDEX.md) → conversions/ |

## Consume Mode

Default mode. Use whenever a DESIGN.md exists in the project root or a specified path.

1. **Parse** YAML front matter — extract all token groups (`colors`, `typography`, `rounded`, `spacing`, `components`)
2. **Resolve** `{path.to.token}` references before applying values
3. **Read** prose sections for design intent — prose answers "why" when tokens alone are ambiguous
4. **Apply** tokens to implementation using the project's CSS approach

Application rules by token group:

| Token Group | How to Apply |
|-------------|-------------|
| `colors` | Map to background, text, border values. Use descriptive names (primary, secondary) as semantic roles |
| `typography` | Bundle fontFamily + fontSize + fontWeight + lineHeight + letterSpacing as a unit |
| `components` | Assemble from sub-properties (`backgroundColor`, `textColor`, `rounded`, `padding`). Variant naming convention: `button-primary`, `button-primary-hover`, `button-primary-active` |
| `rounded` / `spacing` | Apply as sizing values using the scale levels (`sm`, `md`, `lg`, etc.) |

When tokens don't cover a specific need, defer to prose sections for intent, then make a decision consistent with the design personality.

## Create Mode

→ Full workflow in [references/authoring-guide.md](references/authoring-guide.md)

Quick start:
1. Collect brand personality, target audience, emotional response (Overview section)
2. Define color palettes → derive `colors` tokens
3. Choose typography levels → define `typography` tokens
4. Set spacing scale, rounding, elevation strategy
5. Define component tokens using `{path.to.token}` references
6. Write prose sections in required order
7. Run `lint` to validate

## Validate Mode

### CLI Tooling

All commands via `npx @google/design.md` or `bunx @google/design.md`.

```bash
npx @google/design.md lint DESIGN.md             # Structure + WCAG contrast validation
npx @google/design.md lint --format json          # Machine-readable JSON output
npx @google/design.md diff DESIGN.md v2.md        # Detect token + prose regressions
```

**When to run:**

| Situation | Command |
|-----------|---------|
| After authoring a new DESIGN.md | `lint` |
| Before committing design changes | `diff` against previous version |
| Contrast warnings from lint | → [references/wcag-contrast.md](references/wcag-contrast.md) |
| CI/CD integration | `lint --format json` and check `summary.errors` |

→ Full CLI reference: [references/cli-guide.md](references/cli-guide.md)

## Quick Reference

Token types:

| Type | Format | Example |
|------|--------|---------|
| Color | `#` + hex (sRGB) | `"#1A1C1E"` |
| Dimension | number + unit (`px`, `em`, `rem`) | `48px`, `1.5rem` |
| Token Reference | `{path.to.token}` | `{colors.primary}` |
| Typography | object with font properties | `fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, `letterSpacing` |

Prose section order (use `##` headings, can omit but must be in sequence):
1. Overview — brand personality, emotional response
2. Colors — palette rationale
3. Typography — font strategy
4. Layout — grid/spacing model
5. Elevation & Depth — shadow/depth approach
6. Shapes — border radius strategy
7. Components — per-component styling guidance
8. Do's and Don'ts — guardrails

Component token properties: `backgroundColor`, `textColor`, `typography`, `rounded`, `padding`, `size`, `height`, `width`.

→ Full schema: [references/spec-quickref.md](references/spec-quickref.md)

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Omitting prose sections | Prose gives intent — agent needs "why" not just "what" |
| Hardcoding colors instead of token references | Use `{colors.primary}` in components, not `"#1A1C1E"` |
| Wrong section order | Must follow: Overview → Colors → Typography → Layout → Elevation → Shapes → Components → Do's/Don'ts |
| Duplicate section headings | Rejected by spec — each heading must be unique |
| Missing `name` in frontmatter | Required field — design system must have a name |
| Ignoring WCAG contrast | Run `lint` — AA requires 4.5:1 for normal text, 3:1 for large |
| Mixing units inconsistently | Pick `px` or `rem` per token group, stay consistent |

## Self-Learning / Self-Updating Protocol

> This skill tracks the DESIGN.md spec at `google-labs-code/design.md` (currently alpha).
> Agent may modify `references/` files when new evidence or spec changes warrant it.

### Spec Freshness

If `last-reviewed` > 7 days, run freshness check:

```bash

From kvithayathil/agent-resources, Apache-2.0.

More from kvithayathil/agent-resources