references/mapping-rules.md
GitHubMapping rules
Replace the categories, tolerances and threshold with your team's before the first real run. The skill treats this file as agreed.
Classes
One class per row per mode. Purpose is checked first, then value. A value that equals a token but serves another job is never a match. It becomes ambiguous or a gap, and the token goes in Do not use.
Not mapped (counted in the Summary, no row): a role token with alpha applied (color-mix() over its var(), a utility's alpha modifier), and values in the graphic category (logo art, illustrations, decorative gradient stops).
If the list states no purposes at all, the run matches values only. Each reason begins "Value only", Do not use stays empty because it cannot be checked, and the report adds Consistency by role. A palette-only list (gray-500 with no roles) makes almost every palette row Exact by definition, so Consistency by role becomes the main output and the table keeps only rows that are not Exact.
Categories
A candidate belongs to the same category as the row's job.
- Colour by role: surface, text, border, icon, action, focus, status.
- Spacing by job: inset (inside a component) and gap (between items). One scale often serves both, so record which job the row does.
- Size, radius, border width, typography (family, size, weight, line height, letter spacing), shadow (each part its own row), opacity, motion (duration, easing), z-index.
A row whose job cannot be read is ambiguous when the jobs it might do give two or more candidates, and a gap marked "job unread" otherwise.
Normalising
- Lengths to px. A 16 px root for
remunless the project sets another. Line height to a unitless ratio. - Colours to OKLCH plus alpha.
build-design-system/scripts/oklch.mjsreads hex (3, 4, 6, 8 digits),rgb(),hsl(),hwb(),oklch(),oklab()and the CSS named colours, each with its alpha, and prints the OKLCH. It does not readcolor(),lab(),lch(),color-mix()or a relative colour. Resolve those with a browser's computed style, and say so in Source. Compare by delta E OK (OKLab distance times 100), whichoklch.mjs --deltaprints. Under 0.5 is identical, which absorbs 8-bit rounding. - Alpha is part of the colour.
#0F172Aat 80% is not#0F172A:--deltaprints both alphas and saysalpha differspast the opacity tolerance, and such a pair is never Exact.
Tolerances
Applied only after purpose fits, and never turn a wrong-purpose token into a match. A difference equal to the limit is inside it.
| Category | Limit |
|---|---|
| Colour | delta E OK 2 |
| Spacing, size, radius | 2 px |
| Font size | 1 px |
| Line height | 0.05 as a ratio |
| Letter spacing | 0.01 em |
| Opacity | 0.02 |
| Duration | 30 ms |
| Border width, weight, family, easing | none |
Consistency by role
Written when the list states no purposes or the ask is about consistency. Group every colour row by role. For each role give the distinct values with counts, their spread in delta E OK, and near pairs (under 5) that likely mean one thing.
Text: 6 values over 200 rows. gray-500 (80), gray-600 (60), #666 (10) sit within delta E OK 4 and likely mean one muted text.
Source conflicts
Two sources that disagree on a value go in Source with both sides. A project rule that says which wins is quoted. Otherwise neither is chosen and the question goes to For a person to decide.