Add comprehensive comparative audit against reference CSS frameworks

[jackgranatowski]

Summary

This PR adds a detailed comparative audit of SLASHED against four reference CSS frameworks (Pico CSS v2, Automatic.css v4, Bulma v1, and Tailwind CSS v4), documenting the framework's capabilities, identifying 22 findings across multiple severity levels, and providing a prioritized roadmap for addressing issues before v1 release.

Key Changes

• New audit document (audits/comparative-audit-2026.md): 1,478-line comprehensive analysis covering:
  • Capability matrix comparing SLASHED against reference frameworks across 80+ features
  • 22 detailed findings with severity levels (critical, high, medium, low, nit)
  • Verification of two prior audits (2024 quality audit and 2025 API coverage audit)
  • Prioritized roadmap (P0/P1/P2) for addressing issues

Critical Findings Documented

1. Browser support floor mismatch — README declares Safari 15.4/Chrome 99/Firefox 97 but light-dark() and @property with inherits require Safari 17.5+/Chrome 123+/Firefox 128+
2. Empty component/utility stubs — optional/components.css and optional/utilities.css contain only TODO comments, leaving integrators with no button, form, card, or alert components
3. Hardcoded color literal in print.css — #999 hex value violates the framework's own "all values via var()" rule
4. Print stylesheet destroys backgrounds — !important block unconditionally removes all background colors in print, breaking dark-mode and semantic color preservation
5. Cascade layer mismatch — slashed.themes layer declared but never populated; theme rules live in slashed.base instead, creating potential specificity inversions
6. WCAG AA contrast gap — Default tertiary/neutral colors yield only ~4.2:1 contrast (AA Large) instead of 4.5:1 (AA Normal) for body text
7. Shadow token opacity overflow — --sf-shadow-2xl produces alpha >1.0 in dark mode without clamping

Notable Implementation Details

• Audit methodology explicitly documents all files read (complete, no skipping) and reference framework sources consulted
• Capability matrix uses consistent notation (✓ ships, 🟡 partial, ● missing, ⚫ out-of-scope, 📦 stub)
• Verification section cross-references prior audits, identifying 10+ claims that were inaccurate or stale
• Recommendations include effort estimates (XS/S/M/L) and specific code examples for fixes
• Out-of-scope section explicitly documents intentional tradeoffs vs. disputed design decisions

Roadmap Summary

• P0 (must fix before v1): 6 items including browser floor documentation, print.css literal, contrast ratio, and component stubs
• P1 (v1.1): 8 items including print scope refinement, cascade layer reorganization, demo coverage, and utilities implementation
• P2 (nice to have): 8 items including minor token refinements and documentation updates

https://claude.ai/code/session_017pNnrbF63T296c3Abo1RCa

Summary by CodeRabbit

• Documentation
  • Added a comprehensive comparative audit evaluating framework feature coverage and browser-support gaps, noting missing CSS features, cascade-layer and token inconsistencies, print/reset and accessibility/performance/layout concerns, and coverage omissions. Includes validated prior-audit comparisons, prioritized P0/P1/P2 roadmap mapping findings to planned fixes, plus full selector/token inventories and sources for reference.

