actual-css 0.9.2 → 0.10.0

package/docs/design-notes/column-layout.md

@@ -1,9 +1,5 @@
 # Explicit Column Layout
 
-## Status
-
-Proposed for Actual CSS 0.4.
-
 ## Problem
 
 Actual CSS already provides several layout primitives with distinct responsive contracts:
@@ -25,464 +21,176 @@ Examples include:
 * a 3 / 6 / 3 application shell;
 * editorial or dashboard compositions where regions must align to a shared column canvas.
 
-Today these layouts can be expressed with `--grid-columns` and application-specific `grid-column` rules:
-
-```css
-.my-layout {
-  --grid-columns: repeat(12, minmax(0, 1fr));
-}
-
-.my-main {
-  grid-column: span 8;
-}
-
-.my-aside {
-  grid-column: span 4;
-}
-```
-
-This is already possible, but it provides no shared vocabulary and makes every application redefine the same placement conventions.
-
-The missing feature is therefore not new CSS capability. It is a small, explicit composition vocabulary.
+These layouts can be expressed with `--grid-columns` and application-specific `grid-column` rules, but that gives no shared canvas and makes every application redefine the same conventions — including the auto-placement trap described below.
 
 ## Decision
 
-Add an opt-in 12-column horizontal composition primitive:
-
-```html
-<div class="column-layout">
-  <main class="column-span-8">
-    ...
-  </main>
-
-  <aside class="column-span-4 column-start-9">
-    ...
-  </aside>
-</div>
-```
-
-The public API is intentionally limited to:
-
-```text
-.column-layout
-.column-span-1 … .column-span-12
-.column-start-1 … .column-start-12
-```
-
-No responsive behavior is implied.
-
-No row placement, ordering, named areas, breakpoint variants, offsets, or configurable column counts are part of the primitive.
-
-## Why this is separate from `.grid`
-
-`.grid` and `.grid-N` are collection primitives.
-
-They answer questions such as:
-
-> How many peer items should fit here?
-
-or:
-
-> Should these repeated items preserve a known structural density?
-
-`.column-layout` answers a different question:
-
-> Where should these distinct regions sit on a shared composition canvas?
-
-The distinction is intentional.
-
-A layout that happens to contain three regions is not automatically a column layout. If those regions are peers that should switch together, `.switcher` is the correct primitive. If one region is secondary to another, `.sidebar-layout` is usually the better choice.
-
-Use `.column-layout` because **placement is part of the design**, not merely because the design contains columns.
-
-## Choosing the primitive
-
-Use the relationship between regions rather than their visual count.
-
-| Need                                                   | Primitive         |
-| ------------------------------------------------------ | ----------------- |
-| Independent repeated items with intrinsic reflow       | `.grid`           |
-| Equal-width peers with a known structural density      | `.grid-N`         |
-| Peer regions that must switch together                 | `.switcher`       |
-| Main content with a secondary region                   | `.sidebar-layout` |
-| Media paired with flexible content                     | `.media`          |
-| Explicit region placement on a shared 12-column canvas | `.column-layout`  |
-
-A useful diagnostic is:
-
-> If local CSS mainly makes one layout primitive behave like another, reconsider the primitive before adding more CSS.
-
-## Why twelve columns
-
-The column count is deliberately fixed at 12.
-
-Twelve provides useful subdivisions without requiring a configurable grid system:
-
-```text
-6 + 6
-4 + 4 + 4
-3 + 3 + 3 + 3
-8 + 4
-9 + 3
-2 + 8 + 2
-```
-
-The purpose of `.column-layout` is to provide a shared and predictable composition vocabulary.
-
-A configurable `--column-count` would weaken that contract. It would also make utilities such as `.column-span-8` ambiguous once the underlying canvas no longer had twelve units.
-
-Applications that genuinely require a different track system should use custom CSS or `--grid-columns`.
-
-## Base recipe
-
-The primitive uses twelve equal tracks with zero intrinsic minimum:
+An opt-in 12-column horizontal composition primitive, placed through two hooks on each direct child:
 
 ```css
 .column-layout {
   display: grid;
-  grid-template-columns: repeat(12, minmax(0, 1fr));
   gap: var(--gap);
+  grid-template-columns: repeat(12, minmax(0, 1fr));
 }
-```
-
-Using `minmax(0, 1fr)` is an invariant, not responsive behavior.
-
-It prevents the track definition itself from creating a min-content floor that forces the layout wider than its container.
-
-It does **not** guarantee that arbitrary content will remain usable inside a very narrow span.
-
-A two-column span in a narrow container may still be too small for its content. That is an application composition problem, not something the primitive should guess how to solve.
-
-## Gap is not coupled to the track count
-
-A grid that sizes its tracks from `--gap` couples spacing and density: setting the `gap` property on its own can make the two disagree. Actual removed its `.gap-sm` / `.gap-md` / `.gap-lg` utilities before 0.8 for exactly that reason — a local gap is now a direct `gap` declaration, and `--gap` is reserved for rebinding an inherited rhythm.
-
-`.column-layout` never had that coupling. Its track template is `repeat(12, minmax(0, 1fr))` and never reads `--gap` for sizing, so `gap` and the track count are independent at every width.
 
