Skip to content

feat: add corner-scoop, corner/overlap recipe macros - #517

Closed
jackgranatowski wants to merge 16 commits into
mainfrom
claude/macros-scoop-overlay-recipes-lxk7a9
Closed

feat: add corner-scoop, corner/overlap recipe macros#517
jackgranatowski wants to merge 16 commits into
mainfrom
claude/macros-scoop-overlay-recipes-lxk7a9

Conversation

@jackgranatowski

@jackgranatowski jackgranatowski commented Jul 4, 2026

Copy link
Copy Markdown
Contributor

Closing in favor of #519 — a clean re-submission of this same accepted content (.sf-corner-scoop + .sf-overlap/.sf-overlap-host, plus the --sf-bg-inset unit fix and the doc-generator directive-comment fix) on a fresh branch off current main, with a conventionally-formatted commit history instead of this branch's revert-heavy one (which also has a commit that fails the Lint commit messages gate).

The two-corner pair variant and .sf-corners/.sf-corners--leaf recipe that were explored on this branch are not carried forward — cut after review (WebKit mask-composite bug with no viable fix, and judged too niche for the public API, respectively).

No further action needed here.

claude added 2 commits July 4, 2026 10:33
.sf-corner-scoop (#484): a mask-based concave corner that curves away
from the box, revealing whatever sits behind it. Named to mirror the
future `corner-shape: scoop` keyword for an easy @supports migration.

.sf-corners / .sf-overlap / .sf-overlap-host (#490): three independent
recipe macros — coordinated multi-corner radius patterns (leaf shapes),
an element intentionally overlapping the one before it, and the
receiving container that reserves clearance for the intrusion.

#489 (unified background overlay macro): no new class needed —
.sf-bg + .sf-scrim already compose into exactly the requested "media
background + overlay + stacked content, no manual z-index" recipe.
Documented the composition and added regression coverage instead of
duplicating it behind a new abstraction.

Along the way, found and fixed a real latent bug that blocked that
composition: --sf-bg-inset defaulted to a bare `0` instead of `0px`,
which made .sf-bg's `calc(100% - 2 * var(--sf-bg-inset))` sizing
invalid at computed-value time (percentage/number type mismatch),
silently collapsing .sf-bg to the media's intrinsic size whenever the
default inset was used — i.e. by default, for everyone.

.sf-overlap-host's padding-compensation default is resolved via a
var() fallback inside the rule itself (not a pre-baked :root alias),
so a local --sf-overlap-pull override is honored — the same class of
pitfall just fixed for section theming in #496.

Closes #484
Closes #489
Closes #490

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Sg35d8wNVerSUss6UXQMm1
docs/test-coverage-6-token-reference.html and reports/full-api-audit's
tokens-report.json are static artifacts not regenerated by npm run
build/docs — they need a manual patch when the public token surface
changes, per the precedent set in 1ec534f. Adds the 7 new corner-scoop/
corners/overlap tokens to both, sourced from real data already sitting
in this repo: docs/api-index.json for tier/role/category/declared, and
this same tokens-report.json's own existing rows for --sf-radius-2xl,
--sf-radius-l, and --sf-space-xl (the exact tokens these 7 alias),
since none of the 7 are color-scheme-dependent or otherwise need a
fresh browser read to get an accurate computed value.

reachable-ui.json is intentionally left untouched: these 7 tokens have
no configurator UI surface yet (no MacrosPanel control, no matching
domain-patterns.json substring), so adding them there would misreport
audit data that was never actually collected. That's a real, separate
gap worth its own follow-up, not a documentation-sync problem.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Sg35d8wNVerSUss6UXQMm1
@coderabbitai

coderabbitai Bot commented Jul 4, 2026

Copy link
Copy Markdown

Review Change Stack

Warning

Review limit reached

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

Next review available in: 28 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

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 reviews.

How do review 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 refer docs for additional details.

Review details
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 5bdaeeb4-c601-4505-a271-07b5744b0b85

📥 Commits

Reviewing files that changed from the base of the PR and between 078ea14 and b82ec6f.

📒 Files selected for processing (24)
  • CHANGELOG.md
  • badges/badge-optimal.json
  • badges/css-custom-data.json
  • configurator/src/data/api-index.generated.json
  • configurator/src/data/classes.generated.json
  • configurator/src/data/domain-patterns.json
  • configurator/src/data/token-registry.generated.json
  • core/macros.css
  • core/tokens.macros.css
  • docs/api-index.json
  • docs/api-index.md
  • docs/classes.md
  • docs/demo.html
  • docs/llm-guide.md
  • docs/macros.md
  • docs/registry.json
  • docs/test-coverage-6-token-reference.html
  • docs/token-index.json
  • docs/token-index.md
  • docs/tokens.md
  • reports/full-api-audit/results/tokens-report.json
  • tests/macros.spec.js
  • tests/token-api.snapshot.json
  • token-registry.json
📝 Walkthrough

Walkthrough

Adds new corner-scoop, corners, and overlap macros, updates --sf-bg-inset to 0px, refreshes generated token/class data and docs, and updates comment parsing and tests.

Changes

Corner, overlap, and bg-inset surface

Layer / File(s) Summary
Token defaults and macro vocabulary
core/tokens.layout.css, core/tokens.macros.css, badges/css-custom-data.json
Changes --sf-bg-inset to 0px and adds root token defaults and documentation entries for corner-scoop, corners, and overlap behavior.
Macro CSS implementation
core/macros.css
Implements .sf-corner-scoop, .sf-corners, .sf-overlap, and .sf-overlap-host utilities.
Generated indexes and registries
configurator/src/data/*.generated.json, docs/*.json, token-registry.json, docs/registry.json, docs/classes.md
Refreshes generated token/class registries, counts, and registry metadata with the new token and class entries.
Documentation and examples
docs/macros.md, docs/demo.html, docs/llm-guide.md, docs/token-index.md, docs/tokens.md, docs/api-index.md, CHANGELOG.md, badges/badge-optimal.json
Updates macro docs, demos, token/class indexes, changelog text, and badge metadata for the new surface.
Behavior and parser validation
tests/macros.spec.js, tests/parse-lib.test.js, tests/token-api.snapshot.json, scripts/check-macro-catalog.js, scripts/lib/api-index/extract.js, docs/test-coverage-6-token-reference.html
Adds macro behavior coverage, updates token snapshots, and changes comment parsing so directive comments are skipped in context resolution.
Audit report updates
reports/full-api-audit/results/tokens-report.json
Updates token audit totals and appends the new token rows.

Estimated code review effort: 4 (Complex) | ~60 minutes

Possibly related PRs

Suggested labels: codex

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Out of Scope Changes check ⚠️ Warning The parser/comment-classification changes in scripts/lib/api-index/extract.js and tests/parse-lib.test.js are unrelated to the macro/token objectives. Remove or split out the api-index parser/comment changes unless they are required for the macro/docs work, and keep this PR focused on the linked issues.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title is concise and accurately summarizes the new corner-scoop and corner/overlap recipe macro work.
Linked Issues check ✅ Passed The PR implements #484 and #490 and documents the #489 background-overlay composition with the expected supporting docs and tests.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch claude/macros-scoop-overlay-recipes-lxk7a9

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

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

Comment thread tests/macros.spec.js Fixed
@qodo-code-review

Copy link
Copy Markdown

PR Summary by Qodo

Add corner-scoop and corner/overlap recipe macros (plus .sf-bg inset fix)

✨ Enhancement 🐞 Bug fix 📝 Documentation 🧪 Tests ⚙️ Configuration changes 🕐 40+ Minutes

Grey Divider

AI Description

• Add .sf-corner-scoop concave corner macro using mask-image with four corner variants.
• Add .sf-corners leaf radius recipes and .sf-overlap/.sf-overlap-host overlap recipe macros.
• Fix .sf-bg default inset unit, then regenerate docs/registries and add regression tests.
Diagram

graph TD
  A["core/tokens.macros.css"] --> B["core/macros.css"] --> C["docs/macros.md"] --> D["docs/demo.html"]
  E["core/tokens.layout.css"] --> F[("token/registry outputs")]
  A --> F --> G["configurator generated data"]
  B --> H["tests/macros.spec.js"]
  F --> C
Loading
High-Level Assessment

The following are alternative approaches to this PR:

1. Concave corner via `clip-path` (polygon/path)
  • ➕ Doesn’t rely on mask-image, potentially avoids mask composition conflicts.
  • ➕ Can preserve borders/shadows on the clipped element in some cases (depending on approach).
  • ➖ Harder to parameterize cleanly with tokens (especially true curve geometry).
  • ➖ Browser support and authoring ergonomics vary; path() is still inconsistent across environments.
2. Concave corner via pseudo-element overlay (background-colored corner patch)
  • ➕ Keeps the main element’s paint intact (box-shadow/border unaffected).
  • ➕ Composes with other mask-based macros since it doesn’t use masking.
  • ➖ Requires knowing/duplicating the page/background behind the element (not always possible).
  • ➖ More DOM/CSS complexity; tricky with transparent/complex backgrounds.
3. Ship a dedicated unified “bg+scrim” macro instead of documenting composition
  • ➕ Single class could be easier to discover and standardize in consuming code.
  • ➕ Could encode a single canonical DOM structure.
  • ➖ Duplicates existing primitives (.sf-bg + .sf-scrim) and increases surface area.
  • ➖ Risks diverging behavior over time unless kept perfectly in sync with the primitives.

Recommendation: The PR’s approach is the best tradeoff for this design system: mask-image is the most direct way to express a true concave corner and the naming intentionally aligns with future corner-shape: scoop for an @supports migration. For the overlay recipe, documenting the already-correct .sf-bg + .sf-scrim composition avoids redundant abstractions and keeps the surface area minimal. The .sf-overlap-host fix (moving the defaulting logic into the rule via var(--sf-overlap-host-pad, var(--sf-overlap-pull))) is also the right pattern to avoid stale :root alias resolution.

Files changed (23) +1607 / -51

Enhancement (2) +99 / -0
macros.cssAdd corner-scoop, corners, and overlap recipe macros +73/-0

Add corner-scoop, corners, and overlap recipe macros

• Introduces '.sf-corner-scoop' using a radial-gradient mask (with '-webkit-mask-image' for Safari < 18) and physical-corner variants. Adds '.sf-corners' applying logical corner radius longhands with '--leaf' and '--leaf-flip' presets. Adds '.sf-overlap' negative-margin + raised z-index recipe and '.sf-overlap-host' isolation + padding compensation with a per-element 'var()' fallback.

core/macros.css

tokens.macros.cssDefine defaults for new macro knobs +26/-0

Define defaults for new macro knobs

• Adds default macro tokens for corner-scoop size/position, the four logical corners for '.sf-corners', and the overlap pull distance ('--sf-overlap-pull').

core/tokens.macros.css

Bug fix (1) +6 / -1
tokens.layout.cssFix --sf-bg-inset default to be a length (0px) +6/-1

Fix --sf-bg-inset default to be a length (0px)

• Changes '--sf-bg-inset' from '0' to '0px' to avoid 'calc()' percentage/number type mismatch that invalidated '.sf-bg' sizing at computed-value time.

core/tokens.layout.css

Tests (3) +259 / -4
test-coverage-6-token-reference.htmlUpdate frozen token reference snapshot list +1/-1

Update frozen token reference snapshot list

• Updates the embedded token list used by the full token reference coverage artifact to include new macro tokens and keep snapshots consistent.

docs/test-coverage-6-token-reference.html

tokens-report.jsonSync full API audit token report snapshot +94/-3

Sync full API audit token report snapshot

• Updates the audit snapshot totals and adds rows for the new macro tokens so report-based gates remain consistent with the generated token set.

reports/full-api-audit/results/tokens-report.json

macros.spec.jsAdd Playwright coverage for new macros and .sf-bg + .sf-scrim composition +164/-0

Add Playwright coverage for new macros and .sf-bg + .sf-scrim composition

• Adds tests for '.sf-corner-scoop' mask behavior and token overrides, '.sf-corners' logical radius patterns, and '.sf-overlap'/'.sf-overlap-host' negative-margin + padding/isolation behavior. Adds regression coverage ensuring '.sf-bg' auto-fills behind '.sf-scrim' with correct stacking and no manual z-index, plus a no-regression check for plain '.sf-scrim'.

tests/macros.spec.js

Documentation (10) +841 / -36
api-index.jsonUpdate API index counts and register new macro surface +533/-12

Update API index counts and register new macro surface

• Updates counts for tokens/classes and corrects '--sf-bg-inset' value to '0px'. Adds the new macro tokens to the API index dataset.

docs/api-index.json

api-index.mdRefresh human-readable API index tables and counts +27/-7

Refresh human-readable API index tables and counts

• Updates total counts and token/class tables to include the new macros and tokens, and reflects '--sf-bg-inset' default as '0px'.

docs/api-index.md

classes.mdRefresh class reference to include new macro classes +15/-2

Refresh class reference to include new macro classes

• Updates generated class lists and counts, adding the new macro classes and their variants to the reference.

docs/classes.md

demo.htmlAdd demos for corner-scoop, corners leaf, and overlap recipes +26/-0

Add demos for corner-scoop, corners leaf, and overlap recipes

• Adds demo sections exercising '.sf-corner-scoop' variants, '.sf-corners' leaf variants, and the '.sf-overlap' + '.sf-overlap-host' pairing.

docs/demo.html

llm-guide.mdDocument new public knobs for LLM-facing guide +14/-0

Document new public knobs for LLM-facing guide

• Adds knob entries for the new macros, including the optional '--sf-overlap-host-pad' override guidance (even though it’s no longer a defined token default).

docs/llm-guide.md

macros.mdDocument new macros and confirm .sf-bg + .sf-scrim composition recipe +121/-0

Document new macros and confirm .sf-bg + .sf-scrim composition recipe

• Adds dedicated sections for '.sf-corner-scoop', '.sf-corners', and '.sf-overlap'/'.sf-overlap-host', including limitations and token knobs. Documents that '.sf-bg' composes with '.sf-scrim' to satisfy the “background media + overlay + stacked content” recipe without a new macro.

docs/macros.md

registry.jsonUpdate registry lists/counts for new macro tokens/classes +22/-2

Update registry lists/counts for new macro tokens/classes

• Adds the new macro tokens and classes to the public registry lists and updates aggregate counts.

docs/registry.json

token-index.jsonRegenerate token index dataset with new tokens and bg-inset fix +61/-5

Regenerate token index dataset with new tokens and bg-inset fix

• Updates token counts/roles and adds new macro token entries; also corrects '--sf-bg-inset' default value to '0px'.

docs/token-index.json

token-index.mdRefresh token index markdown with new macro tokens +12/-5

Refresh token index markdown with new macro tokens

• Updates totals and tables to include the newly added macro knobs, and reflects the '0px' default for '--sf-bg-inset'.

docs/token-index.md

tokens.mdRefresh generated token reference to include new macro knobs +10/-3

Refresh generated token reference to include new macro knobs

• Updates token counts and lists, adding the new macro tokens and updating '--sf-bg-inset' to '0px'.

docs/tokens.md

Other (7) +402 / -10
badge-optimal.jsonUpdate optimal bundle gzip size badge +1/-1

Update optimal bundle gzip size badge

• Bumps the reported gzip size in the "optimal" badge to reflect the new macro/token additions.

badges/badge-optimal.json

css-custom-data.jsonAdd new macro token entries and fix --sf-bg-inset default text +36/-1

Add new macro token entries and fix --sf-bg-inset default text

• Updates the custom data description for '--sf-bg-inset' to reflect the corrected '0px' default. Adds entries for new macro knobs ('--sf-corner-scoop-*', '--sf-corners-*', '--sf-overlap-pull').

badges/css-custom-data.json

api-index.generated.jsonRegenerate configurator API index (token counts + new macro knobs) +166/-5

Regenerate configurator API index (token counts + new macro knobs)

• Updates generated API index metadata and token values (including '--sf-bg-inset: 0px'). Adds the new macro tokens to the configurator’s token dataset.

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

classes.generated.jsonRegenerate configurator class index with new macro classes +130/-0

Regenerate configurator class index with new macro classes

• Adds generated entries for '.sf-corner-scoop' (and its four variants), '.sf-corners' (and '--leaf' variants), and '.sf-overlap'/'.sf-overlap-host' (and directional variants).

configurator/src/data/classes.generated.json

token-registry.generated.jsonRegenerate configurator token registry IDs for new macro tokens +34/-1

Regenerate configurator token registry IDs for new macro tokens

• Allocates new token IDs for the added macro knobs and marks '--sf-overlap-host-pad' as removed from the registry (no longer a defined token default).

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

check-macro-catalog.jsAllow docs to reference .sf-bg without requiring it in macros CSS +1/-1

Allow docs to reference .sf-bg without requiring it in macros CSS

• Adds '.sf-bg' to the documentation skip-list so macro catalog validation tolerates the new '.sf-bg' + '.sf-scrim' composition note in 'docs/macros.md'.

scripts/check-macro-catalog.js

token-registry.jsonRegenerate root token registry IDs for new macro tokens +34/-1

Regenerate root token registry IDs for new macro tokens

• Allocates new IDs for added macro knobs and marks '--sf-overlap-host-pad' as removed from the registry (shift from ':root' aliasing to per-rule fallback semantics).

token-registry.json

@coderabbitai coderabbitai Bot added the codex label Jul 4, 2026
Add corner-scoop/corners/overlap patterns to the configurator's
domain-patterns.json — its own curation.test.js fails otherwise,
since --sf-corner-scoop-at (a knob-role literal) had no matching
domain and fell through to the disallowed Misc bucket.

Also drop an unused destructured variable flagged by review.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Sg35d8wNVerSUss6UXQMm1
@qodo-code-review

qodo-code-review Bot commented Jul 4, 2026

Copy link
Copy Markdown

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 📜 Skill insights (0)

Context used
✅ Compliance rules (platform): 12 rules

Grey Divider


Action required

1. --sf-overlap-host-pad documented but removed ✓ Resolved 📘 Rule violation ≡ Correctness
Description
docs/llm-guide.md documents --sf-overlap-host-pad as a supported override knob, and it is
referenced by the .sf-overlap-host macro, but token-registry.json marks the token as removed and
it is not declared in the token CSS sources. This creates an inconsistent public API surface that
can mislead users and break consumers/tooling that treat the registry as authoritative, violating
the requirement that docs not reference deleted/renamed tokens.
Code

docs/llm-guide.md[R870-872]

+/* Overlap recipe (.sf-overlap / .sf-overlap-host) */
+--sf-overlap-pull:     var(--sf-space-xl)
+--sf-overlap-host-pad: var(--sf-overlap-pull)  /* defaults to match the pull */
Relevance

⭐⭐⭐ High

Team enforces llm-guide/token-registry sync (PR #383); docs referencing removed tokens is typically
fixed (PR #270).

PR-#383
PR-#270

ⓘ Recommendations generated based on similar findings in past PRs

Evidence
The project checklist requires that documentation not reference tokens that are not part of the live
token set; however, docs/llm-guide.md includes --sf-overlap-host-pad as an override while
token-registry.json explicitly tombstones it with removed: true, indicating it is not a
supported/live token. In addition, the macro/CSS reads the value via `var(--sf-overlap-host-pad,
...)`, reinforcing that the token is treated as supported in implementation even though the registry
declares it removed, demonstrating the mismatch across docs, registry, and CSS sources.

Rule 1353210: Docs must not reference deleted or renamed design tokens
docs/llm-guide.md[860-872]
token-registry.json[2867-2875]
core/macros.css[424-435]
docs/llm-guide.md[860-873]
docs/macros.md[650-679]

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-overlap-host-pad` is being presented and used as a supported token/override hook (documented in `docs/llm-guide.md` and referenced in the overlap host macro/CSS), but `token-registry.json` marks it as `removed: true` and it is not declared in the token source CSS. Align the docs, registry, and implementation so the public token surface is consistent and documentation does not reference deleted/renamed tokens.

## Issue Context
This inconsistency can confuse users and downstream tooling that treats `token-registry.json` as the authoritative set of supported tokens. Decide the intended status of `--sf-overlap-host-pad`: if it should remain a supported override hook, it must not be marked removed (and should be part of the live token set); if it is meant to be retired, remove or update the CSS/macro and documentation references accordingly.

## Fix Focus Areas
- docs/llm-guide.md[870-872]
- token-registry.json[2867-2875]
- docs/macros.md[673-679]
- core/macros.css[428-435]

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



Remediation recommended

2. Stylelint comment leaks ✓ Resolved 🐞 Bug ⚙ Maintainability
Description
A stylelint-disable-next-line comment near -webkit-mask-image is being used as the generated
description for .sf-corner-scoop--* variant classes, polluting API docs and custom-data outputs.
This degrades the public API index and any tooling relying on these descriptions.
Code

docs/api-index.md[R888-892]

+| `.sf-corner-scoop` | PUBLIC | macro | — | Concave corner — a corner that curves AWAY from the box (revealing whatever sits behind it), via a radial-gradient mask. Physical corner names (mask geometry has no logical form, same rationale as .sf-overflow-fade's physical directions). Cuts the element's full paint at that… |
+| `.sf-corner-scoop--bottom-left` | PUBLIC | macro | — | stylelint-disable-next-line property-no-vendor-prefix -- required for Safari < 18 |
+| `.sf-corner-scoop--bottom-right` | PUBLIC | macro | — | stylelint-disable-next-line property-no-vendor-prefix -- required for Safari < 18 |
+| `.sf-corner-scoop--top-left` | PUBLIC | macro | — | stylelint-disable-next-line property-no-vendor-prefix -- required for Safari < 18 |
+| `.sf-corner-scoop--top-right` | PUBLIC | macro | — | stylelint-disable-next-line property-no-vendor-prefix -- required for Safari < 18 |
Relevance

⭐⭐⭐ High

PR #396 accepted fixing comment→description capture in api-index generator; same leak pattern likely
fixed again.

PR-#396

ⓘ Recommendations generated based on similar findings in past PRs

Evidence
The generated class catalog and rendered API index show the variant descriptions as the stylelint
directive; the only nearby comment in the source is the stylelint suppression comment above
-webkit-mask-image.

configurator/src/data/classes.generated.json[837-885]
docs/api-index.md[882-895]
core/macros.css[371-383]
PR-#396

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

### Issue description
The `.sf-corner-scoop--*` variant classes have incorrect descriptions in generated artifacts (they show a stylelint directive). This happens because the nearest preceding comment in `core/macros.css` is the stylelint suppression comment, and the doc generator associates it with subsequent selectors.

### Issue Context
This is the same class of failure as prior comment/description association issues: non-semantic comments end up as public API descriptions.

### Fix Focus Areas
- core/macros.css[371-383]
- configurator/src/data/classes.generated.json[847-885]
- docs/api-index.md[888-892]

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


3. Broken scoop doc example ✓ Resolved 🐞 Bug ⚙ Maintainability
Description
The .sf-corner-scoop docs example omits the required base class .sf-corner-scoop, so copying it
applies only the variant custom property and never sets mask-image (no scoop effect). This will
mislead users into thinking the macro is not working.
Code

docs/macros.md[R591-594]

+```html
+<div class="sf-card sf-corner-scoop--bottom-right">
+  Panel with a corner that curves away
+</div>
Relevance

⭐⭐⭐ High

Docs accuracy fixes are routinely accepted; macro/docs updates merged frequently (e.g., PR #235, PR
#415).

PR-#235
PR-#415

ⓘ Recommendations generated based on similar findings in past PRs

Evidence
The docs snippet is missing the base macro class, while the implementation places the mask on
.sf-corner-scoop and variants only set the position variable.

docs/macros.md[584-595]
core/macros.css[364-383]

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

### Issue description
`docs/macros.md` shows a `.sf-corner-scoop` example that only includes the variant class, but the actual masking is defined on `.sf-corner-scoop`. The snippet should include both classes so it works when copy/pasted.

### Issue Context
Variants like `.sf-corner-scoop--bottom-right` only set `--sf-corner-scoop-at`; they do not define `mask-image`.

### Fix Focus Areas
- docs/macros.md[591-594]
- core/macros.css[371-383]

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


Grey Divider

Qodo Logo

Comment thread docs/llm-guide.md Outdated
Comment thread docs/macros.md
Comment thread docs/api-index.md Outdated

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 3

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)
reports/full-api-audit/results/tokens-report.json (1)

382-393: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Regenerate the token audit snapshot for --sf-bg-inset. reports/full-api-audit/results/tokens-report.json still shows declared: "0" / computed: "0", but core/tokens.layout.css now declares --sf-bg-inset: 0px;, so this report is stale and should be regenerated.

🤖 Prompt for 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.

In `@reports/full-api-audit/results/tokens-report.json` around lines 382 - 393,
The token audit snapshot for --sf-bg-inset is stale in the tokens report and
still reflects the old zero value. Regenerate the audit output from the source
tokens so reports/full-api-audit/results/tokens-report.json matches
core/tokens.layout.css, with the token’s declared and computed values updated
from 0 to 0px and any related snapshot fields refreshed accordingly.
🧹 Nitpick comments (2)
tests/macros.spec.js (2)

432-438: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Test doesn't verify "resolved cut radius" as claimed.

The test name says it verifies the "resolved cut radius" changes, but the assertion only checks that the raw --sf-corner-scoop-size custom property equals the inline value that was just set ('40px') — a tautology, since custom properties always reflect literally whatever inline style set them. It never verifies that the mask-image's radial-gradient(...) actually resolves/uses that value (e.g., by asserting the computed maskImage string contains 40px, or comparing visual/geometry effects at different sizes).

💡 Suggested strengthening
   test('--sf-corner-scoop-size override changes the resolved cut radius', async ({ page }) => {
     await setup(page, `<div id="t" class="sf-corner-scoop" style="width:100px;height:100px; --sf-corner-scoop-size: 40px"></div>`);
-    const size = await page.locator('`#t`').evaluate(el =>
-      getComputedStyle(el).getPropertyValue('--sf-corner-scoop-size').trim()
-    );
-    expect(size).toBe('40px');
+    const mask = await page.locator('`#t`').evaluate(el => getComputedStyle(el).maskImage);
+    expect(mask).toContain('40px');
   });
🤖 Prompt for 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.

In `@tests/macros.spec.js` around lines 432 - 438, The test in macros.spec.js is
only asserting the inline custom property value, not the resolved cut radius
used by the mask. Update the test in the existing `--sf-corner-scoop-size
override changes the resolved cut radius` case to validate the computed
`mask-image` or other geometry derived from `sf-corner-scoop` actually reflects
the overridden size, using the same `setup`, `page.locator('`#t`')`, and
`getComputedStyle` flow. Make the assertion depend on the resolved
`radial-gradient(...)` output or a measurable visual effect so the test proves
the override is consumed by the component.

506-529: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add a regression test for the host padding fallback. The current .sf-overlap-host test only covers the default pull value; add a case with a local --sf-overlap-pull override so the var(--sf-overlap-host-pad, var(--sf-overlap-pull)) fallback path is exercised too.

🤖 Prompt for 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.

In `@tests/macros.spec.js` around lines 506 - 529, The existing .sf-overlap-host
test only verifies the default padding behavior, so add a regression case that
sets a local --sf-overlap-pull override and asserts the host still gets matching
block-start padding. Update the test near the .sf-overlap-host block in
macros.spec.js to exercise the var(--sf-overlap-host-pad,
var(--sf-overlap-pull)) fallback path, reusing setup and getComputedStyle on the
sf-overlap-host element.
🤖 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 `@configurator/src/data/api-index.generated.json`:
- Around line 11194-11216: The generated api-index entry for --sf-overlap-pull
has a truncated description that ends mid-sentence, so regenerate the
corresponding record in api-index.generated.json to restore the full
public-facing text. Update the description field for the --sf-overlap-pull token
so it includes the complete sentence, keeping the existing metadata (such as
name, aliasOf, and group) unchanged.

In `@configurator/src/data/classes.generated.json`:
- Around line 838-886: The class descriptions for
sf-corner-scoop--bottom-left/right/top-left/top-right are being filled from a
lint suppression comment instead of the real variant text. Update the
description extraction in extract.js to ignore stylelint-disable-next-line
property-no-vendor-prefix comments when building the API index, so these macro
entries keep their intended purpose descriptions.

In `@docs/llm-guide.md`:
- Around line 859-872: The `--sf-bg-inset` docs in `docs/llm-guide.md` are still
out of sync with the token default update and should match the `0px` value used
by `core/tokens.layout.css` and the generated indexes. Update the
`--sf-bg-inset` entry in the relevant documentation section so it reflects the
current default exactly, and keep the surrounding token examples consistent with
the same formatting used by the other recipe entries.

---

Outside diff comments:
In `@reports/full-api-audit/results/tokens-report.json`:
- Around line 382-393: The token audit snapshot for --sf-bg-inset is stale in
the tokens report and still reflects the old zero value. Regenerate the audit
output from the source tokens so
reports/full-api-audit/results/tokens-report.json matches
core/tokens.layout.css, with the token’s declared and computed values updated
from 0 to 0px and any related snapshot fields refreshed accordingly.

---

Nitpick comments:
In `@tests/macros.spec.js`:
- Around line 432-438: The test in macros.spec.js is only asserting the inline
custom property value, not the resolved cut radius used by the mask. Update the
test in the existing `--sf-corner-scoop-size override changes the resolved cut
radius` case to validate the computed `mask-image` or other geometry derived
from `sf-corner-scoop` actually reflects the overridden size, using the same
`setup`, `page.locator('`#t`')`, and `getComputedStyle` flow. Make the assertion
depend on the resolved `radial-gradient(...)` output or a measurable visual
effect so the test proves the override is consumed by the component.
- Around line 506-529: The existing .sf-overlap-host test only verifies the
default padding behavior, so add a regression case that sets a local
--sf-overlap-pull override and asserts the host still gets matching block-start
padding. Update the test near the .sf-overlap-host block in macros.spec.js to
exercise the var(--sf-overlap-host-pad, var(--sf-overlap-pull)) fallback path,
reusing setup and getComputedStyle on the sf-overlap-host element.
🪄 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: e41848a5-bdc1-49f8-ba5a-53a45a7ffe88

📥 Commits

Reviewing files that changed from the base of the PR and between 42df157 and d1e5bcc.

📒 Files selected for processing (23)
  • badges/badge-optimal.json
  • badges/css-custom-data.json
  • configurator/src/data/api-index.generated.json
  • configurator/src/data/classes.generated.json
  • configurator/src/data/token-registry.generated.json
  • core/macros.css
  • core/tokens.layout.css
  • core/tokens.macros.css
  • docs/api-index.json
  • docs/api-index.md
  • docs/classes.md
  • docs/demo.html
  • docs/llm-guide.md
  • docs/macros.md
  • docs/registry.json
  • docs/test-coverage-6-token-reference.html
  • docs/token-index.json
  • docs/token-index.md
  • docs/tokens.md
  • reports/full-api-audit/results/tokens-report.json
  • scripts/check-macro-catalog.js
  • tests/macros.spec.js
  • token-registry.json

Comment on lines +11194 to +11216
{
"name": "--sf-overlap-pull",
"tier": "PUBLIC",
"role": "consumption",
"namespace": "overlap",
"category": "Macro tokens",
"group": "Overlap recipe",
"description": "how far .sf-overlap pulls into the adjacent element. .sf-overlap-host's padding compensation defaults to this same value via a var() fallback in the rule itself (not aliased here — see core/macros.css), so one override on the host tunes both unless --sf-overlap-host-pad is set…",
"note": "",
"value": "var(--sf-space-xl)",
"aliasOf": "--sf-space-xl",
"registered": false,
"syntax": null,
"fallbackOnly": false,
"optional": false,
"layer": "slashed.tokens",
"bundles": [
"full",
"optimal",
"optimal-components",
"optimal-utilities"
]
},

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Check the source comment in core/macros.css for --sf-overlap-pull
rg -n -B2 -A2 'sf-overlap-pull' core/macros.css

Repository: codeslash-dev/SLASHED

Length of output: 972


🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "=== overlap entry in generated index ==="
sed -n '11194,11216p' configurator/src/data/api-index.generated.json

echo
echo "=== nearby source comment in core/macros.css ==="
sed -n '424,436p' core/macros.css

echo
echo "=== search for other generated descriptions ending with ellipsis ==="
python3 - <<'PY'
import json, re
from pathlib import Path

p = Path('configurator/src/data/api-index.generated.json')
data = json.loads(p.read_text())
hits = []
for item in data:
    desc = item.get('description')
    if isinstance(desc, str) and desc.endswith('…'):
        hits.append((item.get('name'), desc))
print("count", len(hits))
for name, desc in hits[:20]:
    print(name, "=>", desc)
PY

Repository: codeslash-dev/SLASHED

Length of output: 1927


🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "=== source for overlap-pull docs in repo ==="
rg -n -B2 -A3 --fixed-strings '--sf-overlap-pull' core configurator/src/data

Repository: codeslash-dev/SLASHED

Length of output: 624


configurator/src/data/api-index.generated.json:11194-11216 — Truncated description for --sf-overlap-pull. The generated text ends mid-sentence; regenerate this entry so the public-facing tooltip/docs show the full sentence.

🤖 Prompt for 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.

In `@configurator/src/data/api-index.generated.json` around lines 11194 - 11216,
The generated api-index entry for --sf-overlap-pull has a truncated description
that ends mid-sentence, so regenerate the corresponding record in
api-index.generated.json to restore the full public-facing text. Update the
description field for the --sf-overlap-pull token so it includes the complete
sentence, keeping the existing metadata (such as name, aliasOf, and group)
unchanged.

Comment thread configurator/src/data/classes.generated.json Outdated
Comment thread docs/llm-guide.md Outdated
Comment on lines +859 to +872

/* Concave corner (.sf-corner-scoop) */
--sf-corner-scoop-size: var(--sf-radius-2xl)
--sf-corner-scoop-at: 100% 0

/* Border-radius recipe (.sf-corners) — 4 logical corners */
--sf-corners-start-start: var(--sf-radius-l)
--sf-corners-start-end: var(--sf-radius-l)
--sf-corners-end-end: var(--sf-radius-l)
--sf-corners-end-start: var(--sf-radius-l)

/* Overlap recipe (.sf-overlap / .sf-overlap-host) */
--sf-overlap-pull: var(--sf-space-xl)
--sf-overlap-host-pad: var(--sf-overlap-pull) /* defaults to match the pull */

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Sync the bg-inset entry with the token fix.

The earlier --sf-bg-inset documentation in this file still says 0, which conflicts with the 0px default now used in core/tokens.layout.css and the generated indexes.

As per coding guidelines, docs/llm-guide.md must stay aligned with token/default changes when core CSS or token-registry values change.

🤖 Prompt for 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.

In `@docs/llm-guide.md` around lines 859 - 872, The `--sf-bg-inset` docs in
`docs/llm-guide.md` are still out of sync with the token default update and
should match the `0px` value used by `core/tokens.layout.css` and the generated
indexes. Update the `--sf-bg-inset` entry in the relevant documentation section
so it reflects the current default exactly, and keep the surrounding token
examples consistent with the same formatting used by the other recipe entries.

Source: Coding guidelines

claude and others added 13 commits July 4, 2026 11:45
The corner-scoop/corners/overlap macros add 7 new PUBLIC tokens that
weren't reflected in the locked token-api snapshot, failing the
Regression tests CI job. Updates the snapshot and adds the matching
CHANGELOG entry per the test's own documented update process.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Sg35d8wNVerSUss6UXQMm1
.sf-corner-scoop, .sf-corners--leaf, and .sf-overlap/-host previously
only appeared in isolated per-variant swatches. Adds a realistic
composed example (notched banner + leaf badge + overlapping avatar)
so the demo shows how the recipes combine in practice.

Also fixes the .sf-corner-scoop docs/macros.md example, which was
missing the required base class alongside the variant modifier.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Sg35d8wNVerSUss6UXQMm1
…larify --sf-overlap-host-pad

extract.js's nearest-preceding-comment heuristic picked up
stylelint-disable-next-line directive comments as descriptions for
whatever selector followed them with no comment of its own — visible
on .sf-corner-scoop--* (leaked "stylelint-disable-next-line
property-no-vendor-prefix..." as their public description). Classifies
directive comments (stylelint-/eslint-disable/enable) and skips them
in contextAt the same way header comments already are, so affected
selectors fall back to their governing note instead, matching how
undecorated variants elsewhere in the codebase already behave. Adds a
regression test in tests/parse-lib.test.js.

Also reworded --sf-overlap-host-pad in docs/llm-guide.md and
docs/macros.md: it was listed as if it were a declared token, but it's
only consumed via a var() fallback in core/macros.css and is tombstoned
in token-registry.json — now described as the override hook it
actually is.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Sg35d8wNVerSUss6UXQMm1
demo.html's <link> was swapped to the jsDelivr @dist CDN link, which
only reflects the last release — the new corner-scoop/corners/overlap
macros from this PR don't exist there yet, so they silently didn't
render. It also broke the Playwright demo suite (73/93 failures in
demo-visual.spec.js): the sandboxed test environment can't reach the
external CDN at all, so the page loads with no stylesheet.

The file's own header comment already documents why: the relative
local path is required for Playwright/file://; the CDN link is only
for someone manually sharing a standalone copy externally, not the
committed default.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Sg35d8wNVerSUss6UXQMm1
…verlay-recipes-lxk7a9

# Conflicts:
#	badges/badge-optimal.json
#	configurator/src/data/token-registry.generated.json
#	docs/api-index.json
#	docs/api-index.md
#	docs/classes.md
#	docs/registry.json
#	token-registry.json
.sf-corner-scoop previously only supported one cut per element - a
second single-corner variant would silently overwrite the first
rather than adding a second cut, since the base class's mask-image
only encodes one gradient. Adds --top/--bottom/--left/--right, which
combine two radial-gradient mask layers via mask-composite: intersect
so both cuts survive together (the default "add" compositing is what
caused the original one-cut limitation - the second, mostly-opaque
layer paints back over the first hole).

Sized so the cut radius is half the element's width/height, --bottom
produces a "U"/bowl opening where the two cuts meet in the middle.

Adds a pixel-level regression test (screenshot decoded via canvas in
the browser context, since elementFromPoint can't see mask effects -
masking is paint-only, not hit-testing) confirming both corners are
independently transparent, not just one.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Sg35d8wNVerSUss6UXQMm1
WebKit has a known bug (webkit.org/b/240324) where mask-composite:
intersect against the implicit nothing below the bottommost mask
layer collapses that layer to fully transparent, instead of leaving
it unchanged. The .sf-corner-scoop--top/-bottom/-left/-right pair
variants applied intersect to both of their two layers, so the bottom
layer's cut silently disappeared in WebKit.

Uses intersect only for the top layer (combining with the real layer
below it) and add for the bottom layer (combining with nothing, where
add is the identity operation in every engine — verified unaffected
in Chromium, where the previous intersect/intersect pairing already
worked correctly).

Network access to install Playwright's WebKit binary is blocked in
this environment, so this fix is verified against the documented
WebKit bug report and unchanged Chromium behavior, not a local WebKit
run - CI's webkit project is the first real confirmation.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Sg35d8wNVerSUss6UXQMm1
The unprefixed mask-composite: intersect, add fix (previous commit)
did not resolve the WebKit CI failure - .sf-corner-scoop--bottom's
bottom-left corner still rendered uncut in Playwright's WebKit.

WebKit's actual masking engine evaluates the legacy -webkit-mask-image
/ -webkit-mask-composite pair, not the unprefixed properties, despite
nominal unprefixed mask-composite support. The legacy compositing
keyword set is different (source-over/source-in/source-out/xor, not
add/subtract/intersect/exclude), and per the documented workaround for
this exact class of bug, the bottommost layer needs 'xor' rather than
'source-over' (the legacy equivalent of 'add') - source-over against
nothing still collapses to transparent in WebKit's legacy engine,
unlike the unprefixed spec model where 'add' is a safe identity.

Ships both prefixed forms so spec-compliant engines (Chromium,
Firefox, and correctly-behaving WebKit) use the standard properties,
while WebKit's actual legacy evaluation path gets the compositing
values it needs. Still unverified against a real WebKit run locally
(network access to install Playwright's WebKit binary is blocked in
this environment) - CI is the verification.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Sg35d8wNVerSUss6UXQMm1
.sf-corners was the weakest of the three macros added by this PR: it's
just 4 border-radius longhands with no real cross-browser or
composability pitfalls to encapsulate, unlike .sf-corner-scoop
(vendor-prefixing, mask composition) and .sf-overlap/.sf-overlap-host
(the pull/clearance sync bug this session already found and fixed
twice elsewhere). The "leaf" asymmetric look is a styling opinion, not
a pattern worth a shipped default.

Removes the class, its 4 --sf-corners-* tokens (tombstoned in
token-registry.json per the append-only convention, not deleted),
tests, docs, demo entries, and the domain-patterns.json curation
pattern. Manually syncs the two frozen audit snapshot artifacts
(docs/test-coverage-6-token-reference.html,
reports/full-api-audit/results/tokens-report.json) per the established
precedent for public-token-surface changes.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Sg35d8wNVerSUss6UXQMm1
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants