Golden Ratio Spacing

You are auditing and rewriting all spacing, border, and underline values in $ARGUMENTS so every size belongs to a strict golden-ratio scale (φ = 1.618033…).

The golden ratio is not a style preference — it is a mathematical proportion found throughout nature and classical design. When applied to UI spacing, it creates visual harmony that users feel even when they cannot name it.

The Golden Ratio Scale

The scale is built from a single base unit multiplied or divided by φ at each step.

Deriving the Scale

φ = 1.618033988749895

step(n) = base × φⁿ

n = -3 →  base ÷ φ³   ≈  0.236 × base   (hairline)
n = -2 →  base ÷ φ²   ≈  0.382 × base   (xs)
n = -1 →  base ÷ φ    ≈  0.618 × base   (sm)
n =  0 →  base × φ⁰   =  1.000 × base   (base / md)
n =  1 →  base × φ¹   ≈  1.618 × base   (lg)
n =  2 →  base × φ²   ≈  2.618 × base   (xl)
n =  3 →  base × φ³   ≈  4.236 × base   (2xl)
n =  4 →  base × φ⁴   ≈  6.854 × base   (3xl)
n =  5 →  base × φ⁵   ≈ 11.090 × base   (4xl)

Recommended Default Scale (base = 1rem / 16px)

Adapting the base: If the project uses a different base font size (e.g. 14 px or 18 px), scale every value proportionally. The ratios between steps must always equal φ.

Step 1 — Discover All Size Values

Collect every spacing-related declaration in scope:

• Padding: padding, padding-top/right/bottom/left, padding-inline, padding-block
• Margin: margin, margin-top/right/bottom/left, margin-inline, margin-block
• Gap: gap, row-gap, column-gap
• Border width: border-width, border-top/right/bottom/left-width, outline-width
• Text decoration: text-decoration-thickness, text-underline-offset
• Box shadow spread/blur (spacing intent values only)
• Design tokens / CSS custom properties that feed into any of the above

Build an inventory table:

| Location (file:line)   | Property                    | Current Value | Nearest Scale Step |
|------------------------|-----------------------------|---------------|--------------------|
| button.css:14          | padding: 8px 16px           | 8px / 16px    | sm (9.9px) / md (16px) |
| card.css:32            | border-width: 2px           | 2px           | xs (6.1px) → hair (3.8px) |
| ...                    | ...                         | ...           | ...                |

Step 2 — Establish the Token Set

Before changing any value:

1. Check if CSS custom properties already exist. If so, map them to scale tokens.
2. Propose a token declaration block at the root/theme level:

:root {
  --phi: 1.618033988749895;

  /* Golden Ratio Spacing Scale */
  --space-hair: 0.236rem;  /*  3.8 px */
  --space-xs:   0.382rem;  /*  6.1 px */
  --space-sm:   0.618rem;  /*  9.9 px */
  --space-md:   1.000rem;  /* 16.0 px */
  --space-lg:   1.618rem;  /* 25.9 px */
  --space-xl:   2.618rem;  /* 41.9 px */
  --space-2xl:  4.236rem;  /* 67.8 px */
  --space-3xl:  6.854rem;  /* 109.7 px */
  --space-4xl: 11.090rem;  /* 177.4 px */

  /* Border & Rule Widths */
  --border-hair: 0.063rem; /* 1 px — absolute minimum, not ratio-scaled */
  --border-xs:   0.118rem; /* 1.9 px ≈ φ × hairline */
  --border-sm:   0.191rem; /* 3.1 px */
  --border-md:   0.309rem; /* 4.9 px */

  /* Underline / Text Decoration */
  --underline-thin:   0.063rem; /* 1 px */
  --underline-base:   0.118rem; /* 1.9 px */
  --underline-thick:  0.191rem; /* 3.1 px */
  --underline-offset-sm: 0.191rem;
  --underline-offset-md: 0.309rem;
}

If the project uses a design-token format (JSON, Style Dictionary, Figma Tokens), produce the output in that format instead of raw CSS.

Step 3 — Snap Every Value to the Scale

For each discovered value, apply the nearest-step rule:

• Find the two adjacent scale steps that bracket the current value.
• Choose the step whose ratio to the current value is closest to 1.
• If the current value is already within 2 % of a scale step, keep it and annotate as ✅ compliant.
• If the current value is more than 2 % away, replace it and annotate as 🔧 fixed.
• If the current value is zero or none, leave it unchanged — zero is intentional.

