总则Foundations

橙智合的产品横跨管理系统、APP 与小程序。这套规范的目标不是让三端长得一模一样 —— 那既做不到也不该做 —— 而是让它们用同一套决策依据：同一份色彩语义、同一套间距节奏、同一组状态表达。平台差异只体现在交互形态和尺寸上。

四条设计原则

三端一致与差异

色彩Color

点击任意色块复制其 token 名。所有颜色只能通过 token 引用， 代码里不允许出现裸十六进制色值 —— 这是全端换肤和暗色模式能生效的前提。

品牌橙

主色取 #F05A00。之所以不用更亮的 #FF6A00：亮橙配白字对比度只有 2.87:1， 主按钮在 WCAG 下不合格；#F05A00 是 3.40:1，过了非文本对比门槛，视觉上仍是饱和活力橙。 需要更亮的橙做品牌表达（Logo、插画、渐变）时用 orange-5。

中性灰

中性色带极轻微暖调（偏黄 2–3 度），和橙色主色同处一屏时不会显脏。灰阶承担 90% 的界面面积。

功能色

警告色用琥珀而非橙 —— 橙色已是主色，若警告也用橙，用户无法区分「这是主要操作」和「这里有风险」。 规范上进一步限制：警告态不使用实心按钮，只以浅底 + 深字 + 图标出现。

语义 token

业务代码只允许使用语义 token（下方这层），不允许直接引用上面的原色刻度。原色刻度是给设计系统内部换算用的。

可读性底线

图表配色

8 色循环，已按相邻色相拉开距离；超过 8 个系列请改用分组或明度渐变，不要继续加色。

文字Typography

中文优先的字体栈，不引入 Web Font —— 中文字体包动辄数 MB，管理系统首屏收益为负。 字重只用 400 / 500 / 600：PingFang SC 没有 700，强行加粗会触发浏览器合成假粗体，中文笔画会糊。

管理系统排版级别

移动端排版级别

移动端字号用 px 而非 rpx：rpx 会随屏宽等比放大，大屏手机上中文会膨胀到失衡。布局尺寸才用 rpx。

数字

所有表格、金额、统计数字必须开等宽数字 font-variant-numeric: tabular-nums， 否则数值刷新时列宽会跳动。规范里已在 .czh-table 和 .czh-num 默认开启。

间距与布局Spacing & Layout

4px 基准栅格。所有内外边距、组件间隙都必须落在这个刻度上，不允许出现 7px、15px 这类自由值。

使用约定

断点

管理系统按 1280 设计，向下适配到 1024；低于 1024 折叠侧边栏。移动端按 375 设计（750 设计稿）。

圆角 · 阴影 · 动效Shape, Elevation & Motion

圆角

Web 端克制（控件 6px / 卡片 8px），移动端放大（控件 8px / 卡片 12–16px）—— 触摸界面圆角更大看起来更「可按」。

阴影

阴影只用来表达层级，不用来装饰。同一层级的元素阴影必须一致；平铺在页面上的卡片一律用边框而非阴影。

动效

动效服务于「让用户看清发生了什么」。超过 320ms 的过渡在管理系统里都是负担。已全局适配 prefers-reduced-motion。

缓动

图标Iconography

线性风格，24×24 网格绘制，描边 1.6px，端点与拐角圆头。不混用面性与线性图标。 同一屏内图标只使用一个尺寸档位；图标必须与文字基线对齐，不允许居中偏移。

按钮Button

一屏之内只允许一个主按钮。如果你觉得需要两个，说明这一屏承担了两件事，应该拆开。

表单与输入Form & Input

标签一律置顶左对齐 —— 左侧对齐标签在中文长度不一时会造成参差，且响应式下必须重排。 校验在失焦时触发，不在输入过程中打断用户。

反馈与状态Feedback & Status

四种状态必须全部设计到位：加载中、空、出错、无权限。缺任何一种，都会在真实数据下暴露成白屏。

数据展示Data Display

管理系统Admin Console

布局固定：左侧栏 200–240px + 顶栏 56px + 内容区。内容区最大宽度不设限但表格列需可横向滚动。 面包屑放在内容区顶部而非顶栏 —— 顶栏归属全局，面包屑归属当前页。

关键约定

APP / 小程序Mobile

按 375pt 设计（750 设计稿，1px = 2rpx）。最小触达区域 44×44pt，这是 iOS HIG 与 Material 的共同下限， 也是国内小程序审核的隐性红线。底部必须留出 safe-area-inset-bottom。

关键约定

接入方式Adoption

所有平台的主题文件都由 tokens/czh.tokens.json 生成。改色只改这一个 JSON， 跑 node tokens/build.mjs，四端同时更新。构建时会自动校验对比度，不达标直接失败。

Vue 3 + Element Plus

// main.ts —— 顺序不能变，橙智合主题必须在 element 之后
import 'element-plus/dist/index.css';
import 'element-plus/theme-chalk/dark/css-vars.css';   // 需要暗色时
import '@czh/design/dist/web/czh-tokens.css';
import '@czh/design/dist/element-plus/czh-element.css';

React + Ant Design v5

import { ConfigProvider } from 'antd';
import zhCN from 'antd/locale/zh_CN';
import { czhLightTheme, czhDarkTheme } from '@czh/design/dist/antd/czhTheme';

<ConfigProvider locale={zhCN} theme={isDark ? czhDarkTheme : czhLightTheme}>
  <App />
</ConfigProvider>

小程序 / uni-app / Taro

/* app.wxss */
@import '/styles/czh-tokens.wxss';

/* 页面里只用变量，不写死色值 */
.card {
  background: var(--czh-bg-container);
  border-radius: var(--czh-radius-xl);
  padding: var(--czh-spacing-4);
}

Flutter

MaterialApp(
  theme: CzhTheme.light(),
  darkTheme: CzhTheme.dark(),
  themeMode: ThemeMode.system,
);

// 组件内取色
final c = CzhColors.of(context);
Container(color: c.bgContainer, padding: EdgeInsets.all(CzhSpacing.s4));

React Native

import { useCzhTheme } from '@czh/design/dist/react-native/czhTheme';

const t = useCzhTheme();  // 自动跟随系统亮/暗
<View style={{ backgroundColor: t.color['bg-container'], padding: t.spacing[4] }} />

规范治理Governance

设计规范失效从来不是因为写得不好，而是因为没人维护、没人检查。下面是让它活下去的最小机制。

改动流程

落地检查清单

每个产品在提测前自查，任何一条不过就不算完成：

目录结构

橙智合/
├── tokens/czh.tokens.json   ← 唯一事实源，改色只改这里
├── tokens/build.mjs         ← 生成全部平台产物 + 对比度校验
├── dist/                    ← 生成物，禁止手改
│   ├── web/ element-plus/ antd/ miniprogram/ flutter/ react-native/
│   └── tokens.resolved.json ← 供 Figma Variables 导入
├── styles/czh-components.css← 组件参考实现（手写，只消费变量）
├── site/index.html          ← 本页面，由模板 + token 内联生成
└── docs/                    ← 分主题规范文档