# @dt-dds/themes 中文文档 规范地址：https://npmcn.com/package/%40dt-dds/themes/ 版本：1\.0\.0-beta\.20 npm 元数据更新时间：2026-10-28T13:28:14.184Z 中文译文更新时间：2026-11-12T23:02:57.135Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40dt-dds/themes 原文对照：https://npmcn.com/package/%40dt-dds/themes/?lang=original ## 关键信息（来自 npm 元数据） - 包体积（解压后）：409 kB，38 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - 运行依赖：0 个 - 首次发布：2025-08-26T20:08:07.100Z - 最新版本发布：2026-10-28T13:28:13.868Z - 近 30 天下载量：6307（2026-10-13 至 2026-11-11，npm 官方下载统计） - 已发布版本数：19（近 12 个月 11 个） ## 中文简介 DT-DDS 设计系统主题 ## 安装 ```sh npm install @dt-dds/themes ``` 也可以使用：`pnpm add @dt-dds/themes`、`yarn add @dt-dds/themes`、`bun add @dt-dds/themes` ## README # @dt-dds/主题 DT-DDS 主题包 这个软件包包含DT-DDS的主题系统,包括: - 主题定义和类型 - 主题生成公用事业 - 托肯处理和验证 - 主题公用事业和助手 ## 安装 ```bash yarn add @dt-dds/themes ``` ## 使用量 ```typescript import { daimlerTruckTheme } from '@dt-ui/themes'; const theme: CustomTheme = daimlerTruckTheme; ``` ## 发展 ```bash # Install dependencies yarn install # Build the package yarn build # Run tests yarn test # Generate themes from tokens yarn build:theme ``` ## 主题生成 主题生成系统自动处理 JSON 令牌文件, 并生成相应的匹配 TypeScript 主题文件 `CustomTheme` 类型结构。 它支持多个主题并处理符号验证,参考解析和倒置值. ### JSON 令牌文件 JSON 令牌文件由 Figma 变量生成, 使用以下插件 [设计托肯管理器](https://www.figma.com/community/plugin/1263743870981744253/design-tokens-manager)。 。 。 . 导出的 JSON 文件格式遵循了 [设计 脚本格式](https://www.designtokens.org/tr/drafts/format/) 由W3C工作组设计. ## GitHub 动作工作流程 ### 自动主题生成 包括一个 GitHub 动作工作流程(`.github/workflows/theme-generation.yml`),当符号文件在拉动请求中被修改时自动生成主题. #### 如何运作: 1. **触发**: 工作流程运行于打开、更新或重新打开并包含修改内容的 PR: - `packages/themes/src/tokens/**/*.json` - `packages/themes/src/utils/theme-generator/**/*` - `packages/themes/src/types/theme.ts` - `packages/themes/package.json` 2. **进程**数字 : - 检查 PR 分支 - 安装依赖关系 - 运行 `yarn build:theme` - 向 PR 提交生成的主题文件 - 附有状况资料的关于公关的评论 3. **结果**数字 : - **更改成功**: 主题文件更新并输入到 PR - **无改动的成功**: 不需要修改主题 - **失败**: 错误细节作为评论发布 #### 福利: - **方便设计者**: 设计者可以在不担心主题生成的情况下专注于符号文件 - **自动**: 不需要人工干预 - **透明**: 明确反馈生成的内容 - **保险**: 只运行在公关上, 不运行在主分支上 #### 示例工作流程 : 1. 设计者创建了新分支 2. 设计者修改代号 JSON 文件 3. 设计师执行和推动更改 4. 设计者创建 PR 5. GitHub 动作自动 : - 检测令牌文件更改 - 运行主题生成 - 将生成的主题文件提交 PR - 对PR的评论和结果 6. 设计者审查符号更改和生成的主题文件 7. PR 既可以和符和主题变化合并 ## 手动主题生成 要手动生成主题, 请运行 : ```bash cd packages/themes yarn build:theme ``` 这将: - 在其中发现所有主题文件 `src/tokens/` - 用其语义文件处理每个主题 - 生成主题文件 `src/themes/` - 格式化并插入生成的文件 ## 调试矩阵 ### 核心颜色 - `Core_colors.Grey.grey-*` (00-120) (中文(简体) ) - `Core_colors.Petrol.petrol-*` (00-100) (中文(简体) ) - `Core_colors.Blue.blue-*` (00-100) (中文(简体) ) - `Core_colors.Green.green-*` (00-100) (中文(简体) ) - `Core_colors.Orange.orange-*` (00-100) (中文(简体) ) - `Core_colors.Red.red-*` (00-100) (中文(简体) ) ### 产品颜色 - `Product_colors.Bright_yellow.brightyellow-*` (00-100) (中文(简体) ) - `Product_colors.True_blue.trueblue-*` (00-100) (中文(简体) ) ### 语义色彩 - `Contextual_colors.Surface.*` (默认、轻、中、暗、对比) - `Contextual_colors.Content.*` (默认、轻、中、暗、对比) - `Contextual_colors.Border.*` (默认、轻、中、暗、对比) - `Contextual_colors.Primary.*` (默认,轻,中,暗) - `Contextual_colors.Secondary.*` (默认,轻,中,暗) - `Contextual_colors.Accent.*` (默认,轻,中,暗) - `Contextual_colors.Informative.*` (默认,轻,中,暗) - `Contextual_colors.Success.*` (默认,轻,中,暗) - `Contextual_colors.Warning.*` (默认,轻,中,暗) - `Contextual_colors.Error.*` (默认,轻,中,暗) ### 类型 - `Typography.Font-family.*` - `Typography.Weight.*` - `Typography.Size.*` - `Typography.Line-height.*` - `Typography.Letter-spacing.*` - `Typography.Headings.*` (h1-正统,h1-粗体,h1-正统,h1-正统等) - `Typography.Body.*` (体-lg-正则活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活 - `Typography.Buttons.*` (按钮-lg,按钮-md,按钮-sm) - `Typography.Links.*` (链接-lg-regular,链接-lg-bold,链接-md-regular等) ### 间距 - `Spacings.spacing-*` (0、10、20、30、40、50、60、70、80、90、100、200、300、400、500) ### 半径 - `Radius.radius-*` (0、10、20、30、40、50、60、70、80、90、100、200、300、400、500) ### 阴影/边缘 - `Elevations.*` (100,200,300,400,500,600,套接字) ### 形状 - `Shape.shape-*` (avatar,手风琴,徽章,按钮,卡片,复选框,容器,取日期器,抽屉,空状态,取时器,消息,输入 Fields,模式,进步 Bar,pagination,无线电按钮,标签,togle,tfast,tag-round,分块控制,标记平面,切换,工具提示,定义List,标题,导航Menu,选项,KPIcard,脚步,滑动器,骨架) ### 断点 - `Grid.MQ*.width-default-MQ*` (中文(简体) ) ### 图标大小 - `Icon_size.icon-size-*` (小、中、大、大) ### 字体 - `Fonts.*` (damler-Truck-初等、卡车API-初等、dtcompany-初等、\[品牌\]-中学) ### 组件 产生自 `Themes.*.tokens.json` 文档. ## 文件结构 ``` src/ ├── tokens/ │ ├── Primitives.Value.tokens.json │ ├── text.styles.tokens.json │ ├── Themes.*.tokens.json │ └── Semantic *.Default theme.tokens.json ├── themes/ │ ├── [generated-theme]/ │ ├── colors.ts │ ├── palette.ts │ ├── spacing.ts │ ├── radius.ts │ ├── shadows.ts │ ├── shape.ts │ ├── breakpoints.ts │ ├── typography.ts │ ├── icons.ts │ ├── animations.ts │ ├── components.ts │ └── index.ts │ └── utils/ └── theme-generator/ ├── tokenUtils.ts ├── fileUtils.ts ├── validation.ts ├── formatter.ts ├── generators/ │ ├── colors.ts │ ├── spacing.ts │ ├── radius.ts │ ├── shadows.ts │ ├── shape.ts │ ├── breakpoints.ts │ ├── typography.ts │ ├── icons.ts │ ├── animations.ts │ └── components.ts ├── index.ts └── runner.ts ``` ## 验证 该系统包括全面验证: - **主题完整性**: 检查所需的符号类别 - **托肯验证**: 确保符号存在并有有效值 - **参考决议**: 处理嵌入式符号引用 - **后退处理**: 为缺失的令牌提供倒置值 ## 处理错误 - **缺少托肯斯**: 缺少所需符号的主题被警告跳过 - **无效的引用**: 无法解析的符号引用返回到 `inherit` - **语法错误**: JSON 解析错误被抓住并报告 - **类型出错**: 报告类型脚本编译错误 ## 捐款 修改主题生成系统时 : 1. 更新适当的生成器 `src/utils/theme-generator/generators/` - 对于组件符号,修改 `components.ts` 发电机 - 对于其他令牌,更新相关的生成器(colors.ts,间隔.ts等) 2. 更新 `CustomTheme` 类型在 `src/types/theme.ts` 如果添加了新的符号类别 3. 需要时更新默认主题文件 4. 运行 `yarn build:theme` 测试更改 5. 运行 `yarn test` 确保所有测试通过 6. 更新此文档 ### 添加新组件 为增加新组成部分的支持: 1. 将组件密钥添加到 `COMPONENT_KEYS` 阵列 `src/utils/theme-generator/generators/components.ts` 2. 确保组件符号存在于 `Themes.*.tokens.json` 文件 3. 运行 `yarn build:theme` 生成更新组件 ## 许可证 许可证根据 [MIT 许可证](https://npmcn.com/package/%40dt-dds/themes/LICENSE) ## 常见问题 ### @dt-dds/themes 是什么？ DT-DDS 设计系统主题 ### 如何安装 @dt-dds/themes？ 在项目目录运行 npm install @dt-dds/themes，或使用 pnpm add / yarn add / bun add。 ### @dt-dds/themes 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @dt-dds/themes 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @dt-dds/themes 可以商用吗？ @dt-dds/themes 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @dt-dds/themes 的下载量有多少？ 根据 npm 官方下载统计，@dt-dds/themes 在 2026/10/13 – 2026/11/11 这 30 天内被下载 6,307 次，日均约 210 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @dt-dds/themes 还在维护吗？ 最新版本 1\.0\.0-beta\.20 发布于 2026/10/28（16 天前）；至今共发布 19 个版本，其中过去 12 个月发布了 11 个；首次发布于 2025/08/27。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。