Designesy README
The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Designesy listing page.
Designesy
designesy.org — design-system contract verification, scoring, and review tools for AI agents.
Quick Start
Score any URL in 5 seconds — no install:
Add to Claude Desktop, Cursor, or any MCP client:
Clone this repo? The .mcp.json at root auto-registers the server in Cursor and Claude Code — just open the project.
Gate your CI on design-contract compliance:
The same 42-check engine powers an MCP server (17 tools for AI agents), a zero-dependency CLI (npx designesy-score), a GitHub Action, and a live leaderboard at designesy.org/leaderboard.
Designesy Contract Check is a GitHub Action that scores any URL against a 42-check design-system contract — tokens, motion, accessibility, cadence, takt, poise, identity, interaction, performance, responsive, semantic, security, spec, copywriting — and fails your CI workflow when the score or grade drops below your threshold. No LLM, no heuristics, no vibe-tax: every check is deterministic, reproducible, and grounded in a published contract.
Tools
designesy_score— Score a live URL against the 42-check design contract. Returns score, grade (A–F), and per-check breakdown.designesy_tokens_score— Validate a DTCG design-token file. 10 conformance checks against W3C DTCG 2025.10.designesy_a11y_score— Get the WCAG 2.2 AA accessibility framework and Playwright/axe-core script template.designesy_motion_score— Validate a Lottie animation file. 10 checks against Lottie spec v1.0.1 and §16 motion standards.designesy_contract— Get the design-system contract (tokens, motion, takt, cadence, typography, verification).designesy_catalog— List the 23 published Designesy packages with versions and URLs.designesy_design_review— Get the 8-dimension qualitative design review rubric.designesy_skill_md— Get the contract as an agent-skill-format SKILL.md for Cursor, Claude Code, or Replit.designesy_agent_json— Get the /.well-known/agent.json discovery document.designesy_llms_txt— Get the short /llms.txt agent brief.designesy_llms_full_txt— Get the full /llms-full.txt agent brief with paste-ready prompt.
Tool reference table
| Tool | Description |
|---|---|
designesy_score | Score a live URL against the 42-check design contract — returns score, grade (A–F), per-check breakdown |
designesy_tokens_score | Validate a DTCG design-token file (10 conformance checks, W3C DTCG 2025.10) |
designesy_a11y_score | Get the WCAG 2.2 AA accessibility framework + Playwright/axe-core script template |
designesy_motion_score | Validate a Lottie animation file (10 checks, Lottie spec v1.0.1 + §16 motion standards) |
designesy_contract | Get the design-system contract (tokens, motion, takt, cadence, typography, verification) |
designesy_catalog | List the 23 published Designesy packages with versions and URLs |
designesy_design_review | Get the 8-dimension qualitative design review rubric |
designesy_skill_md | Get the contract as an agent-skill-format SKILL.md (for Cursor/Claude Code/Replit) |
designesy_agent_json | Get the /.well-known/agent.json discovery document |
designesy_llms_txt | Get the short /llms.txt agent brief |
designesy_llms_full_txt | Get the full /llms-full.txt agent brief with paste-ready prompt |
Live
- Site: designesy.org
- MCP endpoint: designesy.org/api/mcp (Streamable HTTP, no auth)
- Score a site: designesy.org/score
- Leaderboard: designesy.org/leaderboard — 30 sites scored
- Methodology: designesy.org/methodology — full 42-check scoring methodology
- Contract: designesy.org/contracts/design-system
- Machine export: designesy.org/contracts/design-system.json
Contract verification
The live site is verified against the design system contract — 40 deterministic checks with provenance back to tokens. Current score: 93% (Grade A) — 36 passed, 0 failed, 0 warned, 1 skipped, 3 manual (browser-only checks; the skip is DESIGN.md not yet served at the site root — see /contracts/design-system). See the methodology page for how the score is computed.
Contract v0.4.0
- 40 verification checks across 14 weighted categories — tokens, motion, accessibility, cadence, takt, poise, identity, interaction, performance, responsive, semantic, security, spec, copywriting
- Copywriting principles (v0.4.0) — 16 UX copy principles + 4 verification checks (button verb phrases, no trailing periods, descriptive link text, no ALL CAPS)
- 10 Non-Negotiable Motion Standards — deliberate easing, explicit properties, opacity entrances, keyboard stillness, no layout animation, touch gating, bounded duration, reduced-motion paths, asymmetric press, no ease-in
- 10 acoustic cues — custom
$type: sound(net-new vs W3C DTCG 2025.10), Cuelume v0.1.0 engine, interaction-only - 9 open tensions — documented, not hidden
- Spring physics — default + momentum tokens via custom
$type: spring - Machine-readable — W3C DTCG 2025.10 format + custom extensions
See the contract page for the full adoption history.
GitHub Action
Gate your CI on design-contract compliance:
Scores a URL via the live /api/score engine and fails the workflow if the score or grade drops below your threshold. Runs on node24, posts PR comments via bare GitHub REST API (zero dependencies). See action/README.md for full usage.
CLI
Score a URL from the command line — for local development, pre-commit hooks, or scripts:
Zero dependencies — Node built-ins only. The --api flag or SCORE_API env var overrides the scoring engine URL (defaults to https://www.designesy.org). See --help for all options.
Repository
This is the controlled public root for Designesy — a Next.js 15 App Router site (React 19, Turbopack, Vercel deploy).
What Designesy is not
Designesy is not a template gallery. Designesy is not a generic AI design tool. Designesy is not a moodboard.
Designesy is a system.
Related tools
- Lyse — 258-check design system health scoring from your codebase (6 axes). Designesy scores any public URL; Lyse scores your repo. Complementary.
- DSAF — 125-criterion LLM-assisted design system maturity audit across 20 categories. Designesy is deterministic URL scoring; DSAF is LLM-assisted maturity assessment. Different layers, same goal.
- axe-core — WCAG accessibility testing. Designesy checks design-contract compliance (tokens, motion, typography) — a different layer. They complement each other.
- Lighthouse — Performance, accessibility, and SEO auditing. Designesy checks design-contract compliance — Lighthouse doesn't know what a design token is.
FAQ
Does it need an API key? No — all 17 tools are read-only. The MCP endpoint is stateless Streamable HTTP with no authentication.
Is it deterministic? Yes. There is no LLM in the scoring loop — every check is deterministic and reproducible. The same URL will always produce the same score.
What does it score against? The Designesy v0.4.0 design-system contract — 42 checks across 14 weighted categories (tokens, motion, accessibility, cadence, takt, poise, identity, interaction, performance, responsive, semantic, security, spec, copywriting).
Can I use it in CI? Yes. The GitHub Action gates your workflow on contract compliance — fail the build if the score drops below your threshold.
Where is the contract published? At designesy.org/contracts/design-system (human-readable) and designesy.org/contracts/design-system.json (machine-readable, W3C DTCG 2025.10).
License
MIT — see LICENSE. The contract is public; the code is open-source under MIT.