OpenDesign 的 Dithered 设计系统包USAGE 契约、Token 结构与 Agent 实战指南【免费下载链接】open-design Best DeepSeek Harness Design Plugin. The open-source Claude Design alternative. ️ Local-first desktop app. ️ Your coding agent becomes the design engine: prototypes, landing pages, dashboards, slides, images video — real files, HTML/PDF/PPTX/MP4 export. Claude Code / Codex / Cursor / DeepSeek Harness / OpenCode 20 CLIs via BYOK.项目地址: https://gitcode.com/gh_mirrors/opend/open-designOpenDesign 以「便携式设计系统包」的方式管理 150 套风格主题每个包都是一组可由 Agent 直接消费的文件契约。dithered是其中基于点阵渲染dot-pattern审美、强调硬边、位图纹理与紧凑单色控件的 Retro Nostalgic 风格包。本文以 dithered/USAGE.md 为主干结合 manifest.json、tokens.css、components.manifest.json 与 daemon 侧消费代码完整讲解该包的阅读顺序、使用守则、56 个语义 Token 的层次划分、组件清单与跨品牌切换的可维护性约束读完即可直接在 Agent 提示词或前端 artifact 中正确落地这套设计系统。包的定位Design System 2.0 契约包根据 design-systems/README.md仓库中每个design-systems/slug/子目录都是一个便携式设计系统包由 Design System 界面或受支持的项目创建流程选中后其设计上下文会被组装进 Agent 提示词。所有捆绑包共享同一套最小机器可读结构design-systems/slug/ ├── manifest.json # 稳定的发现元数据、来源与声明路径 ├── DESIGN.md # 面向 Agent 的规范设计散文canonical design prose └── tokens.css # 规范编译后的语义 Token 样式表dithered包在其 manifest.json 中声明了完整契约schemaVersion: od-design-system-project/v1id: dithered类别为Retro Nostalgicsource.type: bundled来源为OpenDesign curated bundled fixture——即这是由仓库精选的捆绑 fixture 派生而非对上游品牌仓库或网站的实时抓取importMode: normalizedcraft 绑定craft.applies为空craft.suggested建议 craft/color.md 与 craft/accessibility-baseline.md 两份工艺基线预览页preview/提供colors.html、typography.html、spacing.html三张索引页source/目录存放导入证据evidence.md、tokens.source.json与token-contract.report.json。正确阅读顺序Read OrderUSAGE.md 规定了包内文件的消费顺序这是 Agent 与审查者都必须遵守的契约先读本文件USAGE.md理解包契约的全貌再读 DESIGN.md掌握视觉意图、约束与反模式将 tokens.css 粘贴进第一个 artifact 的style块且要在编写任何组件 CSS 之前完成用 components.manifest.json 作为紧凑的组件清单当需要精确的选择器或状态时打开 components.html需要视觉核查时检查preview/页面。从 daemon 源码看这一契约是运行时输入而非装饰性文件。在 apps/daemon/src/design-systems/index.ts 的readDesignSystemAssets中usageMdUSAGE.md、tokensCss、fixtureHtmlcomponents.html与componentsManifestJson会被并行读取连同pullIndex、importMode、craft 绑定一起组装成资产对象在 apps/daemon/src/prompts/system.ts 中USAGE.md被明确标注为「可选的 USAGE.md 路由器」指导提示词如何路由到包内各文件。也就是说USAGE.md 不只是给人看的说明它直接参与 daemon 的提示词组装。设计要点风格立场与关键色USAGE.md 中记录的本包设计要点视觉风格modern, minimal现代、极简色彩立场primary、neutral、success、warning、danger 五类设计意图让输出保持对该风格家族的辨识度同时兼顾可用性与可读性Primary#3B82F6来自风格基础style foundations的 Token。需要说明的是DESIGN.md 顶部对类别的定义是「Retro Nostalgic以有限调色板模拟灰阶的点阵渲染技术营造怀旧、复古、高对比的视觉」而它罗列的 Primary#3B82F6、Secondary#8B5CF6等是「Token from style foundations」——即风格基础层的通用立场色。真正落到这个包的具体:root绑定暖色底、砖橙强调在 tokens.css 中两处各自承载了「风格家族身份」与「具体实现值」两种职责这也是 USAGE.md 强调「不要脱离tokens.css单独重定义设计 Token」的原因。核心资产一tokens.css 与 56 个语义 Tokentokens.css 是本包唯一的事实源样式表整个:root块共声明 56 个 Token按 design-tokens.json 的分层统计可分为四层层数量含义dithered 示例A1-identity8品牌身份层缺失即 guard 失败--bg: #fff4cf、--fg: #2a1810、--accent: #d24b1f、--border: #d9aa7a、--font-display、--font-bodyB-slot4品牌或 schema 建议的别名槽位--surface-warm: #ffdca8、--fg-2: #593625、--meta: #d24b1f、--border-soft: #efd0abA226带 fallback 的通用层--accent-hover、--success、--warn、--danger、字号/间距/圆角/阴影/动效A1-structure18结构层缺失即 guard 失败--text-xs到--text-4xl、--container-max、--section-y-*关于分层契约的完整解释A1/B-slot/A2 谁决定值、缺失时怎么办、C→B-slot→A2 的晋升路径可参考 design-systems/_schema/AGENTS.md 中的「Four layers, two questions」一节。dithered的色彩绑定呈现典型的复古点阵风格暖米色底--bg: #fff4cf、奶油面--surface: #fffaf0、深棕前景--fg: #2a1810、砖橙强调--accent: #d24b1f并通过color-mix(in oklab, var(--accent), black 8%/14%)派生 hover/active 状态。字号阶梯为11/12/14/16/20/28/40/56px间距阶梯为4/8/12/16/20/24/32/48px圆角为4/8/12/9999px动效为100ms/180ms配cubic-bezier(0.2, 0, 0, 1)。字体方面展示字体与等宽字体同为Courier New, ui-monospace, monospace正文为Inter, system-ui, sans-serif——单色等宽的显示字体正是「紧凑单色控件」气质的来源。Token 契约报告可审计的来源绑定source/token-contract.report.json 是 TOKEN_SCHEMA 契约报告把每一个 Token 绑定回tokens.css的具体声明行例如--accent的sources: [tokens.css:16]。其摘要显示总 Token 56、声明 56、全部有来源背书source-backedscore: 100、grade: excellent、recommendRebuild: false。source/evidence.md 同时明确了证据边界本包是 Design System 2.0 backfill不声称对原始上游品牌仓库或网站做过全新抓取来源范围就是DESIGN.md、tokens.css、components.html三份捆绑 fixture。design-tokens.json与tailwind-v4.css是派生产物应从报告与 Token 样式表再生成而非手工编辑。Tailwind v4 映射派生而非重定义tailwind-v4.css 以import tailwindcssimport ./tokens.css开头随后在theme块中把每个 Token 映射为 Tailwind 命名空间theme { --color-bg: var(--bg); --color-surface: var(--surface); --color-accent: var(--accent); --font-display: var(--font-display); --font-sans: var(--font-body); --text-4xl: var(--text-4xl); --spacing-4: var(--space-4); --shadow-raised: var(--elev-raised); --duration-fast: var(--motion-fast); --ease-standard: var(--ease-standard); }文件头注释明确写着「Derived from tokens.css. Keep tokens.css as the source of truth.」——这也是 USAGE.md 中「避免脱离tokens.css独立重定义 Tailwind 或设计 Token 值」这一禁令的实现基础。核心资产二组件清单与组件 fixturecomponents.manifest.json 是从 components.html 与tokens.css派生的组件/Token 索引fixture 摘要给出styleBlockCount: 1、selectorCount: 48、classCount: 26、elementCount: 19。其声明的 8 个组件分组groups及对应的 Token 引用如下分组是否包含代表类/元素引用的核心 Tokenbuttons按钮与 CTA✅.btn、.btn-primary、.btn-secondary--accent、--accent-on、--elev-ring、--motion-fast、--radius-mdinputs表单控件✅.field、input、label--border、--radius-sm、--space-2/4/5、--surfacecards卡片与面板✅.panel、.tile、.card-row--elev-raised、--radius-lg、--border、--surfacebadges徽章/状态标签✅.status—links链接与内联动作✅a—typography字号与文本工具✅.eyebrow、.lead、h1/h2/h3--fg-2、--text-4xl、--text-lg、--text-xllayout布局原语✅.container、section、.metric-grid--container-gutter-*、--section-y-desktopkeyboard / icons❌——同时该清单还提供了 Token 使用审计declared56 个全部有对应、referenced52 个、undeclaredReferenced为空即组件中没有引用未声明的 Token但存在 7 个「声明未使用」的 Token--accent-active、--danger、--elev-flat、--motion-base、--space-1、--space-12、--warn——这些是为状态扩展与跨品牌一致性预留的契约槽位。components.html 则是独立的可运行组件 fixture:root块与tokens.css逐字节一致随后是 hero、按钮组、状态徽章、指标网格.metric-grid、暖色 mini-card、表单输入等 26 个类的完整样式与响应式规则media (max-width: 860px)下 hero/网格降为单列。审查者需要精确选择器与状态时直接查这个文件即可。使用守则Do 与 AvoidDo必须遵守原样保留 schema Token 名称让跨品牌切换保持可靠——--accent等名称是跨品牌契约改名会破坏var()解析链用--accent表达主操作、链接、焦点态与唯一的视觉焦点元素保持整个界面只有一个强调信号优先复用 components.manifest.json 中的组件分组而不是自行发明新控件将source/文件视为捆绑 fixture backfill 的审计证据见 source/evidence.md。Avoid禁止行为不要在复制的:rootToken 块之外使用裸十六进制颜色——硬编码色值会让「改一个 Token 全局生效」失效不要脱离tokens.css独立重定义 Tailwind 或设计 Token 值——派生文件tailwind-v4.css、design-tokens.json的一致性由 guard 校验独立重定义会造成漂移不要声称存在原始上游来源证据——本包基于精选的捆绑 fixture证据边界已在source/evidence.md中声明不要添加components.html或DESIGN.md中不存在的新组件配方。从实现侧看这些守则与仓库的 guard 体系一一对应scripts/check-design-system-manifests.ts 校验 manifest 形状_schema/AGENTS.md描述的派生文件 parity guard 与 A2/B-slot required tokens guard 则从机器层面强制「每个tokens.css都声明全部 A2 与 B-slot Token」——因为 artifact 只粘贴一个品牌的:root块缺少任一 Token 都会让var()引用静默失效。配套视觉规范速览DESIGN.mdDESIGN.md 提供了九个维度的设计意图供 Agent 在生成界面时遵循色彩Primary#3B82F6用于 CTA 强调Surface#FFFFFF用于大面积背景与卡片正文使用 Text#111827保证可读性排版字号阶梯14/16/18/24/32/40字体家族 primaryOpen Sans、displaySpace Grotesk、monoIBM Plex Mono字重100–900全档标题承担风格个性正文优化扫读与对比间距与栅格间距阶梯4/8/12/16/24/32保持跨区块的垂直节奏一致列与模块对齐到可预测的栅格避免临时偏移布局优先清晰的内容块与一致的内部留白层级保持「标题 → 支撑文字 → 主操作」先用留白分隔关注区再考虑边框或阴影组件按钮主操作用#3B82F6、次操作保持中性输入框要有强focus-visible态、清晰标签与可预测的错误提示卡片/区块的圆角、间距与抬升策略全页一致动效用微过渡突出 Primary 这一交互信号默认 150–250ms 短促、稳定缓动hover、focus-visible、active、disabled、loading 状态必须显式反模式不引入调色板外的颜色、不塌平层级、不加损害可读性的装饰效果、不在同一界面混用无关视觉隐喻。预览与核对preview/目录提供三张直接引用../tokens.css的静态预览页供生成结果后做视觉抽查preview/colors.html展示--bg、--surface、--fg、--muted、--border、--accent、--success、--warn、--danger九个颜色角色的色板preview/typography.html字号阶梯与行高演示preview/spacing.html间距刻度演示。此外 system/kit.html 与kit.dark.html是打包进 system 目录的完整组件套件示例按钮、指标网格、chip 状态、卡片栅格其中kit.html的:root块与tokens.css保持一致并额外提供--od-*命名空间用于页面级绑定。编写与校验同类包的流程如果要在仓库中新增或校验类似的捆绑设计系统包design-systems/README.md 给出的流程是创建三个必需文件manifest.json、DESIGN.md、tokens.css文件夹 slug 必须等于manifest.id在manifest.json中记录目录元数据与来源DESIGN.md至少写七个实质性的 H2 小节不限定名称与顺序并与tokens.css保持决策同步在tokens.css中绑定共享语义 Token 契约A1、A2、B-slot 全覆盖需要组件、预览、资产、字体或来源证据时添加富文件USAGE.md、components.html、components.manifest.json、design-tokens.json、tailwind-v4.css、preview/、source/运行pnpm guard与pnpm typecheck通过全部 guard 子检查。小结dithered包完整演示了 OpenDesign Design System 2.0 的包契约以 USAGE.md 为入口路由DESIGN.md 定义风格意图tokens.css 提供唯一事实源的 56 个分层语义 Tokencomponents.manifest.json 与 components.html 给出可复用的组件清单与精确选择器source/目录承载可审计的来源证据daemon 侧在运行时把这一切组装进 Agent 提示词。遵循「原样保留 Token 名称、只用--accent表达强调、复用组件分组、不脱离tokens.css重定义」四条守则即可让生成结果稳定保持 Dithered 的复古点阵辨识度同时保证跨品牌切换时契约不破。【免费下载链接】open-design Best DeepSeek Harness Design Plugin. The open-source Claude Design alternative. ️ Local-first desktop app. ️ Your coding agent becomes the design engine: prototypes, landing pages, dashboards, slides, images video — real files, HTML/PDF/PPTX/MP4 export. Claude Code / Codex / Cursor / DeepSeek Harness / OpenCode 20 CLIs via BYOK.项目地址: https://gitcode.com/gh_mirrors/opend/open-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考