Convert Website Design Details into a Design Report

Contents

• [Use a report structure that supports decisions](#use-a-report-structure-that-supports-decisions)
• [Write observations that another person can check](#write-observations-that-another-person-can-check)
• [Turn the report into an implementation handoff](#turn-the-report-into-an-implementation-handoff)
• [Review the report before implementation](#review-the-report-before-implementation)
• [Use this in your AI agent](#use-this-in-your-ai-agent)

To convert website design details into a design report, capture the page's observable rules and organize them into typography, color, layout, shape, depth, and component sections. A useful report separates what is visible from what is inferred, so a designer or AI coding agent can act on it without treating the report as the site's official internal design system.

Use a report structure that supports decisions

Use this order:

1. Summary: describe the visual direction in two or three sentences.
2. Typography: list families, weights, sizes, line heights, casing, and typical uses.
3. Color roles: name backgrounds, surfaces, text levels, borders, accents, and visible states.
4. Layout: record viewport assumptions, container behavior, columns, gaps, alignment, and responsive changes.
5. Components: document repeated buttons, cards, inputs, navigation, badges, and other patterns.
6. Implementation notes: turn observations into reusable CSS, Tailwind v4, JSON, or DESIGN.md guidance.

The report should answer practical questions quickly: Which font should a heading use? How muted is secondary text? How much space sits between related controls? Which radius belongs on a card? What changes on a narrow screen?

The Linear capture provides a concrete example of a compact sans-serif direction. Its typography evidence lists Inter at weight 400 for body copy, labels, navigation, and controls, and weight 500 for headings and emphasized interface text. Treat those as observed example details, not a universal rule for every website.

Write observations that another person can check

Avoid vague notes such as “clean,” “modern,” or “well balanced” unless you explain what creates that effect. Prefer statements such as:

• “The interface uses a compact sans-serif family, with contrast coming from size, weight, and muted color.”
• “Primary text is distinct from labels and secondary copy through both color and weight.”
• “Cards use a consistent border and radius treatment rather than relying only on shadows.”
• “A repeated spacing interval appears between related controls and inside card content.”

For each detail, add a confidence label: observed, estimated, or needs verification. If a font file, hover state, keyboard focus state, breakpoint, or hidden panel was not visible, say so. This tells the implementer where to check instead of presenting every guess as fact.

Turn the report into an implementation handoff

After the descriptive sections, add a compact token table with the token name, observed value, role, confidence, and location. For example:

Then add component notes. A button entry should cover label casing, font weight, padding, radius, fill, border, hover, focus, and disabled behavior. A card entry should cover width behavior, internal spacing, border, radius, shadow, and the relationship between its title and supporting copy.

This structure works for a human handoff and for an AI coding agent. If you want a machine-readable artifact, keep the report readable first and place JSON or Tailwind values after the explanation. Fudge lets you inspect captured page structure, typography, colors, spacing, borders, radii, shadows, gradients, and component styles, then export supported observed details into a project artifact.

Review the report before implementation

Use this quality check:

• Can someone identify the font and weight for each major text role?
• Are colors labeled by purpose rather than listed as anonymous swatches?
• Are repeated spacing and shape rules separated from one-off exceptions?
• Does the report mention responsive behavior and visible states?
• Are uncertain details clearly marked?
• Does the implementation section preserve the design direction without claiming access to an official internal system?

Finally, ask the implementer to build one representative screen from the report and compare it with the reference. Revise the report when the mismatch comes from a missing rule, rather than adding random overrides.

Use this in your AI agent

> Inspect the saved website reference and write a design report for implementation. Cover the visual summary, typography families and variants, text roles, color roles and contrast, spacing scale, layout and responsive behavior, borders, radii, shadows, gradients, and repeated component states. Mark each detail as observed, estimated, or needing verification. Include a token table and practical notes for headings, body copy, controls, cards, navigation, and forms. Keep observed design details separate from suggestions, and do not claim this is the source site's official internal design system.

Install Fudge for your AI agent

Prioritize details that change implementation decisions. Typography comes first because the wrong family, weight, size, or line height can make every spacing judgment look wrong. Next record color roles, especially page background, surfaces, primary text, muted text, borders, accents, and visible states.

Then document the layout: content width, outer gutters, column behavior, repeated gaps, alignment, and what changes at narrower widths. For components, focus on patterns that appear more than once. A button report should include label treatment, padding, radius, fill, border, focus state, and disabled state. A card report should include internal spacing, title-to-body hierarchy, border, radius, and shadow.

Also record what you could not verify. A visible static page may not reveal hover behavior, keyboard focus, error states, or all breakpoints. Labeling those gaps keeps the report honest and tells the implementer where to make a deliberate choice rather than copying a guess.

End the report with named tokens and a short set of implementation rules. Each token should have a role, value, confidence level, and example use. This makes it easier to correct one global decision instead of hunting through individual components.

Add a representative screen checklist: heading hierarchy, body and muted text, primary and secondary buttons, an input, a card, a border, and a responsive layout. Ask the developer or agent to build that screen using only the report, then compare the result with the reference. Record mismatches under typography, color, spacing, shape, depth, or behavior.

For an AI agent, include guardrails: reuse named tokens, avoid arbitrary values unless the report marks them as one-off, keep uncertain items visible, and ask before inventing missing states. This turns the report into a working brief rather than a static inventory.

Related questions

• Convert Website Design Details into JSON Design Tokens
• Convert website design details into a reusable design reference file
• Convert website design details into CSS variables
• Convert Website Design Details into a Tailwind v4 Theme