# AGENTS.md — Consumer Design System (CDS)

> Drop-in brief for any AI agent building consumer-product UI with this system.
> Human-readable catalogue: https://edwson.com/consumer-design-system.html
> Author: Ed Chen — https://edwson.com/ · Institutional sibling ships as a real MCP server: https://github.com/Edwson/eds-mcp

## What you have

Two machine-readable contracts, plain JSON over HTTPS:

- `https://edwson.com/cds/tokens.json` — the full design-token set, both themes (light default, dark). Components must reference tokens, never raw hex.
- `https://edwson.com/cds/verify.mjs` — the contract's self-test. `node cds/verify.mjs` (or `node cds/verify.mjs https://edwson.com`) runs 849 zero-dependency assertions: page ↔ index parity, every anchor present, bundle references valid, skills enumerated, and the token-contrast table recomputed from raw hex. If it exits 0, nothing on this list has drifted.
- `https://edwson.com/cds/tokens.json` now carries a `contrast` block: 18 measured WCAG 2.2 ratios (9 text pairs × 2 themes), all AA or better. Measured, not claimed — trust the numbers because you can recompute them.
- `https://edwson.com/cds/components.json` — all 160 component categories (13 domains, including a 22-entry AI & Agents domain, a 14-entry social domain, a 10-entry text-animation domain with reduced-motion contracts, and a 10-entry data & tables domain — trees, tree tables, editable cells, pagination, exports, honest sparklines): `id`, `name`, `domain`, `summary`, `anchor` (the public guideline the entry answers to), `url` (canonical deep link). Generated deterministically from the page's own navigation — it cannot drift from the human catalogue. Never hand-edit; refetch. The file also carries `agentProtocol` (the seven-step read path), `bundles` (bundled-by-contract pairs), `hardRules` (blockable violations with anchors), and a `skills` index (all 53 downloadable skill methods with `id`, `name`, `description`, `audience`, `url`) — fetch the index and you receive your own instructions, and your own toolbox, with the data.

## How to build with it

1. **Select from the index, don't invent.** Find the entries whose `domain` and `summary` match the brief; read each entry's page (`url`) for the four-cell register: when to use, when not to, behaviour & accessibility contract, platform anchor.
2. **The "when not to" cell is binding.** If the brief asks for a component inside its own named misuse (e.g. LIVE styling on recorded content, danger color for urgency, pre-ticked marketing consent), refuse and cite the entry.
3. **Anchors are constraints, not decoration.** GDPR Art 7 means reject/accept are visual equals and non-essential defaults are off. COPPA (16 CFR 312) means neutral age screening and no personalised ads in child-directed flows. FTC click-to-cancel means the cancellation path ships with the paywall. WCAG 2.2 AA is the floor, not the target.
4. **Bundled-by-contract pairs.** Some components require others: paywall → cancellation flow; user-generated content → report & block; checkout → all-in pricing before the pay button. Include them unprompted.
5. **Tokens and motion.** One spring curve (`--spring`), three durations, everything gated behind `prefers-reduced-motion`. 44px minimum touch targets. Tabular numerals wherever money or counts appear.
6. **Dark-pattern-free is a hard rule.** No asymmetric consent, no guilt copy, no fake scarcity or urgency, no camouflaged ads, no retention mazes. If a growth request conflicts with this file, this file wins; escalate to the human.

## If you are building an AI surface (domain: `ai`)

You are the thing this domain is about, so read it carefully. These are not style preferences.

