Designesy

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.

Get the Designesy agent discovery document (/.well-known/agent.json) as reference data: the org identity, authority, discovery endpoints, package index, machine exports, permission policy, contact, and citation templates. Use this when integrating with or enumerating Designesy and need the canonical discovery manifest 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 JSON: { kind: "published_document", source_url, media_type: "application/json", note, omitted_fields[], document }, where document is the published object (schema, name, identity, authority, topics, discovery, ingest, packages, machine_exports, contact, permission, cite, and the rest) with any field written as steps for an AI agent (such as ingest.steps) removed and its path listed in omitted_fields. No parameters.

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

Diff two design systems from live URLs — 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 server-side per URL pair.

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; this server caches the fetched contract for 5 minutes. With no arguments it returns the full contract JSON, which is large (on the order of 100 KB, tens of thousands of tokens). To return less, pass sections, a list of top-level keys such as ["motion", "colors"]: the result holds id, version, and only those keys. section (one name) is the older form and returns { section, data }. An unknown name returns an error that lists every valid key.

Get the Designesy Design Review rubric for a qualitative design critique: eight dimensions (Purpose, Clarity, Context, Inclusion, System coherence, Durability, Delight, Responsibility), the output format, and the verification checklist, from the published Design Review kit. 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: it returns reference data and does not evaluate the design. Returns JSON: { kind: "review_rubric", source_url, note, inputs (only when passed), kit { id, title, version, status, purpose, quality_bar, permission }, when_to_use[], required_inputs[], dimensions[8] { num, title, desc }, output_format[], verification_checklist[], anti_patterns[], rationalizations[], kit_prompt_url, kit_prompt_note, omitted_fields[] }. The kit's copy-ready agent prompt is not included; kit_prompt_url is the page where a person can read it. Pass artifact, purpose, context, or rules to have them recorded in inputs (rules defaults to the current contract version).

Score a live URL for AI-generated UI drift. Its 12 checks detect the four documented 2026 drift failure modes: token fabrication (var() references with no fallback to custom properties declared nowhere: not in a stylesheet, a <style> block or a style attribute), within-session drift (spacing/color/radius value variance), between-session amnesia (inconsistent font stacks, shadows, transitions), and silent breaking changes (z-index chaos, alias chains that end in an undeclared property). 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 45-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 custom property declarations (stylesheets, <style> blocks and style attributes) and var() references, runs 12 drift checks. No browser needed. Returns JSON: { ok, url, scope, score (0-100), grade (A-F), pass, warn, fail, skip, total, tokensExtracted, checks[{id, item, category, status, detail}] }. Results cached ~24h per URL.

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. The full bundle grows with the number of tokens a site declares: about 7 KB to about 530 KB of JSON on the 26 sites measured (about 110 KB for designesy.org). To trim it, pass parts, a list of bundle file names such as ["designMd"] or ["tokens", "lintConfig"]: the result keeps score, grade, counts and checks, and its bundle holds only those files, in the order asked. Valid parts: tokens, lintConfig, agentRules, componentContract, antiPatterns, designMd. A single part can still be large on a site with many tokens. An unknown name returns an error that lists the valid parts. 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}] }; with parts it adds parts, and bundle holds only the named files. Results cached ~24h per URL.

Get the Designesy /llms-full.txt brief as reference data: authority, discovery endpoints, topics, every published package with its links, standing rules, and anti-patterns. Use this for a fuller picture of the Designesy ecosystem when the short brief from designesy_llms_txt is not enough. When NOT to use: for a quick orientation, use designesy_llms_txt (a few thousand characters; this one runs over ten thousand); for the contract itself, use designesy_contract. Read-only: no side effects. Returns JSON: { kind: "published_document", source_url, media_type: "text/plain", note, omitted_sections[], content }, where content is the published text with any section written as steps or a prompt for an AI agent (such as the ingest protocol and the paste-ready agent prompt) replaced by a one-line marker and named in omitted_sections. No parameters.

Get the Designesy /llms.txt brief as reference data: what Designesy is, canonical links, topics, the published package list, machine exports, standing rules, and contact. Use this first when you don't know what Designesy is; at a few thousand characters it is the cheapest orientation path before pulling heavier artifacts. When NOT to use: for the longer brief, use designesy_llms_full_txt; for the contract itself, use designesy_contract. Read-only: no side effects. Returns JSON: { kind: "published_document", source_url, media_type: "text/plain", note, omitted_sections[], content }, where content is the published text with any section written as steps for an AI agent (such as the ingest steps) replaced by a one-line marker and named in omitted_sections. No parameters.

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 server-side per URL.

