Add .sf-bg background-layer primitive with layout tokens

[jackgranatowski]

Introduces a new layout primitive .sf-bg for absolutely-positioned cover media that sits behind a parent's content, along with five new layout tokens to control its appearance and behavior.

Summary

This PR adds the .sf-bg background-layer primitive to SLASHED, enabling composable background imagery that works natively under .sf-scrim for layered designs (background → gradient → content). The parent element automatically promotes itself to a positioned, isolated stacking context via :has().

Changes

New layout primitive:

• .sf-bg — absolutely-positioned cover layer with automatic parent positioning via :has()
• Supports both bare <img class="sf-bg"> and wrapper patterns with nested > img / > video
• Includes pointer-events blocking to prevent interference with content

New layout tokens (5):

• --sf-bg-inset (default: 0) — single length applied to all edges; layer size derived from it
• --sf-bg-fit (default: cover) — object-fit value for media
• --sf-bg-position (default: 50% 50%) — object-position value for media
• --sf-bg-radius (default: 0) — border-radius for the layer
• --sf-bg-z (default: -2) — z-index positioning (behind content, above parent background)

Documentation & API updates:

• Updated all API indices and registries to reflect 6 new elements (1 class, 5 tokens)
• Added .sf-bg to demo.html with usage examples
• Updated token counts: 686 → 691 tokens, 232 → 233 classes
• Updated layout token count: 49 → 54
• Updated knob count: 220 → 225
• Updated PUBLIC tier count: 862 → 868

Staged utilities:

• Commented out optional utility classes for text-wrap and object-fit/position overrides (not yet shipped in 0.x)

Implementation details

• Parent auto-positioning uses :where(:has(> .sf-bg)) to avoid specificity issues
• Inset calculation uses calc(100% - 2 * var(--sf-bg-inset)) to maintain correct sizing with non-zero insets
• Both direct .sf-bg elements and nested children (> img, > video) respect the same tokens
• Z-index default of -2 ensures the layer sits behind content but above the parent's background

https://claude.ai/code/session_01U8MyeHDL2kAHLo5uBbx32h

Summary by CodeRabbit

• New Features

  • Added a new background-layer layout option for placing media behind content, with configurable inset, fit, position, radius, and stacking order.
  • Improved layering behavior so parent content can automatically stack correctly when this background layer is used.

• Documentation

  • Updated the public API, layout, token, and demo references to include the new background-layer option and related settings.

[coderabbitai]

Warning

Review limit reached

@jackgranatowski, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 47 minutes and 54 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 16cbf563-4090-4f28-8d53-fbbaa4b5a2ea

📥 Commits

Reviewing files that changed from the base of the PR and between 5b0898c and b755e50.

📒 Files selected for processing (6)

• configurator/src/data/api-index.generated.json
• configurator/src/data/classes.generated.json
• core/layout.css
• docs/api-index.json
• docs/api-index.md
• docs/token-annotations.json

📝 Walkthrough

Walkthrough

Adds the .sf-bg absolutely-positioned background-layer CSS primitive to core/layout.css with five --sf-bg-* custom properties in core/tokens.layout.css. Registers the new tokens in token-registry.json, extends domain classification to include -bg- under layout, and regenerates all derived configurator data, public API indexes, docs, and test snapshots.

Changes

Add .sf-bg background-layer primitive

Layer / File(s)	Summary
.sf-bg CSS tokens and layout rules core/tokens.layout.css, core/layout.css	Defines --sf-bg-inset, --sf-bg-fit, --sf-bg-position, --sf-bg-radius, --sf-bg-z in :root, then implements .sf-bg absolute positioning with parent context promotion via :where(:has(> .sf-bg)) and media child rules for img/video.
Token registry and domain classification token-registry.json, configurator/src/data/token-registry.generated.json, configurator/src/lib/domains.ts, configurator/scripts/check-curation.mjs	Appends the five --sf-bg-* tokens (ids 693–697), increments nextId to 698, and adds "-bg-" to DOMAIN_PATTERNS.layout so tokens are classified under the layout domain.
Generated configurator data configurator/src/data/api-index.generated.json, configurator/src/data/classes.generated.json	Adds the five token entries and the sf-bg class entry to generated data arrays; updates _sync metadata counts and hash.
Docs, public API indexes, and test snapshot docs/api-index.json, docs/api-index.md, docs/token-index.json, docs/token-index.md, docs/tokens.md, docs/classes.md, docs/layout.md, docs/llm-guide.md, docs/demo.html, docs/registry.json, tests/token-api.snapshot.json, badges/badge-optimal.json, CHANGELOG.md, optional/utilities.css	Regenerates all public JSON/Markdown indexes to include the new tokens and class, bumps aggregate counts, adds demo markup for .sf-bg composition with .sf-scrim, updates the badge size to 17.5 kB, adds changelog entries, and documents staged utilities in optional/utilities.css.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• codeslash-dev/SLASHED#2: Introduced the core layout utility system in core/layout.css and core/tokens.layout.css that this PR extends with the .sf-bg primitive.
• codeslash-dev/SLASHED#271: Established the docs/api-index.json generation pipeline that this PR updates with the new .sf-bg tokens and class entries.
• codeslash-dev/SLASHED#434: Modified configurator/src/data/classes.generated.json consumption in the cheatsheet UI, directly coupling with the new sf-bg class entry added here.

