fix(wix-headless): numeric spacing scale — kill the max-w-<size> collision (CODEAI-696) by yanivefraim · Pull Request #416 · wix/skills

yanivefraim · 2026-06-17T14:58:49Z

The root fix for the `max-w-3xl` collapse

Root cause: compose.mjs emitted a named --spacing-* scale using t-shirt sizes (md, 3xl, …). In Tailwind v4 the width family (max-w-/w-/min-w-) is generated from the --spacing-* namespace, so max-w-3xl resolved to --spacing-3xl (~96px) instead of --container-3xl — collapsing reading columns to one word per line. Hand-written templates dodged it by only using max-w-6xl/max-w-prose; LLM-generated layout (#411/#412) tripped it.

Fix (chosen: Tailwind-native numeric): the skill's spacing values already match Tailwind's default scale 1:1 (md=1rem=4, lg=1.5=6, 4xl=6rem=24), so we drop the named scale and use Tailwind's built-in numeric spacing. With no named --spacing-<size> tokens, nothing collides with width keys, and max-w-md/3xl/6xl resolve to --container-* correctly.

Changes

scripts/compose.mjs — stop emitting named --spacing-*; remove it from REQUIRED, the DESIGN.md read, and the container≠spacing check. Containers kept.
scripts/emit-design-tokens.mjs — stop projecting named --spacing-*.
Migration — 112 spacing utility classes (gap-md→gap-4, py-4xl→py-24, …) + 122 var(--spacing-*)→literal-rem, across 27 template + instruction-doc files.
Spec docs (DESIGN_MD.md, DESIGN_SYSTEM.md, STYLING.md) — drop the spacing token group (Designer no longer authors spacing) and correct STYLING's wrong claim that max-w-3xl→--container-3xl.

Mapping

2xs→1 · xs→2 · sm→3 · md→4 · lg→6 · xl→8 · 2xl→12 · 3xl→16 · 4xl→24

Verification

✅ compose emits 0 --spacing-* and the 4 --container-* tokens.
✅ 0 leftover t-shirt spacing classes / var(--spacing-*) refs across templates + docs (only intentional explanatory mentions remain).
✅ both scripts parse.
⏳ Live compiled-CSS check (max-w-3xl→--container-3xl) + Playwright render — pending a network-capable build env (sandbox here had no network for wix build).

Scope note

Branched off main. The feature branches (#408 fragments / #410 hybrid / #411 full-home / #412 full-page) carry extra files (e.g. fragments/**) that need the same mechanical migration when they rebase onto this — the max-w-* guardrail added to #411/#412 stays valid in the meantime.

🤖 Generated with Claude Code

Before / After — live sites

Both are full-page LLM-generated sites (the LLM writes max-w-3xl freely). Same class, opposite outcome:

	Site	`max-w-3xl` resolves to	Rendered width @1200px
Before (pre-fix, named `--spacing-*` scale)	https://solara-yog-e96ca135-yanivef.wix-site-host.com/faq	`var(--spacing-3xl)`	64px — FAQ answer text collapses to a few characters per line
After (this PR, numeric spacing)	https://meridian-c-ed1b2263-yanivef.wix-site-host.com/	`var(--container-3xl)`	896px — proper reading column

Measured live in-browser (computed max-width on the .max-w-3xl wrappers). Compiled CSS on the "after" site: .max-w-3xl{max-width:var(--container-3xl)}, with 0 --spacing-* tokens in @theme.

Tracked in Jira: CODEAI-704.

…the max-w-<size> collision (CODEAI-696) Root cause: compose.mjs emitted a named --spacing-* scale using t-shirt sizes (md, 3xl, …). In Tailwind v4 the width family (max-w-/w-/min-w-) is generated from the --spacing-* namespace, so `max-w-3xl` resolved to --spacing-3xl (~96px) instead of --container-3xl — collapsing any LLM/author-written reading column to one word per line. Hand-written templates dodged it; generated layout (#411/#412) tripped it. Fix — adopt Tailwind v4's built-in numeric spacing (the skill's values already match it 1:1, e.g. md=1rem=`4`, 4xl=6rem=`24`), removing the named scale so nothing collides with width keys: - compose.mjs: stop emitting named --spacing-*; drop it from REQUIRED, the DESIGN.md read, and the container≠spacing check. Tailwind's --spacing base (numeric gap-4/py-24/…) is used directly. Containers kept — now max-w-md/3xl/6xl resolve to --container-* correctly. - emit-design-tokens.mjs: stop projecting named --spacing-* into design-tokens.css / site.d.ts. - Migrated 112 spacing utility classes (gap-md→gap-4, py-4xl→py-24, …) and 122 var(--spacing-*) refs (→ literal rem) across 27 template + instruction-doc files. - Spec docs (DESIGN_MD, DESIGN_SYSTEM, STYLING): dropped the spacing token group (Designer no longer authors spacing) and corrected STYLING's (wrong) claim that max-w-3xl maps to --container-3xl. Verified: compose emits 0 --spacing-* and the 4 --container-* tokens; 0 leftover t-shirt spacing classes/var refs across templates+docs; both scripts parse. Live compiled-CSS/Playwright proof pending a network-capable build env. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…ift-cards COMPONENTS (CODEAI-696) The gift-cards component doc still told authors to fall back to var(--spacing-*), which no longer exists after the numeric-spacing migration. Point at Tailwind's numeric spacing instead. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

adimara

this fix only works because the custom spacing values happened to be identical to tailwind's defaults. if someone ever wants a truly custom spacing scale (different values), putting them under
--spacing-* will break max-w-* again. the namespace would need to change (e.g. --rhythm-*) to avoid the collision.

the CSS template files (components-bookings.css, components-ecom.css, components-gift-cards.css) now have hardcoded rem values like gap: 1.5rem
instead of var(--spacing-lg). That's intentional and correct given the fix — but it means these component styles are now not customizable through the spacing system at all. Before, a brand could technically override --spacing-lg and all components would follow. Now they can't. That's probably fine since the whole point was to remove the scale, but it's a subtle loss of flexibility worth being aware of.

adimara · 2026-06-18T06:31:46Z

The --spacing-* no longer exist. An LLM reading this comment would think they're still emitted.

Fixed in d78da2f — dropped --spacing-* from the @theme substitution comment and reframed it: spacing is Tailwind numeric, and a --spacing-* scale must never be added since that namespace also powers the max-w-*/w-* width utilities.

adimara · 2026-06-18T06:32:24Z

These spacing tokens no longer exist.

Fixed in d78da2f — removed the stale --spacing-{sm,md,lg,…} entry from the reused-tokens header.

adimara · 2026-06-18T06:33:16Z

After this fix, there is no spacing scale to fall back to, so max-w-4xl would fall back to Tailwind's default or undefined — not to a 7rem spacing value. The old warning made sense pre-fix; post-fix it's misleading.

Fixed in d78da2f — the spacing-fallback rationale is obsolete post-fix. Reworded: bare max-w-* keys now resolve to Tailwind --container-*; container-reading remains the recommended prose width.

adimara · 2026-06-18T06:54:06Z

--spacing-md no longer exists.

Fixed in d78da2f — swapped the --spacing-md example for --radius-md and noted spacing is Tailwind-numeric. Applied the same fix to the identical line in ecom/COMPONENTS_CSS.md.

adimara · 2026-06-18T06:55:09Z

spacing was removed from the DESIGN.md vocabulary.

Fixed in d78da2f — dropped spacing from the DESIGN.md vocabulary list.

adimara · 2026-06-18T06:55:43Z

spacing was removed

Fixed in d78da2f — dropped spacing from the DESIGN.md vocabulary list.

adimara · 2026-06-18T06:56:02Z

spacing was removed

Fixed in d78da2f — dropped spacing from the DESIGN.md vocabulary list.

adimara · 2026-06-18T06:56:46Z

@@ -103,7 +103,7 @@ All page scopes share common inputs and rules. Scope-specific details follow.
    ```
 8. **Comments in frontmatter.** Use `//` or `/* */` — never HTML `<!-- -->` comments in `.astro` frontmatter (it's TypeScript, not HTML). HTML comments in the template section are fine.
 9. **Responsive.** All pages must work at mobile (320px), tablet (768px), and desktop (1024px+). Use Tailwind responsive prefixes (`md:`, `lg:`) and the spacing scale from `@theme`.


There is no spacing scale in @theme anymore.

Fixed in d78da2f — changed "the spacing scale from @theme" to Tailwind numeric spacing (gap-4, py-24, …).

@theme

…rences (CODEAI-696) Review (adimara) flagged comments/docs that still referenced the removed named --spacing-* scale, plus a real breakage the main-merge re-introduced. Doc/comment fixes (stale references): - templates/global.css @theme comment: drop --spacing-* from the substituted list; reframe as "spacing is Tailwind numeric; never add --spacing-* (it powers the width utilities)". - gift-cards/components-gift-cards.css header: drop --spacing-{…} from reused tokens. - bookings/services/[slug].astro: the max-w warning's spacing-fallback rationale is obsolete post-fix — reframed (max-w-* now resolves to --container-*). - stores/ecom/COMPONENTS_CSS.md, shared/IMPLEMENTER.md: drop `spacing` from the DESIGN.md vocabulary list; swap the --spacing-md token example for --radius-md. - designer/INSTRUCTIONS.md: "spacing scale from @theme" → Tailwind numeric. Real functional fix: - bookings/components-bookings.css: the merged-in bookings rewrite (610d0ea) shipped 6 var(--spacing-sm/md/xl/xs) refs that resolve to nothing after the fix — migrated to literal rem (sm=.75 md=1 lg=1.5 xl=2 xs=.5). Forward guard (review point on namespace fragility): - STYLING.md: note that --spacing-* must never be reintroduced (it shadows max-w-*); custom spacing *values* should use a different namespace (e.g. --rhythm-*). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

yanivefraim · 2026-06-21T14:18:14Z

Thanks @adimara — all addressed in d78da2f.

Stale --spacing-* references (the 8 inline comments): all cleaned — the @theme substitution comment, the gift-cards reused-tokens header, the bookings max-w warning rationale, the DESIGN.md vocabulary lists (stores / ecom / IMPLEMENTER), the --spacing-md token examples, and the designer "spacing scale from @theme" line.

One real bug your review surfaced indirectly: the recent Merge main pulled in the rewritten bookings vertical (610d0ea), whose components-bookings.css shipped 6 var(--spacing-sm/md/xl/xs) rules — those resolve to nothing post-fix (broken gaps/padding). Migrated them to literal rem.

On the two design points:

Namespace fragility (a truly custom spacing scale under --spacing-* would re-collide with max-w-*; would need e.g. --rhythm-*). Agreed, and captured as a forward guard in STYLING.md: never reintroduce a named --spacing-* scale (that namespace generates the width utilities); if a brand ever needs custom spacing values, use a different namespace (--rhythm-*) or arbitrary values. You're right that the current scale only works because its steps equal Tailwind's numeric defaults — so this is exactly where to warn future authors.
Loss of per-token customizability (component CSS now hardcodes rem instead of var(--spacing-lg)). Intentional, as you noted — removing the scale is the whole point. Brands still customize via the color/type/radius/container @theme tokens; spacing is deliberately pinned to Tailwind's rhythm. If we ever want it brand-overridable again, that's the --rhythm-* path from point 1 — not --spacing-*.

yanivefraim · 2026-06-22T05:15:48Z

#skipreview

main now contains #416 (numeric spacing fix) + the v1.10.0 release bump. Conflict resolution: - STYLING.md / designer/INSTRUCTIONS.md: took main's finalized #416 wording (the spacing-doc + the "never reintroduce --spacing-*" guard note); #412 only carried the pre-review-fix snapshot. - Navigation/Footer/index.astro: kept DELETED — the full-page branch generates header/footer/home via the LLM, so it has no templates for them. Full-page feature intact (compose nav/footer/home path inputs present); spacing fix intact (0 --spacing-* emitted, 0 var(--spacing-*) refs). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

yanivefraim and others added 3 commits June 17, 2026 17:58

Merge branch 'main' into fix/codeai-696-spacing-scale

5ade935

yanivefraim marked this pull request as ready for review June 18, 2026 05:50

adimara reviewed Jun 18, 2026

View reviewed changes

yanivefraim and others added 2 commits June 21, 2026 16:23

Merge branch 'main' into fix/codeai-696-spacing-scale

6d9dd02

yanivefraim merged commit 69df240 into main Jun 22, 2026
1 check passed

yanivefraim deleted the fix/codeai-696-spacing-scale branch June 22, 2026 05:16

Conversation

yanivefraim commented Jun 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

The root fix for the max-w-3xl collapse

Changes

Mapping

Verification

Scope note

Before / After — live sites

Uh oh!

adimara left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

yanivefraim commented Jun 21, 2026

Uh oh!

yanivefraim commented Jun 22, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

yanivefraim commented Jun 17, 2026 •

edited

Loading

The root fix for the `max-w-3xl` collapse