Designesy

Designesy

_{这段 12 秒的循环录制于主页。动画播放一次后停留在评定结果；如果你偏好减少动态效果，也会显示静态画面。观看它在 designesy.org 上运行。}

面向 AI 生成 UI 的设计质量门禁：通过 45 项确定性检查为任意 URL 评分，等级为 A–F。现已上线：designesy.org。

快速开始

5 秒内为任意 URL 评分——无需安装：

npx @designesy/score@latest https://your-site.com

添加到 Claude Desktop、Cursor 或任何 MCP 客户端：

# 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

要克隆此仓库？ 根目录中的 .mcp.json 会将本地服务（uvx designesy-mcp）作为项目服务添加到 Claude Code。首次打开项目时，Claude Code 会要求你批准。需要安装 uv。

在 CI 中设置设计契约合规门禁：

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

同一个 45 项检查引擎为 MCP 服务（提供 17 个供 AI Agent 使用的工具）、无必需依赖的 CLI（npx @designesy/score）和 GitHub Action 提供支持。

Designesy Contract Check 是一个 GitHub Action，可根据包含 45 项检查的设计系统契约（tokens、动效、无障碍性、节奏、拍点、沉稳感、品牌识别、交互、性能、响应式、语义、安全、规范、文案）为任意 URL 评分，并在评分或等级低于阈值时使 CI 工作流失败。整个流程不使用 LLM：每项检查都是已发布的确定性规则，因此同一页面总会得到相同的评定结果。

工具

• designesy_score — 根据 45 项设计规范检查，对实时 URL 进行评分。返回分数、等级（A–F）和逐项检查明细。
• designesy_tokens_score — 验证 DTCG 设计令牌文件。依据 W3C DTCG 2025.10 进行 10 项符合性检查。
• designesy_a11y_score — 获取 WCAG 2.2 AA 无障碍框架，以及 Playwright/axe-core 脚本模板。
• designesy_motion_score — 验证 Lottie 动画文件。依据 Lottie 规范 v1.0.1 和 §16 动效标准进行 10 项检查。
• designesy_contract — 获取设计系统规范（令牌、动效、节拍、节奏、排版、验证），可获取完整内容，也可仅获取你指定的顶层 sections。
• designesy_catalog — 列出已发布的 Designesy 软件包及其版本和 URL（数量会通过 package_count 返回）。
• designesy_design_review — 获取包含 8 个维度的定性设计评审评分标准。
• designesy_skill_md — 获取符合 Agent 技能格式的规范 SKILL.md，适用于 Cursor、Claude Code 或 Replit。
• designesy_agent_json — 获取 /.well-known/agent.json 发现文档。
• designesy_llms_txt — 获取简短的 /llms.txt Agent 简介。
• designesy_llms_full_txt — 获取完整的 /llms-full.txt 简介作为参考数据（其摄取步骤和可直接粘贴的 Agent 提示词保留在已发布文件中）。
• designesy_drift_score — 对实时 URL 进行 UI 漂移评分：检查其自定义属性和 var() 引用，共 12 项。
• designesy_readiness_score — 对 URL 的 AI 就绪度进行评分：通过 10 项探测检查机器可读设计资料（DTCG 令牌、llms.txt、agent.json、MCP 端点、DESIGN.md 等）。
• designesy_guardrails — 根据网站的令牌，为编码 Agent 生成构建规范套件：DTCG 令牌、Stylelint 配置、AGENTS.md 规则、组件规范、反模式和 DESIGN.md。
• designesy_monitor_score — 根据较早的快照重新运行漂移检查，并计算 10 项监控检查；结果中会返回警报。
• designesy_compare — 对比两个实时 URL 的令牌差异：新增、移除、重命名、值变化、尺度和对比度漂移，以及分数变化。
• designesy_report — 为 URL 生成一份综合报告（分数 × 0.5 + 漂移 × 0.3 + 就绪度 × 0.2）；在支持 MCP Apps 的宿主环境中提供交互式仪表板。

工具参考表

工具	描述
designesy_score	根据 45 项设计契约检查对实时 URL 评分 — 返回分数、等级（A–F）和逐项检查明细
designesy_tokens_score	验证 DTCG 设计令牌文件（10 项一致性检查，W3C DTCG 2025.10）
designesy_a11y_score	获取 WCAG 2.2 AA 无障碍框架及 Playwright/axe-core 脚本模板
designesy_motion_score	验证 Lottie 动画文件（10 项检查，Lottie spec v1.0.1 + §16 动效标准）
designesy_contract	获取设计系统契约（令牌、动效、节拍、节奏、排版、验证），可获取全部内容，或仅获取指定的顶层 sections
designesy_catalog	列出已发布的 Designesy 软件包及其版本和 URL
designesy_design_review	获取 8 个维度的定性设计评审标准
designesy_skill_md	将契约作为 Agent 技能格式的 SKILL.md 获取（适用于 Cursor/Claude Code/Replit）
designesy_agent_json	获取 /.well-known/agent.json 发现文档
designesy_llms_txt	获取精简版 /llms.txt Agent 简介
designesy_llms_full_txt	获取完整的 /llms-full.txt 简介作为参考数据（其中的导入步骤和可直接粘贴的 Agent 提示词保留在已发布文件中）
designesy_drift_score	对实时 URL 的 UI 偏移进行评分（针对自定义属性和 var() 引用的 12 项检查）
designesy_readiness_score	对 URL 的 AI 就绪度进行评分（针对机器可读设计资源的 10 项探测）
designesy_guardrails	根据网站令牌为编码 Agent 生成构建契约包（6 个文件）
designesy_monitor_score	根据先前快照重新运行偏移检查；10 项监控检查；结果中包含警报
designesy_compare	比较两个实时 URL 的令牌差异，并提供分数变化
designesy_report	为一个 URL 生成综合报告（分数、偏移、就绪度），并提供 MCP App 仪表板

