@leagent/ledesign

设计系统编译器

从一份 DESIGN.md（DSSF）完成设计系统的编写、校验、编译与预览。

你能得到什么

| 层级 | 作用 | |------|------| | DESIGN.md | 唯一规范源 — Token、组件、设计准则、Agent 指令 | | 编译器 | 输出 CSS 变量、DTCG JSON、TypeScript、Tailwind preset、组件契约 | | CLI | kai / kan / validate / build / export / diff | | 内置预览 | 分屏 UI，随包发布（dist/app/） |

DESIGN.md 是唯一事实来源。ledesign 解析它、生成生产级 Token，并打开实时预览。

快速开始

npm install -g @leagent/ledesign   # 或: npx @leagent/ledesign

mkdir my-design && cd my-design
ledesign kai --name "acme-ui"      # 开 — 生成 DESIGN.md 模板
ledesign validate                  # 校验 DSSF 结构
ledesign build                     # 编译到 ./dist/
ledesign kan                       # 看 — 打开内置预览

| 命令 | 含义 | 作用 | |------|------|------| | kai | 开 | 从模板生成 DESIGN.md | | kan | 看 | 编译当前目录 Token 并打开内置预览 | | validate | — | 校验 schema、准则、对比度、检查清单 | | build | — | 写入 dist/ 产物 | | export | — | 以单一格式输出到 stdout | | diff | — | 对比两份 DESIGN.md 修订 | | dev | — | kan --dev，带 HMR（包开发模式） |

常用参数

ledesign kai ./docs/DESIGN.md --name "acme-ui" --description "Acme UI tokens" --force
ledesign kan DESIGN.md --port 3000 --no-open
ledesign build -o ./dist
ledesign export --format css
ledesign diff DESIGN.md.old DESIGN.md

Windows（无需全局安装）：

npx -p @leagent/ledesign ledesign validate DESIGN.md

安装

CLI（全局）：

npm install -g @leagent/ledesign

库（在应用中使用）：

npm install @leagent/ledesign

项目结构

执行 kai 后，项目只需：

my-design/
├── DESIGN.md          # 编辑此文件
└── dist/              # 由 ledesign build / kan 生成
    ├── tokens.css
    ├── tokens.ts
    ├── tokens.dtcg.json
    ├── tailwind.preset.ts
    ├── component-contracts.ts
    ├── motion.css
    └── metadata.json

预览 UI 内置于 @leagent/ledesign（dist/app/）。kan 运行时读取你的 DESIGN.md 与 ./dist/tokens.css，无需额外脚手架。

内置预览

运行 ledesign kan 打开上文截图所示界面：

| 面板 | 用途 | |------|------| | Source | 实时 DESIGN.md，带 § 锚点导航 | | Preview | 完整组件库 + 仪表盘 Mock（iframe） | | Pipeline | 解析链路、Token/组件计数、警告信息 |

开启 Inspect 后，点击预览元素可跳转到源码中对应的 § 章节。

开发 ledesign 本身时：

npm run dev            # 等同于 ledesign kan --dev（Vite HMR）

编程 API

import { parseDesign, compile, validate, diff } from '@leagent/ledesign';

const model = parseDesign(markdown);
const { css, typescript, dtcg } = compile(model);
const report = validate(markdown);

if (report.summary.errors > 0) throw new Error('Invalid DESIGN.md');

子路径导出：

import '@leagent/ledesign/css';                    // dist/tokens.css
import { tokens } from '@leagent/ledesign/tokens';
import { ThemeProvider } from '@leagent/ledesign/runtime';

输出产物

| 路径 | 说明 | |------|------| | dist/tokens.css | --ds-* 变量、兼容别名、减弱动效 | | dist/tokens.ts | 类型化 tokens、tokensByTheme、TOKEN_NAMES | | dist/tokens.dtcg.json | W3C Design Tokens Format | | dist/tailwind.preset.ts | theme.extend preset | | dist/component-contracts.ts | §5 组件绑定映射 | | dist/motion.css | 动效与无障碍 CSS | | dist/metadata.json | Token ↔ § 锚点追溯 | | dist/app/ | 内置预览（由 kan 提供，不复制到用户项目） |

DSSF 格式（摘要）

1. YAML frontmatter — dssf、name、themes、tokenPrefix
2. § 锚点 — 标题上方写 <!-- §4.1-color-system -->
3. design-token 代码块 — 类型化 YAML（非自由文本）
4. §5 组件 — Anatomy、States、Variants、Acceptance Criteria
5. §12 准则 + §13 检查清单 — 评审门禁

仓库 DESIGN.md 是带 Agent 指令的参考文档与可运行示例。

• docs/spec.md — DSSF 1.0 语法
• docs/authoring.md — 编写指南

Agent 集成

DESIGN.md 开头包含 Agent Instructions。可在 Cursor 中添加：

Read @DESIGN.md before UI work. Run `ledesign validate` before finishing.
Do not add colors outside design-token blocks.

或使用内置规则：.cursor/rules/design-system.mdc

本地开发

git clone https://github.com/vixues/ledesign.git
cd ledesign
npm install
npm run build        # tsup + 编译 Token + 构建 dist/app/
npm run validate
npm run typecheck
npm run kan          # 用本地 DESIGN.md 预览

仓库结构：

ledesign/
├── DESIGN.md          # 参考 DSSF 文档
├── app/               # 内置预览源码（仅开发）
├── src/               # 解析器、编译器、校验、CLI
├── dist/              # 发布产物 + dist/app/ 预览
└── docs/              # 规范、编写指南、资源

发布到 npm

npm run build
npm run validate
npm pack --dry-run     # 检查 tarball 内容
npm publish --access public

作用域包 @leagent/ledesign 首次发布需加 --access public。

版本策略

ledesign diff DESIGN.md.old DESIGN.md

当 Token 或组件被删除时，退出码为 1。

| 变更类型 | Semver | |----------|--------| | 仅文档 / 文案 | patch | | 新增 Token 或组件 | minor | | 删除或重命名 Token | major |

许可证

MIT