OpenDesign 中 Expo 设计系统包的使用指南：从 DESIGN.md 到 tokens.css 的完整落地实践

OpenDesign 中 Expo 设计系统包的使用指南从 DESIGN.md 到 tokens.css 的完整落地实践【免费下载链接】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在 OpenDesign 的design-systems/目录中每个品牌包都是一套可供 Coding Agent 直接消费的设计系统 2.0资产。design-systems/expo/是其中面向开发者工具品类的一个样例包它以 Expo 官网的视觉气质为蓝本将冷白画布 纯黑白灰 胶囊几何 巨型负字距标题的设计语言沉淀为DESIGN.md视觉意图、tokens.css结构化 token、components.html组件 fixture三层可执行资产。阅读本文后你将掌握该包的文件契约与推荐读取顺序、完整的设计 token 语义、组件清单的使用方式以及如何用规范的 Agent Prompt 让生成产物严格贴合 Expo 风格。一、包结构契约Design System 2.0 的固定文件约定design-systems/expo/遵循 OpenDesign 的 Design System Project 包结构约定该契约由 design-systems/_schema/AGENTS.md 定义。manifest.json是包的机器可读入口它声明了本包的来源、文件映射与预览页{ schemaVersion: od-design-system-project/v1, id: expo, name: Expo, category: Developer Tools, description: Bundled OpenDesign package for Expo, derived from curated DESIGN.md, tokens.css, and components.html fixtures., source: { type: bundled, origin: OpenDesign curated bundled fixture }, files: { design: DESIGN.md, tokens: tokens.css, designTokens: design-tokens.json, tailwind: tailwind-v4.css, components: components.html }, usage: USAGE.md, componentsManifest: components.manifest.json, importMode: normalized, craft: { suggested: [color, accessibility-baseline] }, preview: { dir: preview, pages: [colors, typography, spacing] } }包内各文件职责如下manifest.json— 机器可读的项目入口声明来源、文件映射与预览页见上DESIGN.md — 规范的设计散文视觉氛围、色彩角色、排版规则、组件样式、布局与响应式行为tokens.css — 编译后的规范 token 绑定是唯一的 token 事实来源design-tokens.json与 tailwind-v4.css — 由tokens.css派生的产物不应手工编辑components.html — 独立组件 fixture包含精确的选择器与状态components.manifest.json — 由components.htmltokens.css重建的组件清单缓存preview/— 静态预览页colors / typography / spacingsource/— 导入证据evidence.md、tokens.source.json、token-contract.report.json。需要注意source字段本包来源于 OpenDesign精选的捆绑 fixturecurated bundled fixture而非对 Expo 官网的新鲜抓取。source/evidence.md对此有明确声明——It does not claim a fresh crawl of the original upstream brand repository or website。因此在写作或评审时不要把本包描述为 Expo 官方资产的直接镜像。二、推荐的读取顺序先契约、再意图、后实现USAGE.md给出了明确的阅读路径这也是 Agent 与评审者消费本包的标准流程先读本文件USAGE.md理解包契约与边界读DESIGN.md掌握视觉意图、约束与反模式anti-patterns把tokens.css的:root块粘贴到第一个 artifact 的style块中然后再写组件 CSS —— 这是 token 生效的物理前提所有组件样式都应引用 token 变量而不是裸值用components.manifest.json快速浏览组件清单当需要精确选择器或状态细节时打开components.html需要视觉确认时查看preview/页面preview/colors.html、preview/typography.html、preview/spacing.html。这套顺序的本质是契约 → 意图 → 实现三层递进先知道能用什么token 契约再知道为什么这么设计DESIGN.md最后落到怎么写组件选择器与预览。三、设计语言核心冷白画布上的纯黑白灰与胶囊几何USAGE.md提炼了四个设计亮点DESIGN.md则给出了完整的设计意图发光冷白画布#f0f0f3Cloud Gray页面底色是带极轻微蓝紫调的暖灰白配合画廊式的超大垂直间距让每个功能区块都拥有自己的房间严格单色纯黑#000000标题 冷蓝灰#60646cSlate Gray正文界面本身几乎不出现装饰色——颜色只留给产品截图、应用图标与 React 宇宙插画全场景胶囊几何按钮、标签、容器、图片统一采用 24px–9999px 的圆角营造有机、亲和的气质刻意反叛开发者工具常见的锐利直角巨型展示标题64px 的 Display 标题配合 -1.6px 到 -3px 的极端负字距形成近乎 logotype 的致密文字块这是整套设计最具辨识度的排版签名。需要指出的是DESIGN.md描述的是参考意图如 Cloud Gray 页面底色#f0f0f3而tokens.css是结构化绑定后的实际值--bg: #ffffff、--surface: #f6f7f9、--meta: #4630eb。二者存在细微差异属于正常现象——在实现层面请始终以tokens.css为唯一事实来源这也是USAGE.mdAvoid 独立于 tokens.css 重定义 token 值的原因。DESIGN.md还给出了完整的色彩角色体系按语义分组分组角色色值用途主色Expo Black#000000标题、CTA、品牌锚点主色Near Black#1c2024正文主色比纯黑更柔和的蓝黑链接Link Cobalt#0d74ce标准链接色链接Legal Blue#476cff法律/页脚链接链接Widget Sky#47c2ffWidget 品牌元素预览Preview Purple#8145b5预览/测试版指示器表面Cloud Gray / Pure White#f0f0f3/#ffffff页面底 / 卡片表面文本Slate Gray / Mid Slate / Silver#60646c/#555860/#b0b4ba次级 / 强调 / 三级文本语义Warning Amber / Destructive Rose#ab6400/#eb8e90警告 / 禁用态破坏性操作一个值得注意的设计决策是界面层无渐变视觉丰富度完全来自产品截图、插画与克制的阴影分层没有渐变本身就是设计决策。四、排版规则单一字体族 权重即层级排版上Expo 包坚持一种字体完整表达无衬线族仅用Inter权重 400–900系统回退为-apple-system, system-ui等宽族用JetBrains Mono回退ui-monospace用于代码块与终端命令极端负字距只保留给 Display64px 标题使用 -1.6px 至 -3px正文不得宽于 -0.25px行高统一 1.40几乎所有正文与 UI 文本共享 1.40 行高形成节奏上的垂直一致性权重即层级Display 用 700–900Section 标题 600强调 500正文 400层级跳变果断、无模糊中间值。具体层级速查来自DESIGN.md排版表角色字号字重行高字距Display / Hero64px (4rem)700–9001.10-1.6px ~ -3pxSection Heading48px (3rem)6001.10-2pxSub-heading20px (1.25rem)6001.20-0.25pxBody Large18px (1.13rem)400–5001.40normalBody / Button16px (1rem)400–7001.25–1.40normalCaption / Label14px (0.88rem)400–6001.00–1.40normalTag / Small12px (0.75rem)5001.00–1.60normalCode Body / Caption / Small16/14/12px400–6001.40 / 1.40 / 1.60normal五、Token 系统tokens.css 的完整语义与契约约束tokens.css是这套设计的结构化工序它将DESIGN.md的意图编译为一组可复制的 CSS 自定义属性。完整的:root块共约 60 个 token可按语义分组色彩类--bg: #ffffff; /* 页面底色 */ --surface: #f6f7f9; /* 卡片表面 */ --surface-warm: #eef2ff; /* 暖色表面B-slot */ --fg: #0b0d12; /* 前景主色 */ --fg-2: #353945; /* 次级前景B-slot */ --muted: #6b7280; /* 弱化文本 */ --meta: #4630eb; /* 品牌强调/眉题eyebrow */ --border: #dfe3ea; /* 标准边框 */ --border-soft: #edf0f5; /* 柔和边框B-slot */ --accent: #000020; /* 强调色近黑 */ --accent-on: #ffffff; /* 强调色上的前景 */ --accent-hover: color-mix(in oklab, var(--accent), black 8%); --accent-active: color-mix(in oklab, var(--accent), black 14%); --success: #00a36c; --warn: #f59e0b; --danger: #e5484d;字体与文本--font-display: Inter, system-ui, sans-serif; --font-body: Inter, system-ui, sans-serif; --font-mono: Geist Mono, SF Mono, ui-monospace, Menlo, monospace; --text-xs: 12px; --text-sm: 14px; --text-base: 16px; --text-lg: 18px; --text-xl: 22px; --text-2xl: 32px; --text-3xl: 48px; --text-4xl: 68px; --leading-body: 1.52; --leading-tight: 1.06; --tracking-display: -0.025em;间距、圆角、阴影与运动--space-1: 4px; --space-2: 8px; --space-3: 12px; --space-4: 16px; --space-5: 20px; --space-6: 24px; --space-8: 32px; --space-12: 48px; --section-y-desktop: 96px; --section-y-tablet: 68px; --section-y-phone: 48px; --radius-sm: 8px; --radius-md: 14px; --radius-lg: 22px; --radius-pill: 9999px; --elev-flat: none; --elev-ring: 0 0 0 1px var(--border); --elev-raised: 0 18px 48px rgba(0, 0, 32, 0.12); --focus-ring: 0 0 0 4px rgba(70, 48, 235, 0.24); --motion-fast: 140ms; --motion-base: 220ms; --ease-standard: cubic-bezier(0.2, 0, 0, 1); --container-max: 1160px; --container-gutter-desktop: 32px; --container-gutter-tablet: 24px; --container-gutter-phone: 16px;值得注意的实现细节强调色是近黑而非纯黑--accent: #000020配合color-mix(in oklab, ...)派生的 hover/active 态比硬编码三份色值更易维护间距是 4px 基数上的阶梯4/8/12/16/20/24/32/48与DESIGN.md的 8px 基数描述略有出入以 tokens 为准区块纵向节奏内置为三个断点值--section-y-desktop/tablet/phone分别对应 96/68/48px直接支撑画廊式呼吸感层级阴影体系--elev-ring1px 边框环与--elev-raised0 18px 48px rgba(0,0,32,0.12)的柔和大阴影——遵循阴影是低语的哲学。components.manifest.json对 token 契约做了机器化校验其tokens字段列出了全部 57 个声明 token 与 49 个被引用 token并标注了unusedDeclared如--danger、--warn、--space-1等声明但未被当前组件引用的 token与undeclaredReferenced为空说明没有悬空引用。从源码结构看这份 manifest 是可重建缓存——由components.html与tokens.css派生而来由仓库守卫脚本校验不应手工维护。派生产物design-tokens.json 与 tailwind-v4.csstokens.css是唯一事实来源其余两份是派生输出design-tokens.json从tokens.css加source/token-contract.report.json派生tailwind-v4.cssTailwind v4 的theme绑定。它先import ./tokens.css再把每个 token 映射为 Tailwind 主题变量例如theme { --color-bg: var(--bg); --color-accent: var(--accent); --color-accent-on: var(--accent-on); --font-sans: var(--font-body); --text-4xl: var(--text-4xl); --spacing-section-desktop: var(--section-y-desktop); --radius-pill: var(--radius-pill); --shadow-raised: var(--elev-raised); --duration-fast: var(--motion-fast); --ease-standard: var(--ease-standard); --container-max: var(--container-max); --spacing-container-desktop: var(--container-gutter-desktop); }这样在 Tailwind 项目中可以直接使用bg-accent、text-4xl、rounded-pill、shadow-raised等工具类且底层值始终来自tokens.css不会出现双源漂移。六、组件清单先复用、后发明USAGE.md的核心理念之一是从components.manifest.json复用组件组而不是发明新控件。该 manifest 对components.htmlfixture 做了结构化统计1 个style块、48 个选择器、26 个类、19 个元素并按功能分组分组状态关键选择器 / 类主要 token 引用buttonspresent.btn,.btn-primary,.btn-secondary,.btn:focus-visible--accent,--accent-on,--elev-ring,--radius-md,--motion-fastinputspresent.field,input,input:focus,label--border,--radius-sm,--surfacecardspresent.card-row,.panel,.panel-head,.tile--elev-raised,--radius-lg,--surfacebadgespresent.status—linkspresenta—typographypresent.eyebrow,.lead,h1,h2,h3--meta,--text-4xl,--text-xllayoutpresent.container,section,.metric-grid--container-gutter-*,--section-y-desktopkeyboard / iconsabsent——从components.html的实现可以印证几处关键 token 的用法.btn { display: inline-flex; align-items: center; justify-content: center; min-height: 44px; padding: 0 var(--space-5); border: 1px solid transparent; border-radius: var(--radius-md); font: 700 var(--text-sm) / 1 var(--font-body); transition: background-color var(--motion-fast) var(--ease-standard), border-color var(--motion-fast) var(--ease-standard), color var(--motion-fast) var(--ease-standard), transform var(--motion-fast) var(--ease-standard); }这段实现同时展示了三个设计原则44px 最小触达高度贴合DESIGN.md的最小触达目标建议、--space-5驱动的紧凑横向内边距高度由行高决定、以及--motion-fast--ease-standard统一的动效节奏。.eyebrow眉题则使用--meta紫色、--font-mono等宽字体、12px、0.12em 字距加全大写构成开发者工具特有的技术标签气质。七、使用规范Do 与 Avoid继承并展开USAGE.md明确列出的纪律是评审与生成的最重要边界展开如下应该做Do严格保留 schema token 名称保证跨品牌切换cross-brand switching可靠——token 名即契约用--accent表达主操作、链接、焦点态与唯一焦点元素整套系统中--accent近黑承担权威感不允许在它之外再引入更亮的主色优先复用components.manifest.json中的组件组再考虑发明新控件把source/文件当作捆绑 fixture 回填的审计证据source/evidence.md、source/tokens.source.json、source/token-contract.report.json记录了 token 契约与声明行的映射关系。避免做Avoid不要在复制的:roottoken 块之外使用裸十六进制色值不要独立于tokens.css重定义 Tailwind 或 design-token 值这正是tailwind-v4.css只做var()映射的原因不要声称存在原始上游来源证据——本包基于精选捆绑 fixturesource/evidence.md明确不声称对 Expo 官网的新鲜抓取不要添加components.html或DESIGN.md中不存在的组件配方。此外DESIGN.md的 Dont 清单还补充了视觉层禁令交互元素圆角不得小于 6px、区块间距不得小于 64px、不使用厚重投影、不混入第二套字体、正文字距不超过 -0.25px、边框不超过 2px、界面不加渐变、非语义场景不使用饱和色。八、响应式与布局原则DESIGN.md定义了断点与降级策略components.html的实现与之对应断点宽度关键变化Mobile640px单列、汉堡导航、卡片堆叠、Hero 标题缩至约 36pxTablet640–1024px双列网格、紧凑导航、中等 HeroDesktop1024px多列布局、展开导航、64px 巨型 Hero从components.html看响应式通过断点 token 实现section { padding-block: var(--section-y-desktop); } media (max-width: 1023px) { .container { padding-inline: var(--container-gutter-tablet); } section { padding-block: var(--section-y-tablet); } } media (max-width: 639px) { .container { padding-inline: var(--container-gutter-phone); } section { padding-block: var(--section-y-phone); } }DESIGN.md还提示仅检测到一个显式断点640px推测实际体系更可能依赖 fluid / container-query /clamp()而非固定断点快照而components.html中实际出现了 640px 与 1023px 两档媒体查询——以实现为准。间距体系方面基础单位为 8px卡片内边距约 24–32px区块垂直间距 96–144px最大容器宽度约 1200–1400pxtokens 中--container-max: 1160px。九、Agent Prompt 指南把规范变成可复制的指令DESIGN.md的最后一节专门为 Agent 提供了可直接复制的 Prompt 配方这是将本包用于实际生成的关键快速色彩速查Prompt 用语主 CTA / 标题Expo Black#000000页面背景Cloud Gray#f0f0f3卡片表面Pure White#ffffff正文Near Black#1c2024次级文本Slate Gray#60646c边框Border Lavender#e0e1e6链接Link Cobalt#0d74ce三级文本Silver#b0b4ba示例组件 PromptHero 区Create a hero section on Cloud Gray (#f0f0f3) with a massive headline at 64px Inter weight 700, line-height 1.10, letter-spacing -3px. Text in Expo Black (#000000). Below, add a subtitle in Slate Gray (#60646c) at 18px. Place a black pill-shaped CTA button (9999px radius) beneath.功能卡片Design a feature card on Pure White (#ffffff) with a 1px solid Border Lavender (#e0e1e6) border and comfortably rounded corners (8px). Title in Near Black (#1c2024) at 20px Inter weight 600, description in Slate Gray (#60646c) at 16px. Add a whisper shadow (rgba(0,0,0,0.08) 0px 3px 6px).导航栏Build a navigation bar with Expo logo on the left, text links in Near Black (#1c2024) at 14px Inter weight 500, and a black pill CTA button on the right. Background: transparent with blur backdrop. Bottom border: 1px solid Border Lavender (#e0e1e6).迭代指南Iteration Guide一次只聚焦一个组件引用具体色名与十六进制值——use Slate Gray (#60646c)而非make it gray刻意使用圆角值——按钮 6px、卡片 8px、图片 24px、胶囊 9999px在数值之外描述感受——enormous breathing room with 96px section spacing始终指定 Inter 及精确字重——权重对比即层级阴影使用whisper shadow或standard elevation等术语对应 elevation 表保持界面单色——让产品内容成为色彩来源。十、验证与质量保障从仓库的契约体系看本包的质量保障由多个层面构成manifest 守卫manifest.json存在的包会被scripts/check-design-system-manifests.ts校验要求声明的路径安全且存在、JSON 索引可解析、components.manifest.json与从components.htmltokens.css的重新派生一致token 契约守卫source/token-contract.report.json将每个 TOKEN_SCHEMA 绑定映射回tokens.css的声明行design-tokens.json与tailwind-v4.css都应由报告与 token 样式表重新生成而非手工编辑见 source/evidence.md守卫命令修改 token schema 后需运行pnpm guard确认捆绑目录仍通过全部 design-system 子检查见 design-systems/_schema/AGENTS.md视觉预览preview/colors.html、preview/typography.html、preview/spacing.html三页分别展示色彩、排版与间距的落地效果供人工目检。结语design-systems/expo/是 OpenDesign Design System 2.0 包机制的一个完整样例USAGE.md定义了消费契约DESIGN.md承载视觉意图tokens.css提供唯一的 token 事实来源components.html与components.manifest.json固化组件实现与清单preview/与source/则分别承担视觉确认与证据追溯。无论你是要基于该包生成 Expo 风格的原型、落地页还是仪表盘正确的做法都是先读契约、粘贴:roottoken 块、复用组件清单、严守 Do/Avoid 边界再让 Agent 按 Prompt 指南逐组件迭代——这套流程同样适用于design-systems/下其他任意品牌包。【免费下载链接】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），仅供参考