Condense source CSS comments to concise headers and section labels

[jackgranatowski]

Summary

Streamlined all source CSS file headers and inline comments to follow a new concise policy. Removed verbose architectural explanations, usage examples, and detailed rationales from source files, moving that content to dedicated documentation (new docs/source-comment-policy.md). Source comments now serve as quick reference only; full API documentation is maintained separately in docs/llm-guide.md and the configurator.

Key changes

• File headers: Reduced from multi-line blocks to single-line format with module path, layer, purpose, prefix, and scope facts only
• Section separators: Replaced long explanatory comments with concise category labels (e.g., /* Focus */ instead of multi-line focus documentation)
• Inline comments: Removed verbose rationales; kept only essential implementation notes (e.g., specificity justifications, browser compatibility caveats)
• New policy document: Added docs/source-comment-policy.md to codify the approach and redirect readers to authoritative docs
• API index generator: Updated scripts/gen-api-index.js to prefer curated metadata, fall back to previous index, then use concise source banners—preserving public API docs without requiring verbose source comments
• Affected files: core/macros.css, core/layout.css, core/base.css, core/reset.css, core/tokens.css, core/tokens.layout.css, core/tokens.macros.css, core/accessibility.css, core/states.css, core/themes.css, core/motion.css, core/print.css, core/layers.css, optional/theme-example.css, optional/components.css, optional/forms.css, optional/utilities.css, optional/overrides-example.css, optional/config-example.css, optional/tokens.components.css, optional/tokens.palette.css, optional/legacy.css

Implementation details

• Source CSS comments are now implementation artifacts, not primary API docs
• Public API surface remains fully documented in docs/llm-guide.md and the configurator UI
• The API index generator now decouples source comment terseness from documentation completeness
• All version checks and CI gates remain unchanged; no functional impact on builds or releases

https://claude.ai/code/session_01Pdaz7HQGBUBm59X7AU4Qep

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your 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 31 minutes and 36 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: aecf9ce7-8212-4b53-b122-03c1c0739b34

📥 Commits

Reviewing files that changed from the base of the PR and between 129d78a and 6978d24.

📒 Files selected for processing (28)

• configurator/src/components/BundlePicker.svelte
• configurator/src/components/ContrastBadge.svelte
• configurator/tests-components/domain-preview.test.js
• core/accessibility.css
• core/base.css
• core/layers.css
• core/layout.css
• core/macros.css
• core/motion.css
• core/print.css
• core/reset.css
• core/states.css
• core/themes.css
• core/tokens.css
• core/tokens.layout.css
• core/tokens.macros.css
• docs/llm-guide.md
• docs/source-comment-policy.md
• optional/components.css
• optional/config-example.css
• optional/forms.css
• optional/legacy.css
• optional/overrides-example.css
• optional/theme-example.css
• optional/tokens.components.css
• optional/tokens.palette.css
• optional/utilities.css
• scripts/gen-api-index.js

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/adoring-franklin-01ca7m

---

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

Condense CSS source comments and preserve API docs via metadata-first index generation
📝 Documentation ✨ Enhancement 🧪 Tests 🕐 20-40 Minutes

Description

• Replace verbose CSS file banners and section blocks with terse headers and labels.
• Add a documented source-comment policy and expand LLM guide examples to match.
• Update API index generation to prefer curated metadata and backfill from prior index.

Diagram

graph TD
  css["Source CSS (core/*, optional/*)"] --> gen["scripts/gen-api-index.js"] --> api["docs/api-index.json/.md"]
  meta["docs/token-annotations.json"] --> gen --> api
  prev["Previous docs/api-index.json"] --> gen --> api
  policy["docs/source-comment-policy.md"] --> css

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Keep verbose source banners as primary API docs

• ➕ No dependency on generated index quality/availability
• ➕ Greppable, self-contained documentation next to implementation
• ➖ Source becomes noisy and harder to maintain
• ➖ High risk of comments diverging from real behavior
• ➖ Encourages treating implementation files as canonical docs

2. Introduce a structured annotation syntax in CSS (custom tags)

• ➕ More precise, machine-parsable metadata than banner proximity
• ➕ Could avoid needing the previous-index backfill
• ➖ Adds a new authoring language to enforce and document
• ➖ Requires ongoing tooling/linting to keep annotations consistent
• ➖ Still expands source comment volume (against stated goal)

3. Metadata-only API index (no source-banner fallback)

• ➕ Maximally decouples source terseness from docs
• ➕ Simplifies index generation heuristics
• ➖ Higher maintenance burden on curated metadata
• ➖ Risk of missing/incorrect docs when metadata is incomplete

Recommendation: The PR’s approach is the best balance: keep source comments as lightweight navigation/implementation notes, while preserving public API documentation by preferring curated metadata and backfilling from the previous generated index when source banners are intentionally minimal. The added configurator test further reduces the risk of doc drift for hard-coded token references.

Files changed (28) +395 / -2426

Enhancement (1) +46 / -7

