Give Claude Code a Website's Spacing Scale

Contents

• [Use a repeatable spacing method](#use-a-repeatable-spacing-method)
• [Give Claude Code context, not only numbers](#give-claude-code-context-not-only-numbers)
• [Check the result before coding around it](#check-the-result-before-coding-around-it)
• [Use this in your AI agent](#use-this-in-your-ai-agent)

A useful spacing scale for Claude Code should turn observed gaps into named tokens, not just a list of pixel measurements. Give it the page structure, repeated distances, and a rule for rounding them so it can apply the system consistently across a new interface.

Use a repeatable spacing method

Start by collecting the gaps that control the page rhythm:

• Page edge to main content
• Header height and header-to-content gap
• Section-to-section spacing
• Heading-to-paragraph spacing
• Paragraph-to-button spacing
• Card padding
• Card-to-card gaps
• Grid and column gaps
• Form label-to-input spacing
• Icon-to-label spacing
• Mobile changes to any of the above

Do not treat every visible distance as a separate token. Group measurements that are close together and identify the role they serve. For example, 15px and 16px can usually become one space-4 token, while a repeated 47px section gap may belong to a larger layout token rather than the base scale.

A practical output might look like this:

The names and values above are a starting format, not a claim about any particular website. Replace them with values observed from the page you are rebuilding.

Open the examples below and compare the first screen before borrowing a pattern. The Notion Developer Platform, Claude Code, and Exa MCP Server cards are useful reminders that pages with similar developer audiences can still use very different content density, container widths, and section rhythm.

Give Claude Code context, not only numbers

Claude Code will produce a better implementation when each token includes where it appears and what it separates. A spacing record should include:

Also provide the page width, column behavior, breakpoint assumptions, and whether a distance belongs to the component or the surrounding layout. This prevents a common mistake: putting every gap into a global scale when some values are specific to a hero, pricing table, or navigation bar.

Ask Claude Code to separate three layers:

1. Base spacing tokens: small, reusable increments.
2. Component spacing: padding and internal gaps inside cards, forms, buttons, and navigation.
3. Layout spacing: container margins, section gaps, and responsive composition.

That separation makes the result easier to maintain. If a card changes from 24px to 20px padding, the page-level section rhythm should not change with it.

Check the result before coding around it

Use this checklist:

• Are the same gaps repeated across multiple sections?
• Are measurements taken from the same viewport state?
• Are borders, shadows, and text boxes excluded from the gap calculation?
• Do desktop and mobile use the same scale or a reduced one?
• Are the largest gaps reserved for meaningful hierarchy?
• Does the proposed scale cover most measurements without excessive one-off values?
• Can each token be described by a clear role?

If the scale needs many exceptions, do not force it into a neat mathematical progression. Keep a small base scale and document intentional layout values separately. A faithful spacing guide is more useful than an elegant but inaccurate token list.

For implementation, ask Claude Code to create the tokens first, then replace hard-coded margins and padding in a second pass. Have it report any values that do not map cleanly instead of silently rounding them. That report becomes a short review list for the designer.

Use this in your AI agent

> Analyze the supplied website capture and create a spacing system for rebuilding it. Measure repeated gaps between page edges, containers, sections, headings, text, controls, cards, grids, and form fields. Group near-identical values into named base tokens, then separate component spacing from layout spacing. For every token, include the observed value, likely role, repeated locations, confidence, and responsive behavior if visible. Do not invent mobile values when mobile is not shown. Return a table of tokens, a list of intentional one-off values, and CSS custom properties that preserve the observed rhythm. Flag ambiguous measurements for review instead of hiding them through rounding. > > When you want to run this workflow from your AI agent, install Fudge for your AI agent.

Use semantic token names rather than scattering raw numbers through class names. Keep the base scale in one place, then map component and layout roles to those values.

In Tailwind, use the project configuration or theme variables to map these values to utilities. Ask Claude Code to use --space-4 for a repeated component gap only after checking that the captured value and role match. For exceptions, use a descriptive token such as --space-hero-content instead of an unexplained 47px.

Have it produce a migration table from existing values to proposed tokens. That makes it easy to review whether a rounding decision improves consistency or changes the visual rhythm.

Ask it to compare the same relationships at both widths instead of shrinking every desktop value by one percentage. Some spacing can remain fixed, such as icon-to-label gaps, while section padding and container gutters may step down at a breakpoint.

Give Claude Code a table with columns for relationship, desktop value, mobile value, token decision, and evidence. Then ask it to classify each relationship as fixed, stepped, fluid, or unknown. A stepped rule might change 64px to 48px, while a fluid rule could use clamp() when the page clearly scales between widths.

Require a final list of unresolved values. If mobile was not captured, the correct output is a proposed rule marked for visual review, not a presented fact. After implementation, compare the hero, first content section, cards, and footer at both widths. Those areas expose spacing mistakes quickly.

Related questions

• Give Claude Code a Website's Typography Hierarchy
• Give Claude Code a Website's Page Layout
• How to Check Border Radii and Shadows on Any Website
• Give Claude Code a Website's Motion and Interactions