在线服务

• 网站： designesy.org
• MCP 端点： designesy.org/api/mcp（Streamable HTTP，无需身份验证）
• 为网站评分： designesy.org/score
• 方法论： designesy.org/methodology — 完整的 45 项评分方法论
• 契约： designesy.org/contracts/design-system
• 机器可读导出： designesy.org/contracts/design-system.json

契约验证

在线网站已通过设计系统契约验证 — 45 项确定性检查，且可追溯至令牌。两个徽章均读取该网站在 /api/badge?site=designesy.org 中记录的分数，其中包含测量日期；如需查看每项检查的最新结果，请立即为 designesy.org 评分。有关分数的计算方式，请参阅方法论页面。

设计契约

• 45 项验证检查，涵盖 14 个加权类别——令牌、动效、无障碍、节奏、节拍、沉稳、身份、交互、性能、响应式、语义、安全、规范、文案
• 文案原则（v0.4.0 新增）——16 项 UX 文案原则 + 4 项验证检查（按钮使用动词短语、不以句号结尾、链接文本具有描述性、不使用全大写）
• 10 项不可妥协的动效标准——有意设计的缓动、明确指定属性、以透明度呈现进入动效、键盘操作保持静止、不对布局做动画、针对触控进行限制、时长有上限、提供减少动态效果的路径、按压反馈不对称、不使用 ease-in
• 10 个声学提示令牌——自定义 $type: sound（W3C DTCG 2025.10 中没有）、Cuelume 0.2 引擎（MIT）、仅用于交互。声学令牌文档另含 9 个扩展反馈提示，共 19 个
• 10 项公开讨论中的分歧——有记录，不隐瞒
• 弹簧物理——通过自定义 $type: spring 提供默认令牌和动量令牌
• 机器可读——W3C DTCG 2025.10 格式 + 自定义扩展

完整的采用历史请参阅设计契约页面。

GitHub Action

在 CI 中设置设计契约合规门槛：

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

通过实时 /api/score 引擎为 URL 评分，并在分数或等级低于阈值时使工作流失败。运行于 node24，通过原生 GitHub REST API 发布 PR 评论（零依赖）。完整用法请参阅 action/README.md。

CLI

从命令行为 URL 评分——适用于本地开发、提交前钩子或脚本：

# 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

无需必需依赖。引擎在本地运行，无需 Designesy 服务；需要浏览器的检查会返回 MANUAL。所有选项请参阅 --help，完整参考请参阅 packages/score/README.md。

**从此仓库的克隆版本运行：**引擎的 dist/ 文件夹未提交，因此请先构建。

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

旧版 cli/designesy-score.mjs（npm run score）读取相同的构建产物。它已由 @designesy/score 取代。其 --api 标志（或 SCORE_API 环境变量）是可选的远程回退方式，会将 URL 发送到评分服务，而不是在本地评分；默认关闭。

仓库

该网站是一个 Next.js 16 App Router 应用（React 19，webpack 构建），部署在 Vercel 上。npm 软件包和 MCP 服务与它并列存放。

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

契约模式可根据你自己的 DESIGN.md 或 DTCG 令牌文件为页面评分，其规范见 docs/contract-mode-spec.md。

DESIGN.md 格式的设计契约由契约源生成，并发布于 designesy.org/DESIGN.md。根目录中的 DESIGN.md 文件是较早的 v0.1 章程。

Designesy 不是什么

Designesy 不是模板库。Designesy 不是通用 AI 设计工具。Designesy 不是情绪板。

Designesy 是一个系统。

相关工具

• Lyse — 根据你的代码库进行设计系统健康度评分，共 258 项检查（6 个维度）。Designesy 为任意公开 URL 评分；Lyse 为你的仓库评分。二者互为补充。
• axe-core — WCAG 无障碍测试。Designesy 检查设计契约合规性（令牌、动效、排版）——属于不同层面。二者互为补充。
• Lighthouse — 性能、无障碍和 SEO 审计。Designesy 检查设计契约合规性——Lighthouse 并不了解设计令牌。

常见问题

需要 API 密钥吗？ 不需要。MCP 端点使用无状态的 Streamable HTTP，且无需身份验证。全部 17 个工具均为只读。

结果具有确定性吗？ 是。评分流程中没有大模型：每项检查都是确定且可复现的。相同的页面、引擎和契约始终会得出相同的判定结果，任何人都可以通过回执的摘要进行验证。实时 URL 可能会在两次运行之间发生变化，结果会缓存 24 小时。

评分依据是什么？ 当前的 Designesy 设计系统契约，包含 14 个加权类别下的 45 项检查（设计令牌、动效、无障碍性、节奏、节拍、沉稳度、标识、交互、性能、响应式、语义、安全、规格、文案）。

可以在 CI 中使用吗？ 可以。GitHub Action 会根据契约合规情况为工作流设置门槛——如果分数低于阈值，就会使构建失败。

契约发布在哪里？ 位于 designesy.org/contracts/design-system（人类可读）和 designesy.org/contracts/design-system.json（机器可读，W3C DTCG 2025.10）。

许可证

MIT——请参阅 LICENSE。该契约是公开的；代码基于 MIT 开源。