# Convert Website Design Details into a design.md File [Open the live Fudge conversation](https://design.withfudge.com/share/convert-website-design-details-into-design-md-file) Last updated: 2026-08-25 A useful `design.md` file should turn observed website details into decisions another designer or developer can apply. Start with a captured page, record the visible type, colors, spacing, borders, shadows, and repeated components, then organize those findings into tokens, patterns, and page-specific notes. The safest workflow is to separate what you observed from what you recommend. Observed details describe the page as it appears. Recommendations explain how to reproduce the look in a new project. That distinction matters because an extracted document can guide implementation, but it is not automatically the website owner's official internal design system. ## Use a repeatable extraction method Begin with the page's main visual structure: canvas size, content width, header, navigation, hero, primary action, supporting sections, cards, forms, and footer. For each region, note alignment, spacing, background treatment, border use, corner shape, shadow, and whether the element repeats. Capture enough context to understand how the pieces work together, rather than collecting isolated colors or font names. Next, inspect typography and color as systems. Record each font family, available weight, approximate size, line height, casing, and role. A practical table might include body text, labels, navigation, headings, display text, buttons, and captions. For color, name roles such as page background, surface, text, muted text, border, accent, success, and danger. Include the actual value and where it appears so the reader can distinguish a dominant page color from a one-off illustration color. Then check the page at more than one viewport or state when the capture allows it. A design document is much more useful when it records whether content collapses, wraps, stacks, hides, or changes emphasis on smaller screens. If you only have one state, say so. Do not present an inferred mobile layout as an observed 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. ## Structure the design.md file for reuse A good document opens with a short visual summary: the page's overall mood, density, contrast, and main layout principle. Follow that with a token section for colors, typography, spacing, radii, borders, shadows, and motion. Use names that describe roles, such as `--color-surface-muted` or `--radius-card`, instead of names tied to one component. Include raw values beside the names so the file remains useful outside a particular framework. After tokens, document reusable patterns. For each pattern, include its purpose, anatomy, sizing, alignment, states, and responsive behavior. A button entry might cover label hierarchy, height, padding, radius, fill, text color, hover treatment, focus treatment, disabled treatment, and icon spacing. A card entry might cover image ratio, content padding, title-to-description gap, metadata styling, and whether the whole card is clickable. End with page composition notes and implementation cautions. List the order of major sections, the most important content width, likely breakpoints, and any details that need manual review. Mark uncertain values as estimates. If a visual comes from an image, gradient, animation, or captured interaction rather than a reusable token, label it as page-specific. This keeps the document honest and prevents accidental overgeneralization. Open the examples below to compare a concrete reference before borrowing a pattern. The Linear example shows a compact sans-serif approach, with Inter used for body copy and a heavier weight for headings and emphasized interface text. That is useful inspiration for documenting hierarchy, but it should not be treated as a rule for every website. ## A practical design.md outline Use this outline as a starting point: 1. **Overview**: visual character, page purpose, canvas, content width, and key layout rules. 2. **Design tokens**: colors by role; font families and weights; type sizes and line heights; spacing scale; borders; radii; shadows; gradients; motion. 3. **Components**: navigation, buttons, links, cards, forms, alerts, tables, media blocks, and repeated sections. 4. **Page structure**: section order, container behavior, alignment, responsive changes, and important states. 5. **Accessibility checks**: text contrast, visible focus, heading order, labels, target sizes, and motion preferences to verify. 6. **Open questions**: values that were estimated, states not captured, and details requiring review against source files. For every entry, prefer a short table when several values need comparison. For example, list `Body`, `Heading`, and `Display` with family, weight, size, line height, and role. For colors, include a swatch name, value, role, and observed location. For components, use a concise checklist rather than vague prose. The document should help someone build the next screen without reopening the original page for every decision. One specific action can make this faster: use a captured reference to inspect its typography, colors, layout, and repeated components, then export the supported observed details into a `DESIGN.md` starting point. Review the result manually, add the decisions that require judgment, and remove anything that was not actually visible in the capture. ## Use this in your AI agent > Inspect the captured website reference and create a `design.md` file. Separate observed facts from recommendations. Document the page overview, color roles, typography families and weights, spacing, borders, radii, shadows, gradients, responsive behavior, reusable components, accessibility checks, and open questions. Use tables where they improve comparison, mark estimates clearly, and do not invent states or values that are not supported by the capture. End with a short implementation checklist for a developer. > > [Install Fudge for your AI agent](/mcp) to run this workflow from your agent. --- Treat the file as a desktop observation with clearly marked limits. Start by documenting the visible canvas, content width, section order, navigation, hero, buttons, cards, forms, imagery, and footer. For each repeated element, record the spacing, alignment, type hierarchy, colors, borders, corner treatment, and shadows you can actually see. Create a separate section called `Responsive questions` rather than guessing mobile behavior. Note which elements might need to stack, wrap, hide, or change size, but label those as decisions to verify. Do the same for hover, focus, error, loading, and disabled states. A single screenshot cannot prove those states. You can still make the document useful by distinguishing confidence levels. Use labels such as `observed`, `estimated`, and `to verify`. An observed heading size might be approximate if you do not have source measurements; an estimated spacing scale can be proposed from repeated gaps; an unobserved mobile breakpoint belongs in the review list. Include a small implementation checklist so the next person knows what to validate before treating the document as complete. > Copyable prompt: Inspect this desktop capture and create a design.md file. Mark every inferred value or state as estimated or to verify. [Run it with Fudge](/mcp). --- First group values by role, not by where they happened to appear. Use names such as `color.background`, `color.surface`, `color.text`, `color.textMuted`, `color.border`, and `color.accent`. For typography, define roles such as `type.body`, `type.label`, `type.heading`, and `type.display`, with family, weight, size, line height, and letter spacing. Do the same for recurring spacing and shape values. If several sections use similar gaps, propose a small spacing scale and mark it as normalized or estimated. Give repeated card corners a role like `radius.card`; give a one-off illustration treatment a page-specific name instead. This prevents a single visual exception from becoming a global rule. Then connect tokens to components. A button should reference its text, background, border, radius, padding, and state values. A card should reference its surface, border, radius, shadow, internal spacing, and text roles. Finish by checking contrast, focus visibility, heading order, and responsive behavior. The result is more useful than a long list of hex values because it explains how the values work together and where a developer should apply them. > Copyable prompt: Convert the observed website details into role-based design tokens and map them to reusable components. Mark estimates clearly. [Run it with Fudge](/mcp). ## Related questions - [Convert Website Design Details into a Design Report](/share/convert-website-design-details-into-design-report) - [Convert a Website into a Tailwind v4 Theme for AI Coding Agents](/share/website-to-tailwind-v4-theme-converter-for-ai-coding-agents) - [Convert website design details into CSS variables](/share/convert-website-design-details-into-css-variables) - [Convert Website Design Details into JSON Design Tokens](/share/convert-website-design-details-into-json-design-tokens)