OpenDesign 中的 Airtable 设计系统 2.0 使用指南从包契约、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-design本篇技术指南以 design-systems/airtable/USAGE.md 为核心骨架系统讲解 OpenDesign 仓库中「Design System Inspired by Airtable」这一设计系统 2.0 包的完整使用方式它面向编码 Agent 与人工审查者reviewers定义了一份可粘贴、可审计、可跨品牌切换的 token 契约。读完本文你将掌握该包的阅读顺序、设计要点、tokens.css中 56 个设计令牌的语义取舍、组件清单的机器可读结构以及如何在生成 artifact 时正确继承这套「白画布 深海军蓝 Airtable Blue」的视觉体系同时不触犯仓库的 lint 与 guard 校验。一、包是什么一份给 Agent 与审查者的「使用契约」design-systems/airtable/是 OpenDesign 仓库中众多设计系统品牌包之一属于 Design System 2.0 打包规范下的产物。manifest.jsonschema 版本od-design-system-project/v1将其声明为id / nameairtable/AirtablecategoryDesign Creative——「Spreadsheet-database hybrid. Colorful, friendly, structured data aesthetic」source.typebundledorigin 为OpenDesign curated bundled fixture即它来自仓库内置的精选 fixture而非对 Airtable 上游官网/仓库的重新抓取这一点在 source/evidence.md 中被明确声明。包内文件遵循_schema定义的固定 v1 命名见 design-systems/_schema/AGENTS.md文件角色DESIGN.md视觉意图、约束与反模式的权威散文canonical design prosetokens.css已编译的规范 tokencanonical compiled tokensagent 粘贴进 artifact 的style块tokens.css派生文件design-tokens.jsonDesign Tokens JSON、tailwind-v4.cssTailwind v4theme两者都应由脚本重新生成而非手工编辑components.html独立组件 fixture62 个选择器、35 个类、27 个元素components.manifest.json由components.htmltokens.css可重建的组件清单缓存manifest.json机器可读的项目入口USAGE.md面向 Agent 的包使用指南本文主体preview/静态预览页colors / typography / spacingsource/导入证据evidence.md、tokens.source.json、token-contract.report.jsonmanifest.json还声明了importMode: normalized并建议该包结合 craft 规范中的color与accessibility-baseline一起使用craft.suggested。二、Read OrderAgent 拿到包后的五步阅读序列USAGE.md 的核心是一条固定的阅读顺序Read Order它决定了 Agent 组装 artifact 时的信息依赖关系先读USAGE.md本身理解包的契约contract。再读 DESIGN.md掌握视觉意图、约束与反模式。把 tokens.css 的:root块粘贴进第一个 artifact 的style块之后才写组件 CSS——顺序不可颠倒因为组件规则全部引用这些 CSS 变量。用 components.manifest.json 作为紧凑的组件清单当需要精确的选择器或状态如:hover、:focus-visible时打开 components.html 对照。需要视觉 sanity check 时检查 preview/ 页面——colors、typography、spacing 三个静态预览页分别对应当前 token 的实际渲染效果。这条顺序的工程含义在于token 是组件规则的唯一数据源组件清单是「复用而非发明」的索引而 preview 是给人类审查者而非 Agent 的快速验证通道。三、设计要点四根支柱撑起 Airtable 的「精致的简洁」USAGE.md 用四条要点概括了品牌视觉的骨架全部来自 DESIGN.md 的展开白画布 深海军蓝正文--bg: #ffffff正文主色--fg: #181d26Deep Navy而非纯黑——微弱蓝色调的顶部中性色是品牌的一部分。Airtable Blue#1b61c9作为唯一的主 CTA 与链接色全品牌唯一的彩色强调--accent承载主按钮、链接、焦点态与「一个清晰的焦点元素」。Haas Haas Groot Disp 双字体系统Display 用Haas Groot Disp正文与 UI 用Haas回退栈为-apple-system, system-ui, Segoe UI, RobotoDESIGN.md §3 明确记录保证 Haas 未加载时 artifact 依然可读。正文正字距positive letter-spacing0.08px–0.28pxHaas 家族天生为正字距设计正文层级在组件级应用 0.08–0.28px 的 tracking而显示级标题明确为letter-spacing: normal--tracking-display: 0。DESIGN.md 进一步补充了其余可量化的约束12px 圆角按钮、16px–32px 卡片圆角、蓝色调的rgba(45,127,249,0.28) 0px 1px 3px多层阴影、--theme_*语义 token 命名以及 425–1664px 的 23 档响应式断点区间。四、Token 语义深读tokens.css 里九个「反默认」的品牌决策tokens.css 头部注释逐条记录了品牌作者在 schema 惯例之上做的 9 个关键决策——这是理解该包 token 契约的钥匙--accent是 Airtable Blue#1b61c9而非深海军蓝深海军蓝已由--fg承担品牌用--accent作为按钮背景来表达主 CTA把 navy-on-white 留给标题与正文。--accent-hover绑定文档化的 Mid Blue#254fad而不是通用的color-mix压暗——Airtable 明确把 hover 层定义为独立品牌色阶。--fg是#181d26Deep Navy而非#000000纯黑会与 Airtable Blue 冲突。--fg-2为#333333Dark Gray承担正文描述--muted绑定半透明海军蓝rgba(4, 14, 32, 0.69)Weak Text使跨品牌的var(--muted)落到 Airtable 真实的半透明层级上。--surface-warm直接别名到--surfaceAirtable 没有暖色层画布与浮起面都是冷色添加暖色兄弟 token 等于发明品牌不用的色调。--elev-raised逐字复刻 DESIGN.md §6 的四层阴影1px 深色 hairline 2px ambient 3px 蓝色调 glowrgba(45,127,249,0.28)y 偏移 1px 0.5px inset ring。第三层「Airtable glow」是品牌签名覆盖此 token 时不可丢弃。圆角刻度绑定 12 / 16 / 24 / 9999sm / md / lg / pill按钮 12px、卡片 16px、大型特性容器 24px2px「sharp」的 cookie-consent 圆角与 32px 大圆角属于组件级/区块级故意不提升为 schema token。--leading-body: 1.35而非惯例的 1.5Airtable 的产品 UI 密集表格行、记录卡片需要更紧凑的行节奏--leading-tight: 1.2对应标题的 1.15–1.25 区间。--tracking-display: 0normalDESIGN.md 明确显示级标题为letter-spacing: normal正字距只应用在组件级按钮、caption。--success: #006400比 schema 默认的#16a34a更深的森林绿在白画布上读作「已确认/已保存」而非鲜亮告警。区块节奏 96 / 64 / 48desktop / tablet / phone容器上限--container-max: 1200px落在文档化的 425–1664px 响应带中间。这 9 条决策最终落成:root块里的 56 个变量被 design-tokens.json 汇总为A1-identity 8 个、A1-structure 18 个、A2 26 个、B-slot 4 个sourceBackedTokens: 56总分 100 / gradeexcellent。4.1 Token 分层的契约背景要理解上面「A1 / A2 / B-slot」的说法需要读 design-systems/_schema/AGENTS.md 中定义的四层模型。每个共享 token 都要回答两个问题谁决定值品牌作者还是 schema 作者与品牌省略它会发生什么required / fallback / alias层谁决定省略时示例A1-identity品牌guard 失败--bg、--fg、--accent、--font-displayA1-structure品牌guard 失败类型刻度、--container-max、--section-y-*A2品牌有 fallbackguard 失败--motion-fast、--success、--space-4、--font-monoB-slot品牌或 schema 建议的别名guard 失败--fg-2、--surface-warmA2 的 fallback 值镜像在 design-systems/_schema/defaults.css但它不会在运行时参与级联——artifact 是 Agent 把单个品牌的:root粘贴进单个style生成的没有全局样式表兜底所以「每个品牌必须声明每一个 A2 token」是当前唯一安全的契约由design-system: A2 required tokensguard 严格强制见 scripts/check-tokens-fixture-sync.ts 与 scripts/guard.ts。B-slot token 同理共享组件会引用var(--fg-2)、var(--meta)等更丰富的层级品牌缺失时这些引用会静默失效。Airtable 包对 B-slot 的处理是「有主见的绑定」而非默认别名--fg-2: #333333、--surface-warm: var(--surface)、--meta: var(--muted)、--border-soft: #eef0f3——前者独立取值品牌真有这个层级后两者坍缩别名品牌没有更细层级。两种形式都能通过design-system: B-slot required tokensguard。五、组件清单components.manifest.json 的结构与复用原则components.manifest.json 是该包的机器可读组件索引。它先给出一组统计数字styleBlockCount: 1单style块符合 paste 型 artifact 的约束、selectorCount: 62、classCount: 35、elementCount: 27以及literals审计8 个颜色表达式、47 个像素值、5 个硬编码字体族。随后是 9 个组件分组groups每个分组都标注了 selectors、classes、elements 与 tokenReferences方便 Agent 按需取用group idlabel代表选择器引用 token 示例buttonsButtons and calls to action.btn,.btn-primary,.btn-secondary,.btn:focus-visible--accent,--accent-active,--accent-on,--radius-sm,--motion-fastinputsForm fields and controls.field,.field input,.field input:focus-visible--accent,--focus-ring,--muted,--text-smcardsCards and panels.card,.card-icon,.card-link:hover--accent,--space-2,--text-smbadgesBadges, chips, and status labels.badge,.badge-dot,.badge-success--fg,--fg-2,--radius-pill,--text-xslinksLinks and inline actionsa,a:hover--accent-hoverkeyboardKeyboard hintskbd—iconsIcon slots.icon,.icon-lg—typographyTypography scale and text utilities.eyebrow,.lead,.body-muted,h1–h3--font-display,--tracking-display,--leading-tight,--text-3xllayoutLayout primitives.container,.row-between,.stack-3/4/6--container-max,--container-gutter-*,--border,--space-3/4从 components.html 的组件 CSS 可以印证这些 token 的真实消费方式.btn用border-radius: var(--radius-sm)12px、letter-spacing: 0.08px、过渡走var(--motion-fast) var(--ease-standard).btn-primary:active用var(--accent-active).field input:focus-visible走--focus-ring的 3px Airtable-Blue alpha glow.container用var(--container-max)加响应式 gutter 切换1023px / 639px 两个媒体查询分别切换到 tablet / phone gutter。这正好呼应了 DESIGN.md 的按钮规则#1b61c9底、白字、16×24px padding、12px radius、正字距。USAGE.md 的组件复用铁律是从components.manifest.json复用组件组而不是发明新控件任何不在components.html或DESIGN.md中的新组件配方都不应被添加。六、Do 与 AvoidAgent 在生成与审查时的行为边界USAGE.md 用两组清单界定了行为边界本文完整保留并补充背景应该做Do逐字保留 schema token 名保证跨品牌切换cross-brand switching的可靠性——即--accent、--fg、--muted等名字在所有品牌包中语义一致Agent 才能用同一套组件引用。用--accent表达主操作、链接、焦点态且每屏只保留一个清晰的焦点元素。DESIGN.md 的 lint 约束是每屏可见的 accent 用途 ≤2 处装饰性蓝色被禁止因为品牌把 accent 读作「这就是操作」。优先从components.manifest.json复用组件组再考虑发明新控件。把source/文件当作「打包 fixture 回填」的审计证据——它记录 token 契约的每个绑定与来源审查者应依据它核对 tokens.css 与设计文档的一致性。避免做Avoid避免在:roottoken 块之外使用裸 hex 值——颜色只能经 token 引用否则跨品牌切换会失效也逃过 lint 审计。避免独立于tokens.css重新定义 Tailwind 或 design-token 值。tailwind-v4.css 的theme块全部以var(--*)引用 tokens.css注释明确写着「Derived from tokens.css. Keep tokens.css as the source of truth」design-tokens.json同理是派生输出。避免声称有原始上游来源证据——本包基于仓库内置精选 fixturebundled没有做过上游重抓取source/evidence.md 明示这一点。避免添加components.html或DESIGN.md中不存在的组件配方。DESIGN.md 的 Dos and Donts 与之呼应要使用 Airtable Blue 做 CTA、Haas 正字距、12px 圆角按钮不要跳过正字距、不要使用厚重阴影品牌阴影是轻量多层蓝调见 §四第 4 条。七、预览与验证preview/ 与 source/ 的正确用法视觉验证preview/下的 colors.html、typography.html、spacing.html 分别渲染色板、字阶与间距刻度供人类审查者在提交 artifact 前做快速视觉 sanity check。契约审计source/token-contract.report.json把每个 TOKEN_SCHEMA 绑定映射回tokens.css的声明行source/tokens.source.json保留 fixture 的原始 tokenevidence.md 声明取证范围DESIGN.md tokens.css components.html 三个 fixture 文件。manifest.json的sourceFiles字段显式声明了这三份证据文件的路径。八、在 OpenDesign 中落地从粘贴到 guard 通过综合以上全部内容一个 Agent 在 OpenDesign 中使用该包的标准流程是按 Read Order 读取 USAGE.md → DESIGN.md将 tokens.css 的:root块原样粘贴进 artifact 首个style块56 个 token 一个不少尤其 A2 与 B-slot 不可省略否则 artifact 内var()引用静默失效依据 components.manifest.json 的 9 个分组复用组件精确状态对照 components.html遵守 accent ≤2 处、无裸 hex、无额外组件配方等约束如需 Tailwind v4通过 tailwind-v4.css 的theme引用 token绝不独立重定义提交前可用preview/页面做视觉核对用source/证据与design-tokens.json的 layer 统计核对契约完整性仓库侧由 scripts/guard.ts 注册的design system A2 required tokens、design system B-slot required tokens等 guard 以及 scripts/check-tokens-fixture-sync.ts 对每个品牌包强制执行 token 契约——这也是为什么「逐字保留 token 名」「声明每个 A2/B-slot」不是建议而是硬性约束。一句话总结这套体系Airtable 设计系统 2.0 包把「精致简洁的瑞士排版 单一蓝色强调」压缩成一份可粘贴、可 lint、可跨品牌复用的 56-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-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考