| 1 | # WebUI CSS DOX |
| 2 | |
| 3 | ## Purpose |
| 4 | |
| 5 | - Own shared stylesheet modules for the WebUI. |
| 6 | - Keep shared visual primitives stable across components and pages. |
| 7 | |
| 8 | ## Ownership |
| 9 | |
| 10 | - Each CSS file owns a named surface or primitive family such as buttons, messages, modals, notifications, scheduler, settings, surfaces, tables, or toast. |
| 11 | - `loading-indicators.css` owns reusable loading visuals; `messages.css` owns chat-history paging placement, the context-switch splash surface, and lazy message-preview states in addition to message presentation. |
| 12 | - Component-specific styles should usually stay inside the component HTML unless they are intentionally shared. |
| 13 | - `modals.css` owns the shared stacked modal shell, backdrop, scroll area, footer slot, modal button classes, floating/no-backdrop modal behavior, and shared modal section primitives. |
| 14 | - `surfaces.css` owns surface modal switchers, action rails, draggable header affordances, focus-button state, and right-canvas surface primitives. |
| 15 | - `index.css` defines global theme variables such as `--color-*`, `--spacing-*`, `--font-size-*`, and `--transition-speed`. |
| 16 | |
| 17 | ## Local Contracts |
| 18 | |
| 19 | - Use existing CSS variables and naming patterns before introducing new global tokens. |
| 20 | - Avoid broad selectors that unexpectedly restyle plugin UI or unrelated components. |
| 21 | - Keep layout rules responsive and verify text does not overflow fixed controls. |
| 22 | - Shared modal buttons use `btn btn-ok` for positive actions and `btn btn-cancel` for dismissive or negative actions. |
| 23 | - Shared compact text actions use `.text-button`; component-local styles may adjust layout or sizing but must not be the only definition of the primitive. |
| 24 | - Modal footer action order is positive action first, dismissive or negative action second. |
| 25 | - Modal footers use `.modal-footer` plus `data-modal-footer`; do not redefine `.btn`, `.modal-footer`, `.modal-inner`, or `.modal-scroll` inside components. |
| 26 | - Shared modal sizing keeps `.modal-inner` centered with `width: 90%`, `max-width: 960px`, and `max-height: 90vh`. |
| 27 | - Tall modal bodies must scroll inside `.modal-scroll`; pinned footer content must stay outside that scroll area. |
| 28 | - `.modal-floating` must keep the full-screen shell pointer-transparent while `.modal-inner` remains pointer-active. |
| 29 | - Use `.modal-no-backdrop` only for backdrop suppression without click-through floating behavior. |
| 30 | - Shared modal layers must stay above the mobile right-canvas rail while confirmation dialogs remain above normal modals. |
| 31 | - Generic `.loading` placeholders and their shimmer pseudo-elements remain invisible for the default 500ms loading delay. |
| 32 | - Shared message collapsing targets `.message-collapse-content`; user-message attachments must remain outside that target so expanding text never changes attachment visibility. |
| 33 | - The virtualized chat history disables native scroll anchoring and replay fade-in motion; the message-window renderer owns anchor restoration during atomic page swaps. |
| 34 | - The persistent right panel transitions its background symmetrically between Welcome and chat in 200ms; the Welcome container remains transparent so it cannot hide the return transition. |
| 35 | - Do not add decorative one-note palette changes that conflict with existing WebUI design. |
| 36 | |
| 37 | ## Work Guidance |
| 38 | |
| 39 | - Keep shared CSS small and scoped to clear class families. |
| 40 | - Coordinate class renames with all component and plugin references. |
| 41 | - Prefer improving an existing primitive over creating a near-duplicate style family. |
| 42 | - Use component-local styles for unique layouts and shared CSS for repeated primitives such as modal sections, toolbars, buttons, tables, notifications, and surfaces. |
| 43 | - Preserve modal sizing and scrolling expectations: centered `.modal-inner`, constrained viewport height, body scroll inside `.modal-scroll`, and footer outside the scroll area. |
| 44 | |
| 45 | ## Verification |
| 46 | |
| 47 | - Manually inspect affected WebUI screens at desktop and mobile widths for shared CSS changes. |
| 48 | - Run visual or frontend tests if the touched style has coverage. |
| 49 | - For modal CSS, test a tall modal, a footer modal, a stacked modal, and a floating modal. |
| 50 | |
| 51 | ## Child DOX Index |
| 52 | |
| 53 | No child DOX files. |