-This is worth stating explicitly because an author who has read the grid page will reasonably assume the opposite.
-
-## Default child behavior
-
-Unplaced direct children span the full canvas:
-
-```css
 :where(.column-layout) > * {
-  grid-column-end: span 12;
+  --column-start: initial;
+  --column-span: initial;
+
+  grid-column-start: var(--column-start, auto);
+  grid-column-end: span var(--column-span, calc(13 - var(--column-start, 1)));
   min-inline-size: 0;
 }
 ```
 
-This gives the primitive a safe failure mode. Without an explicit placement class, an element remains a normal full-width region instead of implicitly occupying one of twelve very narrow tracks.
-
-Placement is therefore opt-in per child, and a heading or a full-width intro can sit in the same canvas as placed regions without carrying a class of its own.
-
-The span form is load-bearing. The obvious alternative is:
-
 ```css
-/* Rejected. */
-:where(.column-layout) > * {
-  grid-column: 1 / -1;
+.main {
+  --column-span: 8;
 }
-```
-
-That gives every child a **definite** column start of line 1, which removes it from column auto-placement. Two placed peers then both resolve to column 1 and the second is pushed to the next row:
-
-```text
-<section class="column-span-8">   row 1, columns 1-8
-<aside class="column-span-4">     row 2, columns 1-4    ← not 9-12
-```
-
-Measured, not reasoned: the pair renders at `top=8` and `top=26` with the shorthand reset, and at `top=8`/`top=8` with the span reset. Expressing the default as a span keeps the start line `auto`, so auto-placement continues to flow peers across the canvas.
-
-## Placement tiers and source order
 
-The primitive is three zero-specificity tiers, and **only source order separates them**:
-
-```text
-1. :where(.column-layout) > *    auto-placed, spanning the whole canvas
-2. :where(.column-start-N)       a definite start line, running to the canvas end
-3. :where(.column-span-N)        the end only, refining either of the above
+.aside {
+  --column-span: 4;
+}
 ```
 
-Because every tier resolves to specificity `(0,0,0)`, reordering the file changes behavior silently:
-
-* moving tier 3 above tier 2 makes every `start + span` pair run to column 12;
-* moving either above tier 1 makes every placement full-span.
+The public API is one class and two hooks. No responsive behavior is implied. No row placement, ordering, named areas, breakpoint variants, offsets, or configurable column counts are part of the primitive.
 
-Neither failure produces an error, an override warning, or a visibly broken canvas — both look like a plausible layout. The order is therefore asserted twice: `tests/css-audit.test.js` locks the order of the blocks in the source file, and `tests/browser/column-layout.test.js` locks the geometry the order produces.
+## Why hooks rather than placement classes
 
