docs(landing): recommend <link> over @import for CDN install

[jackgranatowski]

@import at the top of a stylesheet is render-blocking and serialized:
the browser must fetch and parse the parent sheet before discovering the
import, then issue a second request that the preload scanner cannot see.
Lead with as the recommended install and demote
@import to a labelled alternative.

Co-Authored-By: Claude Opus 4.8 noreply@anthropic.com
Claude-Session: https://claude.ai/code/session_016WH9Q15j1dZYxqTqMoomxq

Summary by CodeRabbit

• Documentation

  • Refreshed the README with a new layout, updated getting-started guidance, expanded section ordering, and added WordPress integration and license information.
  • Updated architecture and install documentation to reflect the latest component and bundle status.
  • Revised site copy to show the current token count and updated setup examples.

• Chores

  • Cleaned up configuration and removed obsolete documentation content from the site.

[qodo-code-review]

PR Summary by Qodo

docs(landing): recommend over @import for CDN install

📝 Documentation ✨ Enhancement ⚙️ Configuration changes 🕐 20-40 Minutes

AI Description

• Recommend a  tag for CDN installs; demote @import due to render-blocking behavior.
• Refresh landing/README copy to match v0.7.0 token/class counts and component status.
• Clean up site scaffolding by removing old landing sources and adjusting Jekyll exclusions.

Diagram

graph TD
dev([Developer]) --> docs["Landing docs"] --> link["Recommended: link tag"] --> browser["Browser"] --> cdn["jsDelivr CDN"] --> css["SLASHED CSS bundle"]
docs --> imp["Alternative: @import"] --> browser

Loading

High-Level Assessment

The PR’s approach—make the primary CDN install path and keep @import as a clearly-labeled alternative—is the right default for performance and aligns with how browsers’ preload scanners work. Considered adding more advanced patterns (preload/onload, preconnect), but those add complexity and aren’t necessary for the baseline guidance.

Files changed (8) +253 / -220

Enhancement (1) +4 / -0

generate.mjsExtend demo generator’s curated token overrides +4/-0

Extend demo generator’s curated token overrides

• Adds curated values for newly-exposed/renamed tokens (e.g., media radius, selection alt text, scroll exit timeline range tokens) so generated demos render those knobs visibly.

demos/generate.mjs

Documentation (6) +249 / -219

README.mdRewrite README landing copy and switch CDN install to <link> first +127/-172

Rewrite README landing copy and switch CDN install to <link> first

• Reformats the README into a website-style landing narrative with updated token counts (720) and bundle guidance. Adds a prominent CDN <link> snippet and expands sections on tokens, dark mode, layers, browser support, and tooling links (including updated component live/staged status).

README.md

full-api-demo-with-overrides.htmlUpdate demo counts and include newly-generated class/token sections +45/-11

Update demo counts and include newly-generated class/token sections

• Refreshes the displayed class/token counts (e.g., 316 classes, 720 tokens) and expands showcased animations/layout primitives to match the current generated output. Keeps the override-enabled variant in sync with the baseline demo.

demos/full-api-demo-with-overrides.html

full-api-demo.htmlRegenerate baseline full API demo with updated counts and examples +46/-12

Regenerate baseline full API demo with updated counts and examples

• Updates the headline counts and demo tiles to reflect the current class/token inventory, including additional animation variants and layout primitives. Aligns the token reference section totals with 720 tokens.

demos/full-api-demo.html

ultimate-override.cssKeep ultimate override coverage in sync with new knob tokens +7/-1

Keep ultimate override coverage in sync with new knob tokens

• Updates the documented override coverage (206/229) and adds overrides for new configurable tokens like media radius, selection alt text, and scroll exit ranges.

demos/ultimate-override.css

architecture.mdClarify partial component shipping status and bundle contents +15/-14

Clarify partial component shipping status and bundle contents

• Updates architecture docs to reflect that '.sf-btn' and '.sf-card' are live since v0.7.0 while other components remain commented out. Adjusts bundle descriptions and related narrative to match current component/token emission behavior.

docs/architecture.md

index.htmlLanding page: recommend <link> CDN install and refresh token/component messaging +9/-9

Landing page: recommend <link> CDN install and refresh token/component messaging

• Switches the install section to lead with a '<link rel="stylesheet">' snippet and labels '@import' as a slower alternative. Updates token counts (685→720) and bundle/component descriptions to reflect current release state.

index.html

Other (1) +0 / -1

_config.ymlInclude copy-wip content in Jekyll build inputs +0/-1

Include copy-wip content in Jekyll build inputs

• Removes the 'copy-wip' directory from the Jekyll 'exclude' list, allowing it to be processed/published if present.

_config.yml

