Back to Details

ss-tokens

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Design Token Manager

Design Token 管理器

When NOT to use

不适用于以下场景

  • For applying tokens in components → use 
    /ss-component
    or 
    /ss-pattern
  • For finding token violations in existing code → use 
    /ss-lint
  • For non-CSS token systems (Figma, native iOS/Android) — Tailwind v4 / CSS variables only
Action: $0 | Token type: $1 Arguments: $ARGUMENTS
  • 如需在组件中应用令牌 → 使用 
    /ss-component
    或 
    /ss-pattern
  • 如需查找现有代码中的令牌违规问题 → 使用 
    /ss-lint
  • 非CSS令牌系统（Figma、原生iOS/Android）——仅支持Tailwind v4 / CSS variables
Action: $0 | Token type: $1 Arguments: $ARGUMENTS

Token File Locations

令牌文件位置

TypeJSON SourceCSS Implementation
Colors
tokens/colors.json
css/theme.css
:root
+ 
@theme inline
Typography
tokens/typography.json
css/fonts.css
+ 
css/base.css
Spacing
tokens/spacing.json
Tailwind utilities (no custom CSS needed)
Radius
tokens/radii.json
css/theme.css
@theme inline
Shadows
tokens/shadows.json
css/theme.css
:root
类型JSON源文件CSS实现文件
颜色
tokens/colors.json
css/theme.css
:root
+ 
@theme inline
排版
tokens/typography.json
css/fonts.css
+ 
css/base.css
间距
tokens/spacing.json
Tailwind工具类（无需自定义CSS）
圆角
tokens/radii.json
css/theme.css
@theme inline
阴影
tokens/shadows.json
css/theme.css
:root

Instructions

使用说明

generate color
— Derive the system from one key color

generate color
— 从单一主色调生成配色系统

Do not pick a second color by eye or copy a preset. Run the shared StyleSeed generator:
bash
node <styleseed-root>/engine/color/generate-palette.mjs \
  --key-color "#276B5E" \
  --mode light \
  --character calm \
  --harmony auto \
  --temperature neutral \
  --out .styleseed/palette.json
Supported controls are 
light|dark
mode, 
calm|balanced|vivid|deep
character, 
auto|tonal|adjacent|contrast
harmony, and 
neutral|warm|cool
surface temperature. The generator preserves the key hue, maps chroma into sRGB without channel clipping, builds 11-step OKLCH primary/accent ramps, scores the accent against the key and reserved status hues, maps primitives to semantic roles, and adjusts fill lightness until text/action/focus pairs pass.
Use 
--format css
for CSS variables or JSON for an auditable result. Never mark the palette valid unless 
valid
is true and every item in 
contrast
passes. In 
STYLESEED.md
, persist 
Key color
, 
Palette character
, 
Palette mode
, 
Palette harmony
, and 
Surface temperature
, then run 
$ss-resolve
; the resolver emits the same 
.styleseed/palette.json
and 
palette.css
.
请勿手动挑选第二种颜色或复制预设方案。运行共享的StyleSeed生成器：
bash
node <styleseed-root>/engine/color/generate-palette.mjs \
  --key-color "#276B5E" \
  --mode light \
  --character calm \
  --harmony auto \
  --temperature neutral \
  --out .styleseed/palette.json
支持的控制参数包括
light|dark
模式、
calm|balanced|vivid|deep
风格、
auto|tonal|adjacent|contrast
配色和谐度，以及
neutral|warm|cool
表面色调。该生成器会保留主色调的色相，将色度映射到sRGB色域且避免通道裁剪，构建包含11个层级的OKLCH主色/强调色渐变，对比强调色与主色调及预留状态色调的匹配度，将基础色映射到语义角色，并调整填充色亮度，直到文本/操作/焦点组合通过无障碍对比度检测。
使用
--format css
参数可生成CSS变量，使用JSON格式可生成可审计的结果。只有当
valid
为true且所有对比度检测项均通过时，才能标记调色板为有效。在
STYLESEED.md
中记录
Key color
、
Palette character
、
Palette mode
、
Palette harmony
和
Surface temperature
，然后运行
$ss-resolve
；解析器会生成相同的
.styleseed/palette.json
和
palette.css
文件。

list
— Show current tokens

list
— 查看当前令牌

Read and display the requested token file in a formatted table.
读取并以格式化表格的形式显示指定的令牌文件。

add
— Add new token

add
— 添加新令牌

  1. Add the token to the JSON source file (
    tokens/*.json
    )
  2. Add the CSS custom property to 
    css/theme.css
    under 
    :root
  3. If it needs a Tailwind utility, add to the 
    @theme inline
    block
  4. If it has a dark mode variant, add to the 
    .dark
    block
  1. 将令牌添加到JSON源文件（
    tokens/*.json
    ）
  2. 在
    css/theme.css
    的
    :root
    下添加对应的CSS自定义属性
  3. 如需生成Tailwind工具类，添加到
    @theme inline
    块中
  4. 如需支持暗色模式变体，添加到
    .dark
    块中

update
— Modify existing token

update
— 修改现有令牌

  1. Update the value in the JSON source file
  2. Update the CSS custom property in 
    theme.css
  3. Check all components for direct usage that might need updating
  1. 更新JSON源文件中的值
  2. 更新
    theme.css
    中的CSS自定义属性
  3. 检查所有直接使用该令牌的组件，确认是否需要同步更新

Rules

规则

  • Always keep JSON and CSS in sync
  • Use semantic names, not descriptive names (
    --success
    not 
    --green-500
    )
  • Colors should support both light and dark modes
  • New tokens must be added to BOTH the JSON source AND the CSS implementation
  • Treat preset recipes as maintained defaults, not the limit of available colors.
  • Character and role allocation are stronger design controls than complementary/triadic geometry alone.
  • 始终保持JSON源文件与CSS实现文件同步
  • 使用语义化命名，而非描述性命名（如
    --success
    而非
    --green-500
    ）
  • 颜色需同时支持亮色和暗色模式
  • 新增令牌必须同时添加到JSON源文件和CSS实现文件中
  • 将预设方案视为维护的默认值，而非可用颜色的上限
  • 风格与角色分配是比互补色/三色几何搭配更强的设计控制手段。