Designesy

designesy.org — design-system contract verification, scoring, and review tools for AI agents.

Quick Start

Score any URL in 5 seconds — no install:

npx @designesy/score@latest https://your-site.com

Add to Claude Desktop, Cursor, or any MCP client:

# Remote (zero install, no auth):
claude mcp add designesy --transport http https://www.designesy.org/api/mcp

# Or local stdio via PyPI:
pip install designesy-mcp && designesy-mcp

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:

- uses: LE-VAI/designesy-org@v1
  with:
    url: https://your-app.vercel.app
    min-score: 70
    min-grade: B
    post-comment: true   # posts a summary comment on PRs (default)

The same 44-check engine powers an MCP server (17 tools for AI agents), a CLI with no required dependencies (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 44-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 44-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), whole or only the top-level sections you name.
• designesy_catalog — List the published Designesy packages with versions and URLs (the count comes back in package_count).
• 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 brief as reference data (its ingest steps and paste-ready agent prompt stay in the published file).

Tool reference table

Tool	Description
designesy_score	Score a live URL against the 44-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), whole or only the top-level sections you name
designesy_catalog	List the 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 brief as reference data (its ingest steps and paste-ready agent prompt stay in the published file)

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 44-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 — 44 deterministic checks with provenance back to tokens. Both badges read the live leaderboard, which the weekly re-score refreshes, so the score here cannot drift from the engine; the per-check result is on the score page. See the methodology page for how the score is computed.

The contract

• 44 verification checks across 14 weighted categories — tokens, motion, accessibility, cadence, takt, poise, identity, interaction, performance, responsive, semantic, security, spec, copywriting
• Copywriting principles (added in 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:

- uses: LE-VAI/designesy-org@v1
  with:
    url: https://your-app.vercel.app
    min-score: 70
    min-grade: C
    post-comment: true   # posts a summary comment on PRs (default)

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:

# Local (no install needed):
node cli/designesy-score.mjs designesy.org

# With gating (exit 1 on failure):
node cli/designesy-score.mjs linear.app --min-score 70 --min-grade B

# JSON output for piping:
node cli/designesy-score.mjs vercel.com --format canonical --json

# Via npm script:
npm run score -- designesy.org

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).

apps/site          Next.js application
action/            designesy/contract-check GitHub Action
cli/               designesy-score CLI
docs/designesy     context, architecture, logs, registries
DESIGN.md          the design contract (human-readable)
AGENTS.md          agent operating rules

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. The MCP endpoint is stateless Streamable HTTP with no authentication. Sixteen of the 17 tools are read-only; designesy_monitor_score can send a drift-alert email to an address you pass.

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 current Designesy design-system contract — 44 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.