open-design 中的 shadcn 设计系统从 DESIGN.md 到 tokens.css 的最小化现代 UI 规范实战指南【免费下载链接】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导读本文围绕 open-design 仓库内design-systems/shadcn/这一 Design System 2.0 包展开讲解以 shadcn/ui 为灵感来源的现代 极简设计语言如何在 AI Agent 生成前端原型、落地页、仪表盘等 artifact 时落地一套以纯黑主色、单色中性色阶、utility-first 为特征的设计系统。读完本文你将掌握该包从DESIGN.md视觉意图、tokens.cssToken 绑定到components.manifest.json组件清单的完整链路并理解 open-design 的 Token 分层架构如何保证跨品牌切换的可靠性。一、包概览shadcn 设计系统在仓库中的定位在 open-design 仓库中design-systems/目录收纳了上百个品牌级设计系统包airbnb、apple、stripe、notion 等每个包遵循统一的 Design System 2.0 契约。shadcn 包归类为Modern Minimal现代 极简其 manifest.json 定义了包的完整构成DESIGN.md视觉意图、约束与反模式本文的核心主体tokens.css编译后的 Token 绑定是生成 artifact 时真正要粘贴的内容design-tokens.json按 TOKEN_SCHEMA 契约生成的 Token 清单与审计报告tailwind-v4.cssTailwind v4 主题映射文件components.htmlcomponents.manifest.json参考组件实现与组件清单preview/colors / typography / spacing 三个可视化检查页source/来源证据evidence.md、token-contract.report.json、tokens.source.json。该包被标记为source: { type: bundled, origin: OpenDesign curated bundled fixture }即由仓库内的精选 fixture 生成并不声称爬取了上游 shadcn 官网或仓库见 source/evidence.md 的说明。二、视觉主题与氛围少即是多的设计意图DESIGN.md 第一节明确了本设计系统的核心定位Shadcn/ui-inspired design with minimal, clean components, monochrome palette, and utility-first patterns.视觉风格极简、干净minimal, clean色彩立场primary / secondary 两级主次结构设计意图让输出保持对该风格家族的辨识度同时不牺牲可用性与可读性。这与 shadcn/ui 作为被成千上万团队扩展的平静中性基线的定位一致——shadcn 刻意不是一种大声的品牌身份而是提供 zinc/slate 中性色、近黑主色、8px 默认圆角、克制的间距以及无障碍硬性要求可见焦点、AA 对比度、语义状态色。这些描述直接体现在 tokens.css 的文件头注释中说明该 Token 文件正是把 DESIGN.md 的意图预编译进共享 Schema 的产物。三、颜色单色中性系统与纯黑即强调3.1 调色板继承自 DESIGN.md §2角色色值语义Primary主色#000000CTA 强调色唯一的高光时刻Secondary次色#111111次强调Success#16A34A成功状态Warning#D97706警告状态Danger#DC2626危险状态Surface#FFFFFF大背景与卡片Text#111827正文文本Neutral#FFFFFF由 Surface 派生保证官方格式兼容3.2 使用规则用 Primary#000000做 CTA 强调用 Surface#FFFFFF做大面积背景与卡片正文保持 Text#111827以保证可读性。3.3 源码级佐证为什么正文不用纯黑从 tokens.css 的注释可以读到三条关键设计决策--accent是#000000而非彩色色相。shadcn 的主按钮就是白底纯黑这本身就是强调时刻。由于纯黑无法再变暗--accent-hover与--accent-active通过color-mix(in oklab, var(--accent), white 10%/18%)向白色混合约#1a1a1a/#2e2e2e复刻了 shadcn 惯例bg-primary hover:bg-primary/90——悬停时提亮填充而非压暗。--fg是#111827Tailwind slate-900而非#000000。纯黑正文配纯白底会显得生硬略微偏冷的 slate 底色是 shadcn 中性系统的一部分同时把正文与决定性 CTA在语义上分离。--fg-2、--meta、--surface-warm、--border-soft通过var()折叠到同族 Token。shadcn 是单色基线一层前景、一层画布、一层边框。扩展主题如 Warm 主题可以独立重绑定这些插槽共享组件依然能解析完整渐变。对应的真实声明如下节选自 tokens.css:root { --bg: #ffffff; --surface: #ffffff; --surface-warm: var(--surface); --fg: #111827; /* slate-900 — body text */ --fg-2: var(--fg); --muted: #64748b; /* slate-500 — captions */ --meta: var(--muted); --border: #e5e7eb; /* slate-200 — card edge */ --border-soft: var(--border); --accent: #000000; --accent-on: #ffffff; --accent-hover: color-mix(in oklab, var(--accent), white 10%); --accent-active: color-mix(in oklab, var(--accent), white 18%); --success: #16a34a; --warn: #d97706; --danger: #dc2626; }语义色success/warn/danger只用于状态徽章、校验提示不作为装饰填充且要求任何表面上的语义色像素占比不超过 5%。四、排版Geist 与 Fira Code 的克制字阶4.1 字阶与字族继承自 DESIGN.md §3字阶 Scale12 / 14 / 16 / 20 / 24 / 32字族primaryGeistdisplayGeistmonoFira Code字重100900 全档位标题应承载风格个性正文应优先可扫读性与对比度。4.2 tokens.css 中的完整排版 Tokentokens.css 在 DESIGN.md 基础上把字阶扩展至 40/48用于营销 Hero 场景同时保持克制Token值用途--font-display/--font-bodyGeist, Geist Sans, -apple-system, system-ui, Segoe UI, Arial, sans-serif标题与正文--font-monoFira Code, ui-monospace, SF Mono, JetBrains Mono, Menlo, Monaco, Consolas, monospace代码块、kbd--text-xs--text-4xl12px / 14px / 16px / 20px / 24px / 32px / 40px / 48px从 caption 到 display hero--leading-body1.5正文行高--leading-tight1.2标题行高--tracking-display-0.02em标题字距两个值得注意的细节--tracking-display保持温和的-0.02em刻意避开 Vercel 等品牌语音系统惯用的-0.05em激进压缩——shadcn 是低语不是呐喊tokens.css 原注Geist 与 Fira Code 均通过操作系统回退栈引用即使字体未加载artifact 也能以可接受的样式渲染需要真实字体时由宿主页面外部引入。五、间距与网格4px 基线与节律DESIGN.md §4 要求间距刻度4 / 8 / 12 / 16 / 24 / 32跨区块与组件保持一致的垂直节律列与模块对齐到可预测的网格避免临时偏移。tokens.css 按 Schema 要求补齐到 8 档追加 20px 与 48pxTailwind 用户可无翻译地对应space-1→space-12--space-1: 4px; --space-2: 8px; --space-3: 12px; --space-4: 16px; --space-5: 20px; --space-6: 24px; --space-8: 32px; --space-12: 48px;同时定义了响应式区块纵向节律桌面 96px对应 shadcn 营销页的py-24、平板 64px、手机 48px——慷慨但绝不空洞。六、布局与构图清晰的层次与留白优先DESIGN.md §5 的构图原则优先使用带一致内边距的清晰内容块层次保持明显大标题 → 支撑文案 → 主操作headline → support text → primary action先用留白区隔内容再考虑边框或阴影。布局 Token 在 tokens.css 中落地为--container-max: 1280px即max-w-7xlshadcn 营销页的标准宽度、桌面 24px / 平板与手机 16px 的容器 gutter手机端收窄但永不塌缩为 0保证正文缩进可见。七、组件从按钮到键盘提示的完整清单DESIGN.md §6 对核心组件提出要求按钮主操作使用#000000次操作保持中性输入框强 focus-visible 状态、清晰 label、可预期的错误提示卡片/区块跨页面保持一致圆角、间距与层级策略。7.1 components.manifest.json九大组件组components.manifest.json 把参考实现 components.html 中的 68 个选择器、32 个类整理为 9 个组件组并逐一标注其引用的 Token组件组关键类引用 Tokenbuttons按钮与 CTA.btn-primary/.btn-secondary/.btn-ghost--accent-hover、--focus-ring、--space-3inputs表单控件.field/.field-help/.form-row--border、--radius-sm、--muted、--motion-fastcards卡片面板.card--fgbadges徽章状态.badge-default/.badge-secondary/.badge-success/.badge-dot/.badge-outline--accent、--accent-on、--borderlinks行内链接a及 hover/focus-visible—keyboard键盘提示kbd--font-mono、--radius-sm、--text-xsicons图标槽位.iconsvg—typography文字工具类.body-muted/.body-sm/.eyebrow--tracking-display、--leading-tight、--mutedlayout布局原语.container/.row-between/.stack-*--container-max、--space-*清单中还给出了 fixture 统计1 个 style 块、68 选择器、26 元素与 Token 使用分析unusedDeclared列出的--danger、--elev-ring等 Token 在当前参考页中未被引用属于为完整渐变预留的声明而undeclaredReferenced为空说明组件页没有引用任何未声明的 Token——这是契约自洽性的直接证据。7.2 焦点环shadcn 的标志性签名tokens.css 对焦点态给出了组件实现层面的强约束--focus-ring: 0 0 0 2px var(--bg), 0 0 0 4px var(--accent);这是 Tailwind 工具类ring-2 ring-offset-2的等价物2px 画布色光晕偏移 2px 主色环焦点指示用分层 box-shadow 表达因此在深色表面、玻璃表面和滚动容器内都不会出现 outline-offset 裁剪问题。这正是 DESIGN.md §6 strong focus-visible states 的具体落地规则。八、动效与交互短暂而有目的DESIGN.md §7 的动效原则用微妙过渡强调 Primary#000000作为交互信号默认使用 150–250ms 的短促、有目的的过渡与稳定缓动hover、focus-visible、active、disabled、loading 五种状态必须显式定义。tokens.css 将其收敛为两个时长 一条缓动曲线--motion-fast: 150ms; --motion-base: 200ms; --ease-standard: cubic-bezier(0.2, 0, 0, 1);shadcn 原语快速且不引人注目绝不做长时间编排式入场动画。九、语调与品牌简明、自信、产品化DESIGN.md §8 对文案语调的要求语气与视觉风格一致简明、自信、贴近产品微文案microcopy以行动为导向避免空泛套话标题保留风格个性UI 标签保持字面化、清晰。十、反模式九条红线继承自 DESIGN.md §9以下行为在生成 shadcn 风格 artifact 时严禁出现在已有 Token 可解决问题时引入调色板之外的裸色值对所有文本使用相同的字号/字重抹平层级添加降低可读性或可访问性的装饰效果在同一界面混用互不相关的视觉隐喻来自 USAGE.md 的补充在复制的:rootToken 块之外使用裸 hex 值脱离tokens.css独立重定义 Tailwind 或设计 Token 值声称存在上游原始来源证据本包基于精选的 bundled fixture添加未在components.html或DESIGN.md中体现的新组件配方。十一、Agent 实操如何在生成 artifact 时使用该包USAGE.md 是给 OpenDesign Agent 与评审者的使用契约推荐阅读顺序如下先读 USAGE.md 理解包契约再读 DESIGN.md 获取视觉意图、约束与反模式把 tokens.css 的:root块原样粘贴进第一个 artifact 的style块之后再写组件 CSS用 components.manifest.json 做紧凑组件盘点当需要精确选择器或状态时打开 components.html需要视觉检查时查看preview/页面colors.html、typography.html、spacing.html。11.1 三条务必Do原样保留 Schema Token 名称跨品牌切换才可靠用--accent承担主操作、链接、焦点态以及唯一清晰焦点元素优先复用components.manifest.json中的组件组而非自创控件把source/文件当作 fixture 回填的审计证据。11.2 Tailwind v4 映射若产物使用 Tailwind v4可导入 tailwind-v4.css。该文件以tokens.css为唯一事实来源通过theme块把每个 Token 映射为 Tailwind 命名空间颜色--color-bg、--color-surface、--color-fg、--color-accent、--color-muted等字体--font-display、--font-sans、--font-mono字号--text-xs--text-4xl间距--spacing-1--spacing-12及--spacing-section-*圆角--radius-sm/md/lg/pill阴影--shadow-flat/ring/raised/focus-ring动效--duration-fast/base、--ease-standard布局--container-max、--spacing-container-*。注意该文件头注释明确它由 tokens.css 派生应保持 tokens.css 为唯一事实来源不要手工编辑。十二、Token 分层架构跨品牌契约的底层原理shadcn 包的 Token 之所以能可靠地在数百个品牌间切换依赖 open-design 的 TOKEN_SCHEMA 分层契约定义见 token-schema.ts由 design-systems/_schema/tokens.schema.ts 再导出共五层A1-identity必填Token 即品牌本身无可替代的 fallback——--bg、--fg、--accent、字体栈A1-structure必填结构决策字阶、布局网格、区块节律无跨品牌通用默认值A2最终 tokens.css 中必填但 defaults.css 提供合理回退如--success、--radius-*、--motion-*B-slot可选插槽如--surface-warm、--fg-2、--meta、--border-soft品牌可var()别名到同族 TokenC-extension品牌专属需白名单通用跨品牌组件不得引用。Schema 特别解释了 A2 为何是带回退的必填而非可选artifact 由 Agent 把单个品牌的:root块粘贴进单个style不存在全局默认样式表的运行时级联。若粘贴的 tokens.css 缺失某个var()目标产物将直接损坏如transition: var(--motion-fast)变成transition:而被丢弃。12.1 shadcn 的 Token 审计结果design-tokens.json 是对该包 Token 的自动化审计共 56 个 Token全部有来源背书sourceBackedTokens: 56其中 A1-identity 8 个、A1-structure 18 个、A2 26 个、B-slot 4 个审计评分 100、评级excellentrecommendRebuild: false。每个 Token 都带有sources字段精确指向 tokens.css 的声明行号如--bg→tokens.css:95。配套的 source/token-contract.report.json 把每个 TOKEN_SCHEMA 绑定映射回提交的 tokens.css 声明行design-tokens.json与tailwind-v4.css均为派生产物应由报告与 Token 样式表重新生成而非手工编辑。此外 system/tokens.default.json 以精简结构暴露了品牌核心值colorPrimary: #000000、colorPrimaryHover/Active的 color-mix 表达式、fontSize: 16、borderRadius: 8可作为程序化消费入口。十三、验证链路如何确认产物符合 shadcn 契约生成 artifact 后可沿以下路径做事实核查Token 完整性比对components.manifest.json的undeclaredReferenced是否为空组件不得引用未声明 Token来源行号核对design-tokens.json每个 Token 的sources行号与 tokens.css 实际声明是否一致视觉抽检打开preview/三个页面核对颜色、字阶、间距的渲染是否符合预期反模式自查对照第十节九条红线逐条检查——尤其是是否引入了调色板外裸色值焦点态是否可见是否混用视觉隐喻。整体而言shadcn 包是 open-design Design System 2.0 体系中契约驱动生成的典型样本一份 71 行的 DESIGN.md 视觉规范经过 Token 化编译、Schema 校验与组件 fixture 落地最终变成 Agent 可直接粘贴进 artifact 的完整设计系统。理解它的分层与验证机制也就理解了 open-design 让编码 Agent 稳定输出品牌一致 UI 的核心方法。【免费下载链接】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），仅供参考