feat(theme): add semantic/layouts — the container system by gabriel-lisboa-azion · Pull Request #884 · aziontech/webkit

gabriel-lisboa-azion · 2026-08-11T19:03:01Z

What

The layout system every console page is built on, as a theme token group: ten tokens and nine @utility classes, covering three decisions expressed once — how far content sits from the app chrome (boundary), how far things sit from each other (rhythm), and how wide a reading column may get (measure).

Four container types, picked by what the page is:

Class	Type	Today	For
`.layout-column`	Data	1620px	Lists, detail dashboards
`.layout-column-focused`	Focused	1024px	Home, single-task multi-column pages
`.layout-column-form`	Form	1024px	Settings, in-page edit forms
`.layout-form-create`	Create	1192px	Create pages (also retunes `--layout-measure-control`)

Plus .layout-boundary / .layout-boundary-inline, the two rhythm steps (--layout-section-gap, --layout-group-gap) with their .layout-section-start / .layout-group-start margin forms, and .layout-field-control for the control side of a settings row.

A derived group

Every token is a var() reference to --spacing-* / --container-*, never a literal length, and that is why none of them carries a breakpoint map. The spacing scale is already fluid (--spacing-lg is 1rem, then 1.5rem from sm), and var() is substituted at use time on the element — so a layout token follows the breakpoint override for free. Giving it its own map would duplicate the spacing scale into layout and let the two drift.

Why `@utility` and not `@layer components`

Same reason the typography utilities are emitted that way: @layer components classes are opaque to v4's variant resolver, and their modifiers silently drop. A layout class is exactly the kind you want behind a variant — md:layout-column.

Two things worth a reviewer's eye