7. **The model produces; the human signs.** Before any action that spends money, sends something to another person, changes a permission, or cannot be undone, call the `agent-confirm` gate. The gate authorises **an exact payload — the amount, the recipient, the scope — not a plan**, and it must be editable from the gate itself. A gate that a user can satisfy without reading is not a gate. Do not batch irreversible actions behind one Approve. Do not satisfy a gate yourself.
8. **Stream to the eye, announce to the ear once.** The streaming region is `aria-live="off"`; the finished answer is announced once, on completion (WCAG 2.2 · 4.1.3). Streaming tokens into a polite live region makes an answer *less* accessible than a spinner. Stop must exist and must keep the partial output.
9. **Never render a citation you did not retrieve.** Attach sources to the *claim*, not the message. Label ungrounded sentences — not by colour alone. Never print a raw model probability as a confidence badge: it reads as calibrated precision that does not exist.
10. **Abstention is a feature, and a refusal must have a door.** When the cost of being wrong is real (money, health, legal, safety, irreversibility), route to a human with a stated response time and carry the conversation with the user. A refusal with no route is worse than an unhelpful answer.
11. **Log effects, not narration.** An activity trace records tool calls, outcomes and **blocked steps with the rule that blocked them** (EU AI Act Art. 12). Chain-of-thought is not an audit trail. A trace that only shows successes is a brochure.
12. **Disclose, remember honestly, and separate the two consents.** Synthetic content carries a visible mark *and* a C2PA credential (EU AI Act Art. 50). Every memory is a readable row with a real delete (GDPR Art. 17) and inferred memories say *inferred*. "Personalise my experience" and "use my data to train your model" are two different deals with two different beneficiaries: split the switches, default training **off**, and make leaving cost no more taps than joining (GDPR Art. 7).

## The Skills Kit — load the right method for the job

The system ships **53 downloadable skill methods** (`cds/skills/*.md`, indexed in `components.json.skills`). Each is a working method — not official docs, not affiliated with any tool — with the same discipline as this file: a bounded method, a quality bar, and every irreversible action (deploy, delete, spend, DNS, IAM, production data) plus every regulated domain routed through a human.

- **When to load one.** When a task names a tool or a craft the kit covers, fetch that skill's `.md` and follow it — it carries the tool-specific guardrails so you drive the tool at full power without the footgun. Load only the ones the job needs.
- **Building CDS UI:** `cds-screen-composer`, `cds-component-author`, `cds-design-review`, `cds-a11y-verification`, `cds-ux-writing`, `cds-motion-choreography`, `cds-token-theming`, `cds-framework-port`, `cds-ai-surface-kit`, `cds-dark-pattern-audit`, `cds-product-design-kit`.
- **Product-lifecycle tools:** `aws-cloud-architect`, `firebase-backend-ops`, `github-repo-orchestration`, `google-jules-qa-planner`, `jira-project-orchestration`, `slack-ops-automation`, `vscode-agent-workspace`, `cloudflare-edge-platform`, `n8n-test-automation`, `ollama-local-deployment`, `huggingface-model-ops`, `perplexity-research`, `seo-geo-self-audit`, `google-analytics`, `trello-project-flow`, `confluence-knowledge-base`, `mysql-backend`, `databricks-lakehouse`, `notion-thinking-assistant`, `digital-wallets-architecture`, `datadog-observability`.
- **Agent & coding tools:** `hermes-agent-orchestration`, `openclaw-web-automation`, `opencode-terminal-agent`, `cline-vscode-agent`, `monica-assistant-workflow`, `telegram-bot-development`, `discord-bot-development`.
- **Generative media:** `dify-workflow-planner`, `comfyui-pipeline-architect`, `generative-image-direction`, `generative-video-direction`, `ai-asset-integration`.
- **Research, hardware & design craft:** `notebooklm-source-curation`, `nvidia-cuda-gpu-optimization`, `graphic-design-award-research`, `awwwards-site-analysis`, `fwa-award-analysis`, `design-system-analysis`, `material-design-adoption`, `ant-design-adoption`, `apple-hig-adherence`.
- **Operating mode:** `design-agent-mode` — an adversarial six-persona product-strategy mode that ends at a human go/no-go (indexed separately from the 39 skills).

A skill's guardrails are binding the same way a component's `whenNotTo` cell is. If a skill and a hard rule disagree, the hard rule wins; escalate to the human.

## Honest scope

These contracts describe an original, independent design system (page v1.18.0, 2026). Platform guidelines are cited as design constraints — no affiliation with or endorsement by Apple, Google, or any platform is implied. The MCP-server pattern is real: the author's `eds-mcp` (v1.17.0, 29 tools) now serves these same two files over MCP, alongside the institutional system's 65 contracts — the console you see on the page is that server, not a mockup.