Design tokens 交付

文件

这些文件都在 bostonivy-design 仓库里。三个客户端不复制文件，而是按版本号依赖仓库里的两个包：Web 用 npm 包 @bostonivy/design，两个 Flutter 客户端用 Dart 包 bostonivy_design。引用和升级方法见仓库 README。

文件	是什么	谁用
`tokens/bostonivy-tokens.json`	单一来源，W3C Design Tokens Format Module 2025.10 格式	设计和所有构建
`tokens/build-tokens.mjs`	构建脚本，Node 18+，零依赖	CI 与本地
`tokens/dist/bostonivy-tokens.css`	生成的 CSS 变量，6 套主题；npm 包里是 `@bostonivy/design/tokens.css`	bostonivy-web
`src/generated.ts`	生成的主题 id、风格名；npm 包的入口模块从这里导出	bostonivy-web
`flutter/bostonivy_design/lib/src/bostonivy_theme.dart`	生成的 `ThemeData`、`BiColors`、`BiShape` 等，属于 Dart 包 `bostonivy_design`	bostonivy-macos、bostonivy-android
`tokens/dist/contrast-report.md`	生成的对比度报告	评审
本页的 `tokens.json`	生成的设计系统列表格式	这个设计系统页面

文件名一律小写；Dart 文件按 Dart 惯例用下划线。生成的文件不要手改，改 bostonivy-tokens.json 后在仓库根目录重新构建：

npm run build

有任何颜色组合低于 WCAG 要求时，构建以非零状态退出，可以直接放进 CI。

结构

bostonivy-tokens.json
├── $extensions.app.bostonivy      版本、风格列表、默认值、解析规则
├── core                           所有风格共用
│   ├── space.{0…16}               dimension，4px 阶梯
│   ├── radius.pill
│   ├── duration.{instant,fast,base,slow}
│   ├── easing.{standard,enter,exit,pop,linear}   cubicBezier
│   ├── z.{sticky,drawer,popover,modal,toast}
│   ├── breakpoint.{compact,medium,expanded}
│   ├── font.emoji                 彩色 emoji 字体
│   └── script.{hans,hant,hant-hk,jpan,kore,deva,beng,thai,arab,viet}
│       ├── font / font-rounded    该文字的系统字体；萌虎先找圆体
│       ├── leading-min            行高下限，字号的倍数
│       ├── tracking-scale         字距倍数，0 表示归零
│       └── $extensions            languages（选中这一组的语言标签）、direction
└── style.{clean,sticker,pixel}
    ├── font.{ui,display,data}     fontFamily，只写品牌字体和通用字族；构建时插入 core.script
    ├── radius.{sm,md,lg}
    ├── border.{width,focus}
    ├── size.{row,control,sidebar}
    ├── icon.stroke                + $extensions 里的 linecap / linejoin
    ├── typography.{title,heading,task,body,caption,timer}   typography 组合值
    ├── $extensions.app.bostonivy.variants   勾选框、优先级、标签等写法
    └── mode.{light,dark}
        ├── color.*                53 个语义色，每个都带 $description
        └── shadow.{card,raised,overlay}

解析规则：某个主题下的完整 token 集合 = core.* + style.<style>.* + style.<style>.mode.<mode>.*。颜色值用 2025.10 的对象写法（colorSpace + components，另附 hex 方便人读），尺寸写成 { "value": 8, "unit": "px" }。

三端映射

语义	CSS 变量	Flutter	Material 角色
页面底色	`--bg-canvas`	`BiColors.bgCanvas`	`scaffoldBackgroundColor`、`surfaceContainerLowest`
侧栏	`--bg-sidebar`	`bgSidebar`	`surfaceContainerLow`
卡片 / 输入框	`--bg-surface`	`bgSurface`	`surface`
下沉区	`--bg-sunken`	`bgSunken`	`surfaceContainer`
选中	`--bg-selected`	`bgSelected`	`surfaceContainerHighest`
正文	`--text-primary`	`textPrimary`	`onSurface`
次要文字	`--text-secondary`	`textSecondary`	`onSurfaceVariant`
品牌色	`--accent` / `--on-accent`	`accent` / `onAccent`	`primary` / `onPrimary`
品牌浅底	`--accent-soft` / `--on-accent-soft`	`accentSoft` / `onAccentSoft`	`primaryContainer` / `onPrimaryContainer`
紧急	`--danger`、`--danger-soft`	`danger`、`dangerSoft`	`error`、`errorContainer`
高优先级	`--warning`、`--warning-soft`	`warning`、`warningSoft`	`tertiary`、`tertiaryContainer`
信息	`--info`	`info`	`secondary`
控件边框	`--border-strong`	`borderStrong`	`outline`
卡片边框	`--border-default`	`borderDefault`	`outlineVariant`
遮罩	`--scrim`	`scrim`	`scrim`
圆角	`--radius-sm/md/lg`	`BiShape.radiusSm/Md/Lg`	各组件的 `shape`
描边	`--border-width`	`BiShape.borderWidth`	`BorderSide.width`
行高 / 控件高	`--row-height` / `--control-height`	`BiShape.rowHeight` / `controlHeight`	`minimumSize`
字号阶梯	`--type-title` … `--type-timer`	`textTheme.headlineSmall` … `displaySmall`	见「字体」
文字系统	`--font-script`、`--leading-min`、`--tracking-scale`（随 `lang` 变）	`BiScript.of(locale)`、`bostonIvyTheme(..., locale:)`	见「多语言与从右往左」
方向	`--inline-sign`、`.bi-mirror-rtl`（随 `dir` 变）	`Directionality`、`BiIcons.mirrorInRtl`	—
动效	`--motion-duration` / `--motion-easing`	`BiShape.motionDuration` / `motionCurve`	`AnimatedTheme`

Material 的 ColorScheme 只覆盖一部分语义，标签色、头像色、优先级、计时器这些专有颜色只在 BiColors 里。组件应当读 BiColors，不要从 ColorScheme 反推。

增改 token

在 bostonivy-tokens.json 里三种风格、亮暗两种模式都补上值，写好 $description（用在哪、放在什么底上）。
如果是文字色或标记色，把它的组合加进 build-tokens.mjs 的 PAIRS。
运行构建，确认对比度报告全部达标，flutter analyze 没有报错。
按语义化版本升级版本号，bostonivy-tokens.json 的 $extensions.app.bostonivy.version、package.json 和 flutter/bostonivy_design/pubspec.yaml 三处要一致：修正升修订号，新增 token 升次版本号，改名或删除升主版本号（1.0 之前，破坏性改动升次版本号）。
合入后打 vX.Y.Z 标签，三个客户端把依赖里的版本引用改成新标签。