What token extraction can and cannot tell you
Token extraction identifies implemented values and recurring patterns in a website or interface. It can reveal colors, typography, spacing, radii, and component conventions. It cannot determine every design decision from appearance alone: two identical values may have different roles, and an inconsistent value may be an intentional exception.
TDP’s agent-skills article describes using an extraction skill as a starting point for Carrot’s design language. The important next step is review: turn the observed values into a maintained system with explicit roles, rather than treating the first generated file as an approved specification.
This walkthrough is for auditing a site you are authorized to inspect. Prefer the actual implementation when available, and label screenshot-based estimates as estimates.
Step 1. Choose a representative sample
Include a content-heavy page, a form, and a dashboard or card layout where relevant. Inspect supported themes and responsive variants. A single marketing hero may use display styles that do not belong in the product’s everyday interface, so avoid generalizing from one attractive screenshot.
Step 2. Inventory observed values
Record colors, font families, text sizes, line heights, spacing, radii, borders, and shadows. Capture where each value appears. Prefer implementation evidence when available; a screenshot cannot reliably tell you the original token name, font loading behavior, or hidden states.
Step 3. Group values by role
Look for repeated relationships and distinguish intentional variants from accidental drift. Do not merge tokens solely because their current values match. For example, a subtle border and a disabled foreground may share a gray while serving very different purposes.
| Inventory field | Example entry |
|---|---|
| Observed value | 24px padding |
| Source | Settings card in the current implementation |
| Proposed role | Card padding |
| Existing token | Unknown until verified |
| Confidence | Observed on three sampled cards |
| Open question | Does the compact layout use a separate token? |
Step 4. Propose a starter map
Create a small token file using your project’s naming conventions. Label proposed names as proposals until the team agrees. Preserve a traceable mapping from original values to suggested roles. Keep unresolved values in the audit report instead of guessing how the system should work.
Inspect [authorized URL or repository] across [sample pages].
Inventory color, type, spacing, radius, and border values.
For each proposed token, include observed sources and intended role.
Separate verified existing tokens from suggested names.
Do not modify the site during this audit.
Step 5. Validate on a real component
Apply the proposed map to a representative component in a reviewable branch or design file. Compare states, narrow layouts, and long text. Revise the map where the component exposes missing roles. A useful outcome is a small accurate foundation, not a large file of unverified values.
Worked example: turn an inventory into a decision table
Imagine an audit finds six gray text colors, three card paddings, and several border radii. Do not immediately collapse them into one value per category. First locate where each value appears and what it does. Dense table text, disabled content, and secondary descriptions may require different treatment.
| Observation | Evidence | Proposed role | Open question |
|---|---|---|---|
| Dark text repeated across headings | Computed style and source rule | Text primary | Does the dark theme use a different mapping? |
| Two similar muted grays | Field hints and card metadata | Separate or shared secondary roles | Is the difference deliberate? |
| Larger padding on one card | Full-page composition | Spacious card layout | Is it a featured pattern or drift? |
| One unusual radius | Floating widget | Component-specific exception | Is it approved and still used? |
The table makes the decision reviewable. A raw list of colors cannot tell a teammate whether replacing one value would change meaning.
Inspect representative states, not only pages
Pick a small sample that includes forms, dense data, navigation, and feedback. Inspect hover and focus where relevant, plus errors and unavailable states. If the product supports multiple themes, compare them explicitly. A token map built only from the homepage often misses the rules used inside the application.
Record the viewport and state with each observation. A spacing value at a wide breakpoint may intentionally change on mobile. If a color includes transparency, record the background it appears over; the same source value can produce a different visible result on another surface.
Separate primitive values from semantic roles
Primitive values describe the available palette or scale. Semantic roles describe the job a value performs. Build the initial inventory from evidence, then name the roles with the people who own the system.
A token called gray-600 does not explain whether it is approved for body text. A role such as text-secondary does. Keep the relationship explicit so future theme changes can adjust a role without requiring every component to choose another raw color.
The semantic token guide covers this mapping. For a new palette, use the UI color guide before declaring every extracted color part of the future system.
Validate a proposed token map on a real screen
Apply a small approved mapping to one component or flow. Compare before and after at the same viewport and state. Check readable text, control boundaries, hierarchy, and content wrapping. A map can be internally tidy while producing a worse interface.
Inspect the implementation diff as well as the screenshot. Confirm that the expected tokens are used and that the change did not introduce a second source of truth. Keep any unresolved exception visible until its purpose is understood.
Keep the audit reproducible
Save source paths, screenshots where useful, and a brief explanation of the sampling choices. Another reviewer should be able to find the original value and repeat the observation. If access was limited to a screenshot or public page, state that limitation in the audit.
Extraction is the beginning of the system, not its maintenance plan. Assign ownership for new roles, document when exceptions are allowed, and review token changes alongside the components that consume them. The AI-ready system guide connects this foundation to component metadata and agent workflows.
Completion checklist
- The sample represents more than the hero section.
- Every proposed token has observed evidence.
- Existing names and suggested names are distinguishable.
- Modes and states are included where supported.
- A component has been checked against the proposed map.
Common questions
Can an extraction tool recover the original design system?
It can identify observable values and patterns. It cannot reliably infer every historical decision, unsupported state, or intended semantic role without further evidence.
Should I immediately replace all existing values?
No. Agree on the map, pilot one component, and plan the migration with the team that maintains the product.
Sources and TDP resources
- TDP extract-design-system skill
- TDP’s agent skills article provides context for the extraction workflow.