Suggested labels

codex

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main addition of the new .sf-bg background-layer primitive and its layout tokens.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/pr435-reviews-autofix-vnjcq9

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[qodo-code-review]

PR Summary by Qodo

Add .sf-bg background-layer primitive and --sf-bg-* layout tokens
✨ Enhancement 📝 Documentation ⚙️ Configuration changes 🧪 Tests 🕐 40+ Minutes

Description

• Add .sf-bg background-layer primitive using :has() to auto-position/isolate the parent.
• Introduce five --sf-bg-* layout knobs for inset, fit, position, radius, and z-index.
• Regenerate registries/docs, add demo examples, and update token API snapshot.

Diagram

graph TD
  A["core/tokens.layout.css"] --> B["core/layout.css"] --> C[".sf-bg layer"] --> D["Parent (has > .sf-bg)"] --> E[".sf-scrim"] --> F["Content"]
  C --> G["Docs & registries"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Explicit host class instead of :has()

• ➕ Avoids relying on :has() support/perf characteristics
• ➕ Makes stacking-context promotion an explicit opt-in
• ➖ Worse ergonomics (requires an extra class on every host)
• ➖ Harder to compose reliably in third-party markup

2. Pseudo-element background (::before) pattern

• ➕ No extra DOM node required
• ➕ Common pattern for decorative layers
• ➖ Doesn't support / semantics as directly
• ➖ More awkward to parameterize object-fit/object-position without extra markup

3. Use parent background-image only (no .sf-bg)

• ➕ Simplest CSS surface; no layering primitive needed
• ➕ Works without z-index/isolation concerns
• ➖ Cannot handle ``/responsive media the same way
• ➖ Harder to compose with .sf-scrim consistently across components

Recommendation: Keep the PR’s approach: .sf-bg as an explicit layer plus auto-host promotion via :has() is a strong ergonomics win and composes cleanly with .sf-scrim. If browser-support concerns exist, consider adding an optional documented fallback (e.g., a manual host class) without changing the default API.

Files changed (22) +527 / -40

Enhancement (2) +45 / -1

layout.cssImplement .sf-bg background-layer primitive with :has() host promotion +34/-1

Implement .sf-bg background-layer primitive with :has() host promotion

• Introduces '.sf-bg' as an absolutely-positioned cover layer driven by '--sf-bg-*' tokens and with 'pointer-events: none'. Adds a ':where(:has(> .sf-bg))' rule to auto-apply 'position: relative' and 'isolation: isolate' to the host, and supports both direct media and wrapper patterns ('.sf-bg > img/video').

core/layout.css

tokens.layout.cssDefine new --sf-bg-* layout knobs +11/-0

Define new --sf-bg-* layout knobs

• Adds default values for '--sf-bg-inset', '--sf-bg-fit', '--sf-bg-position', '--sf-bg-radius', and '--sf-bg-z' under a dedicated '.sf-bg' section.

core/tokens.layout.css

Tests (1) +5 / -0

token-api.snapshot.jsonUpdate token API snapshot for new --sf-bg-* names +5/-0

Update token API snapshot for new --sf-bg-* names

• Extends the snapshot list with the five new '--sf-bg-*' token names to keep token API contract tests passing.

tests/token-api.snapshot.json

Documentation (10) +277 / -26

CHANGELOG.mdDocument new .sf-bg primitive and staged utilities +6/-0

Document new .sf-bg primitive and staged utilities

• Adds Unreleased changelog entries describing the new '.sf-bg' layout primitive and its '--sf-bg-*' knobs. Notes that new utility helpers in 'optional/utilities.css' are staged/commented out and not shipped by default.

CHANGELOG.md

api-index.jsonUpdate API index source for new token/class counts and entries +175/-10

Update API index source for new token/class counts and entries

• Bumps element counts and adds the five '--sf-bg-*' tokens plus the '.sf-bg' class entry to the canonical API index source.

docs/api-index.json

api-index.mdExpose .sf-bg and --sf-bg-* in rendered API index +12/-6

Expose .sf-bg and --sf-bg-* in rendered API index

• Updates summary counts and adds rows for the five new layout tokens and the '.sf-bg' layout primitive in the human-readable index.

docs/api-index.md

classes.mdInclude .sf-bg in class reference lists +3/-2

Include .sf-bg in class reference lists

• Increments '.sf-*' class count and adds '.sf-bg' to the layout primitives table.

docs/classes.md

demo.htmlAdd .sf-bg usage examples (bare and under .sf-scrim) +15/-0

Add .sf-bg usage examples (bare and under .sf-scrim)

• Adds demo sections showing a bare '.sf-bg' layer and '.sf-bg' composed under '.sf-scrim' to illustrate background → gradient → content layering.

docs/demo.html

layout.mdDocument .sf-bg in layout primitives overview table +1/-0

Document .sf-bg in layout primitives overview table

• Adds '.sf-bg' to the primitives table with a short description and references to its '--sf-bg-*' knobs.

docs/layout.md

llm-guide.mdAdd .sf-bg tokens to LLM guide token listing +7/-0

Add .sf-bg tokens to LLM guide token listing

• Documents the new '--sf-bg-*' knobs and their defaults alongside other layout primitive knobs for model-guided usage.

docs/llm-guide.md

token-index.jsonAdd --sf-bg-* to token index and update counts +43/-3

Add --sf-bg-* to token index and update counts

• Updates counts by tier/role and registers the five new layout knobs with their defining source file.

docs/token-index.json

token-index.mdUpdate token index markdown for new bg knobs and counts +8/-3

Update token index markdown for new bg knobs and counts

• Updates global token counts and adds the five '--sf-bg-*' tokens to the layout section table.

docs/token-index.md

tokens.mdRegenerate tokens reference to include --sf-bg-* defaults +7/-2

Regenerate tokens reference to include --sf-bg-* defaults

• Bumps totals for layout tokens and adds the five new token rows in the layout token table.

docs/tokens.md

Other (9) +200 / -13

badge-optimal.jsonUpdate optimal bundle size badge +1/-1

Update optimal bundle size badge

• Adjusts the reported gzip size for the optimal bundle to reflect the new output after adding '.sf-bg' and tokens.

badges/badge-optimal.json

check-curation.mjsTeach curation checker to recognize -bg- layout domain +1/-1

Teach curation checker to recognize -bg- layout domain

• Extends the layout domain patterns to include '-bg-' so the new '--sf-bg-*' tokens are categorized correctly by tooling.

configurator/scripts/check-curation.mjs

api-index.generated.jsonRegenerate API index to include new bg tokens +119/-4

Regenerate API index to include new bg tokens

• Updates token hashes and count summaries, and adds entries for '--sf-bg-inset/fit/position/radius/z' within Layout tokens. Keeps bundles/tier metadata consistent with existing generation output.

configurator/src/data/api-index.generated.json

classes.generated.jsonAdd .sf-bg to generated classes list +10/-0

Add .sf-bg to generated classes list

• Registers the new '.sf-bg' layout primitive in the generated class catalog, including its category and descriptive text.

configurator/src/data/classes.generated.json

token-registry.generated.jsonAdd --sf-bg-* tokens to generated token registry +21/-1

Add --sf-bg-* tokens to generated token registry

• Allocates new token IDs for the five '--sf-bg-*' knobs and increments the registry 'nextId' accordingly.

configurator/src/data/token-registry.generated.json

domains.tsUpdate domain patterns for bg tokens +1/-1

Update domain patterns for bg tokens

• Adds '-bg-' to the layout domain pattern list so TypeScript-side domain classification matches the curation script.

configurator/src/lib/domains.ts

registry.jsonRegenerate registry to include .sf-bg and --sf-bg-* names +8/-2

Regenerate registry to include .sf-bg and --sf-bg-* names

• Updates token/class counts and appends the five new token names and the 'sf-bg' class to the published registry lists.

docs/registry.json

utilities.cssStage (comment out) optional utility helpers for text-wrap and object-fit +18/-2

Stage (comment out) optional utility helpers for text-wrap and object-fit

• Adds commented-out utility class definitions ('.sf-balance', '.sf-pretty', and '.sf-object-*') and clarifies that utilities are staged and not shipped active in 0.x.

optional/utilities.css

token-registry.jsonAdd --sf-bg-* tokens to root token registry +21/-1

Add --sf-bg-* tokens to root token registry

• Adds five new token entries with assigned IDs and increments 'nextId' to match the updated registry state.

token-registry.json

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/api-index.json`:
- Around line 20854-20878: The sf-bg metadata entry in the curated API index has
an empty group and a truncated description, so update the sf-bg object in
docs/api-index.json to use the same non-empty layout group convention as the
other layout primitives and replace the clipped description with the full
intended text in the class metadata. Make the fix in the sf-bg record itself so
the generated configurator data inherits the corrected group and complete
description from the authoritative source.
- Around line 848-987: The five background tokens in the docs index are all
inheriting the same inset-only description, which is incorrect for
`--sf-bg-fit`, `--sf-bg-position`, `--sf-bg-radius`, and `--sf-bg-z`. Fix this
upstream by adding distinct per-token documentation for each `--sf-bg-*`
property in `core/tokens.layout.css` so the generator can emit the right
descriptions, or update the curated docs metadata fallback used by the
generator. Make sure the generated entries for `--sf-bg-fit`, `--sf-bg-inset`,
`--sf-bg-position`, `--sf-bg-radius`, and `--sf-bg-z` each have token-specific
text.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: db06f6af-9bdd-490d-b8d2-1ef18a984f8a

📥 Commits

Reviewing files that changed from the base of the PR and between a8203f1 and 5b0898c.

📒 Files selected for processing (22)

• CHANGELOG.md
• badges/badge-optimal.json
• configurator/scripts/check-curation.mjs
• configurator/src/data/api-index.generated.json
• configurator/src/data/classes.generated.json
• configurator/src/data/token-registry.generated.json
• configurator/src/lib/domains.ts
• core/layout.css
• core/tokens.layout.css
• docs/api-index.json
• docs/api-index.md
• docs/classes.md
• docs/demo.html
• docs/layout.md
• docs/llm-guide.md
• docs/registry.json
• docs/token-index.json
• docs/token-index.md
• docs/tokens.md
• optional/utilities.css
• tests/token-api.snapshot.json
• token-registry.json

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📜 Skill insights (0)

Context used

✅ Compliance rules (platform): 6 rules

1. Picture wrapper unsupported ✓ Resolved 🐞 Bug ≡ Correctness

Description

The .sf-bg wrapper rules only target direct > img and > video, so a responsive <picture>
inside .sf-bg won’t be sized to fill or receive object-fit/object-position/radius token
behavior. This causes .sf-bg to fail its “cover media” contract for <picture>-based images,
which are treated as first-class media elsewhere in the codebase.

Code

core/layout.css[R296-304]

+  .sf-bg > img,
+  .sf-bg > video {
+    inline-size:     100%;
+    block-size:      100%;
+    object-fit:      var(--sf-bg-fit);
+    object-position: var(--sf-bg-position);
+    border-radius:   var(--sf-bg-radius);
+    pointer-events:  none;
+  }

Relevance

⭐⭐ Medium

No prior reviews mention <picture> support; team often accepts core CSS correctness fixes (PRs
#154,#155,#338).

PR-#154
PR-#155
PR-#338

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

.sf-bg wrapper mode only styles direct img/video children, so <picture>-wrapped responsive
images won’t be sized or token-driven as intended; meanwhile the base layer explicitly includes
picture alongside img/video as a supported media element, making this omission a practical
compatibility gap.

core/layout.css[274-304]
core/base.css[133-142]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
`.sf-bg` supports wrapper patterns via `.sf-bg > img` / `.sf-bg > video`, but it does not support the very common responsive-image wrapper `<picture>`. In markup like:

```html
<div class="sf-bg">
 <picture>
   <source ...>
   <img ...>
 </picture>
</div>
```

neither the `<picture>` nor its nested `<img>` match the current selectors, so they miss the fill sizing and `object-fit` / `object-position` / radius behavior.

### Issue Context
The codebase already treats `<picture>` as a first-class media element in base styling.

### Fix Focus Areas
- core/layout.css[274-304]
- core/base.css[133-142]

### Implementation guidance
Update the wrapper selectors to include `<picture>` and its nested `<img>`, e.g.:
- add sizing/token rules for `.sf-bg > picture`
- add sizing/token rules for `.sf-bg > picture > img`
- (optional) consider using `:is(img, video, picture)` where it makes sense to keep rules concise

This keeps `.sf-bg` behavior consistent across `img`, `video`, and responsive `picture` markup.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---