Validate one Lottie animation file against the Designesy motion contract: its ten checks (m01-m10), drawn from the Lottie spec v1.0.1 and the Designesy §16 Ten Non-Negotiable Motion Standards. Each check returns PASS, FAIL, WARN or SKIP under the contract's own name for its id: m01 the schema's top-level animation object (layer contents are not validated, so a clean file returns SKIP, not PASS), m02 the required fields (v, fr, ip, op, w, h, layers), m03 no deprecated 4.x Bodymovin version, m04 a markers array, m05 a meta object, m06 a reduced-motion path (a marker or slot named for it, or a meta note of an external prefers-reduced-motion wrapper), m07 keyframe easing (linear, ease and ease-in curves fail), m08 duration within 300 ms (longer returns WARN, since a justification cannot be read from a file), m09 layout-property animation and m10 keyboard-initiated motion (both SKIP: they concern the page that embeds the file). Use this to check that a motion asset is well formed and carries reduced-motion support. When NOT to use: for the motion CSS of a whole site, use designesy_score. Executable: fetches the URL or parses the inline JSON; no browser needed. Score: PASS=1, WARN=0.5, FAIL=0, SKIP is not scored; points / scored checks x 100. Returns JSON: { contract_id, contract_version, contract_status, url, lottie_version, layer_count, score (0-100), grade (A-F), pass_count, fail_count, warn_count, skip_count, scoring, checks[{id (m01-m10), name, status (PASS, FAIL, WARN or SKIP), detail}], ten_non_negotiable, provenance, validator_note }. Pass url to fetch a remote Lottie file, or lottie_file to validate an inline JSON string. Provide exactly one.

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 server-side per URL.

Generate a unified design-intelligence report for a single URL, the synthesis capstone. Fires /score (45-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. The full result is large: about 75 to 100 KB of JSON on the ten sites measured, on the order of 20,000 tokens or more, because it carries each engine's whole result beside the merged check list. To trim it, pass detail "summary": the same keys with fewer rows, about 4 to 31 KB on the same sites. It keeps the composite, the totals, each engine's score, grade and counts, and only the checks and synthesis entries that did not PASS; omitted counts what was left out. detail "full" (the default) returns everything. Returns JSON: { ok, url, compositeScore (0-100), compositeGrade (A-F), score { sub-result }, drift { sub-result }, readiness { sub-result }, totalChecks, totalPass, totalWarn, totalFail, totalSkip, totalManual, checks[] (all checks across all engines, tagged with engine), synthesis[] (8 synthesis checks verifying the report ran correctly), appUrl (standalone interactive dashboard URL) }; with detail "summary" it adds detail and omitted. 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.

Score a live URL against the Designesy design contract with the deterministic 45-check verification engine at https://www.designesy.org/api/score. Returns a numeric score, a letter grade (A-F), and the check results. 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. The engine fetches the URL server-side, extracts its CSS, and runs 45 checks. Results are cached ~24h server-side per URL and scope. Checks that need a live browser (Core Web Vitals, sound toggle, overflow) return MANUAL; the full audit (/api/score/audit) resolves them. Checks that do not apply to the site (no tokens, no buttons, no DESIGN.md) return SKIP (N/A). format selects the output. designesy (the default) returns JSON: { url, contract_version, summary { total, pass, fail, warn, skip, manual, score (0-1), score_percent (0-100), grade }, tokens_extracted, checks[{ id, item, category, status, detail }], note }. canonical returns the engine's review-findings.json schema JSON unchanged. review returns the engine's markdown report unchanged (coverage by category, a findings table of the FAIL and WARN checks, and a verdict). google returns the engine's @google/design.md-compatible JSON unchanged. scope sets the scoring scope: contract or universal. Omit it and the engine auto-detects: contract for designesy.org, universal for every other site. If the network fails before the request reaches the engine (no DNS, no route, a refused connection), format designesy falls back to the offline engine: 27 of the 45 checks run locally, each mirroring the live engine's verdict, under the same scope. Its result adds engine (kind offline, the engine version it mirrors, and the checks it did not run) and scope, and its note say…

Get the Designesy SKILL.md: the agent-skill-format export of the design-system contract, for a user to save into .agents/skills/ or a system prompt so a coding agent builds UI to the contract (tokens, anti-patterns, rules, verification). Use this when the user wants the contract in that form. When NOT to use: for the raw contract JSON, use designesy_contract; for scoring, use designesy_score. Read-only: no side effects. Returns JSON: { kind: "published_document", source_url, media_type: "text/markdown", note, omitted_sections[], content }, where content is the SKILL.md markdown (tens of thousands of characters) with any section written as steps or a prompt for an AI agent replaced by a one-line marker and named in omitted_sections. No parameters.

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 or SKIP. Use this to verify a tokens.json (or any DTCG token export) is structurally correct: $type (direct or inherited) present, one $value or $ref per token (a JSON Pointer $ref must resolve), structured colors (colorSpace + components rather than bare hex), dimensions in the 2025.10 { value, unit } form, and a $schema pointer to designtokens.org (a Designesy policy: DTCG does not require $schema). 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. Score: PASS=1, WARN=0.5, FAIL=0, SKIP is not scored; points / scored checks x 100. Returns JSON: { contract_id, contract_version, contract_status, url, total_tokens, score (0-100), grade (A-F), pass_count, fail_count, warn_count, skip_count, scoring, checks[{id (t01-t10), name, status (PASS, FAIL, WARN or SKIP), detail}], provenance, validator_note }. Pass url to fetch a remote token file, or dtcg_file to validate an inline JSON string. Provide exactly one.