Token mapping
A report that lands raw values (hex codes, pixel values, shadows) on a token list someone else owns. With no token set, it hands back groundwork for building one. The rules and an example report are in
references/mapping-rules.md
, finding and reading sources in
. Sibling links are relative to this skill's folder.
Start from whatever the ask gives
"Check the tokens on the settings page" is enough. Find the values and the list yourself, and ask only for what no tool can reach. Defaults:
- Values: what the person named, else the branch diff, else the product code ().
- Mode: the list's default mode, named in Source.
- rem root: 16px, unless the project sets another.
When a coordinator calls it
Take the values and the list in the brief as given and run to the end without asking. Questions go under For a person to decide, which the caller turns into gates. Start with a status line,
,
Status: not actionable (gap threshold)
or
Status: stopped: <condition>
, then
. Return the report, or the stop shape below, as your final message.
Steps
- Load the rules. Read
references/mapping-rules.md
- Load the list. Done when Source has its name, format, location, read method and time.
- Resolve it. Follow every alias to its final value in each mode, and compare any second source. Done when every alias resolves and every disagreement is written down.
- Collect the groundwork. One row per property (a shorthand is two rows), each with its location (, or URL plus selector), category and job, sorted per (What counts as the team's list). Done when every raw and palette value in scope has a row.
- Normalize both sides per the rules file, converting colors with code.
- Classify. List the candidate tokens whose stated purpose covers the row's job, semantic before primitive, and give one class per row per mode. Done when every row has a class and a reason, and every semantic row states its difference in numbers.
- Count and close. Apply the gap threshold, write Consistency by role when the rules call for it, then the Summary and Source.
Output
Seven parts, in this order, each specified in
references/mapping-rules.md
(Report shape): Summary, Mapping, Do not use, Ambiguous, Gaps, For a person to decide, Source.
Run directly, the chat reply gives the Summary's answer with its numbers, each command with its exit code, up to three questions for a person with defaults, and
with one prompt to paste.
The report is ready when:
- Every row has a job, a class and a reason, and every ambiguous row names two or more candidates.
- A semantic token appears wherever one covers the job, never its primitive.
- Anything inferred rather than read, such as a job taken from a class name, is marked inferred.
- Nothing in the repo changed.
Stops
Stop and report on these only.
- No list exists, or no tool can read one.
- One name has two values in the same mode, which makes the list broken.
- Two sources disagree and no project rule says which wins. Report both sides.
A stopped run returns the condition, the groundwork from step 4 (grouped per
, When the repo has no token file), and the shortest message that unblocks it, such as "Paste
or give its path." Gaps are never a stop, at any count.
Hard limits
- Name only tokens in the list that was read. A gap never gets a new token name.
- Match on purpose before value, and on value only within the rules file's tolerances.
- Read the list and the values fresh each run and record the read time. A failed read is reported, never filled from memory.
- A public system's token names, Geist's included, are never the team's list.