gen-api-index.jsPrefer curated metadata and backfill groups/descriptions from previous index +46/-7

Prefer curated metadata and backfill groups/descriptions from previous index

• Adds a compatibility overlay that reads the previously generated API index and backfills missing groups/descriptions when source section banners are intentionally terse. Updates token/class entry builders to accept existing-entry maps and only use prior descriptions when the newly derived text is not useful.

scripts/gen-api-index.js

Bug fix (1) +1 / -1

ContrastBadge.svelteFix token reference in ContrastBadge documentation comment +1/-1

Fix token reference in ContrastBadge documentation comment

• Corrects an example token name in a component doc comment to reference '--sf-color-bg', matching the framework token surface.

configurator/src/components/ContrastBadge.svelte

Tests (1) +15 / -0

domain-preview.test.jsAdd regression test for DomainPreview var() token references +15/-0

Add regression test for DomainPreview var() token references

• Introduces a test that parses DomainPreview source and asserts all hard-coded 'var(--sf-*)' references exist in the generated API index token list.

configurator/tests-components/domain-preview.test.js

Documentation (24) +332 / -2418

accessibility.cssCondense accessibility module headers and keep key rationale notes +22/-177

Condense accessibility module headers and keep key rationale notes

• Replaces long banner-style section documentation with concise headers/labels while retaining critical “why” notes (e.g., focus ring hardening, forced-colors behavior, sr-only atomic contract).

core/accessibility.css

base.cssShorten base.css header and compress browser-specific rationale comments +8/-33

Shorten base.css header and compress browser-specific rationale comments

• Condenses the file header and trims verbose inline rationale while preserving important caveats such as the WebKit 'a:link' UA specificity trap.

core/base.css

layers.cssSimplify layers.css header comment +2/-2

Simplify layers.css header comment

• Rewrites the file header to a brief statement about global cascade order and import expectations.

core/layers.css

layout.cssCondense layout module banner and section documentation +40/-225

Condense layout module banner and section documentation

• Replaces long per-primitive comment blocks with short section labels and a concise file header; keeps select non-obvious notes (e.g., '.sf-cq' intent).

core/layout.css

macros.cssCondense macros module banner and retain specificity exception note +19/-261

Condense macros module banner and retain specificity exception note

• Reduces the top-of-file banner and removes long recipe explanations, keeping essential implementation notes such as the '.sf-not-prose' specificity exception.

core/macros.css

motion.cssShorten motion module banner and keep key behavior notes +8/-75

Shorten motion module banner and keep key behavior notes

• Condenses documentation blocks into brief headers while preserving critical rationale like the unconditional 'animation-duration' fallback for engines without scroll timelines.

core/motion.css

print.cssCondense print module header and section comments +7/-59

Condense print module header and section comments

• Replaces long-form print policy commentary with concise file/section labels while preserving the same print rules and structure.

core/print.css

reset.cssCondense reset module header and trim explanatory comments +2/-36

Condense reset module header and trim explanatory comments

• Shortens the reset.css banner and reduces verbose cross-browser explanations while keeping the normalization rules intact.

core/reset.css

states.cssCondense states module banner and keep important API notes +29/-122

Condense states module banner and keep important API notes

• Replaces multi-line conceptual documentation with concise headings while preserving key behavioral notes (e.g., '.is-disabled' cursor inheritance contract).

core/states.css

themes.cssCondense themes header and keep essential LumLocker/section-theming rationale +13/-150

Condense themes header and keep essential LumLocker/section-theming rationale

• Compresses extensive theme documentation into shorter comments while retaining important notes about LumLocker exclusions and the need for token re-declarations for section-level theming.

core/themes.css

tokens.cssReplace long token architecture banner with concise header +3/-155

Replace long token architecture banner with concise header

• Removes the large architectural and catalog-style header block and replaces it with a short description of token scope and theming entrypoint.

core/tokens.css

tokens.layout.cssCondense layout token file banner +4/-20

Condense layout token file banner

• Replaces the verbose header with a concise description of layout override tokens and load ordering.

core/tokens.layout.css

tokens.macros.cssCondense macro token file banner +4/-18

Condense macro token file banner

• Replaces the verbose header with a concise description of macro override tokens and load ordering.

core/tokens.macros.css

llm-guide.mdExpand explicit token lists and examples for clarity +31/-7

Expand explicit token lists and examples for clarity

• Updates examples and token enumerations to be more explicit (e.g., palette mix steps, max-width knobs, layout token lists) to compensate for reduced verbosity in source CSS comments.

docs/llm-guide.md

source-comment-policy.mdAdd policy for keeping source comments terse +29/-0

Add policy for keeping source comments terse

• Introduces a new policy doc defining what belongs in source CSS comments and where long-form documentation should live under 'docs/'.

docs/source-comment-policy.md

components.cssCondense optional components module banner and section markers +12/-247

Condense optional components module banner and section markers

• Replaces the long explanatory header and per-component comment blocks with concise headings indicating reserved component surfaces.

