refactor(ui): CSS architecture debt cleanup (post #430 converge)

[Astro-Han]

Background

The #430 converge series (motion / typography / spacing) is fully merged and token governance is complete. The post-converge CSS architecture cleanup is tracked here; the React-side cleanup is tracked separately in #477.

Verified against main at 2791ea4c on 2026-07-04, after #480, #485, #487, #508, and #512 merged.

Scope

This issue is CSS-only. Token governance is already done (radius / z-index / color / shadow / motion / typography / spacing all have converge contracts). This issue covers CSS engineering structure, cascade safety, strict parser hygiene, and stylesheet maintainability, not token values or visual redesign.

High-priority CSS cleanup from the original audit is now effectively complete. The only remaining item is a low-priority directionality hygiene pass, which should be done only if we decide it is worth the review cost.

Completed

P0 — CSS parse hygiene is done

Done in #480 fix(ui-css): clean renderer css hygiene.

What changed:

• Fixed the strict parser failure in styles/settings/nav-sidebar.css.
• Added a renderer CSS parse contract over the renderer CSS tree.
• Deleted dead html[data-theme...] CSS selectors.
• Deleted the --font-sans / --font-mono self-referential declarations.
• Added narrow regression assertions so data-theme selectors and font-token self references do not return.

Expected visual impact: none.

P0/P1 — Cascade strategy and input focus resets are done

Done in #485 refactor(ui-css): settle cascade and important resets.

What changed:

• Settled the renderer cascade strategy so local feature styles no longer depend on mixed layered / unlayered override paths.
• Moved embedded bare-field focus/ring behavior into explicit chrome-less input / textarea paths instead of page-level !important resets.
• Narrowed and locked the renderer !important audit.
• Kept visual behavior stable with CSS contracts and targeted smoke coverage.

Expected visual impact: none intended.

P1 — module-pages.css ownership split is done

Done in #487 refactor(ui-css): split module styles.

What changed:

• Split the old catch-all module-pages.css into focused child stylesheets under styles/module-pages/.
• Kept the parent stylesheet as an ordered manifest.
• Added ownership contracts so module-page styles do not absorb global/shared/chat/settings selectors again.
• Moved cross-owner styles back to their real owners during review.

Expected visual impact: none.

Remaining

P2 — Logical vs physical properties are optional / deferred

The original audit found mixed physical and logical CSS properties (padding-left vs padding-inline, margin-left vs margin-inline, border-left vs border-inline-start). This remains low impact for the current Electron desktop app because there is no active RTL support requirement.

Recommended handling:

• Do not start a broad mechanical pass unless we decide directionality hygiene is worth a dedicated review.
• If we do it, keep it to one CSS-only PR with a small allowlist for semantic physical directions, for example a left accent rail.
• Do not bundle it with visual polish or Tailwind migration.

Close criteria

This issue can be closed once we either:

• decide to defer the logical/physical property pass, or
• land one small follow-up PR for that pass.

Out of scope

• Width / height / inset bare px tracking from refactor(ui): converge design-token magic numbers (motion, typography, spacing) #430.
• Full Tailwind migration.
• Visual redesign / aesthetic polish.
• React architecture debt, tracked in refactor(ui): React architecture debt cleanup (post #430 converge) #477.

[Astro-Han]

Proposed 5-PR roadmap

Use this as the canonical tracker for the post-#430 cleanup. CSS work stays owned by this issue; React work stays owned by #477 and is cross-linked there. PR bodies should use Part of #476 / Part of #477 until the final cleanup PR is ready to close the issue.

1. fix(ui-css): clean renderer css hygiene

   • Fix the styles/settings/nav-sidebar.css parser failure.
   • Delete dead [data-theme] selectors.
   • Delete --font-sans / --font-mono self references.
   • Add a renderer CSS parse contract.
   • Expected visual impact: none.

2. refactor(ui-css): settle cascade and important resets

   • Pick and enforce the renderer cascade strategy.
   • Add or route through a chrome-less input / textarea path.
   • Move ring-reset behavior out of page-level !important CSS.
   • Narrow the renderer !important allowlist.
   • Expected visual impact: none intended; verify with computed-style checks and targeted screenshots.

3. refactor(ui-css): split module styles

   • Split module-pages.css by domain while preserving import order and selector behavior.
   • Keep this as a mechanical move, not a visual redesign.
   • Expected visual impact: none.

4. fix(ui-react): harden async and lazy boundaries (tracked by refactor(ui): React architecture debt cleanup (post #430 converge) #477)

   • Add .catch handling to actionable Promise paths.
   • Add compact Suspense fallbacks only where an existing loading pattern can be reused.
   • If a new skeleton visual design is needed, split that into a separate design-led PR.

5. refactor(ui-react): split large components and state (tracked by refactor(ui): React architecture debt cleanup (post #430 converge) #477)

   • Split tool-activity.tsx preview components.
   • Split session-list-panel.tsx into sessions / skills / plan reminders / daily review sections.
   • Aggregate AppShell per-session state with a local reducer.
   • Add targeted memo boundaries after the splits if props are stable.
   • If this becomes too large in implementation, split into "component split" and "AppShell reducer" while keeping the same React architecture track.

Design boundary: default to Codex for the zero-visual-change PRs above. Use opencode + GLM-5.2 only if we decide to introduce new skeleton visuals or redesign the input focus ring instead of preserving current appearance.

[Astro-Han]

PR2 opened: #485 refactor(ui-css): settle cascade and important resets.\n\nScope: settle renderer feature stylesheet cascade by removing local @layer wrappers, route embedded bare fields through explicit chrome-less input/textarea paths, and retire the three page-level important ring-reset sites.\n\nThis remains Refs #476, not closing the issue.

[Astro-Han]

PR3 opened: #487 refactor(ui-css): split module styles.\n\nScope: split the old 2141-line module-pages.css into focused child stylesheets under styles/module-pages/, keep the same renderer import slot as an ordered manifest, and add a contract so new module rules do not grow the catch-all file again.\n\nThis remains Refs #476, not closing the issue.

[Astro-Han]

Roadmap update: the React-side PR5 listed in the original roadmap is superseded by the finer-grained #477 plan.

Instead of one large refactor(ui-react): split large components and state PR, #477 now tracks three top-level React PRs:

• PR5: refactor(ui-react): split tool activity previews
• PR6: refactor(ui-react): split session list modules
• PR7: refactor(ui-react): consolidate app shell session state

CSS-side ownership remains unchanged on this issue. React PR bodies should continue to use Part of #477, not Part of #476.

[Astro-Han]

CSS 侧 roadmap 全部完成，关闭本 issue。

• PR1 fix(ui-css): clean renderer css hygiene #480 clean renderer css hygiene
• PR2 refactor(ui-css): settle cascade and important resets #485 settle cascade and important resets
• PR3 refactor(ui-css): split module styles #487 split module styles

main 上 5 个 CSS contract（renderer-css-parse / renderer-important-audit / renderer-style-layer-cascade / bare-field-chrome / renderer-module-styles）全绿。data-theme 选择器清零，module-pages.css 按域拆为 4 个子文件（2141→4 行 manifest），!important 收敛到 13 项 allowlist。