{
  "markdown": "# Designesy\n\n[![PyPI](https://img.shields.io/pypi/v/designesy-mcp?label=pypi&color=blue)](https://pypi.org/project/designesy-mcp/)\n[![npm](https://img.shields.io/npm/v/designesy-score?label=npm&color=blue)](https://www.npmjs.com/package/designesy-score)\n[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-io.github.LE--VAI%2Fdesignesy--org-purple)](https://registry.modelcontextprotocol.io/v0.1/servers?search=designesy)\n[![Smithery](https://img.shields.io/badge/Smithery-le--vai%2Fdesignesy-blue)](https://smithery.ai/servers/le-vai/designesy)\n[![Glama](https://glama.ai/mcp/servers/LE-VAI/designesy-org/badges/card.svg)](https://glama.ai/mcp/servers/LE-VAI/designesy-org)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n<picture>\n  <source media=\"(prefers-reduced-motion: reduce)\" srcset=\"apps/site/public/hero-score-gate.png\">\n  <img src=\"apps/site/public/hero-score-gate.gif\" alt=\"Designesy Score Gate — a URL flows in, the 42-check contract grid fires, the score counts up to 93% grade A, and the gate passes\" width=\"1280\">\n</picture>\n\n[designesy.org](https://www.designesy.org) — design-system contract verification, scoring, and review tools for AI agents.\n\n## Quick Start\n\n**Score any URL in 5 seconds — no install:**\n\n```bash\nnpx designesy-score@latest https://your-site.com\n```\n\n**Add to Claude Desktop, Cursor, or any MCP client:**\n\n```bash\n# Remote (zero install, no auth):\nclaude mcp add designesy --transport http https://www.designesy.org/api/mcp\n\n# Or local stdio via PyPI:\npip install designesy-mcp && designesy-mcp\n```\n\n**Clone this repo?** The `.mcp.json` at root auto-registers the server in Cursor and Claude Code — just open the project.\n\n**Gate your CI on design-contract compliance:**\n\n```yaml\n- uses: LE-VAI/designesy-org@v1\n  with:\n    url: https://your-app.vercel.app\n    min-score: 70\n    min-grade: B\n    post-comment: true   # posts a summary comment on PRs (default)\n```\n\nThe same 42-check engine powers an MCP server (17 tools for AI agents), a zero-dependency CLI (`npx designesy-score`), a GitHub Action, and a live leaderboard at [designesy.org/leaderboard](https://www.designesy.org/leaderboard).\n\n**Designesy Contract Check** is a GitHub Action that scores any URL against a **42-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.\n\n## Tools\n\n- `designesy_score` — Score a live URL against the 42-check design contract. Returns score, grade (A–F), and per-check breakdown.\n- `designesy_tokens_score` — Validate a DTCG design-token file. 10 conformance checks against W3C DTCG 2025.10.\n- `designesy_a11y_score` — Get the WCAG 2.2 AA accessibility framework and Playwright/axe-core script template.\n- `designesy_motion_score` — Validate a Lottie animation file. 10 checks against Lottie spec v1.0.1 and §16 motion standards.\n- `designesy_contract` — Get the design-system contract (tokens, motion, takt, cadence, typography, verification).\n- `designesy_catalog` — List the 23 published Designesy packages with versions and URLs.\n- `designesy_design_review` — Get the 8-dimension qualitative design review rubric.\n- `designesy_skill_md` — Get the contract as an agent-skill-format SKILL.md for Cursor, Claude Code, or Replit.\n- `designesy_agent_json` — Get the /.well-known/agent.json discovery document.\n- `designesy_llms_txt` — Get the short /llms.txt agent brief.\n- `designesy_llms_full_txt` — Get the full /llms-full.txt agent brief with paste-ready prompt.\n\n### Tool reference table\n\n| Tool | Description |\n|---|---|\n| `designesy_score` | Score a live URL against the 42-check design contract — returns score, grade (A–F), per-check breakdown |\n| `designesy_tokens_score` | Validate a DTCG design-token file (10 conformance checks, W3C DTCG 2025.10) |\n| `designesy_a11y_score` | Get the WCAG 2.2 AA accessibility framework + Playwright/axe-core script template |\n| `designesy_motion_score` | Validate a Lottie animation file (10 checks, Lottie spec v1.0.1 + §16 motion standards) |\n| `designesy_contract` | Get the design-system contract (tokens, motion, takt, cadence, typography, verification) |\n| `designesy_catalog` | List the 23 published Designesy packages with versions and URLs |\n| `designesy_design_review` | Get the 8-dimension qualitative design review rubric |\n| `designesy_skill_md` | Get the contract as an agent-skill-format SKILL.md (for Cursor/Claude Code/Replit) |\n| `designesy_agent_json` | Get the /.well-known/agent.json discovery document |\n| `designesy_llms_txt` | Get the short /llms.txt agent brief |\n| `designesy_llms_full_txt` | Get the full /llms-full.txt agent brief with paste-ready prompt |\n\n## Live\n\n- **Site:** [designesy.org](https://www.designesy.org)\n- **MCP endpoint:** [designesy.org/api/mcp](https://www.designesy.org/api/mcp) (Streamable HTTP, no auth)\n- **Score a site:** [designesy.org/score](https://www.designesy.org/score)\n- **Leaderboard:** [designesy.org/leaderboard](https://www.designesy.org/leaderboard) — 30 sites scored\n- **Methodology:** [designesy.org/methodology](https://www.designesy.org/methodology) — full 42-check scoring methodology\n- **Contract:** [designesy.org/contracts/design-system](https://www.designesy.org/contracts/design-system)\n- **Machine export:** [designesy.org/contracts/design-system.json](https://www.designesy.org/contracts/design-system.json)\n\n## Contract verification\n\n![Designesy Score](https://img.shields.io/badge/contract%20score-93%25%20A%20grade-brightgreen)\n\nThe live site is verified against the design system contract — 40 deterministic checks with provenance back to tokens. Current score: **93% (Grade A)** — 36 passed, 0 failed, 0 warned, 1 skipped, 3 manual (browser-only checks; the skip is DESIGN.md not yet served at the site root — see [/contracts/design-system](https://www.designesy.org/contracts/design-system)). See the [methodology page](https://www.designesy.org/methodology) for how the score is computed.\n\n## Contract v0.4.0\n\n- **40 verification checks** across 14 weighted categories — tokens, motion, accessibility, cadence, takt, poise, identity, interaction, performance, responsive, semantic, security, spec, copywriting\n- **Copywriting principles** (v0.4.0) — 16 UX copy principles + 4 verification checks (button verb phrases, no trailing periods, descriptive link text, no ALL CAPS)\n- **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\n- **10 acoustic cues** — custom `$type: sound` (net-new vs W3C DTCG 2025.10), Cuelume v0.1.0 engine, interaction-only\n- **9 open tensions** — documented, not hidden\n- **Spring physics** — default + momentum tokens via custom `$type: spring`\n- **Machine-readable** — W3C DTCG 2025.10 format + custom extensions\n\nSee the [contract page](https://www.designesy.org/contracts/design-system) for the full adoption history.\n\n## GitHub Action\n\nGate your CI on design-contract compliance:\n\n```yaml\n- uses: LE-VAI/designesy-org@v1\n  with:\n    url: https://your-app.vercel.app\n    min-score: 70\n    min-grade: C\n    post-comment: true   # posts a summary comment on PRs (default)\n```\n\nScores 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`](action/README.md) for full usage.\n\n## CLI\n\nScore a URL from the command line — for local development, pre-commit hooks, or scripts:\n\n```bash\n# Local (no install needed):\nnode cli/designesy-score.mjs designesy.org\n\n# With gating (exit 1 on failure):\nnode cli/designesy-score.mjs linear.app --min-score 70 --min-grade B\n\n# JSON output for piping:\nnode cli/designesy-score.mjs vercel.com --format canonical --json\n\n# Via npm script:\nnpm run score -- designesy.org\n```\n\nZero 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.\n\n## Repository\n\nThis is the controlled public root for Designesy — a Next.js 15 App Router site (React 19, Turbopack, Vercel deploy).\n\n```\napps/site          Next.js application\naction/            designesy/contract-check GitHub Action\ncli/               designesy-score CLI\ndocs/designesy     context, architecture, logs, registries\nDESIGN.md          the design contract (human-readable)\nAGENTS.md          agent operating rules\n```\n\n## What Designesy is not\n\nDesignesy is not a template gallery. Designesy is not a generic AI design tool. Designesy is not a moodboard.\n\nDesignesy is a system.\n\n## Related tools\n\n- **[Lyse](https://github.com/lyse-design/lyse)** — 258-check design system health scoring from your codebase (6 axes). Designesy scores any public URL; Lyse scores your repo. Complementary.\n- **[DSAF](https://github.com/cyberskill-official/design-system-audit-framework)** — 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.\n- **[axe-core](https://github.com/dequelabs/axe-core)** — WCAG accessibility testing. Designesy checks design-contract compliance (tokens, motion, typography) — a different layer. They complement each other.\n- **[Lighthouse](https://github.com/GoogleChrome/lighthouse)** — Performance, accessibility, and SEO auditing. Designesy checks design-contract compliance — Lighthouse doesn't know what a design token is.\n\n## FAQ\n\n**Does it need an API key?**\nNo — all 17 tools are read-only. The MCP endpoint is stateless Streamable HTTP with no authentication.\n\n**Is it deterministic?**\nYes. There is no LLM in the scoring loop — every check is deterministic and reproducible. The same URL will always produce the same score.\n\n**What does it score against?**\nThe Designesy v0.4.0 design-system contract — 42 checks across 14 weighted categories (tokens, motion, accessibility, cadence, takt, poise, identity, interaction, performance, responsive, semantic, security, spec, copywriting).\n\n**Can I use it in CI?**\nYes. The [GitHub Action](#github-action) gates your workflow on contract compliance — fail the build if the score drops below your threshold.\n\n**Where is the contract published?**\nAt [designesy.org/contracts/design-system](https://www.designesy.org/contracts/design-system) (human-readable) and [designesy.org/contracts/design-system.json](https://www.designesy.org/contracts/design-system.json) (machine-readable, W3C DTCG 2025.10).\n\n## License\n\nMIT — see [LICENSE](LICENSE). The contract is public; the code is open-source under MIT.",
  "bytes": 10998,
  "sha": "027cc125b1bbaa388c541158f64af64a59befad0a5d1db662545b2095aa40c1c",
  "repo_slug": "le-vai/designesy-org",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_le_vai_designesy_org_ed36044d/readme"
}