[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: 51bfea9d-3c35-4170-b137-0272e0f3ec98

📥 Commits

Reviewing files that changed from the base of the PR and between aa266e6 and 91118e4.

📒 Files selected for processing (1)

• audits/comparative-audit-2026.md

✅ Files skipped from review due to trivial changes (1)

• audits/comparative-audit-2026.md

---

📝 Walkthrough

Walkthrough

A new comparative audit document (audits/comparative-audit-2026.md) comprehensively reviews SLASHED against CSS framework references, documenting 22 findings across browser support, theming, reset behavior, accessibility, print features, and delivery. It includes capability matrices, prioritized remediation roadmap, full selector/token inventories, and verifies prior audit claims.

Changes

SLASHED Comparative Audit 2026

Layer / File(s)	Summary
Audit overview and framework comparison audits/comparative-audit-2026.md	Executive summary listing priority issues (runtime theming, stubbed optional layers, print tokens/!important reset behavior, contrast, cascade-layer ordering). Methodology and capability matrix comparing SLASHED against reference frameworks across tokens/theming, reset, layout, states, accessibility, motion, print, components, utilities, and distribution.
Findings, verification, and remediation roadmap audits/comparative-audit-2026.md	Twenty-two detailed findings (F-01–F-22) covering browser-compatibility claims, empty optional layers, print token literals and reset side effects, unused slashed.themes cascade-layer, contrast math failures, container-query naming, shadow/transition performance concerns, documentation/demo/bundle completeness. Verifies and updates 2024–2025 audit claims. Prioritized roadmap (P0/P1/P2) maps findings to recommended changes and effort levels, with an Out-of-Scope / Disagreements section.
Reference appendices—selector and token inventories audits/comparative-audit-2026.md	Appendix A: full selector inventory across reset, base, layout, states, motion, accessibility, and print stylesheet layers. Appendix B: property-registered tokens, semantic color resolutions, design tokens, typography/layout aliases, and palette token enumeration. Appendix C: sources-cited table with verified URLs.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• codeslash-dev/SLASHED#28: Both PRs add documentation-only audit reports providing comparative analysis of SLASHED against CSS reference frameworks.

🚥 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 'Add comprehensive comparative audit against reference CSS frameworks' accurately and specifically describes the main change: adding a new audit document comparing SLASHED against multiple CSS frameworks.
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.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/audit-slashed-framework-WG3PK

Warning

Review ran into problems

🔥 Problems

Git: Failed to clone repository. Please run the @coderabbitai full review command to re-trigger a full review. If the issue persists, set path_filters to include or exclude specific files.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

audits/comparative-audit-2026.md (1)

165-170: ⚡ Quick win

Add per-claim “verified on” dates for external compatibility/doc assertions.

This audit includes time-sensitive compatibility statements; adding a short (verified: YYYY-MM-DD) marker near each external claim/source section will make future re-audits more reliable.

Also applies to: 499-505, 1460-1478

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@audits/comparative-audit-2026.md` around lines 165 - 170, Add a short
"(verified: YYYY-MM-DD)" date marker after each time-sensitive external
compatibility claim in the "Browser reality" block (for items like
`light-dark()`, `@property` with `inherits: true`, `sign()` in `calc()`) and
after the "Compared to: Tailwind v4" source line; also apply the same
verification-date markers to the other external-claim blocks called out in the
review (the other compatibility/claim sections referenced), so each external
assertion includes an explicit verification date to aid future re-audits.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@audits/comparative-audit-2026.md`:
- Line 591: The title contains a duplicated token name
`--sf-sf-color-link--visited`; rename it to the correct token
`--sf-color-link--visited` so the audit heading matches the actual token naming
used elsewhere (update the title text "F-21 — `--sf-sf-color-link--visited`
hue-shifts..." to "F-21 — `--sf-color-link--visited` hue-shifts...").
- Around line 175-178: Several fenced code blocks in
audits/comparative-audit-2026.md are missing language identifiers which triggers
markdownlint MD040; update each triple-backtick fence to include an appropriate
tag (use `text` for inventory/plain blocks and `css` for CSS snippets) for the
blocks shown (e.g., the block containing "Requires: Chrome 123+ | Safari 17.5+ |
Firefox 128+" and the many CSS-like blocks starting with selectors like "*,
*::before, *::after", ":root", ".sf-section", ".is-hidden", "`@media`",
":focus:not(:focus-visible)", "`@media` print", and "`@supports`"), ensuring every
opening ``` becomes ```text or ```css as appropriate so the linter warnings are
resolved.

---

Nitpick comments:
In `@audits/comparative-audit-2026.md`:
- Around line 165-170: Add a short "(verified: YYYY-MM-DD)" date marker after
each time-sensitive external compatibility claim in the "Browser reality" block
(for items like `light-dark()`, `@property` with `inherits: true`, `sign()` in
`calc()`) and after the "Compared to: Tailwind v4" source line; also apply the
same verification-date markers to the other external-claim blocks called out in
the review (the other compatibility/claim sections referenced), so each external
assertion includes an explicit verification date to aid future re-audits.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 17a26163-22b3-4712-9ad3-79ec92444857

📥 Commits

Reviewing files that changed from the base of the PR and between e2d8165 and aa266e6.

📒 Files selected for processing (1)

• audits/comparative-audit-2026.md