Create structured JSON design details from a website reference

Contents

• [Build the JSON around design decisions](#build-the-json-around-design-decisions)
• [Check the reference before exporting](#check-the-reference-before-exporting)
• [Choose the right export for the job](#choose-the-right-export-for-the-job)
• [Use this in your AI agent](#use-this-in-your-ai-agent)

To create structured JSON design details from a website reference, first capture the page, inspect its visible design choices, then export the findings as organized fields for colors, typography, layout, spacing, and components. Treat the result as a record of what the page uses, not as proof that you have the site's private or official design system.

A reliable workflow is: capture the reference, check the page structure and viewport, inspect the type and color details, review repeated component patterns, and export only details that are supported by what you observed. This gives you a practical starting point for recreating a visual direction without confusing a single page with every rule used across a product.

Build the JSON around design decisions

Start with a small structure that mirrors the questions you need to answer. Use top-level groups such as meta, colors, typography, layout, spacing, borders, shadows, and components. Keep the source page, capture date, viewport, and any uncertainty in meta, so another person can tell where each observation came from.

For colors, record a usable role rather than only a list of hex values. Fields such as background, surface, text, mutedText, border, accent, and button are easier to apply than unnamed swatches. Include the observed value, where it appears, and whether it seems common or limited to one component. For typography, record the family, variant or weight, approximate size, line height, casing, and likely use such as body copy, heading, label, or navigation.

For layout, capture the page width, major sections, column relationships, alignment, and repeated gaps. Components can hold details for cards, buttons, inputs, navigation, and callouts. A useful component entry might include its background, border, radius, padding, text treatment, and states that were actually visible. Avoid filling unknown fields with guesses. A missing value is more useful than a confident but unsupported one.

Check the reference before exporting

Inspect the page at the viewport that matters for your work, then check a second size if responsive behavior is important. Look for changes in navigation, column stacking, spacing, heading scale, image crops, and button arrangement. Separate a design choice from an accidental result of the captured window: a clipped image or hidden menu may reflect the viewport rather than the intended component rule.

Use repeated evidence to decide what belongs in a shared value. If the same muted text color appears in several labels and paragraphs, it is reasonable to record it as a likely text role. If a color appears once in a decorative illustration, keep it as a local detail instead of promoting it to a global token. The same rule applies to radius, shadow, spacing, and font weight.

Open the examples below and compare the first screen before borrowing a pattern. The Linear reference is represented with a compact sans-serif treatment: Inter is shown at regular weight for body and control text, and at medium weight for headings and emphasized interface text. That is a useful observed example of how contrast can come from size, weight, and muted color, but it should not be treated as a universal rule for every Linear page.

Before saving the JSON, run a simple quality check: every token has a role, every component value has a location or reason, repeated values are grouped consistently, and uncertain observations are marked for review. Also check that the file remains readable to a person who did not inspect the original page.

Choose the right export for the job

Use JSON when you need a portable inventory that another script, design review, or assistant can consume. Use CSS or Tailwind when the goal is immediate implementation. Use a written design document when people need the reasoning and examples alongside the values. These outputs can come from the same inspection, but they serve different next steps.

A JSON record should distinguish raw observations from suggested reuse. For example, observed can hold the exact color and location, while suggestedToken can hold a proposed name such as color.surface.subtle. This keeps the export honest: the page supplied the evidence, while the token naming is your interpretation. Do the same for responsive rules, component states, and semantic color roles.

A practical starter shape is:

Replace placeholders only after checking the reference. If you need to reuse the work, keep the source capture beside the JSON and note which fields were directly observed, which were inferred from repetition, and which still need verification. That makes the artifact useful for implementation without claiming ownership of an official internal design system.

Use this in your AI agent

> Inspect my captured website reference and create a structured JSON design inventory. Record only supported observations for page structure, viewport behavior, colors and their roles, typography families and weights, spacing, borders, radii, shadows, gradients, and repeated components. Separate exact observations from suggested reusable token names, mark uncertain fields for review, and format the result so I can use it as a starting point for CSS or Tailwind implementation. Do not claim this is the site's official internal design system.

Install Fudge for your AI agent to run this workflow while you review the captured reference.

Use fields that describe both the value and its purpose. A useful structure includes meta, colors, typography, layout, spacing, borders, shadows, gradients, components, and responsive. In meta, store the source reference, viewport, page state, and confidence notes.

For each color, include value, role, where, and optionally frequency or contrastNote. For typography, include family, variant, weight, size, lineHeight, letterSpacing, case, and usage. For layout, record container width, section order, columns, alignment, and major gaps. For components, describe the visible states separately: default, hover if captured, disabled if captured, and active if captured.

Keep observed and proposed values apart. For example:

This gives you enough detail to rebuild the visual language while making it clear which names and groupings are your own implementation choices. Ask your AI agent to inspect the capture and flag missing values rather than filling them in.

Copyable prompt: "Inspect my captured reference, list observed JSON fields for colors, type, layout, spacing, and components, then separate proposed tokens from evidence. Start here: /mcp."

First, review the JSON and remove one-off details that do not need to become shared tokens. Keep repeated colors, type scales, spacing steps, radii, shadows, and component rules. Then map the remaining values to stable names based on their role, not their appearance. color.text.primary is more durable than color.darkGray.

Keep a source section so the token file remains traceable to the reference. A simple token layer might look like this:

Validate the result by applying it to one representative screen and comparing the container width, type hierarchy, button treatment, spacing, and surface contrast. If the recreation feels wrong, return to the observed JSON instead of adjusting the token names blindly. The source record should remain the reference point, while the token file is the implementation layer built from it.

Copyable prompt: "Convert my observed design JSON into role-based tokens, preserve the source evidence, identify one-off values, and suggest a validation checklist. Continue at /mcp."

Related questions

• Create a Tailwind CSS Theme from a Website Reference
• Create a reusable design reference file from a website
• Create JSON Design Tokens from a Website Reference
• Export a website design system as color and font tokens