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 40-check engine powers an MCP server (11 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 40-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 40-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 12 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

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 40-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: 99.2% (Grade A) — 35 passed, 0 failed, 1 warn, 4 skipped (browser-only checks). 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:

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

FAQ

Does it need an API key? No — all 11 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 — 40 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.