Convert Website Design Details into a Tailwind CSS Theme

To convert website design details into a Tailwind CSS theme, first separate what you observed from the implementation decisions you need to make. Then map repeated visual patterns to semantic Tailwind theme variables. This produces a theme you can maintain instead of a list of copied CSS values.

Start with semantic tokens

Use names that describe each token's role, such as --color-page, --color-surface, --color-foreground, --color-muted, --color-border, and --color-accent. These names remain useful if the project's palette changes.

Treat these values as an example mapping, not as verified values for every website. Replace them with values you inspected and mark estimates as unverified. Promote a value to a theme token when it recurs or clearly represents a component role. Keep isolated illustration colors and one-off measurements local.

The captured Linear example can help you compare typography observations. Its supplied evidence shows Inter at weights 400 and 500, but that does not establish Linear's complete private design system.

Map the visual system in order

Work through the reference in a consistent order:

1. Canvas and surfaces: page background, cards, overlays, and inverse sections.
2. Text: primary, secondary, disabled, link, and heading roles.
3. Borders and states: dividers, focus rings, success, warning, and danger.
4. Typography: families, available weights, sizes, line heights, and tracking.
5. Spacing: container padding, section gaps, card padding, control gaps, and grid gaps.
6. Shape and depth: radii, shadows, gradients, and image treatments.

Record raw observations before assigning tokens. If two colors are nearly identical, check whether they are separate roles or artifacts from antialiasing, imagery, or a different page state. Keep light and dark surfaces distinct when their contrast affects component behavior.

For spacing, create a compact scale from repeated measurements. A scale based on recurring values such as 4, 8, 12, 16, 24, and 32 pixels is generally easier to use than dozens of one-off values. The exact scale should follow the reference rather than an assumed framework default.

Build and check the Tailwind theme

Tailwind v4 lets you define tokens directly in CSS and use them as utilities:

Render representative components before treating the theme as complete: a page shell, heading and paragraph, primary button, card, form control, and metadata row. Compare text wrapping, contrast, spacing, radius, shadow strength, and responsive behavior at the target viewport. If the capture shows interactive states, check at least one hover, focus, disabled, success, or error state as appropriate.

Verify that the requested font family and weights are available to the project before relying on them. Observed typography is evidence about the reference, not permission to redistribute font files or a guarantee about licensing. Keep a short unverified list for estimated colors, inferred breakpoints, unavailable variants, and states that were not visible.

Use this in your AI agent

> Inspect the saved website reference and convert its observed design details into a Tailwind CSS v4 theme. Identify semantic roles for page surfaces, text, borders, accents, states, typography, spacing, radii, shadows, and component patterns. Return an @theme CSS block, a concise mapping table, representative class examples, and an unverified list. Use observed values where supported, preserve visible type weights and responsive rules, and do not invent an official internal design system.

Install Fudge for your AI agent to inspect saved references and prepare the theme as you build.

Choose names from the role you can observe, not from a guessed internal naming scheme. surface.page, surface.card, text.primary, text.muted, border.subtle, and accent.primary are safer than names such as brand-900 or gray-750 when you do not know how the original team organized its tokens.

In Tailwind CSS v4, you can flatten those roles into readable theme names:

Add a short comment or mapping document that explains where each role appears. If the same value serves multiple purposes, use one shared token only when the roles are visually and behaviorally equivalent. If a color appears once in an illustration, leave it as a local value rather than promoting it to the main theme. This keeps the theme useful without claiming knowledge the page does not show.

Run a focused review before replacing existing project tokens. Check that the theme parses, that every custom utility resolves, and that the required font family and weights are actually available. Then render a small comparison page containing the main background, card, heading, paragraph, button, input, link, focus state, and one responsive layout.

Compare these details in order:

• Text contrast against each surface.
• Heading and body wrapping at the target viewport.
• Spacing between sections and inside components.
• Button and input heights, padding, and radius.
• Border visibility without making cards look heavier than the reference.
• Shadow density and whether it disappears correctly on small screens.
• Focus, hover, disabled, success, and error states.

Keep the source observations beside the generated CSS. Mark estimated colors, inferred breakpoints, and unavailable font variants as unverified. If a token works for one page but creates awkward results elsewhere, split the role or revise the mapping instead of adding arbitrary utility overrides everywhere. The goal is a maintainable theme that reflects the observed design, not a claim that it is the original project's private configuration.

Related questions

• Convert Website Design Details into a Tailwind v4 Theme
• Convert Website Design Details into Structured JSON
• Create color and font tokens from a website reference
• Convert website design details into a reusable design reference file