docs(design-md): sync skill with @google/design.md CLI 0.3.0
The design-md skill documented the Apr 2026 (0.1.x) CLI behavior, which has since drifted: - Lint rules: the skill listed 7 rules that no longer exist by those names (duplicate-section, invalid-color, wcag-contrast, unknown-component-property); the 0.3.0 linter runs 9 rules (contrast-ratio, orphaned-tokens, missing-primary, missing-typography, section-order, unknown-key, token-summary, missing-sections, broken-ref). Verified against live lint output. - Colors: any CSS color is now valid (oklch/rgb/named), not hex-only. - Export: json-tailwind (v3) + css-tailwind (Tailwind v4 @theme CSS) formats; 'tailwind' is a back-compat alias. New exit-code semantics (export exits 0 regardless of source lint findings). - Section order / duplicate headings are lint warnings, not file rejection (verified: duplicate + out-of-order sections exit 0). - Windows: documented the designmd dot-free bin alias (the design.md bin name collides with the .md file association); skill declares platforms: [windows]. - New pitfall: typography sub-property typos (fontwight) are silently dropped with no finding as of 0.3.0. All claims verified by running @google/design.md 0.3.0 live (lint, export, duplicate-section, oklch token, starter template lints clean). Docs page regenerated via generate-skill-docs.py.
This commit is contained in:
Teknium
parent
9a894dae5f
commit
cae5c81956
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
name: design-md
|
||||
description: Author/validate/export Google's DESIGN.md token spec files.
|
||||
version: 1.0.0
|
||||
version: 1.1.0
|
||||
author: Hermes Agent
|
||||
license: MIT
|
||||
platforms: [linux, macos, windows]
|
||||
|
|
@ -98,7 +98,7 @@ Public Sans for everything except small all-caps labels...
|
|||
|
||||
| Type | Format | Example |
|
||||
|------|--------|---------|
|
||||
| Color | `#` + hex (sRGB) | `"#1A1C1E"` |
|
||||
| Color | any CSS color (hex, `rgb()`, `oklch()`, named) | `"#1A1C1E"`, `"oklch(62% 0.18 250)"` |
|
||||
| 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 |
|
||||
|
|
@ -110,8 +110,10 @@ pressed) are **separate component entries** with related key names
|
|||
|
||||
## Canonical section order
|
||||
|
||||
Sections are optional, but present ones MUST appear in this order. Duplicate
|
||||
headings reject the file.
|
||||
Sections are optional, but present ones should appear in this order. The
|
||||
linter flags out-of-order sections (`section-order`, warning) and duplicate
|
||||
headings — consumers per the spec reject duplicates, so fix both before
|
||||
returning the file.
|
||||
|
||||
1. Overview (alias: Brand & Style)
|
||||
2. Colors
|
||||
|
|
@ -150,8 +152,11 @@ 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 Tailwind v3 theme JSON (`tailwind` is a back-compat alias)
|
||||
npx -y @google/design.md export --format json-tailwind DESIGN.md > tailwind.theme.json
|
||||
|
||||
# Export to a Tailwind v4 CSS @theme block (--color-*, --text-*, --radius-*, ...)
|
||||
npx -y @google/design.md export --format css-tailwind DESIGN.md > theme.css
|
||||
|
||||
# Export to W3C DTCG (Design Tokens Format Module) JSON
|
||||
npx -y @google/design.md export --format dtcg DESIGN.md > tokens.json
|
||||
|
|
@ -160,18 +165,28 @@ npx -y @google/design.md export --format dtcg DESIGN.md > tokens.json
|
|||
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.
|
||||
All commands accept `-` for stdin. `lint` returns exit 1 on errors (warnings
|
||||
alone exit 0). `export` exits 0 on a successful export regardless of lint
|
||||
findings in the source — run `lint` separately to gate on those. Output is
|
||||
JSON by default; parse it if you need to report findings structurally.
|
||||
|
||||
### Lint rule reference (what the 7 rules catch)
|
||||
On Windows, the `design.md` bin name can collide with the `.md` file
|
||||
association (silent no-op or the file opens in an editor). Use the dot-free
|
||||
alias: `npx -y -p @google/design.md designmd lint DESIGN.md`.
|
||||
|
||||
### Lint rule reference (the 9 rules, as of CLI 0.3.0)
|
||||
|
||||
- `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
|
||||
- `contrast-ratio` (warning) — component `textColor` vs `backgroundColor`
|
||||
below WCAG AA (4.5:1)
|
||||
- `missing-primary` (warning) — colors defined but no `primary` token
|
||||
- `missing-typography` (warning) — colors defined but no typography tokens
|
||||
- `orphaned-tokens` (warning) — color tokens never referenced by a component
|
||||
- `section-order` (warning) — sections out of the canonical order
|
||||
- `unknown-key` (warning) — top-level YAML key that looks like a typo of a
|
||||
schema key (`colours:` → `colors:`); custom extension keys stay silent
|
||||
- `token-summary`, `missing-sections` (info) — counts and absent optional
|
||||
sections
|
||||
|
||||
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.
|
||||
|
|
@ -184,10 +199,16 @@ summary — WCAG findings are the most load-bearing reason to use the CLI.
|
|||
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.
|
||||
- **Section order matters even though the linter only warns.** If the user
|
||||
gives you prose in a random order, reorder it to match the canonical list
|
||||
before saving — spec-compliant consumers expect it.
|
||||
- **Typography sub-property typos are silently dropped.** As of CLI 0.3.0 a
|
||||
typo like `fontwight:` produces no finding and the value vanishes from
|
||||
exports — double-check sub-property names against the schema
|
||||
(`fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, `letterSpacing`,
|
||||
`fontFeature`, `fontVariation`).
|
||||
- **`version: alpha` is the current spec version** (as of Jul 2026, CLI
|
||||
0.3.0). The spec is marked alpha — watch for breaking changes.
|
||||
- **Token references resolve by dotted path.** `{colors.primary}` works;
|
||||
`{primary}` does not.
|
||||
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@ Author/validate/export Google's DESIGN.md token spec files.
|
|||
|---|---|
|
||||
| Source | Bundled (installed by default) |
|
||||
| Path | `skills/creative/design-md` |
|
||||
| Version | `1.0.0` |
|
||||
| Version | `1.1.0` |
|
||||
| Author | Hermes Agent |
|
||||
| License | MIT |
|
||||
| Platforms | linux, macos, windows |
|
||||
|
|
@ -116,7 +116,7 @@ Public Sans for everything except small all-caps labels...
|
|||
|
||||
| Type | Format | Example |
|
||||
|------|--------|---------|
|
||||
| Color | `#` + hex (sRGB) | `"#1A1C1E"` |
|
||||
| Color | any CSS color (hex, `rgb()`, `oklch()`, named) | `"#1A1C1E"`, `"oklch(62% 0.18 250)"` |
|
||||
| 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 |
|
||||
|
|
@ -128,8 +128,10 @@ pressed) are **separate component entries** with related key names
|
|||
|
||||
## Canonical section order
|
||||
|
||||
Sections are optional, but present ones MUST appear in this order. Duplicate
|
||||
headings reject the file.
|
||||
Sections are optional, but present ones should appear in this order. The
|
||||
linter flags out-of-order sections (`section-order`, warning) and duplicate
|
||||
headings — consumers per the spec reject duplicates, so fix both before
|
||||
returning the file.
|
||||
|
||||
1. Overview (alias: Brand & Style)
|
||||
2. Colors
|
||||
|
|
@ -168,8 +170,11 @@ 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 Tailwind v3 theme JSON (`tailwind` is a back-compat alias)
|
||||
npx -y @google/design.md export --format json-tailwind DESIGN.md > tailwind.theme.json
|
||||
|
||||
# Export to a Tailwind v4 CSS @theme block (--color-*, --text-*, --radius-*, ...)
|
||||
npx -y @google/design.md export --format css-tailwind DESIGN.md > theme.css
|
||||
|
||||
# Export to W3C DTCG (Design Tokens Format Module) JSON
|
||||
npx -y @google/design.md export --format dtcg DESIGN.md > tokens.json
|
||||
|
|
@ -178,18 +183,28 @@ npx -y @google/design.md export --format dtcg DESIGN.md > tokens.json
|
|||
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.
|
||||
All commands accept `-` for stdin. `lint` returns exit 1 on errors (warnings
|
||||
alone exit 0). `export` exits 0 on a successful export regardless of lint
|
||||
findings in the source — run `lint` separately to gate on those. Output is
|
||||
JSON by default; parse it if you need to report findings structurally.
|
||||
|
||||
### Lint rule reference (what the 7 rules catch)
|
||||
On Windows, the `design.md` bin name can collide with the `.md` file
|
||||
association (silent no-op or the file opens in an editor). Use the dot-free
|
||||
alias: `npx -y -p @google/design.md designmd lint DESIGN.md`.
|
||||
|
||||
### Lint rule reference (the 9 rules, as of CLI 0.3.0)
|
||||
|
||||
- `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
|
||||
- `contrast-ratio` (warning) — component `textColor` vs `backgroundColor`
|
||||
below WCAG AA (4.5:1)
|
||||
- `missing-primary` (warning) — colors defined but no `primary` token
|
||||
- `missing-typography` (warning) — colors defined but no typography tokens
|
||||
- `orphaned-tokens` (warning) — color tokens never referenced by a component
|
||||
- `section-order` (warning) — sections out of the canonical order
|
||||
- `unknown-key` (warning) — top-level YAML key that looks like a typo of a
|
||||
schema key (`colours:` → `colors:`); custom extension keys stay silent
|
||||
- `token-summary`, `missing-sections` (info) — counts and absent optional
|
||||
sections
|
||||
|
||||
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.
|
||||
|
|
@ -202,10 +217,16 @@ summary — WCAG findings are the most load-bearing reason to use the CLI.
|
|||
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.
|
||||
- **Section order matters even though the linter only warns.** If the user
|
||||
gives you prose in a random order, reorder it to match the canonical list
|
||||
before saving — spec-compliant consumers expect it.
|
||||
- **Typography sub-property typos are silently dropped.** As of CLI 0.3.0 a
|
||||
typo like `fontwight:` produces no finding and the value vanishes from
|
||||
exports — double-check sub-property names against the schema
|
||||
(`fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, `letterSpacing`,
|
||||
`fontFeature`, `fontVariation`).
|
||||
- **`version: alpha` is the current spec version** (as of Jul 2026, CLI
|
||||
0.3.0). The spec is marked alpha — watch for breaking changes.
|
||||
- **Token references resolve by dotted path.** `{colors.primary}` works;
|
||||
`{primary}` does not.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue