Convert website design details into a reusable design reference file

Contents

• [Use this reference-file method](#use-this-reference-file-method)
• [Capture details without overclaiming](#capture-details-without-overclaiming)
• [Choose the output for the job](#choose-the-output-for-the-job)
• [Review before sharing](#review-before-sharing)
• [Use this in your AI agent](#use-this-in-your-ai-agent)

A reusable design reference file should turn observed website details into decisions your team can apply, not just collect screenshots. Start by recording the page, typography, colors, spacing, components, and open questions in a consistent structure, then export the result as DESIGN.md, JSON, CSS, or Tailwind depending on who will use it.

Use this reference-file method

Create the file in five parts:

1. Reference and scope: record the page used, viewport or page state if relevant, and which parts were actually reviewed.
2. Typography: list each family, role, weight, size, line height, letter spacing, and sample use. Separate interface text from display or editorial text.
3. Color: group colors by role such as page background, surface, text, muted text, border, accent, success, and danger. Include contrast notes where they affect a decision.
4. Layout and components: document container widths, spacing patterns, radii, borders, shadows, buttons, cards, navigation, forms, and repeated sections.
5. Usage rules and unknowns: explain where a token should be used, where it should not be copied, and which details still need confirmation.

This structure keeps the file useful during implementation. A screenshot can show what a page looks like, while the reference file explains what to repeat.

Open the examples below and compare the captured Linear page with its typography notes before borrowing a pattern. The example is useful as a reference point, but treat its details as observations from that captured page rather than a complete internal design system.

Capture details without overclaiming

Use direct observations and clear labels. Write Inter, regular, used for body copy and controls instead of claiming that the entire product uses one font everywhere. Record a color as a role and value, such as surface-subtle: #..., only when the value has been observed. If a value, breakpoint, interaction, or component state was not reviewed, mark it as unknown.

A good entry answers three questions:

• What is it? For example, a type family, spacing step, border, or card treatment.
• Where does it appear? Name the page area or component.
• How should it guide new work? State whether it is a token, a one-off treatment, or an example to compare against.

This prevents a reference file from quietly becoming an invented specification. It also makes later updates easier when another page reveals a different state or a second typeface.

Choose the output for the job

Use DESIGN.md when people need readable guidance, rationale, examples, and implementation notes. Use JSON when another tool needs structured values and roles. Use CSS when the immediate goal is to apply variables in a prototype or existing stylesheet. Use Tailwind v4 when the team already works with utility classes and wants theme values connected to that workflow.

You can keep more than one output if they serve different readers, but use one reviewed source of truth. Check that names match across files: --color-surface, surface, and surface-subtle should not refer to three different ideas by accident.

A practical file might include this compact checklist:

Review before sharing

Before another designer or developer uses the file, check that every token has a role, every role points to an observed example, and every recommendation is separated from the observation. Compare the file against the captured page at the same viewport. Look especially for mobile behavior, hover or focus states, dark mode, and content-length changes, since a single screen may not reveal them.

A useful final test is to ask someone unfamiliar with the source page to build one small section using only the reference. If they can choose the right type, colors, spacing, and component treatment without guessing, the file is doing its job. If they need to reopen the screenshot for every decision, add the missing rule or example.

Use this in your AI agent

> Inspect the captured website reference and create a reusable design reference file. Separate observed details from recommendations, document typography, color roles, spacing, borders, radii, shadows, and repeated components, list unknowns instead of guessing, and return DESIGN.md plus structured JSON or Tailwind v4 values where supported. Keep token names consistent and include a short review checklist.

Install Fudge for your AI agent.

A useful DESIGN.md file should help someone make design decisions without reopening the source page for every detail. Keep it organized around the way the team will use it.

Recommended DESIGN.md outline

Start with Reference, including the page URL or capture name, reviewed sections, viewport, page state, and date of review. Then add Design summary, with two or three sentences describing the visible direction without turning it into a brand claim.

Add Typography with family, role, weight, size, line height, tracking, and examples. Add Colors as named roles, not an unlabelled swatch list. Include background, surfaces, primary and muted text, borders, accents, status colors, and any gradients that matter.

Add Layout for container width, columns, section gaps, padding, alignment, and responsive observations. Add Components for buttons, links, cards, navigation, forms, badges, and repeated patterns. For each component, record shape, dimensions, states, and a short usage rule.

Finish with Open questions and Do not assume notes. That section is important when only one page or state was reviewed. It prevents a visible example from being mistaken for a complete system.

For practical reuse, add a small Decision log with the date, the person who reviewed the reference, and any changes made after comparing a second page or viewport. Keep observations, recommendations, and unresolved questions visually distinct so a later editor can update one without accidentally presenting it as verified source information.

Convert the file in two passes. First, normalize the observations into stable roles. Second, map those roles to the format your project already uses.

Normalize first

Use names based on purpose: color.background, color.surface, color.text, color.textMuted, color.border, and color.accent. For type, use roles such as font.body, font.heading, and font.mono, with separate weight and size values. Keep one canonical value for each role and note where a component needs an exception.

Map to your codebase

For CSS, create custom properties such as --color-surface and --font-body. For JSON, keep the same names and add fields for value, role, source location, and confidence or review status. For Tailwind v4, map the same roles into the theme so utilities and documentation refer to identical concepts.

Then test the tokens in one representative section. Check headings, body copy, muted text, borders, buttons, cards, and spacing together. If the result only works when many one-off overrides are added, the roles are probably too broad or the source page was not reviewed deeply enough. Keep those exceptions documented rather than hiding them.

Before publishing, validate the token set against at least one real content example and one narrow viewport. Confirm that text remains readable, spacing does not collapse, and component states have sensible values. If the reference only shows one state, keep hover, focus, disabled, dark-mode, and responsive values marked as recommendations until they are reviewed.

Related questions

• Convert Website Design Details into Structured JSON
• Convert Website Design Details into a Tailwind CSS Theme
• Create color and font tokens from a website reference
• Create CSS Custom Properties from a Website Reference