# Convert Website Design Details Into Structured JSON for AI Coding Agents

[Open the live Fudge conversation](https://design.withfudge.com/share/website-to-structured-json-design-details-converter-for-ai-coding-agents)

Last updated: 2026-08-25

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:

```json
{
  "reference": {
    "name": "Captured page",
    "url": "https://example.com",
    "viewport": { "width": 1440, "height": 900 }
  },
  "direction": "compact and restrained",
  "typography": {},
  "colors": {},
  "layout": {},
  "components": [],
  "assets": [],
  "uncertainties": []
}
```

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.

## Captured pages

[![The system for product development](https://pin.fontofweb.com/6434?format=jpg)](https://design.withfudge.com/share/pin-6434)

[The system for product development](https://design.withfudge.com/share/pin-6434)

## Linear typography

- **Inter** — weight 400 · Body copy, labels, navigation, and controls.
- **Inter** — weight 500 · Headings and emphasized interface text.

## 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:

```json
{
  "role": "button",
  "observed": {
    "radius": "medium",
    "border": "subtle",
    "textWeight": 500
  },
  "guidance": {
    "reuseToken": "buttonRadius",
    "preserveKeyboardFocus": true
  },
  "notes": ["Exact radius should be confirmed in the reference"]
}
```

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](/mcp)

---

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:

```json
{
  "value": "Inter",
  "role": "body",
  "observed": true,
  "confidence": "high",
  "notes": "Used for labels and paragraph copy"
}
```

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:

```text
Use design-reference.json as the source of truth for visual details. Map semantic colors, typography roles, spacing, radii, borders, and shadows to reusable project variables. Update the header and primary button first. Do not invent values when the JSON is uncertain; note those choices for review. Preserve behavior, content, keyboard access, and responsive usability. After the change, report which JSON fields were applied and which remain unresolved.
```

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](/share/website-to-tailwind-css-theme-converter-for-ai-coding-agents)
- [Convert a Website into a Reusable Design Reference File for AI Coding Agents](/share/website-to-reusable-design-reference-file-converter-for-ai-coding-agents)
- [Website to JSON Design Tokens Converter for AI Coding Agents](/share/website-to-json-design-tokens-converter-for-ai-coding-agents)
- [Convert Website Design Details into Color and Font Tokens](/share/convert-website-design-details-into-color-and-font-tokens)