Give Claude Code a Website's Color Roles

If you want Claude Code to work with a website's colors, give it roles such as page background, surface, text, muted text, border, brand accent, and status colors instead of a loose list of hex codes. That lets it choose colors by purpose and keep new screens consistent with the existing site.

Start with roles, not swatches

Use a small token table that explains what each color does:

The values above are a working example, not a claim about any particular website. The captured examples below include Claude Code, Notion Developer Platform, and Exa MCP Server, along with a green-heavy palette containing colors such as #496c10, #15502e, #14532d, and #2c7a4a. Compare those examples visually before borrowing the pattern.

Make the palette useful to Claude Code

Claude Code needs more than color names. For each role, provide the hex value, where it appears, and how it should behave. A good note might say:

Also include relationships. Tell Claude Code which text color belongs on each surface, whether a button uses a darker hover state, and whether an accent is reserved for actions or can appear in illustrations. These rules prevent a model from treating every sampled color as interchangeable.

Check contrast and hierarchy

Before handing over the tokens, test the combinations people will actually use:

1. Body text on the page background.
2. Muted text on the page background.
3. Button text on the primary accent.
4. Link text on the page background.
5. Placeholder text in inputs.
6. Focus rings against both light and dark surfaces.
7. Status colors beside text, icons, and borders.

If a color works as a decorative accent but fails for small text, label it as decorative. If a muted color is too weak for important information, promote a darker alternative instead of asking Claude Code to guess.

Give it a decision framework

A practical instruction is: use semantic roles first, use the closest existing role second, and add a new token only when the interface needs a meaning the current set cannot express. Ask for a short explanation whenever a new color is introduced. This keeps the palette compact while preserving room for states such as hover, pressed, disabled, selected, error, and success.

For implementation, ask Claude Code to keep the role names stable while allowing the actual values to change. It can then map the same roles to CSS custom properties, Tailwind utilities, or component styles without scattering raw hex codes throughout the project. The goal is an understandable color system that another person can edit safely.

Use this in your AI agent

> Inspect the website's observed color palette and organize it into semantic roles: page background, surface, elevated surface, primary text, muted text, border, accent, accent hover, inverse surface, success, warning, and danger. For each role, return the hex value, where it appears, suitable text colors, contrast concerns, and states such as hover, focus, disabled, and selected. Keep decorative colors separate from usable text colors. Then write a compact implementation brief for Claude Code that uses semantic tokens instead of scattered hex values, and flag any role that needs manual verification.

Install Fudge for your AI agent to pass this kind of design reference into the conversation where Claude Code can use it.

Use names based on purpose rather than appearance. Prefer color.text.primary, color.surface.default, color.action.primary, and color.border.subtle over names such as green-1, dark-green, or light-gray.

A useful structure is:

Add a short usage rule to every token. For example, color.action.primary is for the main action in a group, while color.accent.decorative is not approved for body copy or controls. This distinction matters when several sampled colors look similar but serve different jobs.

Keep state tokens close to their base role. action.primary-hover is easier to understand than a separate generic dark green. If the design has multiple themes, keep the names fixed and provide a value for each theme. Ask Claude Code to use the semantic name in components and only reference the raw hex value inside the token definition.

Ask for a token file and a small usage guide before asking for a full redesign. The first pass should include CSS variables or the project's existing theme format, light and dark surface mappings if needed, text-on-background pairings, and component examples for buttons, links, cards, inputs, alerts, and focus states.

Then ask Claude Code to build a visual verification page with one sample of every role. Include primary and secondary buttons, normal and disabled controls, a form field, a card, a dark panel, inline links, and success, warning, and danger messages. This makes weak contrast or unclear hierarchy easy to spot.

Use this acceptance checklist:

• No component contains an unexplained raw hex value.
• Every action has visible hover, focus, pressed, and disabled behavior.
• Muted text is reserved for secondary information.
• Inverse text remains readable on dark surfaces.
• Status colors are not the only signal for important messages.
• New colors require a stated role and reason.

Only after that review should Claude Code apply the tokens across the wider interface.

Related questions

• Give Claude Code a Website's Component Styles
• Give Claude Code a Website's Border Radii and Shadows
• Give Claude Code a Website's Gradients and Backgrounds
• How to analyze typography hierarchy from a live website