.layout-field-control carries a :not(#\#) specificity pin. It is applied to Item.Actions, whose own root already declares shrink-0, and Vue merges both class lists onto one element. Custom @utility blocks sort before the core utilities, so without the pin shrink-0 wins and the control side can no longer yield to a long field name. Measured, not assumed — .layout-field-control at byte 19079 vs .shrink-0 at 31336 in a built bundle. #\# is an id no element can carry, so the selector always matches while reading (1,1,0); it is Tailwind's own important-strategy idiom and stays variant-safe. Only this one of the nine has it, because only this one has a live conflict.

The boundary widening nests on the column, not the boundary. Specificity is (0,2,0) either way, so correctness does not decide it. Nesting on the column keeps both declarations that can set max-width in one block, keeps .layout-boundary to the three padding declarations its name promises, and keeps "a fifth column class costs one line" true — they are generated from a COLUMN_MEASURE map and the nested rule comes along.

Also in the diff

emitIllustrationUtilities-style emission generalized into emitUtilities(map) with a thin emitLayoutUtilities caller.
Regenerating dist picks up one line main was stale on: an emitted comment still reading bg-[var(--x)] where the source has said bg-(--x) since ENG-47001.
Docs: a new Foundations → Layout Storybook page (built from the token source, so it cannot drift), the Max width section of DESIGN.md, a Layout row in Get Started, and the derived-group note in the theme's token README. DESIGN.md ships here rather than separately because that section is the catalog for these tokens — documenting them before they exist would be the drift the rule guards against.

Verification

build:tokens clean, assertNoZeroWithUnit passing, theme suite 12/12.
git diff dist/v4/globals.css is additions only apart from the stale comment: 10 --layout-* lines in :root, no new @media lines (every token is a bare var()), 9 new @utility blocks.
Storybook builds; validate-story-source --all reports 91/91 compliant.

Ten tokens and nine `@utility` classes: how far content sits from the app chrome (BOUNDARY), how far things sit from each other (RHYTHM), and how wide a reading column may get (MEASURE). A DERIVED group: every token is a var() reference to --spacing-* / --container-*, never a literal length. That is why none carries a breakpoint map — the spacing scale is already fluid and var() is substituted at use time on the element, so a layout token follows the override for free. Duplicating the scale into layout would only let the two drift. Emitting them as `@utility` rather than `@layer components` is what gives them variants (`md:layout-column`), the same reason the typography utilities are emitted that way. Generalizes the utility emitter into emitUtilities(map) with a thin emitLayoutUtilities caller, so the shape is reusable. Regenerating dist also picks up one line main was stale on: an emitted comment that still read `bg-[var(--x)]` where the source has said `bg-(--x)` since ENG-47001.

The catalog's token allowlists are scraped from the built theme, so adding semantic/layouts adds ten --layout-* entries. Regenerated rather than hand-edited, which is what catalog:check verifies.

…lighter type scale `Avatar › VariantGrid` failed the visual shard on `dark-desktop` only, at 1.0301% / 1354px against a 1% threshold — deterministically, byte-identical across two runs. The cause is not this branch. That baseline was last regenerated on 2026-07-22 by #768 and has missed two theme changes since: #889 (opaque neutral border tokens) and #876 (headings and body steps to font-weight 300, body leading 1.5 → 1.375). #876 regenerated 548 baselines across three rounds and updated this story's `--dark-tablet` file, but never the dark-desktop one — which alone keeps the bare story id instead of a `--mode` suffix (see .storybook/visual-modes.js), so it is the easy file to miss in a partial regeneration. Aligning baseline to render needs a zero shift (dx=0, dy=0); what differs is ink — text -9%, icons -7% — the lighter weight. This branch only adds tokens, and is simply the first PR to run the suite with #876 merged in. Regenerated via the app-storybook-generate-baseline workflow on linux. The `-u` path could not rewrite it on its own: stale-baseline vs clean render is 0.9875%, under the threshold, so the snapshot passed and was left alone. The file had to be deleted so it was written as a missing snapshot. Against the render CI actually produced, the new baseline is 0.0426% (56px). Still stale and left alone, since both currently pass: this story's `--dark-mobile` baseline (also 2026-07-22). Worth noting separately that the Avatar stories source their photo from a live Unsplash URL, which contributed the residual noise here and is what kept this story on the 1% boundary. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Brings the three commits demo lacked, so the deployed sample exercises them alongside the four fixes carved out of this branch (#899–#902), whose content was already here: - feat(webkit): chip's three kinds (#883) - feat(theme): the semantic/layouts container system (#884) - feat(theme): lightened heading and body type (#876) Conflict resolutions worth knowing: `build-tokens.mjs` — main has no illustration tokens, so main's side of all six hunks was empty. Taking it would have silently deleted this branch's illustration wiring; ours was kept. The merge then produced a DUPLICATE `emitUtilities` and `emitLayoutUtilities` with no conflict at all (both sides had added an identical helper in different places), which is a syntax error the merge itself reported as clean — the second copy is removed and `emitIllustrationUtilities` reuses the first. `texts.data.js` — the five conflicts were all `text-body-*` weight, resolved to main's `light` since that is the change being previewed. Resolved in place rather than with `--theirs`, which would have discarded the file's auto-merged hunks. Entry count held at 144. `.size-limit.json` — union, not a side: main's `chip` plus this branch's `footer-root` and `resizable-panel-root`. `dist/v4/globals.*` are generated, so they were rebuilt from the merged sources rather than hand-merged. The 466 conflicting visual baselines took main's copies; neither side is valid for a merged tree, and this branch opens no PR the visual gate guards. Verified after: no `undefined` in the built CSS, illustration tokens still emitted, main's layout utilities present, body weights now 300, no token data file lost entries, and 154 tests pass across toast, table, sidebar, resizable-panel and chip.

gabriel-lisboa-azion · 2026-08-11T19:03:01Z

What

The layout system every console page is built on, as a theme token group: ten tokens and nine @utility classes, covering three decisions expressed once — how far content sits from the app chrome (boundary), how far things sit from each other (rhythm), and how wide a reading column may get (measure).

Four container types, picked by what the page is:

Class	Type	Today	For
`.layout-column`	Data	1620px	Lists, detail dashboards
`.layout-column-focused`	Focused	1024px	Home, single-task multi-column pages
`.layout-column-form`	Form	1024px	Settings, in-page edit forms
`.layout-form-create`	Create	1192px	Create pages (also retunes `--layout-measure-control`)

Plus .layout-boundary / .layout-boundary-inline, the two rhythm steps (--layout-section-gap, --layout-group-gap) with their .layout-section-start / .layout-group-start margin forms, and .layout-field-control for the control side of a settings row.

A derived group

Every token is a var() reference to --spacing-* / --container-*, never a literal length, and that is why none of them carries a breakpoint map. The spacing scale is already fluid (--spacing-lg is 1rem, then 1.5rem from sm), and var() is substituted at use time on the element — so a layout token follows the breakpoint override for free. Giving it its own map would duplicate the spacing scale into layout and let the two drift.

Why `@utility` and not `@layer components`

Same reason the typography utilities are emitted that way: @layer components classes are opaque to v4's variant resolver, and their modifiers silently drop. A layout class is exactly the kind you want behind a variant — md:layout-column.

Two things worth a reviewer's eye

.layout-field-control carries a :not(#\#) specificity pin. It is applied to Item.Actions, whose own root already declares shrink-0, and Vue merges both class lists onto one element. Custom @utility blocks sort before the core utilities, so without the pin shrink-0 wins and the control side can no longer yield to a long field name. Measured, not assumed — .layout-field-control at byte 19079 vs .shrink-0 at 31336 in a built bundle. #\# is an id no element can carry, so the selector always matches while reading (1,1,0); it is Tailwind's own important-strategy idiom and stays variant-safe. Only this one of the nine has it, because only this one has a live conflict.

The boundary widening nests on the column, not the boundary. Specificity is (0,2,0) either way, so correctness does not decide it. Nesting on the column keeps both declarations that can set max-width in one block, keeps .layout-boundary to the three padding declarations its name promises, and keeps "a fifth column class costs one line" true — they are generated from a COLUMN_MEASURE map and the nested rule comes along.

Also in the diff

emitIllustrationUtilities-style emission generalized into emitUtilities(map) with a thin emitLayoutUtilities caller.
Regenerating dist picks up one line main was stale on: an emitted comment still reading bg-[var(--x)] where the source has said bg-(--x) since ENG-47001.
Docs: a new Foundations → Layout Storybook page (built from the token source, so it cannot drift), the Max width section of DESIGN.md, a Layout row in Get Started, and the derived-group note in the theme's token README. DESIGN.md ships here rather than separately because that section is the catalog for these tokens — documenting them before they exist would be the drift the rule guards against.

Verification

build:tokens clean, assertNoZeroWithUnit passing, theme suite 12/12.
git diff dist/v4/globals.css is additions only apart from the stale comment: 10 --layout-* lines in :root, no new @media lines (every token is a bare var()), 9 new @utility blocks.
Storybook builds; validate-story-source --all reports 91/91 compliant.

Ten tokens and nine `@utility` classes: how far content sits from the app chrome (BOUNDARY), how far things sit from each other (RHYTHM), and how wide a reading column may get (MEASURE). A DERIVED group: every token is a var() reference to --spacing-* / --container-*, never a literal length. That is why none carries a breakpoint map — the spacing scale is already fluid and var() is substituted at use time on the element, so a layout token follows the override for free. Duplicating the scale into layout would only let the two drift. Emitting them as `@utility` rather than `@layer components` is what gives them variants (`md:layout-column`), the same reason the typography utilities are emitted that way. Generalizes the utility emitter into emitUtilities(map) with a thin emitLayoutUtilities caller, so the shape is reusable. Regenerating dist also picks up one line main was stale on: an emitted comment that still read `bg-[var(--x)]` where the source has said `bg-(--x)` since ENG-47001.

The catalog's token allowlists are scraped from the built theme, so adding semantic/layouts adds ten --layout-* entries. Regenerated rather than hand-edited, which is what catalog:check verifies.

…lighter type scale `Avatar › VariantGrid` failed the visual shard on `dark-desktop` only, at 1.0301% / 1354px against a 1% threshold — deterministically, byte-identical across two runs. The cause is not this branch. That baseline was last regenerated on 2026-07-22 by #768 and has missed two theme changes since: #889 (opaque neutral border tokens) and #876 (headings and body steps to font-weight 300, body leading 1.5 → 1.375). #876 regenerated 548 baselines across three rounds and updated this story's `--dark-tablet` file, but never the dark-desktop one — which alone keeps the bare story id instead of a `--mode` suffix (see .storybook/visual-modes.js), so it is the easy file to miss in a partial regeneration. Aligning baseline to render needs a zero shift (dx=0, dy=0); what differs is ink — text -9%, icons -7% — the lighter weight. This branch only adds tokens, and is simply the first PR to run the suite with #876 merged in. Regenerated via the app-storybook-generate-baseline workflow on linux. The `-u` path could not rewrite it on its own: stale-baseline vs clean render is 0.9875%, under the threshold, so the snapshot passed and was left alone. The file had to be deleted so it was written as a missing snapshot. Against the render CI actually produced, the new baseline is 0.0426% (56px). Still stale and left alone, since both currently pass: this story's `--dark-mobile` baseline (also 2026-07-22). Worth noting separately that the Avatar stories source their photo from a live Unsplash URL, which contributed the residual noise here and is what kept this story on the 1% boundary. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Brings the three commits demo lacked, so the deployed sample exercises them alongside the four fixes carved out of this branch (#899–#902), whose content was already here: - feat(webkit): chip's three kinds (#883) - feat(theme): the semantic/layouts container system (#884) - feat(theme): lightened heading and body type (#876) Conflict resolutions worth knowing: `build-tokens.mjs` — main has no illustration tokens, so main's side of all six hunks was empty. Taking it would have silently deleted this branch's illustration wiring; ours was kept. The merge then produced a DUPLICATE `emitUtilities` and `emitLayoutUtilities` with no conflict at all (both sides had added an identical helper in different places), which is a syntax error the merge itself reported as clean — the second copy is removed and `emitIllustrationUtilities` reuses the first. `texts.data.js` — the five conflicts were all `text-body-*` weight, resolved to main's `light` since that is the change being previewed. Resolved in place rather than with `--theirs`, which would have discarded the file's auto-merged hunks. Entry count held at 144. `.size-limit.json` — union, not a side: main's `chip` plus this branch's `footer-root` and `resizable-panel-root`. `dist/v4/globals.*` are generated, so they were rebuilt from the merged sources rather than hand-merged. The 466 conflicting visual baselines took main's copies; neither side is valid for a merged tree, and this branch opens no PR the visual gate guards. Verified after: no `undefined` in the built CSS, illustration tokens still emitted, main's layout utilities present, body weights now 300, no token data file lost entries, and 154 tests pass across toast, table, sidebar, resizable-panel and chip.

gabriel-lisboa-azion · 2026-08-11T19:03:01Z

What

The layout system every console page is built on, as a theme token group: ten tokens and nine @utility classes, covering three decisions expressed once — how far content sits from the app chrome (boundary), how far things sit from each other (rhythm), and how wide a reading column may get (measure).

Four container types, picked by what the page is:

Class	Type	Today	For
`.layout-column`	Data	1620px	Lists, detail dashboards
`.layout-column-focused`	Focused	1024px	Home, single-task multi-column pages
`.layout-column-form`	Form	1024px	Settings, in-page edit forms
`.layout-form-create`	Create	1192px	Create pages (also retunes `--layout-measure-control`)

Plus .layout-boundary / .layout-boundary-inline, the two rhythm steps (--layout-section-gap, --layout-group-gap) with their .layout-section-start / .layout-group-start margin forms, and .layout-field-control for the control side of a settings row.

A derived group

Every token is a var() reference to --spacing-* / --container-*, never a literal length, and that is why none of them carries a breakpoint map. The spacing scale is already fluid (--spacing-lg is 1rem, then 1.5rem from sm), and var() is substituted at use time on the element — so a layout token follows the breakpoint override for free. Giving it its own map would duplicate the spacing scale into layout and let the two drift.

Why `@utility` and not `@layer components`

Same reason the typography utilities are emitted that way: @layer components classes are opaque to v4's variant resolver, and their modifiers silently drop. A layout class is exactly the kind you want behind a variant — md:layout-column.

Two things worth a reviewer's eye

.layout-field-control carries a :not(#\#) specificity pin. It is applied to Item.Actions, whose own root already declares shrink-0, and Vue merges both class lists onto one element. Custom @utility blocks sort before the core utilities, so without the pin shrink-0 wins and the control side can no longer yield to a long field name. Measured, not assumed — .layout-field-control at byte 19079 vs .shrink-0 at 31336 in a built bundle. #\# is an id no element can carry, so the selector always matches while reading (1,1,0); it is Tailwind's own important-strategy idiom and stays variant-safe. Only this one of the nine has it, because only this one has a live conflict.

The boundary widening nests on the column, not the boundary. Specificity is (0,2,0) either way, so correctness does not decide it. Nesting on the column keeps both declarations that can set max-width in one block, keeps .layout-boundary to the three padding declarations its name promises, and keeps "a fifth column class costs one line" true — they are generated from a COLUMN_MEASURE map and the nested rule comes along.

Also in the diff

emitIllustrationUtilities-style emission generalized into emitUtilities(map) with a thin emitLayoutUtilities caller.
Regenerating dist picks up one line main was stale on: an emitted comment still reading bg-[var(--x)] where the source has said bg-(--x) since ENG-47001.
Docs: a new Foundations → Layout Storybook page (built from the token source, so it cannot drift), the Max width section of DESIGN.md, a Layout row in Get Started, and the derived-group note in the theme's token README. DESIGN.md ships here rather than separately because that section is the catalog for these tokens — documenting them before they exist would be the drift the rule guards against.

Verification

build:tokens clean, assertNoZeroWithUnit passing, theme suite 12/12.
git diff dist/v4/globals.css is additions only apart from the stale comment: 10 --layout-* lines in :root, no new @media lines (every token is a bare var()), 9 new @utility blocks.
Storybook builds; validate-story-source --all reports 91/91 compliant.

Ten tokens and nine `@utility` classes: how far content sits from the app chrome (BOUNDARY), how far things sit from each other (RHYTHM), and how wide a reading column may get (MEASURE). A DERIVED group: every token is a var() reference to --spacing-* / --container-*, never a literal length. That is why none carries a breakpoint map — the spacing scale is already fluid and var() is substituted at use time on the element, so a layout token follows the override for free. Duplicating the scale into layout would only let the two drift. Emitting them as `@utility` rather than `@layer components` is what gives them variants (`md:layout-column`), the same reason the typography utilities are emitted that way. Generalizes the utility emitter into emitUtilities(map) with a thin emitLayoutUtilities caller, so the shape is reusable. Regenerating dist also picks up one line main was stale on: an emitted comment that still read `bg-[var(--x)]` where the source has said `bg-(--x)` since ENG-47001.

The catalog's token allowlists are scraped from the built theme, so adding semantic/layouts adds ten --layout-* entries. Regenerated rather than hand-edited, which is what catalog:check verifies.

…lighter type scale `Avatar › VariantGrid` failed the visual shard on `dark-desktop` only, at 1.0301% / 1354px against a 1% threshold — deterministically, byte-identical across two runs. The cause is not this branch. That baseline was last regenerated on 2026-07-22 by #768 and has missed two theme changes since: #889 (opaque neutral border tokens) and #876 (headings and body steps to font-weight 300, body leading 1.5 → 1.375). #876 regenerated 548 baselines across three rounds and updated this story's `--dark-tablet` file, but never the dark-desktop one — which alone keeps the bare story id instead of a `--mode` suffix (see .storybook/visual-modes.js), so it is the easy file to miss in a partial regeneration. Aligning baseline to render needs a zero shift (dx=0, dy=0); what differs is ink — text -9%, icons -7% — the lighter weight. This branch only adds tokens, and is simply the first PR to run the suite with #876 merged in. Regenerated via the app-storybook-generate-baseline workflow on linux. The `-u` path could not rewrite it on its own: stale-baseline vs clean render is 0.9875%, under the threshold, so the snapshot passed and was left alone. The file had to be deleted so it was written as a missing snapshot. Against the render CI actually produced, the new baseline is 0.0426% (56px). Still stale and left alone, since both currently pass: this story's `--dark-mobile` baseline (also 2026-07-22). Worth noting separately that the Avatar stories source their photo from a live Unsplash URL, which contributed the residual noise here and is what kept this story on the 1% boundary. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Brings the three commits demo lacked, so the deployed sample exercises them alongside the four fixes carved out of this branch (#899–#902), whose content was already here: - feat(webkit): chip's three kinds (#883) - feat(theme): the semantic/layouts container system (#884) - feat(theme): lightened heading and body type (#876) Conflict resolutions worth knowing: `build-tokens.mjs` — main has no illustration tokens, so main's side of all six hunks was empty. Taking it would have silently deleted this branch's illustration wiring; ours was kept. The merge then produced a DUPLICATE `emitUtilities` and `emitLayoutUtilities` with no conflict at all (both sides had added an identical helper in different places), which is a syntax error the merge itself reported as clean — the second copy is removed and `emitIllustrationUtilities` reuses the first. `texts.data.js` — the five conflicts were all `text-body-*` weight, resolved to main's `light` since that is the change being previewed. Resolved in place rather than with `--theirs`, which would have discarded the file's auto-merged hunks. Entry count held at 144. `.size-limit.json` — union, not a side: main's `chip` plus this branch's `footer-root` and `resizable-panel-root`. `dist/v4/globals.*` are generated, so they were rebuilt from the merged sources rather than hand-merged. The 466 conflicting visual baselines took main's copies; neither side is valid for a merged tree, and this branch opens no PR the visual gate guards. Verified after: no `undefined` in the built CSS, illustration tokens still emitted, main's layout utilities present, body weights now 300, no token data file lost entries, and 154 tests pass across toast, table, sidebar, resizable-panel and chip.

gabriel-lisboa-azion · 2026-08-11T19:03:01Z

What

The layout system every console page is built on, as a theme token group: ten tokens and nine @utility classes, covering three decisions expressed once — how far content sits from the app chrome (boundary), how far things sit from each other (rhythm), and how wide a reading column may get (measure).

Four container types, picked by what the page is:

Class	Type	Today	For
`.layout-column`	Data	1620px	Lists, detail dashboards
`.layout-column-focused`	Focused	1024px	Home, single-task multi-column pages
`.layout-column-form`	Form	1024px	Settings, in-page edit forms
`.layout-form-create`	Create	1192px	Create pages (also retunes `--layout-measure-control`)

Plus .layout-boundary / .layout-boundary-inline, the two rhythm steps (--layout-section-gap, --layout-group-gap) with their .layout-section-start / .layout-group-start margin forms, and .layout-field-control for the control side of a settings row.

A derived group

Every token is a var() reference to --spacing-* / --container-*, never a literal length, and that is why none of them carries a breakpoint map. The spacing scale is already fluid (--spacing-lg is 1rem, then 1.5rem from sm), and var() is substituted at use time on the element — so a layout token follows the breakpoint override for free. Giving it its own map would duplicate the spacing scale into layout and let the two drift.

Why `@utility` and not `@layer components`

Same reason the typography utilities are emitted that way: @layer components classes are opaque to v4's variant resolver, and their modifiers silently drop. A layout class is exactly the kind you want behind a variant — md:layout-column.

Two things worth a reviewer's eye

.layout-field-control carries a :not(#\#) specificity pin. It is applied to Item.Actions, whose own root already declares shrink-0, and Vue merges both class lists onto one element. Custom @utility blocks sort before the core utilities, so without the pin shrink-0 wins and the control side can no longer yield to a long field name. Measured, not assumed — .layout-field-control at byte 19079 vs .shrink-0 at 31336 in a built bundle. #\# is an id no element can carry, so the selector always matches while reading (1,1,0); it is Tailwind's own important-strategy idiom and stays variant-safe. Only this one of the nine has it, because only this one has a live conflict.

The boundary widening nests on the column, not the boundary. Specificity is (0,2,0) either way, so correctness does not decide it. Nesting on the column keeps both declarations that can set max-width in one block, keeps .layout-boundary to the three padding declarations its name promises, and keeps "a fifth column class costs one line" true — they are generated from a COLUMN_MEASURE map and the nested rule comes along.

Also in the diff

emitIllustrationUtilities-style emission generalized into emitUtilities(map) with a thin emitLayoutUtilities caller.
Regenerating dist picks up one line main was stale on: an emitted comment still reading bg-[var(--x)] where the source has said bg-(--x) since ENG-47001.
Docs: a new Foundations → Layout Storybook page (built from the token source, so it cannot drift), the Max width section of DESIGN.md, a Layout row in Get Started, and the derived-group note in the theme's token README. DESIGN.md ships here rather than separately because that section is the catalog for these tokens — documenting them before they exist would be the drift the rule guards against.

Verification

build:tokens clean, assertNoZeroWithUnit passing, theme suite 12/12.
git diff dist/v4/globals.css is additions only apart from the stale comment: 10 --layout-* lines in :root, no new @media lines (every token is a bare var()), 9 new @utility blocks.
Storybook builds; validate-story-source --all reports 91/91 compliant.

Ten tokens and nine `@utility` classes: how far content sits from the app chrome (BOUNDARY), how far things sit from each other (RHYTHM), and how wide a reading column may get (MEASURE). A DERIVED group: every token is a var() reference to --spacing-* / --container-*, never a literal length. That is why none carries a breakpoint map — the spacing scale is already fluid and var() is substituted at use time on the element, so a layout token follows the override for free. Duplicating the scale into layout would only let the two drift. Emitting them as `@utility` rather than `@layer components` is what gives them variants (`md:layout-column`), the same reason the typography utilities are emitted that way. Generalizes the utility emitter into emitUtilities(map) with a thin emitLayoutUtilities caller, so the shape is reusable. Regenerating dist also picks up one line main was stale on: an emitted comment that still read `bg-[var(--x)]` where the source has said `bg-(--x)` since ENG-47001.

The catalog's token allowlists are scraped from the built theme, so adding semantic/layouts adds ten --layout-* entries. Regenerated rather than hand-edited, which is what catalog:check verifies.

…lighter type scale `Avatar › VariantGrid` failed the visual shard on `dark-desktop` only, at 1.0301% / 1354px against a 1% threshold — deterministically, byte-identical across two runs. The cause is not this branch. That baseline was last regenerated on 2026-07-22 by #768 and has missed two theme changes since: #889 (opaque neutral border tokens) and #876 (headings and body steps to font-weight 300, body leading 1.5 → 1.375). #876 regenerated 548 baselines across three rounds and updated this story's `--dark-tablet` file, but never the dark-desktop one — which alone keeps the bare story id instead of a `--mode` suffix (see .storybook/visual-modes.js), so it is the easy file to miss in a partial regeneration. Aligning baseline to render needs a zero shift (dx=0, dy=0); what differs is ink — text -9%, icons -7% — the lighter weight. This branch only adds tokens, and is simply the first PR to run the suite with #876 merged in. Regenerated via the app-storybook-generate-baseline workflow on linux. The `-u` path could not rewrite it on its own: stale-baseline vs clean render is 0.9875%, under the threshold, so the snapshot passed and was left alone. The file had to be deleted so it was written as a missing snapshot. Against the render CI actually produced, the new baseline is 0.0426% (56px). Still stale and left alone, since both currently pass: this story's `--dark-mobile` baseline (also 2026-07-22). Worth noting separately that the Avatar stories source their photo from a live Unsplash URL, which contributed the residual noise here and is what kept this story on the 1% boundary. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Brings the three commits demo lacked, so the deployed sample exercises them alongside the four fixes carved out of this branch (#899–#902), whose content was already here: - feat(webkit): chip's three kinds (#883) - feat(theme): the semantic/layouts container system (#884) - feat(theme): lightened heading and body type (#876) Conflict resolutions worth knowing: `build-tokens.mjs` — main has no illustration tokens, so main's side of all six hunks was empty. Taking it would have silently deleted this branch's illustration wiring; ours was kept. The merge then produced a DUPLICATE `emitUtilities` and `emitLayoutUtilities` with no conflict at all (both sides had added an identical helper in different places), which is a syntax error the merge itself reported as clean — the second copy is removed and `emitIllustrationUtilities` reuses the first. `texts.data.js` — the five conflicts were all `text-body-*` weight, resolved to main's `light` since that is the change being previewed. Resolved in place rather than with `--theirs`, which would have discarded the file's auto-merged hunks. Entry count held at 144. `.size-limit.json` — union, not a side: main's `chip` plus this branch's `footer-root` and `resizable-panel-root`. `dist/v4/globals.*` are generated, so they were rebuilt from the merged sources rather than hand-merged. The 466 conflicting visual baselines took main's copies; neither side is valid for a merged tree, and this branch opens no PR the visual gate guards. Verified after: no `undefined` in the built CSS, illustration tokens still emitted, main's layout utilities present, body weights now 300, no token data file lost entries, and 154 tests pass across toast, table, sidebar, resizable-panel and chip.

gabriel-lisboa-azion · 2026-08-11T19:03:01Z

What

The layout system every console page is built on, as a theme token group: ten tokens and nine @utility classes, covering three decisions expressed once — how far content sits from the app chrome (boundary), how far things sit from each other (rhythm), and how wide a reading column may get (measure).

Four container types, picked by what the page is:

Class	Type	Today	For
`.layout-column`	Data	1620px	Lists, detail dashboards
`.layout-column-focused`	Focused	1024px	Home, single-task multi-column pages
`.layout-column-form`	Form	1024px	Settings, in-page edit forms
`.layout-form-create`	Create	1192px	Create pages (also retunes `--layout-measure-control`)

Plus .layout-boundary / .layout-boundary-inline, the two rhythm steps (--layout-section-gap, --layout-group-gap) with their .layout-section-start / .layout-group-start margin forms, and .layout-field-control for the control side of a settings row.

A derived group

Every token is a var() reference to --spacing-* / --container-*, never a literal length, and that is why none of them carries a breakpoint map. The spacing scale is already fluid (--spacing-lg is 1rem, then 1.5rem from sm), and var() is substituted at use time on the element — so a layout token follows the breakpoint override for free. Giving it its own map would duplicate the spacing scale into layout and let the two drift.

Why `@utility` and not `@layer components`

Same reason the typography utilities are emitted that way: @layer components classes are opaque to v4's variant resolver, and their modifiers silently drop. A layout class is exactly the kind you want behind a variant — md:layout-column.

Two things worth a reviewer's eye

.layout-field-control carries a :not(#\#) specificity pin. It is applied to Item.Actions, whose own root already declares shrink-0, and Vue merges both class lists onto one element. Custom @utility blocks sort before the core utilities, so without the pin shrink-0 wins and the control side can no longer yield to a long field name. Measured, not assumed — .layout-field-control at byte 19079 vs .shrink-0 at 31336 in a built bundle. #\# is an id no element can carry, so the selector always matches while reading (1,1,0); it is Tailwind's own important-strategy idiom and stays variant-safe. Only this one of the nine has it, because only this one has a live conflict.

The boundary widening nests on the column, not the boundary. Specificity is (0,2,0) either way, so correctness does not decide it. Nesting on the column keeps both declarations that can set max-width in one block, keeps .layout-boundary to the three padding declarations its name promises, and keeps "a fifth column class costs one line" true — they are generated from a COLUMN_MEASURE map and the nested rule comes along.

Also in the diff

emitIllustrationUtilities-style emission generalized into emitUtilities(map) with a thin emitLayoutUtilities caller.
Regenerating dist picks up one line main was stale on: an emitted comment still reading bg-[var(--x)] where the source has said bg-(--x) since ENG-47001.
Docs: a new Foundations → Layout Storybook page (built from the token source, so it cannot drift), the Max width section of DESIGN.md, a Layout row in Get Started, and the derived-group note in the theme's token README. DESIGN.md ships here rather than separately because that section is the catalog for these tokens — documenting them before they exist would be the drift the rule guards against.

Verification

build:tokens clean, assertNoZeroWithUnit passing, theme suite 12/12.
git diff dist/v4/globals.css is additions only apart from the stale comment: 10 --layout-* lines in :root, no new @media lines (every token is a bare var()), 9 new @utility blocks.
Storybook builds; validate-story-source --all reports 91/91 compliant.

Ten tokens and nine `@utility` classes: how far content sits from the app chrome (BOUNDARY), how far things sit from each other (RHYTHM), and how wide a reading column may get (MEASURE). A DERIVED group: every token is a var() reference to --spacing-* / --container-*, never a literal length. That is why none carries a breakpoint map — the spacing scale is already fluid and var() is substituted at use time on the element, so a layout token follows the override for free. Duplicating the scale into layout would only let the two drift. Emitting them as `@utility` rather than `@layer components` is what gives them variants (`md:layout-column`), the same reason the typography utilities are emitted that way. Generalizes the utility emitter into emitUtilities(map) with a thin emitLayoutUtilities caller, so the shape is reusable. Regenerating dist also picks up one line main was stale on: an emitted comment that still read `bg-[var(--x)]` where the source has said `bg-(--x)` since ENG-47001.

The catalog's token allowlists are scraped from the built theme, so adding semantic/layouts adds ten --layout-* entries. Regenerated rather than hand-edited, which is what catalog:check verifies.

…lighter type scale `Avatar › VariantGrid` failed the visual shard on `dark-desktop` only, at 1.0301% / 1354px against a 1% threshold — deterministically, byte-identical across two runs. The cause is not this branch. That baseline was last regenerated on 2026-07-22 by #768 and has missed two theme changes since: #889 (opaque neutral border tokens) and #876 (headings and body steps to font-weight 300, body leading 1.5 → 1.375). #876 regenerated 548 baselines across three rounds and updated this story's `--dark-tablet` file, but never the dark-desktop one — which alone keeps the bare story id instead of a `--mode` suffix (see .storybook/visual-modes.js), so it is the easy file to miss in a partial regeneration. Aligning baseline to render needs a zero shift (dx=0, dy=0); what differs is ink — text -9%, icons -7% — the lighter weight. This branch only adds tokens, and is simply the first PR to run the suite with #876 merged in. Regenerated via the app-storybook-generate-baseline workflow on linux. The `-u` path could not rewrite it on its own: stale-baseline vs clean render is 0.9875%, under the threshold, so the snapshot passed and was left alone. The file had to be deleted so it was written as a missing snapshot. Against the render CI actually produced, the new baseline is 0.0426% (56px). Still stale and left alone, since both currently pass: this story's `--dark-mobile` baseline (also 2026-07-22). Worth noting separately that the Avatar stories source their photo from a live Unsplash URL, which contributed the residual noise here and is what kept this story on the 1% boundary. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Brings the three commits demo lacked, so the deployed sample exercises them alongside the four fixes carved out of this branch (#899–#902), whose content was already here: - feat(webkit): chip's three kinds (#883) - feat(theme): the semantic/layouts container system (#884) - feat(theme): lightened heading and body type (#876) Conflict resolutions worth knowing: `build-tokens.mjs` — main has no illustration tokens, so main's side of all six hunks was empty. Taking it would have silently deleted this branch's illustration wiring; ours was kept. The merge then produced a DUPLICATE `emitUtilities` and `emitLayoutUtilities` with no conflict at all (both sides had added an identical helper in different places), which is a syntax error the merge itself reported as clean — the second copy is removed and `emitIllustrationUtilities` reuses the first. `texts.data.js` — the five conflicts were all `text-body-*` weight, resolved to main's `light` since that is the change being previewed. Resolved in place rather than with `--theirs`, which would have discarded the file's auto-merged hunks. Entry count held at 144. `.size-limit.json` — union, not a side: main's `chip` plus this branch's `footer-root` and `resizable-panel-root`. `dist/v4/globals.*` are generated, so they were rebuilt from the merged sources rather than hand-merged. The 466 conflicting visual baselines took main's copies; neither side is valid for a merged tree, and this branch opens no PR the visual gate guards. Verified after: no `undefined` in the built CSS, illustration tokens still emitted, main's layout utilities present, body weights now 300, no token data file lost entries, and 154 tests pass across toast, table, sidebar, resizable-panel and chip.

gabriel-lisboa-azion · 2026-08-11T19:03:01Z

What

The layout system every console page is built on, as a theme token group: ten tokens and nine @utility classes, covering three decisions expressed once — how far content sits from the app chrome (boundary), how far things sit from each other (rhythm), and how wide a reading column may get (measure).

Four container types, picked by what the page is:

Class	Type	Today	For
`.layout-column`	Data	1620px	Lists, detail dashboards
`.layout-column-focused`	Focused	1024px	Home, single-task multi-column pages
`.layout-column-form`	Form	1024px	Settings, in-page edit forms
`.layout-form-create`	Create	1192px	Create pages (also retunes `--layout-measure-control`)

Plus .layout-boundary / .layout-boundary-inline, the two rhythm steps (--layout-section-gap, --layout-group-gap) with their .layout-section-start / .layout-group-start margin forms, and .layout-field-control for the control side of a settings row.

A derived group

Every token is a var() reference to --spacing-* / --container-*, never a literal length, and that is why none of them carries a breakpoint map. The spacing scale is already fluid (--spacing-lg is 1rem, then 1.5rem from sm), and var() is substituted at use time on the element — so a layout token follows the breakpoint override for free. Giving it its own map would duplicate the spacing scale into layout and let the two drift.

Why `@utility` and not `@layer components`

Same reason the typography utilities are emitted that way: @layer components classes are opaque to v4's variant resolver, and their modifiers silently drop. A layout class is exactly the kind you want behind a variant — md:layout-column.

Two things worth a reviewer's eye

.layout-field-control carries a :not(#\#) specificity pin. It is applied to Item.Actions, whose own root already declares shrink-0, and Vue merges both class lists onto one element. Custom @utility blocks sort before the core utilities, so without the pin shrink-0 wins and the control side can no longer yield to a long field name. Measured, not assumed — .layout-field-control at byte 19079 vs .shrink-0 at 31336 in a built bundle. #\# is an id no element can carry, so the selector always matches while reading (1,1,0); it is Tailwind's own important-strategy idiom and stays variant-safe. Only this one of the nine has it, because only this one has a live conflict.

The boundary widening nests on the column, not the boundary. Specificity is (0,2,0) either way, so correctness does not decide it. Nesting on the column keeps both declarations that can set max-width in one block, keeps .layout-boundary to the three padding declarations its name promises, and keeps "a fifth column class costs one line" true — they are generated from a COLUMN_MEASURE map and the nested rule comes along.

Also in the diff

emitIllustrationUtilities-style emission generalized into emitUtilities(map) with a thin emitLayoutUtilities caller.
Regenerating dist picks up one line main was stale on: an emitted comment still reading bg-[var(--x)] where the source has said bg-(--x) since ENG-47001.
Docs: a new Foundations → Layout Storybook page (built from the token source, so it cannot drift), the Max width section of DESIGN.md, a Layout row in Get Started, and the derived-group note in the theme's token README. DESIGN.md ships here rather than separately because that section is the catalog for these tokens — documenting them before they exist would be the drift the rule guards against.

Verification

build:tokens clean, assertNoZeroWithUnit passing, theme suite 12/12.
git diff dist/v4/globals.css is additions only apart from the stale comment: 10 --layout-* lines in :root, no new @media lines (every token is a bare var()), 9 new @utility blocks.
Storybook builds; validate-story-source --all reports 91/91 compliant.

Ten tokens and nine `@utility` classes: how far content sits from the app chrome (BOUNDARY), how far things sit from each other (RHYTHM), and how wide a reading column may get (MEASURE). A DERIVED group: every token is a var() reference to --spacing-* / --container-*, never a literal length. That is why none carries a breakpoint map — the spacing scale is already fluid and var() is substituted at use time on the element, so a layout token follows the override for free. Duplicating the scale into layout would only let the two drift. Emitting them as `@utility` rather than `@layer components` is what gives them variants (`md:layout-column`), the same reason the typography utilities are emitted that way. Generalizes the utility emitter into emitUtilities(map) with a thin emitLayoutUtilities caller, so the shape is reusable. Regenerating dist also picks up one line main was stale on: an emitted comment that still read `bg-[var(--x)]` where the source has said `bg-(--x)` since ENG-47001.

The catalog's token allowlists are scraped from the built theme, so adding semantic/layouts adds ten --layout-* entries. Regenerated rather than hand-edited, which is what catalog:check verifies.

…lighter type scale `Avatar › VariantGrid` failed the visual shard on `dark-desktop` only, at 1.0301% / 1354px against a 1% threshold — deterministically, byte-identical across two runs. The cause is not this branch. That baseline was last regenerated on 2026-07-22 by #768 and has missed two theme changes since: #889 (opaque neutral border tokens) and #876 (headings and body steps to font-weight 300, body leading 1.5 → 1.375). #876 regenerated 548 baselines across three rounds and updated this story's `--dark-tablet` file, but never the dark-desktop one — which alone keeps the bare story id instead of a `--mode` suffix (see .storybook/visual-modes.js), so it is the easy file to miss in a partial regeneration. Aligning baseline to render needs a zero shift (dx=0, dy=0); what differs is ink — text -9%, icons -7% — the lighter weight. This branch only adds tokens, and is simply the first PR to run the suite with #876 merged in. Regenerated via the app-storybook-generate-baseline workflow on linux. The `-u` path could not rewrite it on its own: stale-baseline vs clean render is 0.9875%, under the threshold, so the snapshot passed and was left alone. The file had to be deleted so it was written as a missing snapshot. Against the render CI actually produced, the new baseline is 0.0426% (56px). Still stale and left alone, since both currently pass: this story's `--dark-mobile` baseline (also 2026-07-22). Worth noting separately that the Avatar stories source their photo from a live Unsplash URL, which contributed the residual noise here and is what kept this story on the 1% boundary. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Brings the three commits demo lacked, so the deployed sample exercises them alongside the four fixes carved out of this branch (#899–#902), whose content was already here: - feat(webkit): chip's three kinds (#883) - feat(theme): the semantic/layouts container system (#884) - feat(theme): lightened heading and body type (#876) Conflict resolutions worth knowing: `build-tokens.mjs` — main has no illustration tokens, so main's side of all six hunks was empty. Taking it would have silently deleted this branch's illustration wiring; ours was kept. The merge then produced a DUPLICATE `emitUtilities` and `emitLayoutUtilities` with no conflict at all (both sides had added an identical helper in different places), which is a syntax error the merge itself reported as clean — the second copy is removed and `emitIllustrationUtilities` reuses the first. `texts.data.js` — the five conflicts were all `text-body-*` weight, resolved to main's `light` since that is the change being previewed. Resolved in place rather than with `--theirs`, which would have discarded the file's auto-merged hunks. Entry count held at 144. `.size-limit.json` — union, not a side: main's `chip` plus this branch's `footer-root` and `resizable-panel-root`. `dist/v4/globals.*` are generated, so they were rebuilt from the merged sources rather than hand-merged. The 466 conflicting visual baselines took main's copies; neither side is valid for a merged tree, and this branch opens no PR the visual gate guards. Verified after: no `undefined` in the built CSS, illustration tokens still emitted, main's layout utilities present, body weights now 300, no token data file lost entries, and 154 tests pass across toast, table, sidebar, resizable-panel and chip.

gabriel-lisboa-azion · 2026-08-11T19:03:01Z

What

The layout system every console page is built on, as a theme token group: ten tokens and nine @utility classes, covering three decisions expressed once — how far content sits from the app chrome (boundary), how far things sit from each other (rhythm), and how wide a reading column may get (measure).

Four container types, picked by what the page is:

Class	Type	Today	For
`.layout-column`	Data	1620px	Lists, detail dashboards
`.layout-column-focused`	Focused	1024px	Home, single-task multi-column pages
`.layout-column-form`	Form	1024px	Settings, in-page edit forms
`.layout-form-create`	Create	1192px	Create pages (also retunes `--layout-measure-control`)

Plus .layout-boundary / .layout-boundary-inline, the two rhythm steps (--layout-section-gap, --layout-group-gap) with their .layout-section-start / .layout-group-start margin forms, and .layout-field-control for the control side of a settings row.

A derived group

Every token is a var() reference to --spacing-* / --container-*, never a literal length, and that is why none of them carries a breakpoint map. The spacing scale is already fluid (--spacing-lg is 1rem, then 1.5rem from sm), and var() is substituted at use time on the element — so a layout token follows the breakpoint override for free. Giving it its own map would duplicate the spacing scale into layout and let the two drift.

Why `@utility` and not `@layer components`

Same reason the typography utilities are emitted that way: @layer components classes are opaque to v4's variant resolver, and their modifiers silently drop. A layout class is exactly the kind you want behind a variant — md:layout-column.

Two things worth a reviewer's eye

.layout-field-control carries a :not(#\#) specificity pin. It is applied to Item.Actions, whose own root already declares shrink-0, and Vue merges both class lists onto one element. Custom @utility blocks sort before the core utilities, so without the pin shrink-0 wins and the control side can no longer yield to a long field name. Measured, not assumed — .layout-field-control at byte 19079 vs .shrink-0 at 31336 in a built bundle. #\# is an id no element can carry, so the selector always matches while reading (1,1,0); it is Tailwind's own important-strategy idiom and stays variant-safe. Only this one of the nine has it, because only this one has a live conflict.

The boundary widening nests on the column, not the boundary. Specificity is (0,2,0) either way, so correctness does not decide it. Nesting on the column keeps both declarations that can set max-width in one block, keeps .layout-boundary to the three padding declarations its name promises, and keeps "a fifth column class costs one line" true — they are generated from a COLUMN_MEASURE map and the nested rule comes along.

Also in the diff

emitIllustrationUtilities-style emission generalized into emitUtilities(map) with a thin emitLayoutUtilities caller.
Regenerating dist picks up one line main was stale on: an emitted comment still reading bg-[var(--x)] where the source has said bg-(--x) since ENG-47001.
Docs: a new Foundations → Layout Storybook page (built from the token source, so it cannot drift), the Max width section of DESIGN.md, a Layout row in Get Started, and the derived-group note in the theme's token README. DESIGN.md ships here rather than separately because that section is the catalog for these tokens — documenting them before they exist would be the drift the rule guards against.

Verification

build:tokens clean, assertNoZeroWithUnit passing, theme suite 12/12.
git diff dist/v4/globals.css is additions only apart from the stale comment: 10 --layout-* lines in :root, no new @media lines (every token is a bare var()), 9 new @utility blocks.
Storybook builds; validate-story-source --all reports 91/91 compliant.

Ten tokens and nine `@utility` classes: how far content sits from the app chrome (BOUNDARY), how far things sit from each other (RHYTHM), and how wide a reading column may get (MEASURE). A DERIVED group: every token is a var() reference to --spacing-* / --container-*, never a literal length. That is why none carries a breakpoint map — the spacing scale is already fluid and var() is substituted at use time on the element, so a layout token follows the override for free. Duplicating the scale into layout would only let the two drift. Emitting them as `@utility` rather than `@layer components` is what gives them variants (`md:layout-column`), the same reason the typography utilities are emitted that way. Generalizes the utility emitter into emitUtilities(map) with a thin emitLayoutUtilities caller, so the shape is reusable. Regenerating dist also picks up one line main was stale on: an emitted comment that still read `bg-[var(--x)]` where the source has said `bg-(--x)` since ENG-47001.

The catalog's token allowlists are scraped from the built theme, so adding semantic/layouts adds ten --layout-* entries. Regenerated rather than hand-edited, which is what catalog:check verifies.

…lighter type scale `Avatar › VariantGrid` failed the visual shard on `dark-desktop` only, at 1.0301% / 1354px against a 1% threshold — deterministically, byte-identical across two runs. The cause is not this branch. That baseline was last regenerated on 2026-07-22 by #768 and has missed two theme changes since: #889 (opaque neutral border tokens) and #876 (headings and body steps to font-weight 300, body leading 1.5 → 1.375). #876 regenerated 548 baselines across three rounds and updated this story's `--dark-tablet` file, but never the dark-desktop one — which alone keeps the bare story id instead of a `--mode` suffix (see .storybook/visual-modes.js), so it is the easy file to miss in a partial regeneration. Aligning baseline to render needs a zero shift (dx=0, dy=0); what differs is ink — text -9%, icons -7% — the lighter weight. This branch only adds tokens, and is simply the first PR to run the suite with #876 merged in. Regenerated via the app-storybook-generate-baseline workflow on linux. The `-u` path could not rewrite it on its own: stale-baseline vs clean render is 0.9875%, under the threshold, so the snapshot passed and was left alone. The file had to be deleted so it was written as a missing snapshot. Against the render CI actually produced, the new baseline is 0.0426% (56px). Still stale and left alone, since both currently pass: this story's `--dark-mobile` baseline (also 2026-07-22). Worth noting separately that the Avatar stories source their photo from a live Unsplash URL, which contributed the residual noise here and is what kept this story on the 1% boundary. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Brings the three commits demo lacked, so the deployed sample exercises them alongside the four fixes carved out of this branch (#899–#902), whose content was already here: - feat(webkit): chip's three kinds (#883) - feat(theme): the semantic/layouts container system (#884) - feat(theme): lightened heading and body type (#876) Conflict resolutions worth knowing: `build-tokens.mjs` — main has no illustration tokens, so main's side of all six hunks was empty. Taking it would have silently deleted this branch's illustration wiring; ours was kept. The merge then produced a DUPLICATE `emitUtilities` and `emitLayoutUtilities` with no conflict at all (both sides had added an identical helper in different places), which is a syntax error the merge itself reported as clean — the second copy is removed and `emitIllustrationUtilities` reuses the first. `texts.data.js` — the five conflicts were all `text-body-*` weight, resolved to main's `light` since that is the change being previewed. Resolved in place rather than with `--theirs`, which would have discarded the file's auto-merged hunks. Entry count held at 144. `.size-limit.json` — union, not a side: main's `chip` plus this branch's `footer-root` and `resizable-panel-root`. `dist/v4/globals.*` are generated, so they were rebuilt from the merged sources rather than hand-merged. The 466 conflicting visual baselines took main's copies; neither side is valid for a merged tree, and this branch opens no PR the visual gate guards. Verified after: no `undefined` in the built CSS, illustration tokens still emitted, main's layout utilities present, body weights now 300, no token data file lost entries, and 154 tests pass across toast, table, sidebar, resizable-panel and chip.

gabriel-lisboa-azion · 2026-08-11T19:03:01Z

What

The layout system every console page is built on, as a theme token group: ten tokens and nine @utility classes, covering three decisions expressed once — how far content sits from the app chrome (boundary), how far things sit from each other (rhythm), and how wide a reading column may get (measure).

Four container types, picked by what the page is:

Class	Type	Today	For
`.layout-column`	Data	1620px	Lists, detail dashboards
`.layout-column-focused`	Focused	1024px	Home, single-task multi-column pages
`.layout-column-form`	Form	1024px	Settings, in-page edit forms
`.layout-form-create`	Create	1192px	Create pages (also retunes `--layout-measure-control`)

Plus .layout-boundary / .layout-boundary-inline, the two rhythm steps (--layout-section-gap, --layout-group-gap) with their .layout-section-start / .layout-group-start margin forms, and .layout-field-control for the control side of a settings row.

A derived group

Every token is a var() reference to --spacing-* / --container-*, never a literal length, and that is why none of them carries a breakpoint map. The spacing scale is already fluid (--spacing-lg is 1rem, then 1.5rem from sm), and var() is substituted at use time on the element — so a layout token follows the breakpoint override for free. Giving it its own map would duplicate the spacing scale into layout and let the two drift.

Why `@utility` and not `@layer components`

Same reason the typography utilities are emitted that way: @layer components classes are opaque to v4's variant resolver, and their modifiers silently drop. A layout class is exactly the kind you want behind a variant — md:layout-column.

Two things worth a reviewer's eye

.layout-field-control carries a :not(#\#) specificity pin. It is applied to Item.Actions, whose own root already declares shrink-0, and Vue merges both class lists onto one element. Custom @utility blocks sort before the core utilities, so without the pin shrink-0 wins and the control side can no longer yield to a long field name. Measured, not assumed — .layout-field-control at byte 19079 vs .shrink-0 at 31336 in a built bundle. #\# is an id no element can carry, so the selector always matches while reading (1,1,0); it is Tailwind's own important-strategy idiom and stays variant-safe. Only this one of the nine has it, because only this one has a live conflict.

The boundary widening nests on the column, not the boundary. Specificity is (0,2,0) either way, so correctness does not decide it. Nesting on the column keeps both declarations that can set max-width in one block, keeps .layout-boundary to the three padding declarations its name promises, and keeps "a fifth column class costs one line" true — they are generated from a COLUMN_MEASURE map and the nested rule comes along.

Also in the diff

emitIllustrationUtilities-style emission generalized into emitUtilities(map) with a thin emitLayoutUtilities caller.
Regenerating dist picks up one line main was stale on: an emitted comment still reading bg-[var(--x)] where the source has said bg-(--x) since ENG-47001.
Docs: a new Foundations → Layout Storybook page (built from the token source, so it cannot drift), the Max width section of DESIGN.md, a Layout row in Get Started, and the derived-group note in the theme's token README. DESIGN.md ships here rather than separately because that section is the catalog for these tokens — documenting them before they exist would be the drift the rule guards against.

Verification

build:tokens clean, assertNoZeroWithUnit passing, theme suite 12/12.
git diff dist/v4/globals.css is additions only apart from the stale comment: 10 --layout-* lines in :root, no new @media lines (every token is a bare var()), 9 new @utility blocks.
Storybook builds; validate-story-source --all reports 91/91 compliant.

Ten tokens and nine `@utility` classes: how far content sits from the app chrome (BOUNDARY), how far things sit from each other (RHYTHM), and how wide a reading column may get (MEASURE). A DERIVED group: every token is a var() reference to --spacing-* / --container-*, never a literal length. That is why none carries a breakpoint map — the spacing scale is already fluid and var() is substituted at use time on the element, so a layout token follows the override for free. Duplicating the scale into layout would only let the two drift. Emitting them as `@utility` rather than `@layer components` is what gives them variants (`md:layout-column`), the same reason the typography utilities are emitted that way. Generalizes the utility emitter into emitUtilities(map) with a thin emitLayoutUtilities caller, so the shape is reusable. Regenerating dist also picks up one line main was stale on: an emitted comment that still read `bg-[var(--x)]` where the source has said `bg-(--x)` since ENG-47001.

The catalog's token allowlists are scraped from the built theme, so adding semantic/layouts adds ten --layout-* entries. Regenerated rather than hand-edited, which is what catalog:check verifies.

…lighter type scale `Avatar › VariantGrid` failed the visual shard on `dark-desktop` only, at 1.0301% / 1354px against a 1% threshold — deterministically, byte-identical across two runs. The cause is not this branch. That baseline was last regenerated on 2026-07-22 by #768 and has missed two theme changes since: #889 (opaque neutral border tokens) and #876 (headings and body steps to font-weight 300, body leading 1.5 → 1.375). #876 regenerated 548 baselines across three rounds and updated this story's `--dark-tablet` file, but never the dark-desktop one — which alone keeps the bare story id instead of a `--mode` suffix (see .storybook/visual-modes.js), so it is the easy file to miss in a partial regeneration. Aligning baseline to render needs a zero shift (dx=0, dy=0); what differs is ink — text -9%, icons -7% — the lighter weight. This branch only adds tokens, and is simply the first PR to run the suite with #876 merged in. Regenerated via the app-storybook-generate-baseline workflow on linux. The `-u` path could not rewrite it on its own: stale-baseline vs clean render is 0.9875%, under the threshold, so the snapshot passed and was left alone. The file had to be deleted so it was written as a missing snapshot. Against the render CI actually produced, the new baseline is 0.0426% (56px). Still stale and left alone, since both currently pass: this story's `--dark-mobile` baseline (also 2026-07-22). Worth noting separately that the Avatar stories source their photo from a live Unsplash URL, which contributed the residual noise here and is what kept this story on the 1% boundary. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Brings the three commits demo lacked, so the deployed sample exercises them alongside the four fixes carved out of this branch (#899–#902), whose content was already here: - feat(webkit): chip's three kinds (#883) - feat(theme): the semantic/layouts container system (#884) - feat(theme): lightened heading and body type (#876) Conflict resolutions worth knowing: `build-tokens.mjs` — main has no illustration tokens, so main's side of all six hunks was empty. Taking it would have silently deleted this branch's illustration wiring; ours was kept. The merge then produced a DUPLICATE `emitUtilities` and `emitLayoutUtilities` with no conflict at all (both sides had added an identical helper in different places), which is a syntax error the merge itself reported as clean — the second copy is removed and `emitIllustrationUtilities` reuses the first. `texts.data.js` — the five conflicts were all `text-body-*` weight, resolved to main's `light` since that is the change being previewed. Resolved in place rather than with `--theirs`, which would have discarded the file's auto-merged hunks. Entry count held at 144. `.size-limit.json` — union, not a side: main's `chip` plus this branch's `footer-root` and `resizable-panel-root`. `dist/v4/globals.*` are generated, so they were rebuilt from the merged sources rather than hand-merged. The 466 conflicting visual baselines took main's copies; neither side is valid for a merged tree, and this branch opens no PR the visual gate guards. Verified after: no `undefined` in the built CSS, illustration tokens still emitted, main's layout utilities present, body weights now 300, no token data file lost entries, and 154 tests pass across toast, table, sidebar, resizable-panel and chip.

gabriel-lisboa-azion requested a review from a team as a code owner August 11, 2026 19:03

github-actionsBot assigned gabriel-lisboa-azion Aug 11, 2026

gabriel-lisboa-azionand others added 2 commits August 11, 2026 16:07

chore(webkit): regenerate the catalog for the layout tokens
55bc988
The catalog's token allowlists are scraped from the built theme, so adding semantic/layouts adds ten --layout-* entries. Regenerated rather than hand-edited, which is what catalog:check verifies.

Merge branch 'main' into feat/theme-layout-tokens
9767fab

herbert-julio-azion approved these changes Aug 12, 2026
View reviewed changes

herbert-julio-azionand others added 3 commits August 13, 2026 15:39

Merge branch 'main' into feat/theme-layout-tokens
a2a1e37

Merge branch 'main' into feat/theme-layout-tokens
3c65b87

Merge branch 'main' into feat/theme-layout-tokens
23714da

isaque-bock-azion previously approved these changes Aug 14, 2026
View reviewed changes

guilherme-santana-azion previously approved these changes Aug 14, 2026
View reviewed changes

isaque-bock-azionand others added 3 commits August 14, 2026 17:52

Merge branch 'main' into feat/theme-layout-tokens
a93651b

Merge branch 'main' into feat/theme-layout-tokens
8a37e76

isaque-bock-azion dismissed stale reviews from guilherme-santana-azion and themself via 3c9dc47August 14, 2026 21:26

robsongajunior approved these changes Aug 14, 2026
View reviewed changes

robson-junior-azion approved these changes Aug 14, 2026
View reviewed changes

rafael-garbinatto-azion approved these changes Aug 14, 2026
View reviewed changes

isaque-bock-azion merged commit 282f768 into mainAug 15, 2026
23 checks passed

isaque-bock-azion deleted the feat/theme-layout-tokens branch August 15, 2026 22:36