# @clay-design-system/tokens 中文文档 规范地址：https://npmcn.com/package/%40clay-design-system/tokens/ 版本：0\.24\.0 npm 元数据更新时间：2026-11-09T17:27:34.454Z 中文译文更新时间：2026-11-10T00:33:58.387Z 软件包许可：未声明 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40clay-design-system/tokens 原文对照：https://npmcn.com/package/%40clay-design-system/tokens/?lang=original ## 关键信息（来自 npm 元数据） - 包体积（解压后）：494 kB，23 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - 运行依赖：0 个 - peer 依赖：stylelint ^16\.0\.0 - 首次发布：2026-10-13T06:46:53.402Z - 最新版本发布：2026-11-09T17:27:34.297Z - 近 30 天下载量：2928（2026-10-10 至 2026-11-08，npm 官方下载统计） - 已发布版本数：17（近 12 个月 17 个） ## 中文简介 Clay设计系统的设计符,由DTCG JSON源使用"风格词典"4编译而来. ## 安装 ```sh npm install @clay-design-system/tokens ``` 也可以使用：`pnpm add @clay-design-system/tokens`、`yarn add @clay-design-system/tokens`、`bun add @clay-design-system/tokens` ## README # @clay-dedesign- system/tokens (英语) Clay设计系统的设计符,由DTCG JSON源使用"风格词典"4编译而来. ## 分级系统 托肯按层次排列: ``` Foundation (base primitives — colors, type, spacing, radius, effects) ↓ referenced by Semantic (purpose-driven tokens — background, text, border, icon, size, motion) ↓ referenced by Web / Platform / Marketing (tier-specific tokens — typography scales, component tokens) ``` 组件会消耗语义或分级特定符号. 原始原生组件可能使用的一个是品牌调色板(`--clay-foundation-brand-color-*`); 下方的样式林特规则会阻断已退休的颜色名. 首选语义半径/相距于生 `--clay-foundation-radius/spacing-*` (指向,不是被强制). ## 源结构 ``` src/ ├── foundation/ Foundation primitives │ ├── colors.json Brand color palette → --clay-foundation-brand-color-* — exact Figma "Mode 1" stops (grey, yellow, lime, stone, harvest, orange, magenta, pink, iris, purple, blue, teal, green) │ ├── typography.json Font families, weights, size scale │ ├── spacing.json 18-step spacing scale (0-180) │ ├── radius.json 10 radius values (none → full) │ ├── effects.json Shadow + blur primitives │ ├── stroke.json Border width + color │ └── customer-logos.json Logo surface colors ├── semantic/ Purpose-driven tokens │ ├── color-primitives.json Neutrals, greys, brand palette aliases │ ├── brand.json Product colors (monday, wm, crm, dev, svc) │ ├── text.json 7 text color variants │ ├── icon.json 7 icon color variants │ ├── background.json 8 background variants + utilities │ ├── border.json 9 border color variants │ ├── size.json Space scale, icon sizes, depth │ ├── radius.json Layout/card radius scale + aliases │ ├── layout.json Container, grid, section, header, footer │ ├── effects.json Shadows, glass, device-frame │ ├── motion.json Duration, easing, transitions │ └── breakpoints.json Responsive breakpoints ├── web/ Web tier (marketing surfaces) │ ├── typography.json 40 text styles (desktop + mobile) │ ├── button.json Button: 4 sizes × 4 styles × 4 colors │ ├── card.json Card: container, image, size scale │ ├── input.json Input: colors, sizes, states │ ├── toggle.json Toggle: track, thumb │ ├── checkbox.json Checkbox: control, group, square │ ├── tag.json Tag: background + dot variants │ ├── tabs.json Tabs: triggers, panels, shells │ └── slider.json Slider: dots + arrows ├── platform/ Platform tier (product UI) │ └── typography.json 11 text styles (headlines, labels, captions) ├── marketing/ Marketing tier (campaigns) │ └── customer-logos.json Logo height + surface colors └── email/ Email tier (read by @clay-design-system/email at build time) └── typography.json Lifecycle email type scale ``` ## 产出 `pnpm --filter @clay-design-system/tokens build` (单位:千美元)`src/build.ts`写道: - `dist/tokens.css` (单位:千美元)`@clay-design-system/tokens/css`——作为 CSS 自定义属性的每一级 `:root`; 别名停留 `var()` 所以改变级联 - `dist/tokens.resolved.css` (单位:千美元)`@clay-design-system/tokens/css-resolved`)——字面价值相同 - `dist/tokens.js` + 键 `.d.ts` (单位:千美元)`@clay-design-system/tokens`——联署材料常数(被 `@clay-design-system/email`(三); `dist/index.cjs` + 键 `.d.cts` 页:1 `require()` - `dist/mq.js` 编号 : `mq.cjs` (单位:千美元)`@clay-design-system/tokens/mq`(b) —— `mq` 编号 : `breakpoints` 媒体 -- -- 冷冻助手、无害环境管理和CJS - `dist/TOKEN_REFERENCE.md` ——生成出每个令牌的列表 ## 使用量 ```tsx // In your app entry point: import '@clay-design-system/tokens/css' // In component CSS: .card { border-radius: calc(var(--clay-card-radius-value) * 1px); padding: calc(var(--clay-card-padding-value) * 1px); background: var(--clay-card-background); } ``` ## 命名公约 ``` --clay-{tier?}-{category}-{variant?}-{property} ``` - **基金会**数字 : `--clay-foundation-brand-color-iris-300`, (中文(简体) ), `--clay-foundation-type-weight-medium` - **语义**数字 : `--clay-color-background-brand-default`, (中文(简体) ), `--clay-size-space-400`, (中文(简体) ), `--clay-motion-duration-fast` - **网页**数字 : `--clay-web-type-large-desktop-size`, (中文(简体) ), `--clay-btn-primary-black-bg` - **平台**数字 : `--clay-platform-type-headline-xl-600-size` - **构成部分**数字 : `--clay-card-radius`, (中文(简体) ), `--clay-input-border-color`, (中文(简体) ), `--clay-tabs-trigger-font-size` ## 添加或修改符号 1. 编辑或创建 `.json` 文件输入 `src/{tier}/` 2. 使用 DTCG 格式 : `{ "$value": ..., "$type": "..." }` 3. 引用其他符号 `{clay.path.to.token}` 语法 4. 运行 `pnpm build` - 核查 `dist/tokens.css` 更新 5. 检查 `dist/TOKEN_REFERENCE.md` 用于生成的产出 ## 执行 样式林特插件 `@clay-design-system/tokens/stylelint-plugin/no-foundation-tokens.js` (运行于 `pnpm --filter @clay-design-system/react lint`封锁已退役的颜色名称—— `--clay-foundation-color-*`, (中文(简体) ), `--clay-web-color-*`, (中文(简体) ), `--clay-brand-color-*`。它只规范颜色层. ```json { "plugins": ["@clay-design-system/tokens/stylelint-plugin/no-foundation-tokens.js"], "rules": { "clay-ds/no-foundation-tokens": true } } ``` ## 无单位值 多数数字符号为无单位. 在CSS中,乘以 `1px`数字 : ```css padding: calc(var(--clay-size-space-400) * 1px); /* → 16px */ ``` 这允许在计算时使用符号而无需单位冲突. Agent-faceing 标志性指南(标题分级,命名,使用规则): `skills/web-design-brain/reference/TOKENS.md`。 。 。 . ## 常见问题 ### @clay-design-system/tokens 是什么？ Clay设计系统的设计符,由DTCG JSON源使用"风格词典"4编译而来\. ### 如何安装 @clay-design-system/tokens？ 在项目目录运行 npm install @clay-design-system/tokens，或使用 pnpm add / yarn add / bun add。 ### @clay-design-system/tokens 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @clay-design-system/tokens 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @clay-design-system/tokens 可以商用吗？ @clay-design-system/tokens 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。 ### @clay-design-system/tokens 的下载量有多少？ 根据 npm 官方下载统计，@clay-design-system/tokens 在 2026/10/10 – 2026/11/08 这 30 天内被下载 2,928 次，日均约 98 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @clay-design-system/tokens 还在维护吗？ 最新版本 0\.24\.0 发布于 2026/11/10（今天）；至今共发布 17 个版本，其中过去 12 个月发布了 17 个；首次发布于 2026/10/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。