Convert Website Design Details Into Structured JSON for AI Coding Agents

Contents

• [Use a schema that supports real implementation](#use-a-schema-that-supports-real-implementation)
• [Recommended JSON sections](#recommended-json-sections)
• [Keep observed data separate from agent instructions](#keep-observed-data-separate-from-agent-instructions)
• [A reliable conversion and review checklist](#a-reliable-conversion-and-review-checklist)
• [Use this in your AI agent](#use-this-in-your-ai-agent)

A website-to-structured-JSON converter turns a captured reference into machine-readable design details that an AI coding agent can inspect, validate, and apply in a project. The most useful JSON separates page structure, typography, color roles, layout, components, assets, and confidence instead of putting every observation into one unstructured description.

Use a schema that supports real implementation

Your JSON should answer the questions an agent needs during coding:

• What page or component was inspected?
• Which details are directly observed?
• Which values are approximate?
• Where should each color, font, spacing value, or shape be used?
• Which components repeat across the page?
• What changes at smaller viewport sizes?

A practical top-level structure looks like this:

The exact values should come from the captured reference, not from assumptions. If a size or responsive breakpoint is unclear, store it as an estimate or add it to uncertainties rather than presenting it as fact.

Recommended JSON sections

Typography should contain families, variants, weights, sizes, line heights, and roles. For example, a family entry might distinguish body text from headings and controls. The captured Linear example below shows why role-based records help: Inter at weight 400 is associated with body copy, labels, navigation, and controls, while weight 500 is associated with headings and emphasized interface text.

Colors should use semantic names such as background, surface, textPrimary, textMuted, border, and accent. Include a value, role, and where it appears. If you record frequency or contrast, label those as observations from the reference rather than universal rules.

Layout can include content width, columns, alignment, section spacing, grid behavior, and viewport-specific changes. Keep numeric values in a consistent unit and record whether they are exact, estimated, or inferred from repeated patterns.

Components should be an array of reusable patterns. Each item can include a name, instances, dimensions, padding, radius, border, shadow, typography, colors, states, and responsive notes. This gives an agent enough information to update a button or card consistently across several pages.

Keep observed data separate from agent instructions

A common mistake is mixing measurements with implementation decisions. Use fields such as source, confidence, or notes to make the boundary visible:

The observed object describes the reference. The guidance object explains how the agent should work in the project. This makes the JSON useful for both review and automation without hiding uncertainty.

A reliable conversion and review checklist

1. Capture the page at the viewport and state that matter.
2. Record the page regions before extracting individual components.
3. Inspect fonts and variants, then map them to roles.
4. Group colors by use and verify text contrast where relevant.
5. Record spacing, borders, radii, shadows, gradients, and alignment.
6. Describe repeated components and their visible states.
7. Add image, video, crop, overlay, motion, and clipping notes only when they affect the design.
8. Mark estimates and unanswered questions.
9. Validate the JSON against a stable schema.
10. Give the coding agent a scoped task and tell it to preserve behavior.

Open the captured Linear example below as a reference for how a compact visual system can be summarized without inventing a complete internal token set. Treat it as inspiration for the shape of your records, not as a result for a new website.

Fudge supports exporting observed website details to structured JSON, as well as CSS, Tailwind v4, and DESIGN.md. JSON is the better choice when your coding workflow needs to transform, validate, or combine the design details before implementation. A human should still review the capture and remove anything that is not supported by the visible reference.

Use this in your AI agent

> Inspect the captured website reference and export its observed design details as structured JSON for this project. Include page structure, typography families and weights, semantic color roles, layout and spacing, borders, radii, shadows, gradients, repeated components, responsive behavior, and relevant image or motion treatment. Separate observed values from implementation guidance, label estimates and uncertainties, and avoid inventing details that are not visible. Then use the JSON to propose reusable design tokens without changing existing behavior or accessibility. > > Install Fudge for your AI agent

Use fields that map directly to implementation decisions. A useful schema includes reference, direction, typography, colors, layout, components, assets, and uncertainties.

Inside typography, include family, variant, weight, size, line height, tracking, and role. Inside colors, use semantic roles such as background, surface, primary text, muted text, border, accent, and status colors. Inside layout, include content width, columns, alignment, grid behavior, section gaps, and viewport notes. Inside components, describe repeated patterns with padding, radius, border, shadow, typography, colors, and states.

Add provenance-friendly fields where they help review:

Keep implementation instructions separate from observations. That lets an agent apply the data while preserving a clear record of what came from the reference and what was chosen for the new project.

Make the JSON the explicit source of truth and give the agent a small, testable task. Tell it to inspect the existing code first, map JSON roles to reusable variables, and list any missing or uncertain values before making broad changes.

Your prompt should also define boundaries: preserve routes, content behavior, accessibility semantics, and existing interactions unless the task specifically changes them. Ask for one representative component first, such as a button, card, or header. Compare that result with the captured reference, then extend the same tokens and rules to the rest of the page.

A concise instruction is:

This workflow keeps the agent focused and makes visual differences easier to trace back to a documented decision.

Related questions

• Website to Tailwind CSS theme converter for AI coding agents
• Convert a Website into a Reusable Design Reference File for AI Coding Agents
• Website to JSON Design Tokens Converter for AI Coding Agents
• Convert Website Design Details into Color and Font Tokens