docs: fix stale README content and make bundle-size badge self-updating

[jackgranatowski]

This pull request was created by @kiro-agent on behalf of @jackgranatowski 👻

Comment with /kiro fix to address specific feedback or /kiro all to address everything.
_{Learn about Kiro Web}

---

Summary

The README contained several stale/untrue statements and a hardcoded, broken badge. This PR corrects the prose and makes the bundle-size badge update itself from the build pipeline.

Badges (now always current)

• essential bundle — was a hardcoded 11.6kB gzip static badge linking to dist/slashed.essential.min.css, which 404s on main (dist is gitignored and lives only on the dist branch). The actual size is 15.0 kB gzip. Replaced with a shields.io endpoint badge fed by dist/badge-essential.json, now generated during npm run build and published to the dist branch by publish-dist.yml on every merge — so it self-updates and never goes stale. The badge now links to the real CDN file on jsDelivr.
• release — link pointed at /releases/latest, which 404s because every release so far is a prerelease (latest is v0.5.25). Repointed to /releases. The badge image already used include_prereleases, so it was rendering fine.
• CI — pinned to ?branch=main for deterministic status.
• license — already correct (MIT), unchanged.

Prose accuracy

• À la carte core list was missing core/tokens.color-fallbacks.css (present in every bundle in bundle.config.json); added it after layers.css.
• À la carte optional list was missing optional/tokens.sizes-extended.css (part of the optimal set); added it.
• Customising tokens example claimed a 6-token rebrand but only showed 4 source tokens. Now shows all 6 brand -light tokens (primary, secondary, tertiary, action, neutral, base), matching docs/theming.md, and clarifies the 11-light + 11-dark count (the 5 status colours auto-derive but are overridable).
• npm run test:install description said "Chromium test browser"; it actually installs Chromium, Firefox & WebKit (per package.json).

New build output

scripts/bundle.js now writes dist/badge-essential.json (shields endpoint schema) computed from the freshly built slashed.essential.min.css gzip size.

Testing

• npm run build — succeeds; emits dist/badge-essential.json → 15.0 kB gzip
• npm run lint:css — clean
• Node unit suite (tier1-p*, api-index-sync) — 56/56 pass

Note

The endpoint badge resolves once this lands on main and publish-dist.yml regenerates the dist branch with badge-essential.json. Until then it will read as not-found on the branch preview — this self-heals on merge.

Summary by CodeRabbit

• Documentation

  • Updated quick start example with additional stylesheet imports for extended customization options.
  • Clarified token customization requirements, including minimum brand tokens and status-color auto-derivation scope.
  • Added new development command for installing browser dependencies.
  • Updated badge and CI references.

• Chores

  • Enhanced build process to generate badge endpoint descriptor.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 93c2ed97-41b0-401f-8b07-f7fd86f8232c

📥 Commits

Reviewing files that changed from the base of the PR and between acd79a1 and effc30b.

📒 Files selected for processing (2)

• README.md
• scripts/bundle.js

---

📝 Walkthrough

Walkthrough

The PR updates the build pipeline to generate a shields.io endpoint descriptor for the essential bundle gzip size at dist/badge-essential.json, and updates README documentation to reference this new endpoint-based badge while adding stylesheet load-order examples and clarifying token customization requirements and development setup.

Changes

Essential bundle badge and documentation

Layer / File(s)	Summary
Badge endpoint generation scripts/bundle.js	New writeSizeBadge() function reads the essential CSS bundle, computes gzip size, and writes a shields.io endpoint descriptor to dist/badge-essential.json. The bundle() function is updated to call writeSizeBadge() after bundling.
Documentation and examples README.md	Badge section updated to reference the generated endpoint descriptor. Stylesheet load-order examples expanded with core/tokens.color-fallbacks.css and optional/tokens.sizes-extended.css. Customising tokens section rewritten to specify minimum 6 -light brand tokens and optional -dark counterparts. Development commands list adds npm run test:install.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• codeslash-dev/SLASHED#48: Both PRs update README essential bundle badge and stylesheet wiring documentation.
• codeslash-dev/SLASHED#5: Both PRs modify scripts/bundle.js build flow logic.
• codeslash-dev/SLASHED#70: Both PRs update README customising tokens guidance for rebrand requirements.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ 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 accurately summarizes the main changes: fixing stale README content and implementing a self-updating bundle-size badge mechanism.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/readme-accuracy-and-badges

---

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 and usage tips.}