企业官网建设流程全解析

Open Mercato 设计系统详解：OKLCH 令牌、shadcn/ui 与 Figma Code Connect 完整指南

【免费下载链接】open-mercatoThe AI-Engineering Foundation Framework for CRM/ERP and commerce: open-source TypeScript, with multi-tenancy, RBAC, events and domain modules already decided as conventions and specs, so Cursor, Claude Code and Codex build features instead of re-deciding architecture. Start with 80% done.项目地址: https://gitcode.com/GitHub_Trending/op/open-mercato

Open Mercato 是一个面向 CRM/ERP 与商务场景的开源 AI 工程框架，其设计系统基于 OKLCH 色彩令牌、shadcn/ui 组件库与 Figma Code Connect 打通设计到代码的全链路。本文带你快速读懂这套设计系统的三层架构：令牌怎么定、组件怎么建、设计稿如何自动变成代码 🎨

为什么需要一套设计系统？

在审计了160 个页面、34 个模块后，团队发现了这些典型问题：

• 372 处硬编码颜色——每位贡献者都在"凭感觉猜色"
• 61 种随意的文字大小——text-[11px]、text-xs、text-[12px]三种方式表达同一种"小字"
• 深色模式下语义色彻底失效

完整审计结论见 audit.md，8 条设计原则见 principles.md。

一、OKLCH 令牌：用感知均匀的颜色空间定义语义色

什么是 OKLCH，为什么弃用 HSL？

OKLCH 是一种感知均匀的颜色空间：相同数值变化对应相同的视觉变化。这意味着"错误红"在浅色和深色背景下可以有完全不同的数值，但视觉权重保持一致——这正是 HSL 做不到的。

核心决策：扁平令牌（Flat Tokens）

设计系统做了一个关键架构决策：每个语义角色一个独立 CSS 变量，浅色/深色各给一套完整值，而不是"一个基础色 + 透明度"：

为什么不用透明度方案（如bg-status-error/5）？因为 5% 透明度的红色在白底上是淡粉色，在纯黑底上却几乎看不见——透明度无法控制深色模式的对比度。

色相角不是拍脑袋定的

四类状态色的色相角直接复用现有图表配色，保证全局一致性：

• 🔴 错误 ≈ 25°（取自--destructive）
• 🟢 成功 ≈ 160°（取自--chart-emerald）
• 🟡 警告 ≈ 80°（取自--chart-amber）
• 🔵 信息 ≈ 260°（取自--chart-blue）

所有文字/背景组合都经过WCAG AA 4.5:1 对比度校验，具体数值表见 token-values.md。

二、组件层：shadcn/ui + Radix + CVA 的黄金组合

技术栈分工

组件库位于 packages/ui/，三者各司其职：

22+ 个核心组件

src/primitives/目录下沉淀了按钮、状态徽章、表单字段、日期选择器、命令菜单等常用原语，其中 button.tsx 与 status-badge.tsx 是最常被复用的两个。

组件的优先级、迁移状态见 components.md，每个组件的 Props 规范见 component-apis.md。

三、Figma Code Connect：设计稿自动变代码

它解决什么问题？

传统流程里，设计师在 Figma 画一个按钮，开发者手写一个同名组件，两边靠口头对齐属性名。Code Connect 在 Figma 组件与真实代码组件之间建立显式映射：在 Figma 中复制组件时，粘贴出来的就是可直接运行的 React 代码。

映射长什么样？

每个*.figma.tsx文件声明"Figma 属性名 → 代码属性值"的转换规则。以 button.figma.tsx 为例：

• Figma 的Variant=Primary→ 代码variant='default'
• Figma 的Size=Small→ 代码size='sm'
• Figma 的Disabled=true→ 代码disabled

figma.config.json 指定了映射文件的扫描范围，覆盖 Button、Badge、StatusBadge、Drawer、Tabs 等11 个高频组件。

设计到交付的闭环

Figma 设计稿 → Code Connect 映射 → 复制即得真实代码 → ESLint 强制令牌用法

最后一步的"强制"由 6 条结构化 ESLint 规则实现（插件位于 packages/eslint-plugin-ds/），规则清单见 lint-rules.md，迁移工具链见 enforcement.md。

新手上手路径：3 步参与设计系统

1. 读 2 分钟：从 executive-summary.md 了解全局结论
2. 建模块前：阅读 onboarding-guide.md，按页面模板与反模式清单开发
3. 改颜色前：对照 migration-tables.md 的映射表，把旧色值换成语义令牌

总结

Open Mercato 的设计系统是一套可运行的工程实践：

• ✅OKLCH 扁平令牌——深色模式对比度可控，告别 372 处硬编码颜色
• ✅shadcn/ui + Radix + CVA——可访问性与变体管理开箱即用
• ✅Figma Code Connect——设计稿复制粘贴即得真代码，设计与开发零翻译损耗

如果你想深入了解 7 层覆盖框架与治理策略，完整文档索引在 docs/design-system/README.md，架构决策记录见 decision-log.md。🚀

【免费下载链接】open-mercatoThe AI-Engineering Foundation Framework for CRM/ERP and commerce: open-source TypeScript, with multi-tenancy, RBAC, events and domain modules already decided as conventions and specs, so Cursor, Claude Code and Codex build features instead of re-deciding architecture. Start with 80% done.项目地址: https://gitcode.com/GitHub_Trending/op/open-mercato