Rounding Rules

• CSS rem values: round to 3 decimal places.
• Pixel values: round to 1 decimal place. Use whole pixels only when the platform requires it (e.g. native mobile, canvas).
• Never use px for spacing in web if the project already uses rem — convert and keep consistency.

Step 4 — Fix Borders

Border widths are often sub-pixel values. Apply the golden-ratio border scale:

Rules:

• border-width: 1px → keep as --border-hair (1 px is already the floor).
• border-width: 2px → snap to --border-xs (1.9 px).
• border-width: 3px → snap to --border-sm (3.1 px).
• border-width: 4px or 5px → snap to --border-md (4.9 px).
• Never introduce a border-width value that does not exist in the token set.

Step 5 — Fix Underlines and Text Decoration

Apply the underline token set:

/* Thin underline — links in body text */
text-decoration-thickness: var(--underline-thin);   /* 1 px */
text-underline-offset:     var(--underline-offset-sm); /* 3.1 px */

/* Base underline — default interactive elements */
text-decoration-thickness: var(--underline-base);   /* 1.9 px */
text-underline-offset:     var(--underline-offset-md); /* 4.9 px */

/* Thick underline — headings, emphasis */
text-decoration-thickness: var(--underline-thick);  /* 3.1 px */
text-underline-offset:     var(--underline-offset-md); /* 4.9 px */

Rules:

• text-decoration-thickness: auto → replace with --underline-thin for body text or --underline-base for interactive elements.
• text-decoration-thickness: from-font → acceptable; annotate as ✅ deferred to font metrics.
• text-underline-offset not set → add var(--underline-offset-sm) as the default.

Step 6 — Component-Level Spacing Audit

For each component or layout section, verify that the ratio between adjacent spacing levels equals φ (within 5 % tolerance):

padding-sm / padding-xs ≈ 1.618 ✅
gap-lg / gap-md         ≈ 1.618 ✅
margin-xl / margin-lg   ≈ 1.618 ✅

If a component uses only two spacing values and their ratio diverges significantly from φ, flag it and propose corrected values.

Step 7 — Produce the Diff

Output a structured diff for every changed file:

/* button.css */
- padding: 10px 20px;
+ padding: var(--space-sm) var(--space-md);   /* 9.9px 16px — golden ratio compliant */

/* card.css */
- border-width: 2px;
+ border-width: var(--border-xs);             /* 1.9px — snapped from 2px */

/* typography.css */
- text-decoration-thickness: 1px;
- text-underline-offset: 4px;
+ text-decoration-thickness: var(--underline-thin);    /* 1px */
+ text-underline-offset: var(--underline-offset-sm);   /* 3.1px — snapped from 4px */

Step 8 — Validate Consistency

After applying changes, run a consistency check:

• [ ] Every spacing value references a token — no raw px or rem literals remain (except zero).
• [ ] Every border-width value is from the border token set.
• [ ] Every text-decoration-thickness and text-underline-offset uses a token.
• [ ] The ratio between any two adjacent token steps is φ ± 5 %.
• [ ] No spacing value was introduced that falls between two scale steps.
• [ ] 0, 0px, 0rem values are preserved unchanged.
• [ ] Negative margins (if any) use the same magnitude scale as positive margins.

Output Format

## Golden Ratio Spacing Audit — [target]

### Token Map
[Full :root token block]

### Inventory
[Table of all discovered values with compliance status]

### Changes Required
[Grouped by file — diff format]

### Validation Summary
[Checklist results]

### Before / After Reference
| Property            | Before  | After                   | Scale Step |
|---------------------|---------|-------------------------|------------|
| button padding-y    | 10px    | 9.9px (--space-sm)      | n = -1     |
| card border-width   | 2px     | 1.9px (--border-xs)     | n = -2     |
| link underline      | 1px     | 1px   (--underline-thin)| floor      |

Constraints

• Do not change font sizes, line-heights, or colour values — those are out of scope for this skill. Use the [typography] or [design-tokens] skill for those.
• Do not invent spacing that was not already present. Only correct existing values.
• Preserve zero values. Zero is intentional and is not part of the scale.
• Respect platform conventions. On React Native or iOS/Android, rem is not valid — use px equivalents of the same scale values.
• Flag, do not silently drop, any value you cannot confidently snap — present it to the user for a decision.