Add directional variants to .sf-overflow-fade macro

[jackgranatowski]

Extends the .sf-overflow-fade macro with six new directional modifier classes to support fading on specific edges or axes, rather than only the default right edge.

Changes

• New macro variants in core/macros.css:

  • .sf-overflow-fade--right — explicit alias for default (right/inline-end edge)
  • .sf-overflow-fade--left — left/inline-start edge
  • .sf-overflow-fade--top — top/block-start edge
  • .sf-overflow-fade--bottom — bottom/block-end edge
  • .sf-overflow-fade--block — both top and bottom edges simultaneously
  • .sf-overflow-fade--inline — both left and right edges simultaneously

• Refactored mask variable naming: Changed --sf-scroll-shadow-size to --sf-mask-scrim-start / --sf-mask-scrim-end for clarity and to support multi-directional fades

• Updated documentation (docs/macros.md):

  • Clarified that base class fades the right edge
  • Added reference table showing all variants and their behavior
  • Expanded examples to demonstrate single-edge, dual-axis, and use-case scenarios

• API registry updates: Added all six new classes to docs/api-index.json, docs/classes.md, docs/registry.json, and configurator/src/data/classes.generated.json

• Test coverage: Added parametrized tests for all six variants to verify mask gradient and overflow:hidden are applied correctly

• Metrics: Total class count increased from 233 to 239; macro classes from 36 to 42; PUBLIC tier from 868 to 874

Implementation notes

All variants use the same mask-image approach (linear-gradient with alpha masking) and respect the element's background. The refactored variable names (--sf-mask-scrim-start / --sf-mask-scrim-end) make the intent clearer and allow independent control of fade depth on each edge.

https://claude.ai/code/session_01W3cC2BQwGM6WMyHtycK4yn

