ShippedMedium

Add semantic layout primitives (container, stack, cluster, grid, sidebar, split, center, cover) with docs and fixtures

Proposed by Jonathan Miller 1 month agoFunding opened 1 month agoFunded 1 month agoShipped 1 month ago
Acceptance · round 1
Shipped
CINo checks
Automated reviewPass with concerns

This is a well-built, intrinsic, token-only implementation of all eight primitives and exactly the requested `-sm`/`-lg` variants. It comes with a thorough docs page, a compact AI vocabulary table, a narrow/wide fixture with nesting, and a dependency-free check script with unit tests. The CSS follows established intrinsic-layout patterns and introduces no media queries or reordering. The main reservations: `.stack` stretches its children, which is arguably not "natural width"; no CI ran; and the optional browser check is unproven and has a possibly fragile split-wrap expectation.

Acceptance criteria · 6 of 7 met
  • YESAll eight classes exist in the shipped CSS and are included in the main bundle.`src/layout.css` defines `.container`, `.stack`, `.cluster`, `.grid`, `.sidebar`, `.split`, `.center` and `.cover`, and the new `src/synthcss.css` `@import`s `tokens.css` then `layout.css`.
  • YESSpacing and size values reference existing tokens; any new token is added to `:root` and documented.All gaps, padding and widths use `var(--space-N)`, `--container-width`, `--content-width` or the new `--sidebar-width`/`--grid-min`, which are added to `tokens.css`, the `docs/tokens.md` Sizing table and `REQUIRED_TOKENS`.
  • YES`-sm`/`-lg` variants exist exactly for stack, cluster, grid, split, sidebar.`layout.css` defines exactly those 10 variants (`--space-2`/`--space-6` against a `--space-4` default), and `checkLayoutCss` rejects any other class such as `.container-sm`.
  • YESNo breakpoint utility classes and no reading-order-altering properties.There are no at-rules, no `order`, no `*-reverse` and no grid placement in `layout.css`, and the check script enforces this with tests for media queries, `column-reverse` and `order`.
  • YESThe fixture page shows narrow and wide behavior for each primitive, plus nesting.`examples/layout.html` has `-narrow`/`-wide` frames for every primitive and variant, plus a nested sidebar › container › split/cluster › grid › stack example.
  • YESDocs cover every primitive with all six sections and include the AI vocabulary table.`docs/layout.md` has Purpose, HTML example, Variants, Responsive behavior, Recommended uses and Common misuses for all eight primitives, plus a compact "AI Layout Vocabulary" table, and `checkDocs` enforces this.
  • PARTIALPer-primitive required behavior (e.g. stack children keep natural width, sidebar wraps without media queries, cover uses 100vh/100dvh with `margin-block: auto`).The sidebar, grid, cover, center, split, cluster and container rules match the spec table. `.stack` stretches its children rather than leaving them at intrinsic width, which is a debatable reading of "natural width".
Concerns
  • `.stack` relies on the default `align-items: stretch`, so children fill the stack's width. The spec says children "keep their natural width". The docs openly say buttons stretch and suggest wrapping them in a `.cluster`. That is a defensible reading, but backers may have expected `align-items: flex-start`.
  • No CI ran on this commit, and the builder's Verification section is cut off. The claims that `npm test` passes and that `check-layout.mjs` can import `parseBlocks`, `parseDeclarations` and `parseTokens` from `check-tokens.mjs` cannot be confirmed from the diff, because those exports are not shown.
  • The optional Playwright check (`check-layout-browser.mjs`) shows no evidence of having been run. Some of its expectations look fragile. For example, the narrow `.split` header ("SynthCSS Dashboard" plus three short links) may fit in about 357px without wrapping, which would make `splitWrapped === narrow` fail.
  • `check-layout.test.mjs` builds the repo path with `new URL('..', import.meta.url).pathname`. That breaks on Windows and on paths containing spaces or percent-encoded characters; `fileURLToPath` would be safer.
  • Minor: `.sidebar`'s main child uses `min-inline-size: 50%` without subtracting the gap, so the wrap threshold is slightly off "about 50%". The fixture also nests `.container` inside the page's `.container`, a pattern the docs list as a misuse (it is demo-only).
