Back to Details

token-mapping

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Token mapping

Token 映射

A read-only report that lands raw values (hex, px, shadows) on a token list someone else owns. Classes, normalising and tolerances are in 
references/mapping-rules.md
. "Check the tokens on the settings page" is enough of an ask. Find the values and the list yourself.
一份只读报告，将原始值（hex、px、阴影）对应到由他人维护的 token 列表。分类、归一化和容差规则见 
references/mapping-rules.md
。只需提出“检查设置页面上的 token”这样的要求。自行查找相关值和列表。

Steps

步骤

  1. Find the list. Token files, theme entries, custom properties on 
    :root
    , a component library's variable pairs. A framework's default theme is not the team's list, and neither is a public system's (Geist's names never stand in for the team's). Record its name, location and how you read it. If a read fails, say so and stop. Never fill a list from memory.
  2. Find the values. What the person named, else the branch diff, else the product code. Record each with its file, line, property and job.
  3. Resolve. Follow every alias to its final value in each mode. Write down every disagreement between two sources.
  4. Normalise both sides (lengths to px, colours to OKLCH compared by delta E OK) with code, never by eye.
  5. Classify each row once per mode. Purpose first, then value.
    • Exact: the token's stated job covers the row and the values match.
    • Semantic: the job covers it and the value is inside tolerance. State the difference in numbers.
    • Ambiguous: two or more tokens fit and nothing picks one. Name every candidate.
    • Gap: no token's job covers it, or the only fitting token is out of tolerance. A gap never gets a new name.
  6. Count and close. When gaps are over 30% of rows and number 12 or more, the list is usually the wrong one. Say so, still deliver the table, and lead with 
    Status: not actionable (gap threshold)
    .
  1. 查找列表。 Token 文件、主题条目、
    :root
    上的 custom properties，或组件库中的变量对。框架的默认主题不是团队的列表，公共系统的默认主题也不是（Geist 的名称绝不能代替团队的名称）。记录其名称、位置和读取方式。如果读取失败，说明情况并停止。绝不能凭记忆补全列表。
  2. 查找值。 优先查找用户指定的对象，否则使用分支 diff，否则使用产品代码。逐项记录其文件、行号、属性和用途。
  3. 解析。 针对每种模式，追踪每个 alias 直到其最终值。记录两个来源之间的每一处分歧。
  4. 归一化 两侧（将长度转换为 px，将颜色转换为 OKLCH，并通过 delta E OK 比较），必须使用代码完成，绝不能目测。
  5. 对每一行在每种模式下分类一次。 先判断用途，再判断值。
    • 精确（Exact）：token 声明的用途涵盖该行，且值完全匹配。
    • 语义（Semantic）：用途涵盖该行，且值处于容差范围内。用数字说明差异。
    • 歧义（Ambiguous）：两个或更多 token 都适用，且没有任何依据能够选定其中一个。列出每个候选项。
    • 缺口（Gap）：没有任何 token 的用途涵盖该行，或唯一适用的 token 超出了容差范围。不要为缺口创造新的 token 名称。
  6. 计数并收尾。 当缺口数超过映射行数的 30%，且达到 12 行或以上时，通常说明所选列表不对。明确指出这一点，但仍交付表格，并以 
    Status: not actionable (gap threshold)
    开头。

Report

报告

Summary, Mapping, Do not use (a token whose value matches but whose job differs), Ambiguous, Gaps, For a person to decide, Source. Last line 
Coverage:
with what was scanned and what was not. Run on its own, the chat reply gives the answer with its numbers and one prompt the person can paste to take the next step.
报告应包含：摘要、映射、不要使用（值匹配但用途不同的 token）、歧义、缺口、需由人员决定、来源。最后一行是 
Coverage:
，说明扫描了什么以及未扫描什么。独立运行时，聊天回复应给出带数字的答案，以及一条供对方粘贴以推进下一步的简短提示。

Rules

规则

  • A match on value before purpose is wrong. Wrong: 
    #6b7280
    mapped to 
    color.border.default
    because the hex is equal. Right: it is text, so the candidates are text tokens, and the border token goes in Do not use.
  • A semantic token wins over the primitive it aliases. Map to a primitive only when no semantic token covers the job, and say so.
  • A palette class (
    text-gray-500
    ) names a value and no job. It gets a row, counted apart from raw values.
  • Anything inferred rather than read, such as a job taken from a class name, is marked inferred.
  • Counts carry their unit: occurrences, lines or mapping rows.
  • 先匹配值、后判断用途是错误的。错误示例：仅因 hex 相等，就将 
    #6b7280
    映射到 
    color.border.default
    。正确示例：它是文本，因此候选项应为文本 token，而 border token 应放入“不要使用”。
  • 语义 token 优先于其 alias 的 primitive token。只有在没有语义 token 覆盖该用途时，才映射到 primitive token，并明确说明这一点。
  • palette class（
    text-gray-500
    ）只表示一个值，并不表示用途。它也需要单独占一行，并与原始值分开计数。
  • 任何并非实际读取、而属于推断的信息，例如根据 class 名称推断出的用途，都应标记为 
    inferred
    （推断）。
  • 计数必须标明单位：occurrences（出现次数）、lines（行数）或 mapping rows（映射行数）。

Stops

停止条件

Stop and report on these only. No list exists. One name has two values in the same mode. Two sources disagree and no project rule says which wins (report both). Return what stopped it, the groundwork so far, and the shortest message that unblocks it, such as "Paste 
tokens.json
or give its path."
仅在以下情况下停止并报告：不存在 token 列表；同一模式下，同一名称对应两个不同的值；两个来源存在分歧，且没有项目规则说明哪个来源优先（报告两者）。返回导致停止的原因、目前完成的基础工作，以及用于解除阻塞的最短消息，例如“粘贴 
tokens.json
或提供其路径”。

Done

完成标准

Every row has a job, a class and a reason. Every ambiguous row names two or more candidates. Nothing in the repo changed (
git status
is the same before and after). The last line reads 
Coverage:
.
每个映射行都有用途、分类和理由。每个歧义行都列出两个或更多候选项。仓库中没有任何改动（
git status
在执行前后相同）。最后一行是 
Coverage:
。