feat(ui): @layer + :where() override contract for grid CSS#160
Merged
Conversation
Design for making @pretable/ui's shipped CSS reliably overridable by external consumers via @layer pretable + :where()-flattened selectors. Both token and deep-CSS overrides win without specificity tricks; layer order survives Tailwind Preflight. Behavior-preserving one-time migration of grid.css + theme files, plus a consumer-facing cascade-and-overrides docs page. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
4-task TDD plan: migrate grid.css to @layer pretable + :where() (structural test guard), declare app layer order, Playwright cascade proof, docs. Amends spec: token files stay unlayered (jsdom can't resolve layered custom props; token overrides already win by source order). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…lectors Makes every grid default specificity (0,0,0) inside the pretable cascade layer, so consumer overrides (tokens, deep CSS, or unlayered/later-layer rules) win without !important or specificity tricks. Token files stay unlayered. Source order already yields correct state precedence; the only behavior delta is selected/focused now winning over zebra/hover (previously a specificity artifact). Guarded by a structural test.
The selector loop skipped only \`@layer pretable\`; a future @media/@supports inside the layer would have failed the test confusingly. Skip any at-rule opener instead.
Adds '@layer theme, base, pretable, components, utilities;' to the website and bench global CSS. Doubles as the reference example for external Tailwind consumers.
…layer Loads excel.css + the migrated grid.css in Chromium and asserts an unlayered consumer rule beats the layered :where() default, and that the selected background survives the zebra/hover rules.
Test 1 now injects the unlayered consumer rule BEFORE the layered grid.css, so it fails without the @layer migration (grid would win by source order at equal specificity) and passes with it. Replaces the vacuous non-empty color check with a real display:flex sanity assertion. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
New 'Cascade & overrides' page plus the layer-order line in the architecture overview, Tailwind page, and @pretable/ui README.
The new page was reachable only via in-content links; _nav.ts is the nav source of truth (no MDX auto-discovery), so add it to the Theming section. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
Vercel preview readyPreview: https://pretable-mdup1rhmk-cacheplane.vercel.app Updated automatically by the |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Makes
@pretable/ui's grid CSS reliably overridable by consumers.grid.cssnow lives in a single@layer pretablecascade layer with every selector:where()-flattened to specificity(0,0,0), so consumer styles win — by layer order, by specificity, or both — without!importantor specificity wars. Closes the highest-leverage gap in the consumer theming story (the rest of theming was already built).Spec:
docs/superpowers/specs/2026-06-05-css-cascade-override-contract-design.mdPlan:
docs/superpowers/plans/2026-06-05-css-cascade-override-contract.mdWhat changed
grid.css→@layer pretable+:where()(packages/ui/src/grid.css). Token files stay unlayered (jsdom can't resolve layered custom props, and token overrides already win by source order). Source order already yields correct state precedence — the one intentional behavior delta is selected/focused now winning over zebra/hover (previously a specificity artifact where they lost).@layer theme, base, pretable, components, utilities;in the website + bench global CSS. Puts the grid after Tailwind Preflight (reset can't clobber it) but before utilities (utility classes still win). Doubles as the consumer reference.theming/cascade-and-overrides.mdx(registered in nav) + updates to the theming index, Tailwind page, override-tokens page, and@pretable/uiREADME.Tests
@layer pretable+ every selector wrapped in:where(), so a future raw selector fails CI.grid.css(so it would fail without the migration) and proves the consumer wins; plus selected-beats-zebra.Verification
@pretable/uivitest: 16/16 (incl. existing contract/density token-resolution tests — confirms token files stayed unlayered)Process
Brainstorm → spec → plan → subagent-driven execution (implementer + spec + code-quality review per task). The final whole-branch review caught the missing nav registration, now fixed.
Out of scope (tracked separately)
Semantic targeting attributes (
data-column-id/data-cell-type), brand/semantic token-alias layer, dark-mode for Excel, unstyled/headless variant.🤖 Generated with Claude Code