Fluid type/space scale is viewport-relative while layout is container-relative

[jackgranatowski]

Finding

The fluid type and space scales (--sf-text-*, --sf-space-* in core/tokens.css:964-972, 1102-1110) compute via clamp() driven by 100vw — they respond to the browser viewport width. Meanwhile the framework's layout primitives (.sf-grid-cols-*, .sf-content-grid, .sf-bento in core/layout.css) respond to @container — they respond to their own parent's width.

Why this matters

Nest a section inside a narrow context (a sidebar, a 1/3 column, a card once .sf-card ships) and the two systems disagree: the layout primitive correctly adapts to the narrow container, but the text and spacing inside it still scale as if the element spans the full viewport, because vw-based clamps have no awareness of an ancestor container's actual width. This is an internal inconsistency between two core pillars of the same framework, not a cosmetic gap.

Scope

• Investigate a container-relative variant of the fluid scale (cqi-based clamps) for components that opt in — likely not a wholesale replacement of the viewport-based default (that's the right choice for page-level type), but an additional token set or opt-in mechanism for nested/narrow contexts.
• Needs design work on where the opt-in boundary lives (per-component class? a --sf-fluid-context: container switch?) before implementation.
• Update docs/llm-guide.md if a new token role/mechanism ships, per repo CLAUDE.md.

[jackgranatowski]

Spike: container-relative fluid scale — options and recommendation

Investigated as a design spike (no implementation yet). Confirmed the root cause in core/tokens.css:964-985: every --sf-text-* / --sf-space-* tier is a clamp() driven by 100vw (e.g. --sf-text-m's formula interpolates against var(--sf-fluid-min-vw)/var(--sf-fluid-max-vw), both viewport-relative). Meanwhile the layout primitives (.sf-grid-cols-*, .sf-content-grid, .sf-bento) respond to @container — so nesting a section in a narrow context (sidebar, card, 1/3 column) makes the layout adapt correctly while type/spacing inside it keeps scaling as if it spans the full viewport.

Options considered

1. --sf-fluid-context switch — a token that toggles the unit used inside the clamp() formula. Rejected: @container conditions can't take a var(), and there's no way to parameterize the unit (vw vs cqi) inside calc()/clamp() via a custom property — you'd need two fully separate formulas either way, so the "switch" buys nothing over a class.

2. Opt-in class (.sf-fluid-cq or similar) — re-declares --sf-text-*/--sf-space-* with the same clamp formulas, swapping 100vw → 100cqi, scoped inside the existing named sf-layout container (already established by .sf-container). Zero new public token names — same tokens, contextually overridden. Cost: the clamp formulas are non-trivial (pow()-based generative scale) and must be duplicated/kept in sync — same "keep two copies in sync" maintenance burden already accepted elsewhere in the codebase (see core/themes.css's SL-001 comment for a precedent of exactly this trade-off).

3. Separate token set (--sf-text-cq-*, --sf-space-cq-*) — consumers opt in per-property (font-size: var(--sf-text-cq-m)) instead of per-scope. More granular, but doubles the public token surface (adds ~14+ new PUBLIC tokens) and requires consumers to rewrite selectors rather than just wrapping a container — more invasive to adopt.

Recommendation

Option 2 (opt-in class re-declaring the existing tokens inside a container scope). Rationale: zero growth in the public token API surface, matches the "opt-in wrapper" ergonomics of the rest of the layout system (.sf-cq already exists as a bare container-scope primitive to compose with), and the sync-burden is a known, already-accepted pattern in this codebase rather than a new risk.

Open questions before implementation

• Exact container-query unit choice: cqi (inline) alone, or cqi/cqb split like some of the layout primitives use?
• Whether the class re-declares tokens on itself (inheriting down) or needs to be paired with .sf-cq/.sf-container to guarantee a container ancestor exists — needs a clear failure mode (silently falling back to viewport units isn't necessarily wrong, but should be intentional and documented).
• Whether this belongs in core/ (since it's arguably a token-system concern) or optional/ given it's opt-in.

No code changes in this pass — flagging for a decision before implementation.

---

Generated by Claude Code

[jackgranatowski]

Resolved by #559 (currently open): adds .sf-fluid-cq (opt-in container-relative fluid scale, cqi-based) alongside the existing viewport-based default, exactly matching this issue's scope. Closing as completed; will ship once #559 merges.

---

Generated by Claude Code