定制与迁移

主题 / 密度 / 级联层 / RTL / 国际化 / 设计工具导出，以及 v0.9 → v0.10 命名空间迁移 codemod。

主题：三层正交，全部 data 属性

色彩预设 × 明暗 × 风格三层正交，全部挂在 <html> 的 data 属性上（不再是类——[data-icen-theme="dark"] 是全业界最危险的类名，v0.10 起废弃类形态）： data-icen-preset（benzhen 默认 / clay / piano / art / vangogh / ink）· data-icen-theme="dark"（摘除即亮色）· data-icen-style（benzhen 本真 / pixel 像素）。

html

<html data-icen-preset="piano" data-icen-theme="dark" data-icen-style="benzhen"><!-- 运行时切换（含持久化与系统跟随）： --><script>import { initTheme, setTheme, toggleDark, setStyle, registerThemePreset } from '@icen.ai/ui/behaviors/theme';initTheme();                          // 尽早调用（读 localStorage 防闪烁；无偏好时跟随系统）toggleDark();                         // 明暗setTheme({ preset: 'piano' });        // 色彩预设setStyle('benzhen');                    // 原语（与色彩正交）registerThemePreset('brand');         // 自建品牌主题：自家 CSS 写好 token 面即可</script>

自建预设 = 在自家 CSS 写两块完整 token 面：[data-icen-preset="brand"] 与 [data-icen-preset="brand"][data-icen-theme="dark"]（仿照 colors.css 现有 6 套）。防闪烁：首帧前内联脚本同步恢复（本站 ThemeRestore 组件即参考实现）。

主题工作台：调旋钮 → 拿覆盖 CSS

下面的工作台全部用本库组件搭成（吃狗粮）：左侧旋钮改动实时作用于右侧预览卡（容器级 data 属性 + CSS 变量子树覆盖），底部生成可复制片段。accent 明度三档的对比度实时验算并如实展示——不达标会明说（诚实呈现纪律），不会悄悄给你一个不过 AA 的品牌色。

色彩预设

明暗

原语

密度（预览卡容器级）

品牌色 accent（留空 = 预设原生）

圆角基准 radius-md：10px（预设原生）

订单总览3

已支付待审核已逾期

生成的覆盖片段（含实测对比度注释）

密度

容器挂 data-icen-density="compact|normal"（AI 族另有 summary 档）——行高/间距/字号/控件高度全部经 --icen-density-* 标尺联动，组件不写死尺寸。

级联层：你的样式永远赢

v0.10 起库的全部产物 CSS 包在 @layer icen.tokens / icen.base / icen.components（层序由 tokens.css 顶部声明锚定）。你项目里不写层的样式优先级恒高于库——覆盖库样式不需要提权重、不需要 !important：

css

/* 你的样式表（无层 = 恒赢库的三层） */.icen-btn { border-radius: 999px; }        /* 直接生效 *//* 想插队到库的层序里也可以显式入层： */@layer icen.components {  .icen-btn { letter-spacing: 0.02em; }}

RTL（从右到左）

全库流向布局已迁移到 CSS 逻辑属性（margin-inline-start 等），方向性图标在 RTL 下自动镜像。消费方零接线：<html dir="rtl"> 即生效。图表坐标系与浮层定位保持物理坐标（按设计不镜像）。

国际化（i18n）

行为层每一句面向用户的文案都收敛在 IcenLocale 注册表（683 key：AI 族 / kb 族 / charts / datatable / 表单族 / 控件族全覆盖）。内置中文（默认）与英文；局部覆盖任意 key；组件监听 icen:locale-change 即可响应切换。

import { setIcenLocale, resetIcenLocale, ICEN_LOCALE_EN_US } from '@icen.ai/ui/behaviors/i18n';import { onIcen } from '@icen.ai/ui/behaviors/events';setIcenLocale(ICEN_LOCALE_EN_US);                 // 整站切英文setIcenLocale({ 'select.searchPlaceholder': '搜索组件…' });   // 只改一句resetIcenLocale();                                 // 回中文默认onIcen('icen:locale-change', (e) => console.log('变化的 key：', e.detail.changed));

设计工具导出

设计 tokens 三种标准产物：bun run dtcg 产 W3C DTCG 经典版（Style Dictionary 生态）； bun run design-tokens 再产 Tokens Studio 与 Figma Variables 两种格式。产物路径与色板见色彩 Tokens 页。

v0.9 → v0.10 迁移（codemod 随包发布）

v0.10 完成命名空间跃迁：.btn→.icen-btn、data-tabs→data-icen-tabs、 --token-*→--icen-token-*、主题类→data 属性。包内自带迁移工具（API 感知 tokenizer；歧义 token 保守跳过并给人工清单）：

bash

# 先看报告（dry-run，不写盘）bunx @icen.ai/ui migrate src# 确认后落盘bunx @icen.ai/ui migrate src --write# 迁移后跑项目自身的类型检查/构建验证；歧义处（类名∩标签名∩领域词）按打印的人工清单逐条确认

手写主题切换代码的项目（classList.add('dark') 等）需人工改为 data-icen-* 属性或走 setTheme()——codemod 会在报告中列出这些点。