refactor(ui): normalize the renderer CSS cascade into explicit layers - #1654
Merged
Conversation
Astro-Han
marked this pull request as draft
July 30, 2026 10:20
Declare the layer order once in cascade-layers.css and move the Maka-owned unlayered product imports into layer(maka.legacy), declared after utilities so precedence is unchanged. Two files need special handling to stay order-equivalent, both caught by the zero computed-style-diff gate: - maka-tokens.css stays unlayered: it declares its own @layer base/ utilities/components blocks that must keep merging into the top-level Tailwind layers instead of nesting under maka.legacy. - overlayscrollbars joins maka.legacy: the library and the product CSS trade wins by specificity in both directions, so they must share a layer to preserve those contests. The three imports already in layer(components) and the remaining third-party imports keep their current standing. Refs #1565
Review follow-up on the #1565 PR 1 cascade normalization. The existing layer-cascade contract asserted the pre-#1565 model (rules win by being unlayered) and stayed green through the rewrite because its helper drops import-site layer() semantics. Re-anchor it on the new invariants: - cascade-layers.css declares the five layers in order with maka.legacy after utilities, and styles.css loads it first (mutation-checked: a reorder fails the suite). - every styles.css import sits in its contracted layer, with the deliberate unlayered exceptions enumerated; overlayscrollbars is pinned to maka.legacy. - the .maka-nav-row guards now assert their files are imported into maka.legacy (mutation-checked: demoting sidebar.css to layer(components) fails the suite). Adapt the overlayscrollbars and segmented import assertions to the layered form, align the CSS governance docs, and update the comments whose unlayered rationale the rewrite obsoleted. Refs #1565
Astro-Han
force-pushed
the
refactor/1565-pr1-cascade-normalization
branch
from
July 30, 2026 13:10
452b278 to
111bf21
Compare
Astro-Han
marked this pull request as ready for review
July 30, 2026 13:11
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
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
PR 1 of the Astryx renderer migration (#1565, "PR 1 — Cascade normalization"): rewrite the renderer's implicit CSS cascade into an explicit, order-equivalent layered cascade. Refs #1565.
cascade-layers.cssis the single owner of the layer order (theme, base, components, utilities, maka.legacy) and becomesstyles.css's first import, so the order is established before any CSS loads.layer(maka.legacy), declared afterutilities— they keep beating Tailwind utilities exactly as unlayered CSS did, and their intra-layer order is the unchanged import order.layer(components)(chat-message.css,prose.css,markdown-link.css) are untouched.Two files deviate from the issue's nominal "wrap everything Maka-owned / leave third-party unlayered" rule; both deviations were caught by the zero-diff gate, which is exactly the arbiter role #1565 assigns it:
maka-tokens.cssstays unlayered: it declares its own@layer base/@layer utilities/@layer componentsblocks that must keep merging into the top-level Tailwind layers. Wrapping the import nests them undermaka.legacyand lifts them above theutilitieslayer (observed as button borderColor / segmented-control flips in chat and settings).overlayscrollbarsjoinsmaka.legacy: the library and the product CSS trade wins by specificity in both directions (e.g. the library's[data-overlayscrollbars-viewport]:not(...)reset vs.maka-chatViewportheight rules), so no unlayered/layered split can preserve today's outcomes. Sharing the layer preserves the intra-layer specificity and source-order contests exactly (observed as a 40px onboarding viewport height shift before the fix).Verification
check:visual-contract(PR 0's computed-style snapshot harness + baselines, borrowed locally from the PR 0 worktree): 10/10 captures clean, exact zero diff — all five routes (chat, settings-general, settings-providers, mcp-hub, onboarding) × light/dark.main'sstyles.cssagainst the same baselines confirmed the baselines represent currentmainon this machine.check:hit-test: reports the same unhittable-element list on this branch and on an unmodifiedmainbuild (identical elements, e.g. composer controls intercepted by.maka-overlay-scrollarea-viewport) — pre-existing behavior of the WIP harness/main, not a regression from this PR; owned by the PR 0 work.npm run format:check,npm run typecheck,npm run check:release(includes the dead-CSS gate): all pass.Review follow-up
An independent review pass (subagent + Codex, both verifying the built CSS AST against
main) confirmed order-equivalence and surfaced one actionable gap: the existingrenderer-style-layer-cascade-contract.test.tsasserted the pre-#1565 model and stayed green through the rewrite because its helper drops import-sitelayer()semantics. The second commit re-anchors that contract on the new invariants — layer order is append-only withmaka.legacyafterutilities, every import sits in its contracted layer, and the.maka-nav-rowfiles are pinned tomaka.legacy— each mutation-checked (reordering the layers or demotingsidebar.csstolayer(components)fails the suite). The CSS governance docs (EN + zh-CN) and the comments whose unlayered rationale the rewrite obsoleted are aligned in the same commit.Merge order
Development was parallel to PR 0 (file-disjoint), but merge is serial: do not merge until PR 0 (visual-contract harness + baselines) is on
main, then rebase and re-runcheck:visual-contractas the final gate. The harness scripts and baseline fixtures are deliberately not part of this PR — they ship with PR 0.