{"id":49401118,"url":"https://github.com/google-labs-code/design.md","last_synced_at":"2026-04-30T08:03:46.200Z","repository":{"id":352903848,"uuid":"1207222725","full_name":"google-labs-code/design.md","owner":"google-labs-code","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-21T17:34:51.000Z","size":190,"stargazers_count":96,"open_issues_count":0,"forks_count":10,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-21T17:41:43.866Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/google-labs-code.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-10T17:54:59.000Z","updated_at":"2026-04-21T17:41:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/google-labs-code/design.md","commit_stats":null,"previous_names":["google-labs-code/design.md"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/google-labs-code/design.md","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google-labs-code%2Fdesign.md","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google-labs-code%2Fdesign.md/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google-labs-code%2Fdesign.md/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google-labs-code%2Fdesign.md/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/google-labs-code","download_url":"https://codeload.github.com/google-labs-code/design.md/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google-labs-code%2Fdesign.md/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32458241,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T22:27:22.272Z","status":"online","status_checked_at":"2026-04-30T02:00:05.929Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-28T18:00:34.915Z","updated_at":"2026-04-30T08:03:46.194Z","avatar_url":"https://github.com/google-labs-code.png","language":"TypeScript","funding_links":[],"categories":["TypeScript","Configuration \u0026 Rules","Design Primitives","10x your design","DESIGN.md by Aesthetic Family"],"sub_categories":["Context Delivery \u0026 Compaction","External catalogs"],"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: \u003cstring\u003e          # optional, current: \"alpha\"\nname: \u003cstring\u003e\ndescription: \u003cstring\u003e      # optional\ncolors:\n  \u003ctoken-name\u003e: \u003cColor\u003e\ntypography:\n  \u003ctoken-name\u003e: \u003cTypography\u003e\nrounded:\n  \u003cscale-level\u003e: \u003cDimension\u003e\nspacing:\n  \u003cscale-level\u003e: \u003cDimension | number\u003e\ncomponents:\n  \u003ccomponent-name\u003e:\n    \u003ctoken-name\u003e: \u003cstring | token reference\u003e\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 \u0026 Style |\n| 2 | Colors | |\n| 3 | Typography | |\n| 4 | Layout | Layout \u0026 Spacing |\n| 5 | Elevation \u0026 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 (tailwind, dtcg).\n\n```bash\nnpx @google/design.md export --format tailwind DESIGN.md \u003e tailwind.theme.json\nnpx @google/design.md export --format dtcg DESIGN.md \u003e tokens.json\n```\n\n| Option | Type | Default | Description |\n|:-------|:-----|:--------|:------------|\n| `file` | positional | required | Path to DESIGN.md (or `-` for stdin) |\n| `--format` | `tailwind` \\| `dtcg` | required | Output format |\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 theme config** — `npx @google/design.md export --format tailwind DESIGN.md`\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).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoogle-labs-code%2Fdesign.md","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgoogle-labs-code%2Fdesign.md","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoogle-labs-code%2Fdesign.md/lists"}