feat: redesign bundle structure — drop essential, remove legacy from defaults

[jackgranatowski]

• Remove slashed.essential bundle (was core-only; optimal is now the base)
• Add forms.css to optimal (classless, broadly useful, safe default)
• Remove legacy.css from all bundles — opt-in only, not a default
• Four bundles remain: optimal, optimal+components, optimal+utilities, full
• Update package.json exports, README, architecture.md, macros.md
• Switch all test fixtures from essential → optimal bundle
• Update configurator BUNDLE_META copy and bundle size budgets
• Regenerate dist/, api-index, token-index, registry and configurator data

[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 21 minutes and 50 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: a59ef9aa-ef66-46cd-b9a5-6e3a0c0a6570

📥 Commits

Reviewing files that changed from the base of the PR and between 35e927a and 383131b.

⛔ Files ignored due to path filters (2)

• dist/badge-essential.json is excluded by !**/dist/**
• dist/badge-optimal.json is excluded by !**/dist/**

📒 Files selected for processing (23)

• README.md
• _layouts/default.html
• bundle.config.json
• configurator/src/data/api-index.generated.json
• configurator/src/data/bundles.generated.json
• configurator/src/lib/bundles.js
• configurator/tests-components/bundle-picker.test.js
• docs/api-index.json
• docs/architecture.md
• docs/demo.html
• docs/macros.md
• index.md
• package.json
• scripts/bundle.js
• scripts/gen-api-index.js
• tests/bundle-size.spec.js
• tests/container-queries.spec.js
• tests/layers.spec.js
• tests/layout.spec.js
• tests/macros.spec.js
• tests/print.spec.js
• tests/states-full.spec.js
• tests/typography.spec.js

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/bundle-structure-redesign-na422t

---

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

Redesign bundles: remove essential tier; make legacy.css opt-in; add forms to optimal
✨ Enhancement ⚙️ Configuration changes 📝 Documentation 🧪 Tests 🕐 40+ Minutes

Description

• Remove the essential bundle tier and make optimal the baseline bundle.
• Drop optional/legacy.css from all default bundles; keep it opt-in only.
• Update exports, docs, configurator metadata, and tests to reference optimal.

Diagram

graph TD
  A["core/ + optional CSS"] --> B["bundle.config.json"] --> C(["scripts/bundle.js"]) --> D[("dist bundles")]
  D --> E["package exports"]
  D --> F["API index docs"] --> G["configurator data"]
  D --> H["Playwright tests"]
  subgraph Legend
    direction LR
    _f["File/config"] ~~~ _s(["Build script"]) ~~~ _a[("Generated artifacts")]
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Keep `essential` as a deprecated alias to `optimal`

• ➕ Avoids breaking existing imports/URLs (./essential, slashed.essential.css)
• ➕ Lets docs and ecosystem migrate gradually
• ➖ Adds another tier name to support and document
• ➖ Alias may confuse users about which bundle is the baseline

2. Introduce a dedicated `core` bundle/export (replacing essential semantics)

• ➕ Preserves a true core-only option without implying it’s recommended
• ➕ Clearer naming for consumers who want minimal CSS
• ➖ Reintroduces an extra tier (more outputs, docs, budgets, tests)
• ➖ Undercuts the goal of simplifying bundle choices

3. Publish `legacy` as a standalone artifact (e.g., `slashed.legacy.css`)

• ➕ Makes legacy inclusion explicit and easy (single file)
• ➕ Keeps defaults modern while providing a clear escape hatch
• ➖ Another distributed artifact to version/badge/document
• ➖ Risk of users including it by default anyway

Recommendation: If this ships as a major version, the PR’s approach (remove essential and keep four tiers) is the simplest long-term model. If not a major, consider keeping a temporary deprecated essential export/asset pointing to optimal to prevent immediate breakage while still steering users to the new baseline.

Files changed (22) +82 / -1732

Enhancement (1) +7 / -11

bundles.jsUpdate configurator bundle copy for new baseline +7/-11

Update configurator bundle copy for new baseline

• Removes 'essential' bundle metadata, updates taglines so 'optimal' is the recommended default, and adjusts documentation/comments to reflect core-only configs mapping to 'optimal'.

configurator/src/lib/bundles.js

Tests (8) +14 / -15

bundle-size.spec.jsRemove essential bundle size budget +0/-1

Remove essential bundle size budget

• Deletes the 'slashed.essential.min.css' budget check so CI only enforces size constraints for remaining bundles.

tests/bundle-size.spec.js

container-queries.spec.jsSwitch container-query tests to load optimal bundle +1/-1

Switch container-query tests to load optimal bundle

• Updates the bundle path constant from 'slashed.essential.css' to 'slashed.optimal.css'.

tests/container-queries.spec.js

layers.spec.jsSwitch layer-ordering tests to load optimal bundle +6/-6

Switch layer-ordering tests to load optimal bundle

• Replaces all 'page.addStyleTag' references to the essential bundle with the optimal bundle.

tests/layers.spec.js

layout.spec.jsSwitch layout tests to load optimal bundle +1/-1

Switch layout tests to load optimal bundle

• Updates the bundle constant used by layout tests to point at 'slashed.optimal.css'.

tests/layout.spec.js

macros.spec.jsSwitch macros tests to load optimal bundle +1/-1

Switch macros tests to load optimal bundle

• Updates the bundle constant so macro tests run against 'slashed.optimal.css'.

tests/macros.spec.js

print.spec.jsSwitch print tests to load optimal bundle +3/-3

Switch print tests to load optimal bundle

• Replaces all essential bundle injections with optimal so print regressions validate the new baseline bundle.

tests/print.spec.js

states-full.spec.jsSwitch states-full tests to load optimal bundle +1/-1

Switch states-full tests to load optimal bundle

• Updates the bundle constant from 'slashed.essential.css' to 'slashed.optimal.css'.

tests/states-full.spec.js

typography.spec.jsSwitch typography tests to load optimal bundle +1/-1

Switch typography tests to load optimal bundle

• Updates the bundle constant used alongside the HTML fixture to load 'slashed.optimal.css'.

tests/typography.spec.js

Documentation (5) +41 / -945

README.mdDocument new bundle tiers and make legacy opt-in +20/-15

Document new bundle tiers and make legacy opt-in

• Removes the essential bundle badge and replaces install examples with 'optimal', 'optimal-components', 'optimal-utilities', and 'full'. Clarifies that 'optional/legacy.css' is not bundled by default and must be explicitly added last if needed.

README.md

api-index.jsonRegenerate published API index without essential tier +1/-913

Regenerate published API index without essential tier

• Removes 'essential' from the schema description and from per-entry 'bundles' arrays, leaving only 'optimal', 'optimal-components', 'optimal-utilities', and 'full'.

docs/api-index.json

architecture.mdUpdate architecture docs for four-tier bundle model +17/-14

Update architecture docs for four-tier bundle model

• Reframes bundle documentation around 'optimal' as the baseline (core + forms), updates the tier table, and notes that 'optional/legacy.css' is opt-in only.

docs/architecture.md

macros.mdUpdate macros docs to reference optimal bundle +1/-1

Update macros docs to reference optimal bundle

• Changes the referenced shipping bundle for macro tokens from essential to optimal.

docs/macros.md

index.mdUpdate landing page CDN examples to optimal bundle +2/-2

Update landing page CDN examples to optimal bundle

• Replaces essential CDN import/link examples with 'slashed.optimal.min.css'.

index.md

Other (8) +20 / -761

default.htmlSwitch docs site default CSS from essential to optimal +1/-1

Switch docs site default CSS from essential to optimal

• Updates the Jekyll layout to load 'dist/slashed.optimal.css' instead of 'slashed.essential.css'.

_layouts/default.html

bundle.config.jsonRemove essential outputs and drop legacy from all bundles +8/-53

Remove essential outputs and drop legacy from all bundles

• Deletes the 'slashed.essential' and 'slashed.essential.flat' bundle definitions. Removes 'optional/legacy.css' from all remaining bundles and ensures 'optional/forms.css' is included in 'optimal'-based tiers.

bundle.config.json

api-index.generated.jsonRegenerate configurator API index without essential tier +1/-682

Regenerate configurator API index without essential tier

• Updates the synced API-index metadata to remove 'essential' from the known bundle list and per-element bundle membership arrays, and refreshes the sync hash.

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

bundles.generated.jsonRemove essential from configurator bundle catalog +8/-20

Remove essential from configurator bundle catalog

• Deletes the 'essential' bundle entry and adjusts remaining bundle module lists and file counts to reflect removal of 'optional/legacy.css' (and updated optimal composition).

configurator/src/data/bundles.generated.json

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

Update optimal size badge after bundle changes

• Adjusts the badge message to reflect the regenerated gzip size for the optimal bundle.

dist/badge-optimal.json

package.jsonRemove essential exports +0/-2

Remove essential exports

• Drops the './essential' and './essential/flat' export paths so consumers use './optimal' and the remaining tiers.

package.json

bundle.jsStop generating essential size badge +0/-1

Stop generating essential size badge

• Removes the call that wrote the 'essential' size badge, aligning the build script with the reduced bundle set.

scripts/bundle.js

gen-api-index.jsRemove essential from API index schema copy +1/-1

Remove essential from API index schema copy

• Updates the schema description text so the 'bundles' field enumerates only the remaining tiers.

scripts/gen-api-index.js

[qodo-code-review]

Code Review by Qodo

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

Context used

✅ Compliance rules (platform): 5 rules

1. Demo references removed bundle ✓ Resolved 🐞 Bug ≡ Correctness

Description

The PR removes generation of dist/slashed.essential.css, but docs/demo.html still links to
../dist/slashed.essential.css, so the demo page will fail to load framework styles after running the
new build.

Code

bundle.config.json[4]

-      "output": "dist/slashed.essential.css",

Relevance

⭐⭐⭐ High

Team previously fixed demo.css links when they broke after bundle/dist changes (PRs #64, #66).

PR-#64
PR-#66
PR-#270

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

bundle.config.json no longer includes any dist/slashed.essential.css output, while
docs/demo.html still loads that file, guaranteeing a broken stylesheet link after a rebuild. The
bundler also no longer emits an essential badge, reinforcing that essential is no longer treated as
a build output.

bundle.config.json[1-22]
docs/demo.html[7-12]
scripts/bundle.js[216-246]

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/demo.html` still links to `../dist/slashed.essential.css`, but this PR removes the `slashed.essential` bundle outputs from `bundle.config.json`. After `npm run build`, the referenced CSS file will no longer exist, leaving the demo unstyled.

## Issue Context
- The build pipeline (`scripts/bundle.js`) builds whatever is listed in `bundle.config.json`.
- After this PR, `bundle.config.json` starts at `slashed.optimal.css` and does not emit any `slashed.essential.css` artifact.

## Fix Focus Areas
- docs/demo.html[7-12]

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

---