Create JSON Design Tokens from a Website Reference

You can create JSON design tokens from a website reference by separating what you observed from the names and structure you propose for your project. The useful output covers typography, colors, spacing, borders, radii, shadows, gradients, and recurring component styles. It also records the page state, viewport, context, and uncertainty behind each value.

Use a two-pass token method

Start with a captured reference rather than a screenshot alone. Review the page structure, sections, components, layout, viewport, and page state that you intend to reproduce. Then organize the result into two layers:

1. Raw observations: details seen on the page, such as a font family, weight, muted text color, border treatment, card radius, or shadow.
2. Project tokens: stable names your team can use, such as color.text.muted, font.body.family, space.section, or radius.card.

This keeps a proposed token name from being mistaken for the original site's official naming system. Record the source page and the context for each important value.

The supplied Linear reference is paired with typography evidence that lists Inter at weights 400 and 500. The usage notes distinguish body copy, labels, navigation, and controls from headings and emphasized interface text. Treat those details as grounded observations for that reference, not as universal rules for every project.

Use a predictable JSON structure

Keep the source record honest. If the exact page URL, state, viewport, or value was not captured, use unverified or leave the field empty instead of filling it with a guess. For colors, record both the role and the value. For typography, include family, variant, size, weight, and line height when those details are available.

For component groups, use names such as button.primary, card.default, input.error, and navigation.desktop only when those states were actually observed. Mark proposed groups separately from observed groups.

Review the file before implementation

Use this checklist:

• Confirm that every value was observed or is labeled as proposed.
• Record the page, viewport, and state where important values appeared.
• Separate text, background, border, accent, and status colors.
• Record font family and weight by usage, not only as a list of names.
• Capture page gaps, card padding, control height, and section separation.
• Keep radii, borders, shadows, and gradients separate.
• Add groups for recurring buttons, cards, inputs, navigation, and content sections.
• Mark responsive, hover, open-menu, modal, and other state-specific observations.
• Review contrast and readability before reusing a color relationship.

A practical naming rule is to put the design role first and the component name second only when the value is genuinely component-specific. color.surface.raised is broadly reusable, while button.primary.radius is appropriate when a button differs from the rest of the interface.

Keep observations separate from claims

A JSON export can provide a strong starting point for recreating the visible language of a reference. It should not claim to be the site's official design system unless the owner supplied that system. Use fields such as status: "observed", status: "proposed", and status: "unverified" so later reviewers can tell what is ready to use.

You can also add a review record for important values:

The fastest workflow is to capture the page, inspect its visible details, group them into the structure above, and export the supported observations to JSON. Keep a short list of decisions that still need a closer page comparison or designer approval.

Use this in your AI agent

> Inspect the captured website reference and create a structured JSON design-token file. Include observed typography families, variants, sizes, weights, line heights, color roles and values, spacing, borders, radii, shadows, gradients, and recurring component styles. Separate raw observations from proposed token names, label uncertain values as unverified, note page state and viewport context, and do not claim the result is the site's official internal design system. Return valid JSON followed by a short verification checklist.

Install Fudge for your AI agent

For typography, include family, variant, weight, size, lineHeight, letterSpacing, and a usage role such as body, heading, navigation, label, or control. If an exact variant is not available, keep the observed family and weight, then mark the missing detail for verification.

For colors, include a semantic role, observed value, context, and status. Useful roles include text.primary, text.muted, surface.base, surface.raised, border.subtle, and accent.primary. Store the raw color separately from the semantic name so a later review can change the token name without losing the observation.

Also record whether a value appeared in text, a background, a border, an icon, a gradient, or an interaction state. This makes the JSON easier to compare across pages and safer to adapt.

Convert the export into three review lists. First, ask whether each value was directly observed and whether its page, viewport, and state are recorded. Second, check whether token names describe reusable roles instead of copying arbitrary class names or visual labels. Third, test the tokens against the components you plan to build.

A simple review table can include token path, observed value, where it appeared, status, proposed use, and approval status. Review the highest-impact items first: body and heading type, main text and background colors, control height, section spacing, card radius, border contrast, and shadow strength. Then review secondary details such as gradients, icon colors, hover states, and responsive changes.

Keep a clear distinction between observed, proposed, and unverified. That lets the team use the file immediately while preserving a short list of decisions that still need a closer page comparison or designer approval.

Related questions

• Create a reusable design reference file from a website
• Create structured JSON design details from a website reference
• Create a Tailwind CSS Theme from a Website Reference
• Create CSS Custom Properties from a Website Reference