Turn Website Color Roles Into Reusable Design Tokens

Turn website colors into reusable design tokens by first identifying each color's job, then grouping related shades into named roles instead of saving isolated hex values. A practical token set should explain where a color belongs, how strong it is, and which accessible alternatives to use when the same role appears on different surfaces.

Start with roles, not hex codes

Begin with a role map for the interface:

• color.text.primary for the main reading color
• color.text.muted for supporting copy and metadata
• color.surface.canvas for the page background
• color.surface.raised for cards, panels, and inputs
• color.border.subtle for low-emphasis separators
• color.action.primary for the main button or link
• color.action.primary-hover for interaction feedback
• color.state.success, warning, and danger for status messages

This prevents a common mistake: naming tokens after their current appearance, such as green-700, when the real requirement is usually button-primary or success-text. A named role can stay stable even when the visual palette changes.

Open the examples below and compare the first screen before borrowing a pattern. The captured Pangram example is associated with a muted green direction, while the color list includes dark greens, medium greens, gray-green neutrals, and a lighter green-gray. Treat those colors as observations to classify, not as a finished token system.

Build a small token ladder

For each important role, create a limited ladder rather than assigning every observed shade a separate name. A useful structure is:

The exact assignments above are a starting illustration based on the supplied observed palette, not a claim about an official internal system. Check every proposed assignment against the actual component and background where it appears. If several dark greens serve the same purpose, keep the strongest candidate and document the others as alternatives or context-specific tones.

Check usage before exporting

A color's frequency does not prove its role. A common dark shade may be body text, navigation, or a large illustration. A rare bright shade may be the only meaningful action color. Review colors alongside page structure and component usage, then test:

1. Does text remain readable on its surface?
2. Does the action color stand apart from surrounding content?
3. Does hover or focus feedback remain visible without relying on color alone?
4. Do success and danger states remain distinguishable for people with color-vision differences?
5. Can the role work in both light and dark surfaces, or does it need a paired token?

Keep semantic tokens separate from raw palette tokens. For example, --color-brand-700 is a palette value, while --color-action-primary is a decision about use. That separation makes later redesigns safer.

Make the token file usable

For a handoff, include the token name, value, intended use, contrast notes, and replacement guidance. A compact JSON shape works well:

Do not confuse an extracted palette with ownership of an official design system. The observed colors can help you recreate a direction, but your team still needs to confirm naming, contrast, states, themes, and component rules before adopting the tokens across a product.

Use this in your AI agent

> Inspect the saved website reference, group its observed colors into semantic roles, separate raw palette tokens from component tokens, flag uncertain assignments, check text and action contrast, and return a compact CSS and JSON token draft with usage notes. Do not treat frequency alone as proof of a role.

Install Fudge for your AI agent to reuse this prompt while comparing saved website references.

Choose roles by combining three signals: where the color appears, what it does in the interface, and whether it remains readable in that context. Start with the largest repeated jobs: page background, main text, supporting text, borders, primary action, secondary action, and status states.

Use the darkest repeated neutral or tinted shade for primary text only if it works on the main surface. Use a lighter gray-green for muted text only after checking that small text remains readable. A medium or saturated color is a stronger candidate for actions when it appears on buttons, links, active controls, or selected states. Do not assign a color to a state role just because it looks green, amber, or red. Confirm that the surrounding message or icon also communicates the state.

Keep near-duplicates out of the first token pass. Pick one value for each role, record the alternatives, and test them in real components. If two shades have different jobs, name the jobs directly, such as action-primary and surface-accent, rather than inventing arbitrary numeric labels. Then add hover, pressed, focus, and disabled variants only where the interface demonstrates a meaningful change.

Use this five-step workflow:

1. Create a raw palette. Store each observed hex value with its source reference and a short note. Keep this layer unchanged so you can trace later decisions.
2. Assign semantic roles. Map only the colors you can explain: text, surfaces, borders, actions, links, and states. Mark uncertain mappings instead of hiding them.
3. Add component aliases. Point button, input, card, badge, and navigation tokens to semantic roles. This avoids repeating hex values throughout component styles.
4. Test combinations. Check normal and large text, icons, borders, buttons, focus indicators, hover states, and disabled states on every relevant surface. Recheck any role that changes in dark mode.
5. Export with notes. Deliver CSS variables or JSON alongside a short table that explains each token, its intended use, its contrast result, and its fallback.

Before merging, ask a designer or engineer to review names and confirm that the tokens describe decisions rather than temporary screenshots. A token file is ready when another person can use it without reopening the reference to guess what each value means.

Related questions

• Turn a Website Gradient Palette Into Reusable Design Tokens
• How to analyze accessible CTA colors on a live website
• Turn Text and Background Contrast Into Reusable Design Tokens
• Analyze a Dark Mode Color Palette on a Live Website