CI details
No CI checks ran on this commit.

BackersAccepted
1 accept · 0 rebuild · 0 not voted · quorum 1 of 1
MaintainerMerge

Accepted by the backers and merged by the maintainer.

Ballots · 1
AcceptJonathan Miller

Automated review cost $0.19, counted as builder cost.

Motivation

Give SynthCSS a small, intent-named structural vocabulary so that AI agents can build responsive layouts without composing low-level flex/grid utilities.

Scope

Implement eight layout primitives using only existing SynthCSS design tokens (spacing, sizes) from the :root token set added in #1. Use Flexbox/Grid and min()/max()/clamp()/minmax()/auto-fit. Media queries are allowed only where intrinsic techniques cannot do the job.

Class Required behavior
.container margin-inline: auto; max-width from a token (or a new --layout-max-width token if none exists); fluid horizontal padding via clamp(); full width below the max width.
.stack Flex column with gap from a default spacing token; children keep their natural width.
.cluster Flex row with flex-wrap: wrap, align-items: center and a token gap.
.grid display: grid; grid-template-columns: repeat(auto-fit, minmax(min(<token min>, 100%), 1fr)); never overflows narrow containers.
.sidebar Two children. The first child (sidebar) has a token-based basis width; the second (main) grows and has a min inline size of about 50%. It wraps to a single column on narrow widths via flex-wrap, without media queries. DOM order is preserved.
.split Flex row, justify-content: space-between, flex-wrap: wrap, token gap; wraps cleanly when space is tight.
.center box-sizing: content-box, margin-inline: auto, max-inline-size from a token. Centers the element horizontally (intrinsic centering).
.cover min-block-size: 100vh with a 100dvh progressive enhancement and no fixed height. Flex column. The direct child with class .cover-main (or the only child) is vertically centered via margin-block: auto.

Variants

Only -sm and -lg spacing variants, applied consistently to the gap-based primitives: .stack-sm/-lg, .cluster-sm/-lg, .grid-sm/-lg, .split-sm/-lg, .sidebar-sm/-lg. Each maps to an existing smaller/larger spacing token. No other variant matrix.

Constraints

  • No JavaScript.
  • No order, flex-direction: *-reverse, or grid placement that changes visual order relative to DOM order.
  • Classes work on any element (nav, main, ul, section, …) and do not depend on child tag types.
  • Nested primitives work. For example, .stack inside .grid inside .container must not leak margins or gaps between levels.

Documentation

Add a layout docs page (assumption: alongside the existing token reference). For each primitive include:

  • Purpose
  • HTML example
  • Variants
  • Responsive behavior
  • Recommended uses
  • Common misuses

Also include a compact "AI Layout Vocabulary" intent→class table (as in the proposal) that is short enough to paste into a model's context.

Verification

Assumption, pending a question: add an HTML fixture page that demonstrates every primitive, every variant, and a nested example. If the repo already has a test runner, add automated checks that these hold at about 375px and about 1280px widths:

  • grid column count drops
  • sidebar stacks
  • cluster/split wrap
  • no horizontal overflow

Otherwise, document how to view the fixtures at both widths and add a simple script check that every primitive class exists and references var(--…) tokens rather than hard-coded spacing values.

Acceptance Criteria

  • All eight classes exist in the shipped CSS and are included in the main bundle.
  • Spacing and size values reference existing tokens. Any newly required token (e.g. max width, sidebar width, grid min) is added to :root and documented.
  • -sm/-lg variants exist exactly for the gap-based primitives listed above.
  • No breakpoint utility classes are introduced, and no reading-order-altering properties are used.
  • The fixture page shows narrow and wide behavior for each primitive, plus nesting.
  • The docs cover every primitive with all six sections and include the AI vocabulary table.

Out of Scope

  • Breakpoint utility classes.
  • Component styles.
  • Alignment/justify variant matrices.
  • JavaScript.
  • Container-query-based variants.

No comments yet.