How do I install Designesy?

Copy the http config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Designesy need an API key?

No required environment variable is listed on this record.

What transport does Designesy use?

Designesy is reached over HTTP.

When was Designesy last checked?

Last checked 2026-10-16. Score any URL against a real design contract — 44 checks, A-F grade, token + motion validation.

Designesy MCP server

Designesy

Design quality gate for AI-generated UI: score any URL on 45 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:

# Claude Code, remote (zero install, no auth):
claude mcp add --transport http designesy 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 adds the local server (uvx designesy-mcp) to Claude Code as a project server. Claude Code asks you to approve it the first time you open the project. It needs uv.

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)

The same 45-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 45-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.

Tools

designesy_score — Score a live URL against the 45-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

Tool	Description
`designesy_score`	Score a live URL against the 45-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)
`designesy_drift_score`	Score a live URL for UI drift (12 checks on custom properties and var() references)
`designesy_readiness_score`	Score a URL for AI readiness (10 probes for machine-readable design artifacts)
`designesy_guardrails`	Generate a build-contract bundle for coding agents from a site's tokens (6 files)
`designesy_monitor_score`	Re-run drift checks against earlier snapshots; 10 monitor checks; optional drift-alert email
`designesy_compare`	Diff the tokens of two live URLs, with the score delta
`designesy_report`	Composite report for one URL (score, drift, readiness), with an MCP App dashboard

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

45 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 cue tokens — custom $type: sound (net-new vs W3C DTCG 2025.10), Cuelume 0.2 engine (MIT), interaction-only. The acoustic token document adds 9 extended feedback cues, 19 in all
10 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:

# No install needed:
npx @designesy/score designesy.org

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

# JSON output for piping:
npx @designesy/score vercel.com --format canonical --json

No required dependencies. The engine runs locally, with no Designesy server; the checks that need a browser return MANUAL. See --help for all options and packages/score/README.md for the full reference.

From a clone of this repo: the engine's dist/ folder is not committed, so build it first.

npm --prefix packages/score ci
npm run build:score
node packages/score/dist/cli.js designesy.org

The older cli/designesy-score.mjs (npm run score) reads the same build. It is superseded by @designesy/score. Its --api flag (or the SCORE_API env var) is an opt-in remote fallback that sends the URL to a scoring server instead of scoring locally; it is off by default.

Repository

The site is a Next.js 16 App Router app (React 19, webpack build), deployed on Vercel. The npm packages and the MCP server live beside it.

apps/site                              the site, its API routes (/api/score, /api/mcp) and its build checks (scripts/)
packages/score                         @designesy/score: the scoring engine and CLI (npm)
packages/cli                           @designesy/cli: one CLI for tokens and score (npm)
packages/tokens                        @designesy/tokens: DTCG token validator (npm)
packages/stylelint-plugin-dtcg-tokens  @designesy/stylelint-plugin-dtcg-tokens (npm)
packages/lab-builder                   @designesy/lab-builder (npm)
packages/designesy-mcp                 designesy-mcp: the local stdio MCP server (PyPI)
packages/vai-icons, vai-motion         @vai/icons and @vai/motion (not yet published)
action.yml, action/dist                the Designesy Contract Check GitHub Action
cli/                                   designesy-score, the older CLI (superseded by @designesy/score)
scripts/                               repo-level scripts
docs/designesy                         founding notes from May 2026: mission, architecture, contracts, labs
DESIGN.md                              operating principles and agent rules (v0.1)
AGENTS.md                              agent operating rules

Contract mode, which scores a page against your own DESIGN.md or DTCG token file, is specified in docs/contract-mode-spec.md.

The design contract in DESIGN.md format is generated from the contract source and served at designesy.org/DESIGN.md. The root DESIGN.md file is the older v0.1 charter.

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

Designesy

Design quality gate for AI-generated UI: score any URL on 45 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:

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

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

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)

Tools

designesy_score — Score a live URL against the 45-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

Tool	Description
`designesy_score`	Score a live URL against the 45-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)
`designesy_drift_score`	Score a live URL for UI drift (12 checks on custom properties and var() references)
`designesy_readiness_score`	Score a URL for AI readiness (10 probes for machine-readable design artifacts)
`designesy_guardrails`	Generate a build-contract bundle for coding agents from a site's tokens (6 files)
`designesy_monitor_score`	Re-run drift checks against earlier snapshots; 10 monitor checks; optional drift-alert email
`designesy_compare`	Diff the tokens of two live URLs, with the score delta
`designesy_report`	Composite report for one URL (score, drift, readiness), with an MCP App dashboard

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 45-check scoring methodology
Contract: designesy.org/contracts/design-system
Machine export: designesy.org/contracts/design-system.json

Contract verification

The contract

45 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 cue tokens — custom $type: sound (net-new vs W3C DTCG 2025.10), Cuelume 0.2 engine (MIT), interaction-only. The acoustic token document adds 9 extended feedback cues, 19 in all
10 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)

CLI

Score a URL from the command line — for local development, pre-commit hooks, or scripts:

# No install needed:
npx @designesy/score designesy.org

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

# JSON output for piping:
npx @designesy/score vercel.com --format canonical --json

From a clone of this repo: the engine's dist/ folder is not committed, so build it first.

npm --prefix packages/score ci
npm run build:score
node packages/score/dist/cli.js designesy.org

Repository

The site is a Next.js 16 App Router app (React 19, webpack build), deployed on Vercel. The npm packages and the MCP server live beside it.

apps/site                              the site, its API routes (/api/score, /api/mcp) and its build checks (scripts/)
packages/score                         @designesy/score: the scoring engine and CLI (npm)
packages/cli                           @designesy/cli: one CLI for tokens and score (npm)
packages/tokens                        @designesy/tokens: DTCG token validator (npm)
packages/stylelint-plugin-dtcg-tokens  @designesy/stylelint-plugin-dtcg-tokens (npm)
packages/lab-builder                   @designesy/lab-builder (npm)
packages/designesy-mcp                 designesy-mcp: the local stdio MCP server (PyPI)
packages/vai-icons, vai-motion         @vai/icons and @vai/motion (not yet published)
action.yml, action/dist                the Designesy Contract Check GitHub Action
cli/                                   designesy-score, the older CLI (superseded by @designesy/score)
scripts/                               repo-level scripts
docs/designesy                         founding notes from May 2026: mission, architecture, contracts, labs
DESIGN.md                              operating principles and agent rules (v0.1)
AGENTS.md                              agent operating rules

Contract mode, which scores a page against your own DESIGN.md or DTCG token file, is specified in docs/contract-mode-spec.md.

The design contract in DESIGN.md format is generated from the contract source and served at designesy.org/DESIGN.md. The root DESIGN.md file is the older v0.1 charter.

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

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.

Designesy

Add this server

Host a copy with our keys and logs.

Related MCP

Related skills

Questions

Designesy

Quick Start

Tools

Tool reference table

Live

Contract verification

The contract

GitHub Action

CLI

Repository

What Designesy is not

Related tools

FAQ

License

Designesy

Add this server

Host a copy with our keys and logs.

Related MCP

Related skills

Questions

Designesy

Quick Start

Tools

Tool reference table

Live

Contract verification

The contract

GitHub Action

CLI

Repository

What Designesy is not

Related tools

FAQ

License