Design quality gate for AI-generated UI: score any URL on 45 deterministic checks, A–F grade.
io.github.LE-VAI/designesy-org MCP Server
This MCP server scores any provided URL against a real design contract. It runs 42 checks and assigns an A–F grade. Validation includes token checks and motion validation, as described in the server description, and is positioned for design-contract style evaluation workflows.
🛠️ Key Features
42 URL scoring checks
A–F grade output
Token validation
Motion validation
Tooling count: 17 tools
🚀 Use Cases
Verifying design implementations against a “real design contract”
Auditing UI output for token-related issues
Checking motion behavior during design verification
⚡ Developer Benefits
Enables contract-first verification through a scoring workflow
Supports design-system related validation topics (design tokens, WCAG/APCA-related themes listed)
⚠️ Limitations
Scope is limited to “score any URL” workflows and the specific validations mentioned (token + motion).
List the 24 published Designesy packages with versions, URLs, and statuses. Use this to discover what Designesy publishes before fetching a specific contract. When NOT to use: if you already know which package you need, skip this and call designesy_contract directly. Read-only: no side effects. Returns JSON: { package_count, packages[{id, kind, title, version, status, human_url, machine_url}], standing_rules[], machine_exports[] }. No parameters: accepts empty input.
Parameters
No parameters.
Raw schema
{
"type": "object",
"properties": {}
}
designesy_contract
Get the Designesy design-system contract: the canonical tokens, motion, acoustic, takt, cadence, typography, components, and verification rules that define what the Designesy org considers legitimate design. Use this when you need the actual contract values (token names and values, motion timings, accessibility rules) to author, check, or bind a design. When NOT to use: for a pass/fail score of a live site, use designesy_score; for an agent-skill-format export, use designesy_skill_md. Read-only; cached ~24h server-side. Returns the full contract JSON, or a single section when "section" is provided. Pass section to get one slice (e.g. "motion" for just the motion tokens) instead of the full contract, which saves tokens when you only need one dimension.
Parameters1
section
string
optional
Optional: filter to a specific contract section (colors, motion, acoustic, typography, takt, cadence, verification, open_tensions, components, interaction).
Get the Designesy Design Review framework: an 8-dimension rubric (Purpose, Clarity, Context, Inclusion, System coherence, Durability, Delight, Responsibility) plus the agent prompt, output format, and verification checklist for a qualitative design critique. Use this when you want a structured rubric to critique a design holistically, rather than a numeric compliance score. When NOT to use: for a deterministic numeric score, use designesy_score; this tool gives you a rubric, not a number. Read-only: returns the rubric + prompt. The calling agent performs the actual critique (this tool does not evaluate the design for you). Returns JSON: { rubric, dimensions[8], agent_prompt, output_format, verification_checklist }. Pass artifact/purpose/context/rules to get a pre-filled critique prompt; omit all four to get the blank framework.
Parameters4
artifact
string
optional
URL or description of the artifact to review.
purpose
string
optional
What the design is trying to make possible.
context
string
optional
Audience, device, environment, and constraints.
rules
string
optional
Governing rules or contract version (default: designesy design system v0.4.2).
Raw schema
{
"type": "object",
"properties": {
"artifact": {
"description": "URL or description of the artifact to review.",
"type": "string"
},
"purpose": {
"description": "What the design is trying to make possible.",
"type": "string"
},
"context": {
"description": "Audience, device, environment, and constraints.",
"type": "string"
},
"rules": {
"description": "Governing rules or contract version (default: designesy design system v0.4.2).",
"type": "string"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}
designesy_skill_md
Get the Designesy SKILL.md: the agent-skill-format export of the design-system contract, written as behavioral rules an AI coding agent can drop into .agents/skills/ or a system prompt. Use this when you want the contract in a form that steers how an agent *builds* UI (tokens, anti-patterns, behavioral rules, verification). When NOT to use: for the raw contract JSON, use designesy_contract; for scoring, use designesy_score. Read-only: no side effects. Returns markdown text (SKILL.md format) to drop into .agents/skills/ or paste into a system prompt. No parameters.
Parameters
No parameters.
Raw schema
{
"type": "object",
"properties": {}
}
designesy_agent_json
Get the Designesy agent discovery document (/.well-known/agent.json): the org identity, authority, ingest protocol, package index, machine-export list, permission policy, and citation templates. Use this when you are integrating with or enumerating Designesy as a machine agent and need the canonical discovery/manifest endpoint rather than one specific contract. When NOT to use: for the package list, use designesy_catalog (lighter); for the contract, use designesy_contract. Read-only: no side effects. Returns the /.well-known/agent.json object: { identity, authority, ingest_protocol, package_index, permission_policy, citation_templates }. No parameters.
Parameters
No parameters.
Raw schema
{
"type": "object",
"properties": {}
}
designesy_llms_txt
Get the Designesy /llms.txt: a short agent-facing brief with the canonical reference, topic index, ingest steps, package list, and contact. Use this first when you don't know what Designesy is; it's the cheapest orientation path before pulling heavier artifacts. When NOT to use: for the full expanded brief, use designesy_llms_full_txt; for the contract itself, use designesy_contract. Read-only: no side effects. Returns text/plain (~500 tokens). No parameters.
Parameters
No parameters.
Raw schema
{
"type": "object",
"properties": {}
}
designesy_llms_full_txt
Get the Designesy /llms-full.txt, the complete agent-facing brief: ingest protocol, discovery endpoints, every package, standing rules, anti-patterns, and a paste-ready agent prompt. Use this for comprehensive onboarding to the Designesy ecosystem when the short /llms.txt is not enough. When NOT to use: for a quick orientation, use designesy_llms_txt first (~500 tokens vs ~3000). Read-only: no side effects. Returns text/plain (~3000 tokens, includes a paste-ready agent prompt). No parameters.
Parameters
No parameters.
Raw schema
{
"type": "object",
"properties": {}
}
designesy_score
Score a live URL against the Designesy design contract: a deterministic 42-check verification engine that returns a numeric score, letter grade (A-F), and per-check breakdown. Use this to audit whether a website or AI-generated UI complies with a real design contract (tokens, motion, accessibility, cadence, takt, typography, copywriting). When NOT to use: for token-file validation only, use designesy_tokens_score; for a Lottie file, use designesy_motion_score; for a qualitative critique, use designesy_design_review. Executable: fetches the URL server-side, extracts CSS, runs 42 checks. Results cached ~24h per URL. Checks needing a live browser (Core Web Vitals, sound toggle, overflow) return MANUAL (not FAIL); run the full audit (/api/score/audit) to resolve them. Checks that are not applicable to the site (no tokens, no buttons, no DESIGN.md) return SKIP (N/A). Returns JSON: { url, score (0-100), grade (A-F), pass_count, fail_count, checks[{id, name, status, weight, category}] }. Pass format="canonical" for review-findings.json schema, "review" for markdown, or "google" for design.md-compatible output.
Parameters1
url
string
optional
URL to score. Defaults to https://www.designesy.org/ if not provided.
Raw schema
{
"type": "object",
"properties": {
"url": {
"description": "URL to score. Defaults to https://www.designesy.org/ if not provided.",
"type": "string"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}
designesy_tokens_score
Validate a design token file against the W3C Design Tokens Community Group (DTCG) 2025.10 Final Community Group Report (the spec's first stable version, published Oct 28 2025 as a Candidate Recommendation and considered stable). Returns 10 conformance checks (t01-t10) with PASS/FAIL/WARN. Use this to verify a tokens.json (or any DTCG token export) is structurally correct: $type/$value/$description present, structured colors (colorSpace + components rather than bare hex), a valid $schema pointer to designtokens.org, and correct dimension units. With 84% of teams now using design tokens (zeroheight Design Systems Report 2025, up from 56% in 2024) and the spec finally stable, every adopting team needs a validator. When NOT to use: for scoring a whole live site (not just its token file), use designesy_score. Executable: fetches the URL or parses the raw JSON you provide, runs 10 checks server-side. No browser needed. Returns JSON: { checks[{id (t01-t10), name, status (PASS/FAIL/WARN), detail}], valid, score }. Pass url to fetch a remote token file, or dtcg_file to validate an inline JSON string. Provide exactly one.
Parameters2
url
string
optional
URL to a DTCG token file (JSON). The tool fetches and validates it.
dtcg_file
string
optional
Raw DTCG token JSON string to validate (alternative to url).
Raw schema
{
"type": "object",
"properties": {
"url": {
"description": "URL to a DTCG token file (JSON). The tool fetches and validates it.",
"type": "string"
},
"dtcg_file": {
"description": "Raw DTCG token JSON string to validate (alternative to url).",
"type": "string"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}
designesy_a11y_score
Get the Designesy WCAG 2.2 AA accessibility verification framework: 11 conformance checks (a01-a11) plus a ready-to-run Playwright + axe-core 4.13.0 script template targeting your URL. Use this to audit a site for accessibility violations. When NOT to use: for a full design-contract score (not just a11y), use designesy_score. Does NOT run the scan: axe-core needs a real browser DOM. Returns the 11 checks + a Playwright script you execute locally (npm i -D @axe-core/playwright). The score comes from your local run, not from this tool. Returns JSON: { checks[{id (a01-a11), name, status: "PENDING_EXECUTION"}], playwright_script, install_command, run_command }. Pass config (JSON string) to customize axe.configure(), for example with branding overrides or rule disables. Omit for standard WCAG 2.2 AA.
Parameters3
url
string
required
URL to scan for accessibility. The returned script template will target this URL.
ruleset
string
optional
Ruleset tag (default: wcag22aa). Options: wcag2a, wcag2aa, wcag21aa, wcag22aa, best-practice.
config
string
optional
Brand customization JSON for axe.configure(): branding, checks, rules, disableOtherRules.
Raw schema
{
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "URL to scan for accessibility. The returned script template will target this URL."
},
"ruleset": {
"description": "Ruleset tag (default: wcag22aa). Options: wcag2a, wcag2aa, wcag21aa, wcag22aa, best-practice.",
"type": "string"
},
"config": {
"description": "Brand customization JSON for axe.configure(): branding, checks, rules, disableOtherRules.",
"type": "string"
}
},
"required": [
"url"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}
designesy_motion_score
Validate a Lottie animation file against the Lottie spec v1.0.1 and the Designesy §16 Ten Non-Negotiable Motion Standards, returning 10 checks (m01-m10) with PASS/FAIL/WARN. The DTCG 2025.10 spec leaves motion tokens as a second-class citizen: there is no standard for motion token structure, reduced-motion markers, or animation accessibility. Designesy's motion validator fills this gap: it checks required fields (v, fr, ip, op, w, h, layers), $version, a markers array for reduced-motion compliance, and no deprecated version. Use this to verify a motion/animation asset is well-formed AND accessible: the only validator that checks both. When NOT to use: for full-site motion scoring (not a single Lottie file), use designesy_score. Executable: fetches the URL or parses the raw Lottie JSON, runs 10 checks server-side. No browser needed. Returns JSON: { checks[{id (m01-m10), name, status (PASS/FAIL/WARN), detail}], valid, score }. Pass url to fetch a remote Lottie file, or lottie_file to validate an inline JSON string. Provide exactly one.
Parameters2
url
string
optional
URL to a Lottie JSON file. The tool fetches and validates it.
lottie_file
string
optional
Raw Lottie JSON string to validate (alternative to url).
Raw schema
{
"type": "object",
"properties": {
"url": {
"description": "URL to a Lottie JSON file. The tool fetches and validates it.",
"type": "string"
},
"lottie_file": {
"description": "Raw Lottie JSON string to validate (alternative to url).",
"type": "string"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}
designesy_drift_score
Score a live URL for AI-generated UI drift. Its 12 checks detect the four documented 2026 drift failure modes: token fabrication (var() to undeclared custom properties), within-session drift (spacing/color/radius value variance), between-session amnesia (inconsistent font stacks, shadows, transitions), and silent breaking changes (z-index chaos, dangling alias chains). Use this when you need to verify whether a site (especially an AI-generated one) is drifting off its own declared token system. When NOT to use: for a full 42-check design-contract score, use designesy_score; for token-file format validation, use designesy_tokens_score. Executable: fetches the URL server-side, extracts all CSS (inline + linked stylesheets), parses :root custom properties and var() references, runs 12 drift checks. No browser needed. Returns JSON: { ok, url, score (0-100), grade (A-F), pass, warn, fail, total, tokensExtracted, checks[{id, item, category, status, detail}] }. Results cached ~24h per URL.
Parameters1
url
string
optional
URL to scan for drift. Defaults to https://www.designesy.org/ if not provided.
Raw schema
{
"type": "object",
"properties": {
"url": {
"description": "URL to scan for drift. Defaults to https://www.designesy.org/ if not provided.",
"type": "string"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}
designesy_readiness_score
Score a URL for design-system AI readiness, the 6th maturity axis (zeroheight 2026). 10 checks probe the target origin for machine-readable artifacts: DTCG token files, llms.txt, agent.json, MCP endpoint (tools/list), DESIGN.md, token $description, component schemas, sitemap.xml, robots.txt, and Open Graph/Twitter meta. Use this to verify whether a design system is the default context AI tools build from, or whether AI is silently working around it. When NOT to use: for full design-contract scoring, use designesy_score; for AI-drift detection, use designesy_drift_score. Executable: fetches the URL and probes the origin via HEAD/GET for each artifact. No browser needed. Returns JSON: { ok, url, score (0-100), grade (A-F), pass, warn, fail, total, checks[{id, item, category, status, detail}] }. Results cached ~24h per URL.
Parameters1
url
string
optional
URL to score for AI readiness. Defaults to https://www.designesy.org/ if not provided.
Raw schema
{
"type": "object",
"properties": {
"url": {
"description": "URL to score for AI readiness. Defaults to https://www.designesy.org/ if not provided.",
"type": "string"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}
designesy_guardrails
Generate a frozen build-contract bundle for AI coding agents from any design system URL (the product layer). Ingests a site, extracts its :root tokens, and emits 6 outputs: (1) DTCG-format token file, (2) Stylelint config generated from token values, (3) AGENTS.md-format rules with token allowlist, (4) component contract with allowed prop patterns, (5) anti-pattern documentation, (6) DESIGN.md file (Google open spec, google-labs-code/design.md), the de-facto AI-readable design-context standard: YAML front matter plus a markdown body. Use this when you need to turn a design system into the file AI agents read and the lint that enforces it. When NOT to use: for design-contract scoring, use designesy_score; for token-file validation, use designesy_tokens_score; for drift detection, use designesy_drift_score. Executable: fetches the URL, extracts CSS + :root custom properties, generates the bundle. No browser needed. Returns JSON: { ok, url, score (0-100, emission completeness), grade, pass, warn, fail, total, tokensExtracted, bundle: { tokens, lintConfig, agentRules, componentContract, antiPatterns, designMd }, checks[{id, item, category, status, detail}] }. Results cached ~24h per URL.
Parameters1
url
string
optional
URL to generate guardrails for. Defaults to https://www.designesy.org/ if not provided.
Raw schema
{
"type": "object",
"properties": {
"url": {
"description": "URL to generate guardrails for. Defaults to https://www.designesy.org/ if not provided.",
"type": "string"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}
designesy_monitor_score
Score a URL for continuous design-drift governance, the temporal layer over the drift radar. Re-runs the 12 drift checks (d01-d12) on the URL and computes 10 monitor checks (m01-m10): schedule registered, last run fresh, drift delta vs baseline, trend slope (3-run trajectory), new violations since last run, resolved since last run (the healing signal), score degradation threshold, token-set mutation, contract version drift, and alert delivered. When alerts fire and an email address is provided, sends an HTML drift-alert email via Resend (requires RESEND_API_KEY env var). Pass a history array of prior snapshots to compute deltas; omit it for a first-run baseline. Use this to watch a design system over time: "weekly audits at cents per report" (Into Design Systems 2026). When NOT to use: for a single point-in-time drift check, use designesy_drift_score; for design-contract scoring, use designesy_score. Executable: fetches the URL, extracts CSS + :root tokens, runs checks, computes deltas. No browser needed. Returns JSON: { ok, url, score (0-100, governance health), grade (A-F), pass, warn, fail, total, currentSnapshot, baseline, previous, driftChecks, monitorChecks, alerts, emailAlert }. Results cached ~24h per URL.
Parameters3
url
string
optional
URL to monitor for drift. Defaults to https://www.designesy.org/ if not provided.
email
string
optional
Email address to receive drift alerts. When alerts fire AND this is provided AND RESEND_API_KEY is set, an HTML alert email is sent. Optional: without it, alerts surface in-UI only.
history
array
optional
Prior snapshots for delta computation. Omit for a first-run baseline.
Raw schema
{
"type": "object",
"properties": {
"url": {
"description": "URL to monitor for drift. Defaults to https://www.designesy.org/ if not provided.",
"type": "string"
},
"email": {
"description": "Email address to receive drift alerts. When alerts fire AND this is provided AND RESEND_API_KEY is set, an HTML alert email is sent. Optional: without it, alerts surface in-UI only.",
"type": "string"
},
"history": {
"description": "Prior snapshots for delta computation. Omit for a first-run baseline.",
"type": "array",
"items": {
"type": "object",
"properties": {
"timestamp": {
"type": "string"
},
"score": {
"type": "number"
},
"grade": {
"type": "string"
},
"tokensExtracted": {
"type": "number"
},
"checks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"item": {
"type": "string"
},
"category": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"PASS",
"FAIL",
"WARN"
]
},
"detail": {
"type": "string"
}
},
"required": [
"id",
"item",
"category",
"status",
"detail"
]
}
}
},
"required": [
"timestamp",
"score",
"grade",
"tokensExtracted",
"checks"
]
}
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}
designesy_compare
Diff two design systems from live URLs, using the only URL-scoped design-token diff engine. Fetches both URLs in parallel, extracts their :root custom properties, and produces a structured diff across 8 dimensions: tokens added (in A not B), removed (in B not A), renamed (heuristic Levenshtein ≤ 2), value-changed (same name, different value), scale-stop-changed (spacing/radius/color scale steps), contrast-drift-per-pair (WCAG contrast ratio change for shared color tokens), structure-delta (token count + category distribution), and score-delta (runs /score on both URLs and diffs). Use this to answer "what actually changed between two design systems" or "how does our design system differ from a reference". When NOT to use: for single-site drift detection, use designesy_drift_score; for continuous monitoring, use designesy_monitor_score. Executable: fetches both URLs, extracts CSS + tokens, computes diff. No browser needed. Returns JSON: { ok, urlA, urlB, score (0-100, diff completeness), grade, pass, warn, fail, total, tokensA, tokensB, added[], removed[], renamed[], valueChanged[], scaleDiff, structureDelta, contrastDrift[], scoreDelta, checks[] }. Results cached ~24h per URL pair.
Parameters2
urlA
string
required
First URL to compare (e.g. your design system).
urlB
string
required
Second URL to compare (e.g. a reference or competitor).
Raw schema
{
"type": "object",
"properties": {
"urlA": {
"type": "string",
"description": "First URL to compare (e.g. your design system)."
},
"urlB": {
"type": "string",
"description": "Second URL to compare (e.g. a reference or competitor)."
}
},
"required": [
"urlA",
"urlB"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}
designesy_report
Generate a unified design-intelligence report for a single URL, the synthesis capstone. Fires /score (42-check audit), /drift (12-check drift radar), and /readiness (10-check AI readiness) in parallel, then computes a weighted composite: score × 0.5 + drift × 0.3 + readiness × 0.2. One input, one output, one composite grade. Use this when you need a single holistic assessment instead of three separate scans, or when sharing a design-intelligence verdict (the report is the most shareable surface). When NOT to use: for just the audit score, use designesy_score; for just drift, use designesy_drift_score; for just AI readiness, use designesy_readiness_score. Executable: fires 3 internal APIs in parallel, each fetches the target URL. No browser needed. Returns JSON: { ok, url, compositeScore (0-100), compositeGrade (A-F), score { sub-result }, drift { sub-result }, readiness { sub-result }, totalChecks, totalPass, totalWarn, totalFail, totalSkip, checks[] (all checks across all engines, tagged with engine), synthesis[] (8 synthesis checks verifying the report ran correctly), appUrl (standalone interactive dashboard URL) }. Results cached ~24h per URL. MCP Apps: hosts that support io.modelcontextprotocol/ui render an interactive dashboard inline; others get the JSON plus an appUrl link.
Parameters1
url
string
required
Public URL to generate a design-intelligence report for.
A 12-second loop, recorded from the homepage. It plays once and rests on the verdict, and shows a still frame if you prefer reduced motion. Watch it run on designesy.org.
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:
bash
npx @designesy/score@latest https://your-site.com
Add to Claude Desktop, Cursor, or any MCP client:
bash
# 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:
yaml
-uses:LE-VAI/designesy-org@v1with:url:https://your-app.vercel.appmin-score:70min-grade:Bpost-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
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.
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:
yaml
-uses:LE-VAI/designesy-org@v1with:url:https://your-app.vercel.appmin-score:70min-grade:Cpost-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:
bash
# 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).
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.