[qodo-code-review]

Code Review by Qodo

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

Context used

✅ Compliance rules (platform): 12 rules

1. Utilities bundle called inert ✓ Resolved 🐞 Bug ≡ Correctness

Description

README.md describes slashed.optimal-utilities.css as “inert in 0.x”, but the bundle includes
optional/utilities.css which contains active utility class rules (e.g. .sf-h1–.sf-h6,
.sf-text-*). This misrepresents bundle behavior for users choosing the utilities bundle.

Code

README.md[109]

+| `slashed.optimal-utilities.css` | optimal + the staged utility layer *(inert in 0.x)* |

Relevance

⭐⭐⭐ High

Team frequently fixes docs/code mismatches; README truthfulness corrections accepted in PRs #34,
#70, #280.

PR-#34
PR-#70
PR-#280

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The README claims the utilities bundle is inert, but the repository’s optional/utilities.css
contains active utility rules and bundle.config.json includes that file in the
slashed.optimal-utilities.css bundle output, so the bundle cannot be inert.

README.md[105-110]
optional/utilities.css[1-66]
bundle.config.json[85-104]

Agent prompt

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

## Issue description
`README.md` states that `slashed.optimal-utilities.css` is “inert in 0.x”, but the utilities layer is not inert: `optional/utilities.css` contains active utility classes and is included in the utilities bundle output.

## Issue Context
- `optional/utilities.css` explicitly notes that multiple blocks are active and defines live selectors.
- `bundle.config.json` shows `slashed.optimal-utilities.css` includes `optional/utilities.css`.

## Fix Focus Areas
- README.md[105-110]
- optional/utilities.css[1-66]
- bundle.config.json[85-104]

## What to change
- Update the README bundle table row for `slashed.optimal-utilities.css` to accurately describe what ships (e.g., “utilities layer (partially active; more utilities staged/commented out)”, optionally naming the active groups like heading/text-size helpers).
- Consider mirroring the same corrected wording anywhere else the “inert” claim appears (e.g., the landing page bundle table), to keep docs consistent.

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

---

[coderabbitai]

Warning

Review limit reached

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

Next review available in: 29 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: fdcbe1b4-2cfa-4be5-8c47-c55f2d036044

📥 Commits

Reviewing files that changed from the base of the PR and between 83897a1 and 6377c09.

📒 Files selected for processing (10)

• README.md
• _config.yml
• copy-wip/github-readme.md
• demos/full-api-demo-with-overrides.html
• demos/full-api-demo.html
• demos/generate.mjs
• demos/ultimate-override.css
• docs/architecture.md
• index.html
• index.md

📝 Walkthrough

Walkthrough

This PR reworks README.md's structure and content, removes copy-wip/github-readme.md and index.md content, drops a Jekyll exclude entry, updates docs/architecture.md to reflect partial component completion, updates index.html's token count and install snippets, and adds curated token overrides in demos/generate.mjs and demos/ultimate-override.css.

Changes

Documentation and site content overhaul

Layer / File(s)	Summary
README restructure README.md	Reworks hero layout, philosophy/what's-inside framing, cascade layers, bundles, browser support, documentation table, adds WordPress section, and updates development scripts and license.
Removal of superseded draft/site content copy-wip/github-readme.md, index.md, _config.yml	Removes copy-wip draft README body and index.md home page content, and drops the copy-wip exclude entry from Jekyll config.
Architecture docs component progress docs/architecture.md	Updates file-structure, layer, bundle, and deferred-item descriptions to reflect partial component completion (.sf-btn/.sf-card live, rest staged).
Homepage marketing and install snippets index.html	Updates design token count to 720 across meta description, hero, and stats strip, and revises Install section code snippets and bundle wording.

Demo curated token overrides

Layer / File(s)	Summary
Curated override map additions demos/generate.mjs	Adds explicit curated overrides for media radius, color selection text alt, and scroll-timeline exit range tokens.
Generated override CSS output demos/ultimate-override.css	Reflects updated coverage count and new CSS custom property overrides matching the curated map additions.

Estimated code review effort: 2 (Simple) | ~12 minutes

Possibly related PRs

• codeslash-dev/SLASHED#48: Both PRs substantially rewrite README.md's philosophy/what's-inside documentation flow and token-count/installation/bundle guidance.
• codeslash-dev/SLASHED#503: The main PR rewrites README.md using content previously in copy-wip/github-readme.md, then removes that draft file's old body.
• codeslash-dev/SLASHED#545: Both PRs update demos/generate.mjs and/or demos/ultimate-override.css for new curated token knobs.

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 matches the main docs change: recommending over @import for CDN installation.
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/import-performance-impact-ovvjpb

---

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