Designesy

Design quality gate for AI-generated UI: score any URL on 44 deterministic checks, A–F grade. Live at designesy.org.

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 in the loop: every check is a published, deterministic rule, so the same page gives the same verdicts.

Related MCP server: art-director-mcp

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

• designesy_drift_score — Score a live URL for UI drift: 12 checks on its custom properties and var() references.

• designesy_readiness_score — Score a URL for AI readiness: 10 probes for machine-readable design artifacts (DTCG tokens, llms.txt, agent.json, an MCP endpoint, DESIGN.md and more).

• designesy_guardrails — Generate a build-contract bundle for coding agents from a site's tokens: DTCG tokens, Stylelint config, AGENTS.md rules, component contract, anti-patterns and DESIGN.md.

• designesy_monitor_score — Re-run the drift checks against earlier snapshots and compute 10 monitor checks; can send a drift-alert email to an address you pass.

• designesy_compare — Diff the tokens of two live URLs: added, removed, renamed, changed values, scale and contrast drift, and the score delta.

• designesy_report — One composite report for a URL (score × 0.5 + drift × 0.3 + readiness × 0.2), with an interactive dashboard in hosts that support MCP Apps.

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

• 19 acoustic cues — custom $type: sound (net-new vs W3C DTCG 2025.10), Cuelume 0.2 engine (MIT), 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.

• 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 page, engine and contract always produce the same verdicts, and the receipt's digest lets anyone check that. A live URL can change between runs, and results are cached for 24 hours.

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.