[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-609":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":20,"compositeScore":21,"rankGlobal":10,"rankLanguage":10,"license":22,"archived":23,"fork":23,"defaultBranch":24,"hasWiki":25,"hasPages":23,"topics":26,"createdAt":10,"pushedAt":10,"updatedAt":27,"readmeContent":28,"aiSummary":29,"trendingCount":16,"starSnapshotCount":16,"syncStatus":30,"lastSyncTime":31,"discoverSource":32},609,"design.md","google-labs-code\u002Fdesign.md","google-labs-code","A format specification for describing a visual identity to coding agents. DESIGN.md gives agents a persistent, structured understanding of a design system.","https:\u002F\u002Fstitch.withgoogle.com\u002Fdocs\u002Fdesign-md\u002Fspecification",null,"TypeScript",15657,1472,101,20,0,79,377,3332,366,119.5,"Apache License 2.0",false,"main",true,[],"2026-06-11 04:00:32","# 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\u002Fdesign.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\u002Fdesign.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\u002Fspec.md`](docs\u002Fspec.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: \u003Cstring>          # optional, current: \"alpha\"\nname: \u003Cstring>\ndescription: \u003Cstring>      # optional\ncolors:\n  \u003Ctoken-name>: \u003CColor>\ntypography:\n  \u003Ctoken-name>: \u003CTypography>\nrounded:\n  \u003Cscale-level>: \u003CDimension>\nspacing:\n  \u003Cscale-level>: \u003CDimension | number>\ncomponents:\n  \u003Ccomponent-name>:\n    \u003Ctoken-name>: \u003Cstring | 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\u002Fdesign.md\n```\n\nOn **Windows**, quote the package name if your shell treats `@` specially (PowerShell, some terminals):\n\n```bash\nnpm install \"@google\u002Fdesign.md\"\n```\n\nOr run directly (always resolves from the public npm registry):\n\n```bash\nnpx @google\u002Fdesign.md lint DESIGN.md\n```\n\n#### `npm error ENOVERSIONS` (“No versions available for @google\u002Fdesign.md”)\n\nThe CLI is published as [`@google\u002Fdesign.md` on npm](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002F@google\u002Fdesign.md). `ENOVERSIONS` almost always means npm is not querying the public registry (custom `registry=` in `.npmrc`, a corporate mirror that has not synced this package, or a misconfigured `@google:registry` for the `@google` scope).\n\nCheck your effective registry:\n\n```bash\nnpm config get registry\n```\n\nFor a normal install from the internet it should be `https:\u002F\u002Fregistry.npmjs.org\u002F`. After fixing config, retry with `npm cache clean --force` if a stale 404 was cached.\n\nAll commands accept a file path or `-` for stdin. Output defaults to JSON.\n\n> **Windows tip**: when invoking the CLI directly from a `package.json` script\n> (rather than through `npx`), use the `designmd` alias instead of `design.md`.\n> The `.md` suffix in the original bin name confuses Windows command resolution\n> with the file association for Markdown files. The `designmd` shim resolves to\n> the same entrypoint and works identically across all platforms.\n>\n> ```jsonc\n> \u002F\u002F package.json\n> {\n>   \"scripts\": {\n>     \"design:lint\": \"designmd lint DESIGN.md\"\n>   }\n> }\n> ```\n\n### `lint`\n\nValidate a DESIGN.md file for structural correctness.\n\n```bash\nnpx @google\u002Fdesign.md lint DESIGN.md\nnpx @google\u002Fdesign.md lint --format json DESIGN.md\ncat DESIGN.md | npx @google\u002Fdesign.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\u002Fdesign.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\u002Fdesign.md export --format json-tailwind DESIGN.md > tailwind.theme.json\nnpx @google\u002Fdesign.md export --format css-tailwind DESIGN.md > theme.css\nnpx @google\u002Fdesign.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\u002Fdesign.md spec\nnpx @google\u002Fdesign.md spec --rules\nnpx @google\u002Fdesign.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`\u002F`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\u002Fdesign.md\u002Flinter';\n\nconst report = lint(markdownString);\n\nconsole.log(report.findings);       \u002F\u002F Finding[]\nconsole.log(report.summary);        \u002F\u002F { errors, warnings, info }\nconsole.log(report.designSystem);   \u002F\u002F Parsed DesignSystemState\n```\n\n## Design Token Interoperability\n\nDESIGN.md tokens are inspired by the [W3C Design Token Format](https:\u002F\u002Fwww.designtokens.org\u002F). The `export` command converts tokens to other formats:\n\n- **Tailwind v3 config (JSON)** — `npx @google\u002Fdesign.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\u002Fdesign.md export --format css-tailwind DESIGN.md` — emits a CSS `@theme { ... }` block using Tailwind v4's CSS-variable token namespaces (`--color-*`, `--font-*`, `--text-*`, `--leading-*`, `--tracking-*`, `--font-weight-*`, `--radius-*`, `--spacing-*`).\n- **DTCG tokens.json** ([W3C Design Tokens Format Module](https:\u002F\u002Ftr.designtokens.org\u002Fformat\u002F)) — `npx @google\u002Fdesign.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:\u002F\u002Fbughunters.google.com\u002Fopen-source-security).","DESIGN.md 是一种用于向编码代理描述视觉标识的格式规范，它为代理提供了一个持久且结构化的设计系统理解。该项目的核心功能包括通过结合机器可读的设计令牌（YAML 前置内容）与人类可读的设计原理（Markdown 格式文本），使代理能够准确地获取并理解设计值及其应用方式。适用于需要确保设计一致性、易于维护和更新的设计系统场景中，如企业级应用界面开发或跨团队协作项目。此外，还提供了验证、对比不同版本设计系统的工具，帮助开发者快速定位问题并保持设计的一致性。",2,"2026-06-11 02:38:03","CREATED_QUERY"]