[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 40 minutes. 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: da262ed8-7ed4-4a40-bd0a-68661d6d2298

📥 Commits

Reviewing files that changed from the base of the PR and between 3ab425f and bac62c7.

📒 Files selected for processing (12)

• badges/badge-optimal.json
• configurator/src/data/classes.generated.json
• core/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/token-annotations.json
• tests/macros.spec.js

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/directional-overflow-fade-yreavx

---

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 directional variants to .sf-overflow-fade macro
✨ Enhancement 📝 Documentation 🧪 Tests ⚙️ Configuration changes 🕐 20-40 Minutes

Description

• Add directional .sf-overflow-fade--* variants for edge- and axis-specific fades.
• Rename fade sizing knobs to --sf-mask-scrim-start/end to support multi-edge masks.
• Regenerate API/registry docs and add tests asserting mask gradients + overflow: hidden.

Diagram

graph TD
  A["UI component"] --> B[".sf-overflow-fade--*"] --> C["core/macros.css"] --> D["tests/macros.spec.js"]
  C --> E["docs/api-index & registry"]
  C --> F["configurator classes JSON"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Factor gradients via a shared CSS custom property

• ➕ Reduces duplication by defining gradients once per variant (e.g., --sf-overflow-fade-mask) and assigning mask-image / -webkit-mask-image in a shared rule.
• ➕ Makes it easier to add future variants (e.g., diagonal) without repeating vendor-prefixed blocks.
• ➖ Still requires each variant to set a full gradient value; debugging can be slightly less direct than fully inlined gradients.
• ➖ Some teams prefer explicit duplication in macros.css for readability and greppability.

2. Use multi-layer masks for axis variants (two gradients composited)

• ➕ Inline/block variants could be expressed as a composition of the corresponding single-edge masks (potentially clearer intent).
• ➕ May simplify tuning per-edge fade independently if later extended.
• ➖ Mask compositing has more cross-browser sharp edges; increases risk versus the current single-gradient approach.
• ➖ Harder to validate visually and may require additional browser-targeted handling.

Recommendation: The PR’s approach (standalone directional classes with explicit gradients) is a good tradeoff for clarity and browser robustness. If maintainability becomes a concern, consider the shared-custom-property refactor to remove repetition while keeping the same runtime behavior and Safari-prefixed support.

Files changed (11) +400 / -24

Enhancement (1) +108 / -2

macros.cssAdd directional '.sf-overflow-fade--*' macros and rename mask knob +108/-2

Add directional '.sf-overflow-fade--*' macros and rename mask knob

• Introduces six standalone directional overflow-fade classes, each setting 'overflow: hidden' and a direction-specific 'mask-image'/'-webkit-mask-image' linear gradient. Updates the base '.sf-overflow-fade' to use '--sf-mask-scrim-end' instead of '--sf-scroll-shadow-size' for the fade depth.

core/macros.css

Tests (1) +19 / -0

macros.spec.jsAdd parametrized tests for all '.sf-overflow-fade--*' variants +19/-0

Add parametrized tests for all '.sf-overflow-fade--*' variants

• Adds a looped test that asserts each new directional class sets a 'linear-gradient' mask image and forces 'overflow: hidden'.

tests/macros.spec.js

Documentation (6) +205 / -20

api-index.jsonExpose new overflow-fade variants in API index and counts +156/-6

Expose new overflow-fade variants in API index and counts

• Updates summary counts (elements/classes/macros/PUBLIC tier) and adds entries for all six new directional macro classes with 'isVariant' and 'baseClass' metadata.

docs/api-index.json

api-index.mdRefresh API index markdown counts and macro class list +10/-4

Refresh API index markdown counts and macro class list

• Updates element/class/tier totals and appends the new '.sf-overflow-fade--*' rows under Macro classes to match the generated index.

docs/api-index.md

classes.mdUpdate generated class reference to include new macro classes +8/-2

Update generated class reference to include new macro classes

• Adjusts '.sf-*' and macro class counts and adds the six new overflow-fade variant classes to the macro list.

docs/classes.md

llm-guide.mdClarify that '--sf-scroll-shadow-size' no longer applies to overflow-fade +1/-1

Clarify that '--sf-scroll-shadow-size' no longer applies to overflow-fade

• Updates the knob list comment so '--sf-scroll-shadow-size' is associated with '.sf-scroll-shadow' only, reflecting the overflow-fade variable rename.

docs/llm-guide.md

macros.mdDocument overflow-fade directional variants and new mask knob names +24/-7

Document overflow-fade directional variants and new mask knob names

• Rewrites the '.sf-overflow-fade' docs to describe the new '--sf-mask-scrim-start/end' variables, clarifies default right-edge behavior, and adds a table + examples for single-edge and axis fades.

docs/macros.md

token-annotations.jsonAdd annotations for overflow-fade directional variants +6/-0

Add annotations for overflow-fade directional variants

• Adds human-readable descriptions for each new '.sf-overflow-fade--*' variant to the annotations map.

docs/token-annotations.json

Other (3) +68 / -2

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

Update optimal bundle gzip size badge

• Bumps the reported gzip size from 17.5 kB to 17.6 kB to reflect the expanded class set.

badges/badge-optimal.json

classes.generated.jsonRegister new overflow-fade variants in configurator class data +60/-0

Register new overflow-fade variants in configurator class data

• Adds six new macro class entries for '.sf-overflow-fade--{right,left,top,bottom,block,inline}' including descriptions and layer metadata.

configurator/src/data/classes.generated.json

registry.jsonAdd new macro classes to registry and update counts +7/-1

Add new macro classes to registry and update counts

• Increases '.sf' class counts and appends the six new overflow-fade variants to the registry class list.

docs/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. RTL fade edge mismatch ✓ Resolved 🐞 Bug ≡ Correctness

Description

The new .sf-overflow-fade and directional variants use physical gradient directions (to right)
but are documented as fading logical inline-start/inline-end edges, so RTL documents will fade the
wrong logical side. This creates a correctness gap for RTL layouts (the repo already uses
:dir(rtl) in other CSS to mirror direction-sensitive UI).

Code

core/macros.css[R126-137]

    -webkit-mask-image: linear-gradient(
      to right,
      black 0,
-      black calc(100% - var(--sf-scroll-shadow-size)),
+      black calc(100% - var(--sf-mask-scrim-end)),
      transparent 100%
    );
    mask-image: linear-gradient(
      to right,
      black 0,
-      black calc(100% - var(--sf-scroll-shadow-size)),
+      black calc(100% - var(--sf-mask-scrim-end)),
+      transparent 100%
+    );

Relevance

⭐⭐⭐ High

Team prioritizes RTL correctness; PR #321 logical-property audit and PR #341 added RTL-specific CSS
fallbacks.

PR-#321
PR-#341
PR-#155

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The CSS hard-codes linear-gradient(to right, ...) for .sf-overflow-fade, while the docs
explicitly describe the base class and variants in logical inline terms; without :dir(rtl)
mirroring, RTL layouts won’t match that description. The repo demonstrates an existing practice of
adding :dir(rtl) overrides for direction-sensitive styling.

core/macros.css[123-171]
docs/macros.md[191-208]
optional/forms.css[118-127]
core/layout.css[338-345]

Agent prompt

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

## Issue description
`core/macros.css` implements `.sf-overflow-fade` (and related variants) with physical gradient directions (e.g., `linear-gradient(to right, ...)`), but the docs describe the behavior in logical terms (inline-start/inline-end). In RTL documents, inline-end is the physical left edge, so the current implementation won’t match the documented intent.

## Issue Context
The codebase already uses `:dir(rtl)` to mirror direction-sensitive visuals (e.g., select chevron positioning), so direction-aware handling is an established pattern.

## Fix Focus Areas
- core/macros.css[123-244]
- docs/macros.md[191-208]

## Suggested fix
1. Add `:dir(rtl)` overrides for the horizontal single-edge fades so logical intent matches docs:
  - `:dir(rtl) .sf-overflow-fade` and `:dir(rtl) .sf-overflow-fade--right`: switch to `linear-gradient(to left, ...)` so the fade occurs at inline-end in RTL.
  - If `.sf-overflow-fade--left` is intended to mean inline-start (as stated), add `:dir(rtl) .sf-overflow-fade--left` using `linear-gradient(to left, ...)` with stops adjusted so the fade occurs on the physical right edge in RTL.
2. If the intent is actually *physical* left/right (not logical), update the docs text to remove inline-start/inline-end claims and describe them as physical edges.
3. Consider adding a small test case to assert RTL mirroring (e.g., set `dir="rtl"` on the document and assert the computed `maskImage` direction contains the expected `to left`/`to right` for the relevant classes).

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

---