-This is the cost of the zero-specificity design, and it is worth paying: the alternative is placement classes at normal class specificity, which would put every application-owned recomposition rule back into a source-order tie with the framework.
+A span and a start are two numbers. As classes they need twenty-four adapters (`.column-span-1` … `.column-start-12`) to encode CSS coordinates, and those adapters interact: a start class must also set the end line so it can stand alone, a span class must refine that end, and the only thing separating them at zero specificity is source order. The primitive then depended on a file order no browser reports when it breaks, guarded by a test whose only job was that order.
 
-## Span utilities
+As custom properties the two inputs are independent. One rule reads both, and there is nothing to order.
 
-Span utilities set only the column span:
+Recomposition also stays inside the primitive's API. With classes, an application's container query had to leave the vocabulary and write `grid-column` itself. With hooks, it sets the same two properties the region was placed with.
 
-```css
-:where(.column-span-1) {
-  grid-column-end: span 1;
-}
-
-:where(.column-span-2) {
-  grid-column-end: span 2;
-}
+The API does not require inline styles. The documented form puts the hooks on an application class; `style="--column-span: 8"` is a shortcut for a composition that never changes. An inline value outranks every rule, so coordinates that a container query recomposes belong on a class.
 
-/* … */
+## One rule, four placements
 
-:where(.column-span-12) {
-  grid-column-end: span 12;
-}
-```
-
-For example:
-
-```html
-<div class="column-layout">
-  <section class="column-span-8">...</section>
-  <aside class="column-span-4">...</aside>
-</div>
+```text
+neither set        start auto, span 12       auto-placed, full canvas
+span only          start auto, span N        auto-placed over N units
+start only         start S,    span 13 - S   from line S to the canvas end
+start and span     start S,    span N        explicit
 ```
 
-With normal grid auto-placement, this produces an 8 / 4 composition: neither child has a definite start line, so the aside flows into columns 9-12.
-
-Auto-placement also means a pair that does not fit wraps rather than overflowing. Two `column-span-8` regions occupy sixteen units, so the second moves to the next row. That is correct grid behavior, not a canvas violation.
+### The start defaults to `auto`
 
-## Start utilities
+The obvious way to write "full canvas" is `grid-column: 1 / -1`. It gives every child a **definite** column start of line 1, which removes it from column auto-placement. Two placed peers then both resolve to column 1 and the second is pushed to the next row:
 
-Start utilities set the explicit starting grid line:
-
-```css
-:where(.column-start-1) {
-  grid-column: 1 / -1;
-}
+```text
+<section style="--column-span: 8">   row 1, columns 1-8
+<aside style="--column-span: 4">     row 2, columns 1-4    ← not 9-12
+```
 
-:where(.column-start-2) {
-  grid-column: 2 / -1;
-}
+Measured, not reasoned: the pair renders on two rows with a definite default start and on one row with an `auto` start, which `tests/browser/column-layout.test.js` asserts. Keeping the start `auto` until an author sets it lets auto-placement flow peers across the canvas.
 
-/* … */
+### A start alone runs to the edge
 
-:where(.column-start-12) {
-  grid-column: 12 / -1;
-}
-```
+With a fixed `span 12` default, `--column-start: 9` would place a region across lines 9 to 21 and add nine implicit columns. The span fallback is therefore derived from the start, `calc(13 - start)`, so a start alone always ends on the canvas edge. With no start, the same expression resolves to `span 12`.
 
-This allows deliberate offsets without introducing a separate margin-based `offset-*` abstraction.
+`calc()` in an integer position resolves to a whole number once `var()` is substituted. Support for `calc()` in number contexts predates the CSS floor by years (Chrome 31, Firefox 48, Safari 6); the browser tests prove the four placements in Chromium.
 
-Each start utility also sets the end line to `-1`, so a start used **without** a span runs to the edge of the canvas:
+### Coordinates are local to the grid item
 
-```html
-<aside class="column-start-9">...</aside>
-```
+Custom properties inherit. A nested `.column-layout` placed with `--column-start: 3; --column-span: 8` would hand those values to each of its own children, which would all land on line 3.
 
-occupies columns 9 through 12. The alternative — setting `grid-column-start` alone — would leave the tier 1 default of `span 12` in place and place the region across lines 9 to 21, adding nine implicit columns. A single class must not be able to do that.
+The reset is declared on each child, not on the canvas: the nested canvas needs its coordinates for its own position in the parent, and its children must start from nothing. `--column-start: initial` makes the property guaranteed-invalid, so `var()` takes its fallback. The rule has zero specificity, so any author rule on the child wins.
 
-A `column-span-*` on the same element then refines the end, because tier 3 follows tier 2 in source order.
+`@property { inherits: false }` would express the same thing, but it is above the CSS floor and two declarations already do the job.
 
-For example:
+## Why this is separate from `.grid`
 
-```html
-<div class="column-layout">
-  <article class="column-span-10 column-start-2">
-    ...
-  </article>
-</div>
-```
+`.grid` and `.grid-N` are collection primitives. They answer:
 
-The article occupies columns 2 through 11.
+> How many peer items should fit here?
 
-When combining `column-start-S` and `column-span-N`, the author must keep the placement inside the twelve-column canvas:
+`.column-layout` answers a different question:
 
-```text
-S + N - 1 <= 12
-```
+> Where should these distinct regions sit on a shared composition canvas?
 
-For example:
+A layout that happens to contain three regions is not automatically a column layout. If those regions are peers that should switch together, `.switcher` is the correct primitive. If one region is secondary to another, `.sidebar-layout` is usually the better choice.
 
-```text
-start 9 + span 4 → valid
-start 10 + span 4 → exceeds the canvas
-```
+Use `.column-layout` because **placement is part of the design**, not merely because the design contains columns.
 
-Actual CSS does not attempt to guard against invalid combinations, and the failure is worth stating precisely because it is not local.
+| Need                                                   | Primitive         |
+| ------------------------------------------------------ | ----------------- |
+| Independent repeated items with intrinsic reflow       | `.grid`           |
+| Equal-width peers with a known structural density      | `.grid-N`         |
+| Peer regions that must switch together                 | `.switcher`       |
+| Main content with a secondary region                   | `.sidebar-layout` |
+| Media paired with flexible content                     | `.media`          |
+| Explicit region placement on a shared 12-column canvas | `.column-layout`  |
 
-When a placement exceeds the explicit canvas, CSS Grid adds implicit columns at the end. `grid-auto-columns` defaults to `auto`, so an implicit column is sized by its content while the twelve `1fr` tracks divide whatever inline size is left. Every region in the canvas therefore shifts, not just the region carrying the invalid placement — a thirteenth column silently re-scales the coordinate system for everything else.
+> If local CSS mainly makes one layout primitive behave like another, reconsider the primitive before adding more CSS.
 
-## Low specificity is intentional
+## Why twelve columns
 
-Placement utilities use `:where()` so their specificity remains zero.
+Twelve provides useful subdivisions without requiring a configurable grid system: `6 + 6`, `4 + 4 + 4`, `3 + 3 + 3 + 3`, `8 + 4`, `9 + 3`, `2 + 8 + 2`.
 
-This makes application-owned recomposition additive rather than corrective.
+A configurable `--column-count` would weaken the shared canvas: a span of 8 would mean different widths in different layouts, and the start-only fallback would need the count too. Applications that genuinely require a different track system should use `--grid-columns`.
 
-For example:
+## Base recipe
 
-```html
-<div class="container-query">
-  <div class="column-layout profile-layout">
-    <main class="column-span-8 profile-main">...</main>
-    <aside class="column-span-4 column-start-9 profile-aside">...</aside>
-  </div>
-</div>
-```
+`minmax(0, 1fr)` is an invariant, not responsive behavior. It prevents the track definition itself from creating a min-content floor that forces the layout wider than its container. It does **not** guarantee that arbitrary content remains usable inside a very narrow span; that is an application composition problem.
 
-The application can later redefine placement with a normal class selector:
+The track template never reads `--gap`, so `gap` and the track count are independent at every width. This is worth stating because an author who has read the grid page will reasonably assume the opposite.
 
-```css
-@container (width < 48rem) {
-  .profile-main {
-    grid-column: 1 / span 6;
-  }
+## Exceeding the canvas
 
-  .profile-aside {
-    grid-column: 7 / span 6;
-  }
-}
-```
+When combining a start and a span, the author keeps `start + span - 1 <= 12`. Actual CSS does not guard against invalid combinations, and the failure is worth stating precisely because it is not local.
 
-The author does not need to undo framework specificity before applying a new composition.
+When a placement exceeds the explicit canvas, CSS Grid adds implicit columns at the end. `grid-auto-columns` defaults to `auto`, so an implicit column is sized by its content while the twelve `1fr` tracks divide whatever inline size is left. Every region shifts, not just the one carrying the invalid placement.
 
-Normal cascade-layer rules still apply. If application CSS is placed in an earlier layer than Actual CSS, layer order can still take precedence over selector specificity.
+A pair that does not fit *without* explicit starts wraps instead: two eight-unit regions occupy sixteen units, so the second moves to the next row. That is correct grid behavior, not a canvas violation.
 
 ## Responsive contract
 
-`.column-layout` has **no automatic responsive collapse**.
-
-This is deliberate.
-
-Different compositions have different useful breakpoints:
+`.column-layout` has **no automatic responsive collapse**. Different compositions have different useful breakpoints:
 
 * `8 + 4` may remain useful longer than `3 + 9`;
 * a centered article may only need reduced side gutters;
 * a dashboard may recombine from three regions into two before eventually stacking;
 * an editorial layout may switch to a completely different representation on narrow screens.
 
-A single framework threshold would therefore be arbitrary.
-
-It would also recreate a hidden two-part contract where a layout class silently changes behavior only when combined with a wrapper or breakpoint rule.
-
-Actual CSS does not make that decision.
-
-The author owns narrow-container behavior.
-
-## Author-owned recomposition
-
-A simple composition may stack completely:
-
-```css
-@container (width < 40rem) {
-  .profile-layout > * {
-    grid-column: 1 / -1;
-  }
-}
-```
-
-A more complex composition can preserve the coordinate system through intermediate states.
-
-For example, desktop:
-
-```text
-[              MAIN 8              ][   ASIDE 4   ]
-```
-
-Intermediate:
-
-```text
-[         MAIN 6        ][        ASIDE 6         ]
-```
-
-Narrow:
-
-```text
-[                     MAIN                     ]
-[                    ASIDE                     ]
-```
-
-Implementation:
+A single framework threshold would be arbitrary, and a hidden one would force authors to undo it before writing their own. The author owns narrow-container behavior, and writes it with the same hooks:
 
 ```css
 @container (width < 48rem) {
   .profile-main {
-    grid-column: 1 / span 6;
+    --column-start: 1;
+    --column-span: 6;
   }
 
   .profile-aside {
-    grid-column: 7 / span 6;
+    --column-start: 7;
+    --column-span: 6;
   }
 }
 
 @container (width < 32rem) {
   .profile-main,
   .profile-aside {
-    grid-column: 1 / -1;
+    --column-start: 1;
+    --column-span: 12;
   }
 }
 ```
 
-This ability to deliberately recompose regions is part of the value of a coordinate system.
-
-The framework should not reduce every narrow layout to a single automatic stack.
-
-## Relationship with `.container-query`
+The ability to recompose through intermediate states is part of the value of a coordinate system; the framework should not reduce every narrow layout to a single automatic stack.
 
-`.container-query` is not required by `.column-layout`.
-
-The primitive does not inspect container width and does not contain hidden container-query behavior.
-
-An author may choose to use `.container-query` because their own responsive rules use `@container`:
-
-```html
-<div class="container-query">
-  <div class="column-layout profile-layout">
-    ...
-  </div>
-</div>
-```
-
-In that case, the dependency is explicit:
-
-> the author uses a query container because the author wrote a container query.
-
-This is intentionally different from a framework primitive whose responsive contract depends on an unrelated wrapper being present.
+`.container-query` is not required by `.column-layout`. An author uses it because their own rules use `@container` — the author uses a query container because the author wrote a container query.
 
 ## Narrow containers
 
-A twelve-column coordinate system is primarily a wide-context composition tool.
-
-At narrow widths, individual tracks can become extremely small, and eleven gaps consume a large share of the available inline size rather than a marginal one.
+With the default `--gap: 0.75rem` and a container measuring 279px at a 360px viewport, the eleven gaps take 132px. The twelve tracks divide the remaining 147px, roughly **12px per unit**: a four-unit region is 84px wide.
 
-With the default `--gap: 0.75rem` and a `.center` container measuring 279px at a 360px viewport, the eleven gaps take 132px. The twelve tracks divide the remaining 147px, which is roughly **12px per unit**: a `column-span-4` region is 84px wide.
-
-That number is the argument. There is no useful composition to guess at that width, which is precisely why the primitive does not try.
-
-The framework guarantees that the explicit track definition can shrink:
-
-```css
-repeat(12, minmax(0, 1fr))
-```
-
-It does not guarantee that every arbitrary span remains a useful content width.
-
-Applications should define an appropriate narrow representation where necessary.
-
-This is not considered a failure of the primitive. The purpose of `.column-layout` is explicit composition, not intrinsic reflow.
-
-For intrinsic responsive behavior, prefer `.grid`, `.switcher`, or `.sidebar-layout`.
+That number is the argument. There is no useful composition to guess at that width, which is precisely why the primitive does not try. For intrinsic responsive behavior, prefer `.grid`, `.switcher`, or `.sidebar-layout`.
 
 ## One-dimensional scope
 
-Despite being implemented with CSS Grid, `.column-layout` exposes only horizontal column placement.
-
-Actual CSS does not provide:
-
-```text
-.row-span-*
-.row-start-*
-.area-*
-.column-end-*
-```
-
-as part of this primitive.
-
-Applications remain free to use native CSS Grid features where a genuinely two-dimensional composition requires them:
+Despite being implemented with CSS Grid, `.column-layout` exposes only horizontal column placement. There are no row, area, end-line, or order hooks. Applications remain free to use native CSS Grid where a genuinely two-dimensional composition requires it:
 
 ```css
 .dashboard-summary {
@@ -490,188 +198,63 @@ Applications remain free to use native CSS Grid features where a genuinely two-d
 }
 ```
 
-Keeping the framework API one-dimensional prevents the primitive from growing into a general-purpose grid DSL.
-
-The `column-*` prefix is reserved for placement on this canvas. If Actual CSS later needs CSS multi-column utilities, they must not be named `column-count-*` or `column-width-*` under the same prefix — the two concepts would be indistinguishable in markup. A separate name such as `text-columns-*` keeps the coordinate domain unambiguous.
+Keeping the API one-dimensional prevents the primitive from growing into a general-purpose grid DSL.
 
-## Source order and `order`
-
-`column-layout` does not provide `order-*` utilities.
-
-Visual reordering has consequences for reading order, keyboard navigation, and accessibility. It is also not specific to the column-layout primitive.
-
-If Actual CSS introduces ordering utilities in the future, they should be designed and documented independently.
-
-Authors should prefer DOM order that remains sensible when the composition changes.
+Visual reordering has consequences for reading order, keyboard navigation, and accessibility, and is not specific to this primitive. Authors should prefer DOM order that stays sensible when the composition changes.
 
 ## Direct-child box requirement
 
-Placement applies to grid items.
-
-A direct child carrying `column-span-*` or `column-start-*` must therefore generate a box.
-
-Avoid:
-
-```css
-.region {
-  display: contents;
-}
-```
-
-when `.region` is the element carrying column placement.
-
-With `display: contents`, the element's own box is removed and its descendants become grid items instead. The `grid-column-*` values assigned to the boxless element no longer control those descendants.
-
-This is a general limitation of box-dependent layout primitives, not something `.column-layout` attempts to compensate for.
-
-## Relationship with `--grid-columns`
-
-Before `.column-layout`, custom `--grid-columns` was the only built-in escape hatch for arbitrary asymmetric track systems.
-
-After introducing `.column-layout`, the responsibilities become clearer:
-
-Use `.column-layout` when distinct regions need explicit spans or starts on a standard twelve-column canvas.
-
-Use `--grid-columns` for genuinely custom track templates that do not fit existing primitives or the twelve-column composition model.
-
-For example:
-
-```css
-.custom-layout {
-  --grid-columns: minmax(12rem, 18rem) 1fr minmax(10rem, 14rem);
-}
-```
-
-is still a legitimate custom grid because its tracks encode meaningful sizing rather than twelve interchangeable coordinate units.
+Placement applies to grid items. A direct child carrying coordinates must generate a box: with `display: contents`, its own box is removed, its descendants become grid items, and the coordinates no longer control them.
 
 ## Why this is opt-in
 
-A general coordinate system is easy to misuse.
-
-Given:
-
-```text
-main + aside
-```
-
-it is tempting to write:
-
-```html
-<div class="column-layout">
-  <main class="column-span-8">...</main>
-  <aside class="column-span-4">...</aside>
-</div>
-```
-
-even when `.sidebar-layout` already expresses the relationship and provides a more appropriate intrinsic responsive behavior.
-
-Likewise, three peer panels should not become three `column-span-4` regions merely because the coordinate system makes that possible.
+A general coordinate system is easy to misuse. Given `main + aside`, it is tempting to write an 8 + 4 composition even when `.sidebar-layout` already expresses the relationship with intrinsic responsive behavior. Likewise, three peer panels should not become three four-unit regions merely because the canvas makes that possible.
 
-The primitive therefore belongs to the Layout family but is not part of the core baseline.
-
-Its documentation must make the selection boundary explicit.
-
-The convenience of `column-layout` should not turn every layout problem into coordinate arithmetic.
+The primitive belongs to the Layout family but is not part of the core baseline, and its documentation makes the selection boundary explicit.
 
 ## Rejected alternatives
 
-### Make `.grid-N` support arbitrary spans
-
-Rejected.
+### Placement classes (`.column-span-N`, `.column-start-N`)
 
-`.grid-N` represents structural peer density. Adding arbitrary child placement would blur the distinction between a collection and an explicit composition canvas.
+Rejected. Twenty-four classes encode two numbers, the start and span classes must be ordered in the source for a start alone to end on the canvas edge, and application recomposition has to leave the vocabulary to write `grid-column`. See [Why hooks rather than placement classes](#why-hooks-rather-than-placement-classes).
 
-### Use `.layout-grid`
+### Reset the hooks on the canvas
 
-Technically accurate, but potentially confusing beside `.grid` and `.grid-N`.
+Rejected. A nested canvas is also a grid item of its parent; resetting on `.column-layout` would erase the coordinates it needs for its own placement.
 
-The public concept exposed to authors is a column composition system. CSS Grid is its implementation mechanism.
+### `@property` with `inherits: false`
 
-### Use `.columns`
+Rejected for the base contract: above the CSS floor, and the per-child reset already keeps coordinates local.
 
-Rejected as too generic and potentially confused with CSS multi-column layout.
+### Make `.grid-N` support arbitrary spans
 
-### Use `.span-N` and `.start-N`
+Rejected. `.grid-N` represents structural peer density. Arbitrary child placement would blur the distinction between a collection and a composition canvas.
 
-Rejected because the class names are overly broad and would reserve generic application vocabulary.
+### Use `.layout-grid` or `.columns`
 
-`column-span-N` and `column-start-N` make the coordinate domain explicit.
+Rejected. `.layout-grid` is confusing beside `.grid` and `.grid-N`; `.columns` is too generic and reads as CSS multi-column layout.
 
 ### Add `--column-count`
 
-Rejected.
-
-Twelve columns are part of the primitive's contract. A configurable track count would make the placement vocabulary inconsistent and weaken interoperability between layouts.
-
-### Give unplaced children `grid-column: 1 / -1`
-
-Rejected, after measurement.
-
-It reads as the natural way to express "spans the whole canvas", but the shorthand sets a definite `grid-column-start: 1` on every child, which removes all of them from column auto-placement. `.column-span-8` beside `.column-span-4` then stacks instead of composing 8 + 4, because both children resolve to column 1.
-
-Every placed region would need an explicit `column-start-*`, turning the most common two-region composition into coordinate arithmetic. `grid-column-end: span 12` gives the same default width while leaving the start line `auto`.
-
-### Add automatic container-query collapse
-
-Rejected.
-
-There is no universally correct threshold for arbitrary per-region compositions.
-
-A hidden default would also force authors with different requirements to undo framework behavior before implementing their intended layout.
-
-### Add breakpoint variants
-
-Rejected.
+Rejected. Twelve columns are part of the primitive's contract.
 
-Classes such as:
+### Add automatic container-query collapse, breakpoint variants, or offsets
 
-```text
-md-column-span-6
-lg-column-span-4
-```
-
-would recreate a breakpoint-driven layout DSL and move responsive strategy back into markup.
-
-Author-owned CSS and container queries are preferred.
-
-### Add offset utilities
-
-Rejected.
-
-`column-start-N` directly expresses native grid placement and avoids introducing a second, margin-based placement model.
-
-### Add row placement and named areas
+Rejected. There is no universally correct threshold; breakpoint variants would move responsive strategy back into markup; `--column-start` already expresses native grid placement without a second, margin-based model.
 
-Rejected for the initial scope.
+### Add row placement, named areas, or ordering
 
-The primitive intentionally provides only horizontal coordinate placement.
-
-### Add ordering utilities
-
-Rejected as unrelated to the primitive and carrying separate accessibility concerns.
+Rejected for this scope. Row placement and areas belong to native Grid on an application class; ordering carries separate accessibility concerns.
 
 ## Decision summary
 
-Actual CSS will provide an explicit, opt-in twelve-column composition vocabulary:
-
-```text
-.column-layout
-.column-span-1 … .column-span-12
-.column-start-1 … .column-start-12
-```
-
 The primitive:
 
 * uses twelve equal `minmax(0, 1fr)` tracks;
-* gives unplaced direct children full-width placement, expressed as a span so auto-placement keeps working;
-* uses low-specificity placement utilities in three source-order-dependent tiers;
-* provides no automatic responsive behavior;
-* leaves narrow-container recomposition to the application;
+* places each direct child from `--column-start` and `--column-span`, in one rule;
+* keeps the start `auto` until set, so auto-placement composes spans;
+* derives the default span from the start, so a start alone ends on the canvas edge;
+* resets both hooks on each child, so coordinates never leak into a nested canvas;
+* provides no automatic responsive behavior and leaves recomposition to the application, through the same hooks;
 * remains horizontal-only;
-* provides no order, row, area, breakpoint, offset, or configurable-count API;
-* requires placed children to generate grid-item boxes;
 * complements rather than replaces `.grid`, `.grid-N`, `.switcher`, `.sidebar-layout`, and `.media`.
-
-The purpose is not to add layout capability that CSS Grid does not already provide.
-
-The purpose is to give explicit application and editorial compositions a small, shared, readable coordinate vocabulary without weakening the intrinsic layout primitives used everywhere else.