feat(design): promote .flow-aside into shared chrome

Andrew Dunnrequested to merge
andunn-flow-aside into main

What does this MR do and why?

Promotes a new shared chrome component, .flow-aside, to address the asymmetric-content failure mode in .pane: when the receipts column carries only one or two items but the claim column runs five-plus paragraphs, the existing 1.4fr : 1fr grid leaves the right column tall and empty.

.flow-aside is the additive shape for that case. The author drops <aside class="flow-aside"> anywhere inside a prose section at the chosen anchor point; prose above the aside sits full-width, prose adjacent to the aside wraps to the left, prose past the aside's vertical extent returns to full width. Tufte / magazine-sidenote shape.

Existing .pane stays the right answer when the two columns balance. This MR is purely additive — no .pane markup or styling changes, no consumer-side breakage.

Surfaced from the rootless lab's editorial pass on gitlab-com/public-sector/lab/rootless, where multiple ADR sections carry one or two receipts against multi-paragraph claims and the existing pane shape produces the gap the editor flagged.

What changes

  • New shared CSS at design/chrome/flow-aside.css. Sibling to copy-btn.css at the chrome layer's root, imported by both chrome aggregators' index.css. Authored against the canonical token names (--surface, --rule, --accent, --ink-3, --text-xs, --weight-semibold).
  • Token aliases in design/chrome/docs/tokens.css extended by two lines: --ink-3 maps to the provisional --text-muted, --weight-semibold hardcodes 600 until the canonical tokens import lands.
  • Walkthrough entry in site/src/pages/design/chrome.astro so consumers see the canonical markup contract on the live Design > Chrome page.
  • Lab chrome README updated with the new cross-chrome row.
  • Authoring guides updated so the closed-catalog anti-pattern in both templates/docs/.ai/docs-authoring.md and templates/lab/.ai/lab-authoring.md knows about the new shape. Lab guide adds a cross-link from .pane to .flow-aside for the asymmetric case; docs guide adds a Flow asides entry under the Pattern catalog alongside Callouts.

Consumer-side markup contract

<section class="flow-prose">
  <p>Paragraph above the aside, full width.</p>

  <aside class="flow-aside">
    <p class="aside-eyebrow">Receipts</p>
    <a class="receipt" href="#">…</a>
  </aside>

  <p>Paragraph adjacent to the aside, wraps to the left.</p>
  <p>Paragraph below; returns to full width when the aside ends.</p>
</section>

The .flow-prose wrapper anchors the clearfix. The aside itself can also be dropped inside any container that already establishes a block formatting context (a docs <section class="section">, for instance); the wrapper is the default safe shape.

A left-float variant ships as .flow-aside.flow-aside-left. Below 720px the aside collapses to a full-width block — no horizontal room to accommodate a 240px-min aside next to readable prose on phone-width viewports.

Test plan

  • make check REPO=$PWD passes self-conformance.
  • Live Design > Chrome page shows the new .flow-aside row with the markup snippet rendered correctly.
  • Local serve of any docs or lab consumer that lifts the new shape: aside floats right, prose wraps, prose below returns to full width, mobile collapse below 720px.

Follow-up

  • The rootless lab's editorial pass adopts .flow-aside where the current .pane shape leaves whitespace gaps. Separate MR against gitlab-com/public-sector/lab/rootless.

🤖 Generated with Claude Code

Merge request reports