optional/components.css

config-example.cssCondense starter config commentary into concise section headers +31/-82

Condense starter config commentary into concise section headers

• Shortens the copy/customize header and replaces verbose section explanations with concise labeled sections while keeping the example token overrides intact.

optional/config-example.css

forms.cssCondense classless forms module documentation and keep key caveats +25/-147

Condense classless forms module documentation and keep key caveats

• Replaces long multi-paragraph commentary with short section labels while retaining critical interoperability notes (e.g., WebKit autofill background behavior and FieldText chevron rationale).

optional/forms.css

legacy.cssCondense legacy support banner and section headers +5/-53

Condense legacy support banner and section headers

• Shortens the module explanation and replaces detailed headings with concise labels, keeping legacy fallback rules unchanged.

optional/legacy.css

overrides-example.cssCondense overrides example banner +9/-176

Condense overrides example banner

• Replaces the long “how/why” header content with a concise description of the overrides layer purpose while retaining the example structure.

optional/overrides-example.css

theme-example.cssCondense theme example banner and section headers +18/-246

Condense theme example banner and section headers

• Reduces the verbose reference commentary to concise section markers and a shorter file header, preserving the example theme patterns.

optional/theme-example.css

tokens.components.cssCondense optional component token banner +4/-20

Condense optional component token banner

• Replaces the long header block with a concise description of reserved component token surface and status (commented until classes ship).

optional/tokens.components.css

tokens.palette.cssCondense palette token module banner +4/-43

Condense palette token module banner

• Replaces the long palette rationale and token catalog preface with a concise header describing the optional numeric palettes and load order.

optional/tokens.palette.css

utilities.cssCondense utilities module banner and section heading +3/-64

Condense utilities module banner and section heading

• Shortens the file header and replaces the large commented usage block with a concise section label for heading helper utilities.

optional/utilities.css

Other (1) +1 / -0

BundlePicker.svelteSuppress a11y lint warning for scrollable code snippet focus target +1/-0

Suppress a11y lint warning for scrollable code snippet focus target

• Adds a targeted 'svelte-ignore' comment explaining why a non-interactive 'tabindex' is required on the horizontally scrollable snippet container.

configurator/src/components/BundlePicker.svelte

[qodo-code-review]

Code Review by Qodo

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

Context used

✅ Compliance rules (platform): 5 rules

1. Header comment misclassified ✓ Resolved 🐞 Bug ≡ Correctness

Description

The condensed CSS headers (e.g., in core/layout.css) no longer satisfy gen-api-index.js’s
file-header detection (it requires a divider run), so the header is treated as a normal note and can
become the nearest description for early classes/tokens when generating without an existing
api-index overlay. This breaks the intended “source banners” fallback and can pollute descriptions
with the file header string (e.g., "SLASHED — core/layout.css …").

Code

core/layout.css[R1-4]

+/* SLASHED — core/layout.css
+   @layer slashed.layout
+   Layout primitives: section, container, stack, cluster, grid, sidebar, switcher, frame.
+   Prefix: .sf-*; local rhythm via --sf-*-gap / sizing tokens. */

Evidence

The new header in core/layout.css starts with "SLASHED —" but contains no divider run; however,
collectComments() only marks a comment as isHeader if DIVIDER_RUN.test(raw) is true. Since
contextAt() skips only comments marked isHeader, the condensed header can be treated as the
nearest comment, and describe() will use nearest.description (i.e., the header text) when there
is no preceding banner/attached note—exactly the case at the start of core/layout.css before the
first section comment.

core/layout.css[1-15]
scripts/gen-api-index.js[151-157]
scripts/gen-api-index.js[224-236]
scripts/gen-api-index.js[266-299]
scripts/gen-api-index.js[63-85]

Agent prompt

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

## Issue description
`scripts/gen-api-index.js` detects file headers only when the header block contains a long divider run (the old banner style). After this PR, CSS headers are condensed and no longer include divider lines, so they are parsed as ordinary notes and may be attached as element descriptions when the generator runs without a previous `docs/api-index.json` overlay.

## Issue Context
The generator’s documented fallback chain includes “concise source section banners”. For that fallback to be correct in a clean run (or for newly added elements not present in the previous index), the file header comment must still be classified as `isHeader` and skipped by `contextAt()`.

## Fix Focus Areas
- scripts/gen-api-index.js[224-236]
- scripts/gen-api-index.js[266-299]
- scripts/gen-api-index.js[151-157]

## Implementation notes
- Update `collectComments()` so `isHeader` matches the new condensed header style (e.g., first block comment in file, `start < 4`, contains `SLASHED —`), without requiring `DIVIDER_RUN`.
- Keep the existing `contextAt()` behavior (`if (c.isHeader) continue;`) so the header can’t become `nearest`.
- Optional: add a small unit-style assertion (or a fixture-based test) that a condensed header is skipped and does not become the description for the first extracted class/token in a file.

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

---