{"_id":"@google/design.md","_rev":"3-adc6d25cadd30ffeb692fb398b249f02","name":"@google/design.md","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@google/design.md","version":"0.1.0","keywords":["design.md"],"_id":"@google/design.md@0.1.0","maintainers":[{"name":"google-wombot","email":"node-team-npm+wombot@google.com"},{"name":"ofrobots","email":"ofrobots@google.com"},{"name":"mrdoob","email":"info@mrdoob.com"}],"homepage":"https://github.com/google-labs-code/design.md#readme","bugs":{"url":"https://github.com/google-labs-code/design.md/issues"},"bin":{"design.md":"dist/index.js"},"dist":{"shasum":"d7e0236ec2effa25ee6b54dbf1b46c28a6e73df3","tarball":"https://registry.npmjs.org/@google/design.md/-/design.md-0.1.0.tgz","fileCount":47,"integrity":"sha512-LrYXtap8g3utRe8d8kV0OdDSB99AYUwuluXB7rtO4qiwXdfyYL2FNa5DzwW/8GfS/p6NfwBJuaNrt3SlkzX2Pw==","signatures":[{"sig":"MEUCIQCDspYvMaAk4WqhXxz2DptepY8IC2pPGdgvA96xlLkt9QIgIMJjlUedqaZ3JuoUTRMJqyk1kZQogj4RyWPKkO8pATo=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1515766},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./linter":{"types":"./dist/linter/index.d.ts","import":"./dist/linter/index.js"}},"gitHead":"816513b520f1ba7992419816bf9e2b862cec05f0","private":false,"scripts":{"dev":"bun run src/index.ts","test":"bun test","build":"bun build src/index.ts src/linter/index.ts --outdir dist --target node && npx tsc --project tsconfig.build.json --emitDeclarationOnly --skipLibCheck && cp src/linter/spec-config.yaml dist/linter/ && cp src/linter/spec-config.yaml dist/ && cp ../../docs/spec.md dist/linter/","check-package":"bun run scripts/check-package.ts"},"_npmUser":{"name":"google-wombot","email":"node-team-npm+wombot@google.com"},"repository":{"url":"git+https://github.com/google-labs-code/design.md.git","type":"git"},"_npmVersion":"10.9.3","description":"Bridging design systems and code: a linter and exporter for the DESIGN.md format","directories":{},"_nodeVersion":"22.19.0","dependencies":{"ink":"^7.0.0","zod":"^3.24.0","yaml":"^2.7.1","citty":"^0.1.6","mdast":"^3.0.0","react":"^19.2.5","unified":"^11.0.5","remark-mdx":"^3.1.1","remark-parse":"^11.0.0","@json-render/ink":"^0.16.0","remark-stringify":"^11.0.0","unist-util-visit":"^5.1.0","@json-render/core":"^0.16.0","remark-frontmatter":"^5.0.0"},"publishConfig":{"access":"public","registry":"https://wombat-dressing-room.appspot.com"},"_hasShrinkwrap":false,"devDependencies":{"bun-types":"^1.3.12","@types/bun":"latest","typescript":"^5.7.3","@types/node":"^20.11.24","tailwindcss":"3","@types/mdast":"^4.0.4","@types/react":"^19.2.14"},"_npmOperationalInternal":{"tmp":"tmp/design.md_0.1.0_1776787332550_0.18657519503420983","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@google/design.md","version":"0.1.1","keywords":["design.md"],"_id":"@google/design.md@0.1.1","maintainers":[{"name":"google-wombot","email":"node-team-npm+wombot@google.com"},{"name":"ofrobots","email":"ofrobots@google.com"},{"name":"mrdoob","email":"info@mrdoob.com"}],"homepage":"https://github.com/google-labs-code/design.md#readme","bugs":{"url":"https://github.com/google-labs-code/design.md/issues"},"bin":{"design.md":"dist/index.js"},"dist":{"shasum":"e350e30aef6eed28a44117be221d00cc7f1836ef","tarball":"https://registry.npmjs.org/@google/design.md/-/design.md-0.1.1.tgz","fileCount":47,"integrity":"sha512-S5xdF4DrELQwY2186vishZ9ZHxzMo7eikM8FHFNDS87oULElLDF5eko33DPCXtWyzEPyzkZWuUTpm/M0pPtbNQ==","signatures":[{"sig":"MEUCIQCzAPZwPdFwR4UdsBCPni35ZqEbUH2zuRK/YgfU4LCfbwIgCvPYjsAVCx6zAkXIfLP3qLRbqmglWpEBMxIHFqp+izs=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1515822},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./linter":{"types":"./dist/linter/index.d.ts","import":"./dist/linter/index.js"}},"gitHead":"6589f05166473ddc54ca01a615254a673add492c","private":false,"scripts":{"dev":"bun run src/index.ts","test":"bun test","build":"bun build src/index.ts src/linter/index.ts --outdir dist --target node && npx tsc --project tsconfig.build.json --emitDeclarationOnly --skipLibCheck && cp src/linter/spec-config.yaml dist/linter/ && cp src/linter/spec-config.yaml dist/ && cp ../../docs/spec.md dist/linter/","spec:gen":"bun run src/linter/spec-gen/generate.ts","check-package":"bun run scripts/check-package.ts"},"_npmUser":{"name":"google-wombot","email":"node-team-npm+wombot@google.com"},"repository":{"url":"git+https://github.com/google-labs-code/design.md.git","type":"git"},"_npmVersion":"10.9.3","description":"Bridging design systems and code: a linter and exporter for the DESIGN.md format","directories":{},"_nodeVersion":"22.19.0","dependencies":{"ink":"^7.0.0","zod":"^3.24.0","yaml":"^2.7.1","citty":"^0.1.6","mdast":"^3.0.0","react":"^19.2.5","unified":"^11.0.5","remark-mdx":"^3.1.1","remark-parse":"^11.0.0","@json-render/ink":"^0.16.0","remark-stringify":"^11.0.0","unist-util-visit":"^5.1.0","@json-render/core":"^0.16.0","remark-frontmatter":"^5.0.0"},"publishConfig":{"access":"public","registry":"https://wombat-dressing-room.appspot.com"},"_hasShrinkwrap":false,"devDependencies":{"bun-types":"^1.3.12","@types/bun":"latest","typescript":"^5.7.3","@types/node":"^20.11.24","tailwindcss":"3","@types/mdast":"^4.0.4","@types/react":"^19.2.14"},"_npmOperationalInternal":{"tmp":"tmp/design.md_0.1.1_1776792835068_0.7016435663035623","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@google/design.md","version":"0.2.0","description":"Bridging design systems and code: a linter and exporter for the DESIGN.md format","keywords":["design.md"],"repository":{"type":"git","url":"git+https://github.com/google-labs-code/design.md.git"},"bugs":{"url":"https://github.com/google-labs-code/design.md/issues"},"main":"./dist/index.js","types":"./dist/index.d.ts","private":false,"type":"module","bin":{"design.md":"dist/index.js","designmd":"dist/index.js"},"exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts"},"./linter":{"import":"./dist/linter/index.js","types":"./dist/linter/index.d.ts"}},"publishConfig":{"registry":"https://wombat-dressing-room.appspot.com","access":"public"},"scripts":{"build":"bun build src/index.ts src/linter/index.ts --outdir dist --target node && npx tsc --project tsconfig.build.json --emitDeclarationOnly --skipLibCheck && cp src/linter/spec-config.yaml dist/linter/ && cp src/linter/spec-config.yaml dist/ && cp ../../docs/spec.md dist/linter/","dev":"bun run src/index.ts","test":"bun test","spec:gen":"bun run src/linter/spec-gen/generate.ts","check-package":"bun run scripts/check-package.ts"},"dependencies":{"@json-render/core":"^0.16.0","@json-render/ink":"^0.16.0","citty":"^0.1.6","ink":"^7.0.0","mdast":"^3.0.0","react":"^19.2.5","remark-frontmatter":"^5.0.0","remark-mdx":"^3.1.1","remark-parse":"^11.0.0","remark-stringify":"^11.0.0","unified":"^11.0.5","unist-util-visit":"^5.1.0","yaml":"^2.7.1","zod":"^3.24.0"},"devDependencies":{"@types/bun":"latest","@types/mdast":"^4.0.4","@types/node":"^20.11.24","@types/react":"^19.2.14","bun-types":"^1.3.12","tailwindcss":"3","typescript":"^5.7.3"},"_id":"@google/design.md@0.2.0","gitHead":"887a4bff8943f37ef7c9a2d8c01266f18e3fe895","homepage":"https://github.com/google-labs-code/design.md#readme","_nodeVersion":"22.19.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-0z+a8ZGMBnk9M9/OGv7Cw05fvednlSg4QijuBJ5vFe3I5sFZTbLSu/dk/Lmju9osUoxd+sPMAZoBC/8qLL18tw==","shasum":"cfdf0726c97ccbc620ca649c73e00d42f2256c8d","tarball":"https://registry.npmjs.org/@google/design.md/-/design.md-0.2.0.tgz","fileCount":50,"unpackedSize":1556292,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIDVudznygtUjeOLRAcZXN1x4PHRKZdUpM7/nyEY0m6uyAiBKDPACiAcokcmvQGktf8kImwAIvoppOa8lFBjBjhH+kw=="}]},"_npmUser":{"name":"google-wombot","email":"node-team-npm+wombot@google.com"},"directories":{},"maintainers":[{"name":"google-wombot","email":"node-team-npm+wombot@google.com"},{"name":"ofrobots","email":"ofrobots@google.com"},{"name":"mrdoob","email":"info@mrdoob.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/design.md_0.2.0_1779802848255_0.665300023111747"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-21T16:02:12.419Z","modified":"2026-05-26T13:40:48.558Z","0.1.0":"2026-04-21T16:02:12.748Z","0.1.1":"2026-04-21T17:33:55.283Z","0.2.0":"2026-05-26T13:40:48.445Z"},"bugs":{"url":"https://github.com/google-labs-code/design.md/issues"},"homepage":"https://github.com/google-labs-code/design.md#readme","keywords":["design.md"],"repository":{"type":"git","url":"git+https://github.com/google-labs-code/design.md.git"},"description":"Bridging design systems and code: a linter and exporter for the DESIGN.md format","maintainers":[{"name":"google-wombot","email":"node-team-npm+wombot@google.com"},{"name":"ofrobots","email":"ofrobots@google.com"},{"name":"mrdoob","email":"info@mrdoob.com"}],"readme":"# DESIGN.md\n\nA format specification for describing a visual identity to coding agents. DESIGN.md gives agents a persistent, structured understanding of a design system.\n\n## The Format\n\nA DESIGN.md file combines machine-readable design tokens (YAML front matter) with human-readable design rationale (markdown prose). Tokens give agents exact values. Prose tells them *why* those values exist and how to apply them.\n\n```md\n---\nname: Heritage\ncolors:\n  primary: \"#1A1C1E\"\n  secondary: \"#6C7278\"\n  tertiary: \"#B8422E\"\n  neutral: \"#F7F5F2\"\ntypography:\n  h1:\n    fontFamily: Public Sans\n    fontSize: 3rem\n  body-md:\n    fontFamily: Public Sans\n    fontSize: 1rem\n  label-caps:\n    fontFamily: Space Grotesk\n    fontSize: 0.75rem\nrounded:\n  sm: 4px\n  md: 8px\nspacing:\n  sm: 8px\n  md: 16px\n---\n\n## Overview\n\nArchitectural Minimalism meets Journalistic Gravitas. The UI evokes a\npremium matte finish — a high-end broadsheet or contemporary gallery.\n\n## Colors\n\nThe palette is rooted in high-contrast neutrals and a single accent color.\n\n- **Primary (#1A1C1E):** Deep ink for headlines and core text.\n- **Secondary (#6C7278):** Sophisticated slate for borders, captions, metadata.\n- **Tertiary (#B8422E):** \"Boston Clay\" — the sole driver for interaction.\n- **Neutral (#F7F5F2):** Warm limestone foundation, softer than pure white.\n```\n\nAn agent that reads this file will produce a UI with deep ink headlines in Public Sans, a warm limestone background, and Boston Clay call-to-action buttons.\n\n## Getting Started\n\nValidate a DESIGN.md against the spec, catch broken token references, check WCAG contrast ratios, and surface structural findings — all as structured JSON that agents can act on.\n\n```bash\nnpx @google/design.md lint DESIGN.md\n```\n\n```json\n{\n  \"findings\": [\n    {\n      \"severity\": \"warning\",\n      \"path\": \"components.button-primary\",\n      \"message\": \"textColor (#ffffff) on backgroundColor (#1A1C1E) has contrast ratio 15.42:1 — passes WCAG AA.\"\n    }\n  ],\n  \"summary\": { \"errors\": 0, \"warnings\": 1, \"info\": 1 }\n}\n```\n\nCompare two versions of a design system to detect token-level and prose regressions:\n\n```bash\nnpx @google/design.md diff DESIGN.md DESIGN-v2.md\n```\n\n```json\n{\n  \"tokens\": {\n    \"colors\": { \"added\": [\"accent\"], \"removed\": [], \"modified\": [\"tertiary\"] },\n    \"typography\": { \"added\": [], \"removed\": [], \"modified\": [] }\n  },\n  \"regression\": false\n}\n```\n\n## The Specification\n\nThe full DESIGN.md spec lives at [`docs/spec.md`](docs/spec.md). What follows is a condensed reference.\n\n### File Structure\n\nA DESIGN.md file has two layers:\n\n1. **YAML front matter** — Machine-readable design tokens, delimited by `---` fences at the top of the file.\n2. **Markdown body** — Human-readable design rationale organized into `##` sections.\n\nThe tokens are the normative values. The prose provides context for how to apply them.\n\n### Token Schema\n\n```yaml\nversion: <string>          # optional, current: \"alpha\"\nname: <string>\ndescription: <string>      # optional\ncolors:\n  <token-name>: <Color>\ntypography:\n  <token-name>: <Typography>\nrounded:\n  <scale-level>: <Dimension>\nspacing:\n  <scale-level>: <Dimension | number>\ncomponents:\n  <component-name>:\n    <token-name>: <string | token reference>\n```\n\n### Token Types\n\n| Type | Format | Example |\n|:-----|:-------|:--------|\n| Color | `#` + hex (sRGB) | `\"#1A1C1E\"` |\n| Dimension | number + unit (`px`, `em`, `rem`) | `48px`, `-0.02em` |\n| Token Reference | `{path.to.token}` | `{colors.primary}` |\n| Typography | object with `fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, `letterSpacing`, `fontFeature`, `fontVariation` | See example above |\n\n### Section Order\n\nSections use `##` headings. They can be omitted, but those present must appear in this order:\n\n| # | Section | Aliases |\n|:--|:--------|:--------|\n| 1 | Overview | Brand & Style |\n| 2 | Colors | |\n| 3 | Typography | |\n| 4 | Layout | Layout & Spacing |\n| 5 | Elevation & Depth | Elevation |\n| 6 | Shapes | |\n| 7 | Components | |\n| 8 | Do's and Don'ts | |\n\n### Component Tokens\n\nComponents map a name to a group of sub-token properties:\n\n```yaml\ncomponents:\n  button-primary:\n    backgroundColor: \"{colors.tertiary}\"\n    textColor: \"{colors.on-tertiary}\"\n    rounded: \"{rounded.sm}\"\n    padding: 12px\n  button-primary-hover:\n    backgroundColor: \"{colors.tertiary-container}\"\n```\n\nValid component properties: `backgroundColor`, `textColor`, `typography`, `rounded`, `padding`, `size`, `height`, `width`.\n\nVariants (hover, active, pressed) are expressed as separate component entries with a related key name.\n\n### Consumer Behavior for Unknown Content\n\n| Scenario | Behavior |\n|:---------|:---------|\n| Unknown section heading | Preserve; do not error |\n| Unknown color token name | Accept if value is valid |\n| Unknown typography token name | Accept as valid typography |\n| Unknown component property | Accept with warning |\n| Duplicate section heading | Error; reject the file |\n\n## CLI Reference\n\n### Installation\n\n```bash\nnpm install @google/design.md\n```\n\nOr run directly:\n\n```bash\nnpx @google/design.md lint DESIGN.md\n```\n\nAll commands accept a file path or `-` for stdin. Output defaults to JSON.\n\n### `lint`\n\nValidate a DESIGN.md file for structural correctness.\n\n```bash\nnpx @google/design.md lint DESIGN.md\nnpx @google/design.md lint --format json DESIGN.md\ncat DESIGN.md | npx @google/design.md lint -\n```\n\n| Option | Type | Default | Description |\n|:-------|:-----|:--------|:------------|\n| `file` | positional | required | Path to DESIGN.md (or `-` for stdin) |\n| `--format` | `json` | `json` | Output format |\n\nExit code `1` if errors are found, `0` otherwise.\n\n### `diff`\n\nCompare two DESIGN.md files and report token-level changes.\n\n```bash\nnpx @google/design.md diff DESIGN.md DESIGN-v2.md\n```\n\n| Option | Type | Default | Description |\n|:-------|:-----|:--------|:------------|\n| `before` | positional | required | Path to the \"before\" DESIGN.md |\n| `after` | positional | required | Path to the \"after\" DESIGN.md |\n| `--format` | `json` | `json` | Output format |\n\nExit code `1` if regressions are detected (more errors or warnings in the \"after\" file).\n\n### `export`\n\nExport DESIGN.md tokens to other formats.\n\n```bash\nnpx @google/design.md export --format json-tailwind DESIGN.md > tailwind.theme.json\nnpx @google/design.md export --format css-tailwind DESIGN.md > theme.css\nnpx @google/design.md export --format dtcg DESIGN.md > tokens.json\n```\n\n| Option | Type | Default | Description |\n|:-------|:-----|:--------|:------------|\n| `file` | positional | required | Path to DESIGN.md (or `-` for stdin) |\n| `--format` | `json-tailwind` \\| `css-tailwind` \\| `tailwind` \\| `dtcg` | required | Output format |\n\n| Format | Output | Description |\n|:-------|:-------|:------------|\n| `json-tailwind` | JSON | Tailwind v3 `theme.extend` config object |\n| `css-tailwind` | CSS | Tailwind v4 `@theme { ... }` block with CSS custom properties |\n| `tailwind` | JSON | Alias for `json-tailwind` |\n| `dtcg` | JSON | W3C Design Tokens Format Module |\n\n### `spec`\n\nOutput the DESIGN.md format specification (useful for injecting spec context into agent prompts).\n\n```bash\nnpx @google/design.md spec\nnpx @google/design.md spec --rules\nnpx @google/design.md spec --rules-only --format json\n```\n\n| Option | Type | Default | Description |\n|:-------|:-----|:--------|:------------|\n| `--rules` | boolean | `false` | Append the active linting rules table |\n| `--rules-only` | boolean | `false` | Output only the linting rules table |\n| `--format` | `markdown` \\| `json` | `markdown` | Output format |\n\n## Linting Rules\n\nThe linter runs seven rules against a parsed DESIGN.md. Each rule produces findings at a fixed severity level.\n\n| Rule | Severity | What it checks |\n|:-----|:---------|:---------------|\n| `broken-ref` | error | Token references (`{colors.primary}`) that don't resolve to any defined token |\n| `missing-primary` | warning | Colors are defined but no `primary` color exists — agents will auto-generate one |\n| `contrast-ratio` | warning | Component `backgroundColor`/`textColor` pairs below WCAG AA minimum (4.5:1) |\n| `orphaned-tokens` | warning | Color tokens defined but never referenced by any component |\n| `token-summary` | info | Summary of how many tokens are defined in each section |\n| `missing-sections` | info | Optional sections (spacing, rounded) absent when other tokens exist |\n| `missing-typography` | warning | Colors are defined but no typography tokens exist — agents will use default fonts |\n| `section-order` | warning | Sections appear out of the canonical order defined by the spec |\n\n### Programmatic API\n\nThe linter is also available as a library:\n\n```typescript\nimport { lint } from '@google/design.md/linter';\n\nconst report = lint(markdownString);\n\nconsole.log(report.findings);       // Finding[]\nconsole.log(report.summary);        // { errors, warnings, info }\nconsole.log(report.designSystem);   // Parsed DesignSystemState\n```\n\n## Design Token Interoperability\n\nDESIGN.md tokens are inspired by the [W3C Design Token Format](https://www.designtokens.org/). The `export` command converts tokens to other formats:\n\n- **Tailwind v3 config (JSON)** — `npx @google/design.md export --format json-tailwind DESIGN.md` — emits a `theme.extend` JSON object for `tailwind.config.js`. `--format tailwind` is a backwards-compatible alias.\n- **Tailwind v4 theme (CSS)** — `npx @google/design.md export --format css-tailwind DESIGN.md` — emits a CSS `@theme { ... }` block using Tailwind v4's CSS-variable token namespaces.\n- **DTCG tokens.json** ([W3C Design Tokens Format Module](https://tr.designtokens.org/format/)) — `npx @google/design.md export --format dtcg DESIGN.md`\n\n## Status\n\nThe DESIGN.md format is at version `alpha`. The spec, token schema, and CLI are under active development. Expect changes to the format as it matures.\n\n## Disclaimer\n\nThis project is not eligible for the [Google Open Source Software Vulnerability\nRewards Program](https://bughunters.google.com/open-source-security).","readmeFilename":"README.md"}