Structure legacy-compatible frontend CSS

2026-07-27 11:13:54 +00:00
parent 1509a39d26
commit ab6f4129a9
38 changed files with 466 additions and 366 deletions
@@ -0,0 +1,61 @@
+# Game frontend CSS architecture
+
+The game frontend preserves the rendered contract of `ref/sam`; CSS reuse is
+not a reason to normalize a page's width, height, typography, texture, or
+interaction states. When reuse and the reference geometry conflict, the
+reference geometry wins.
+
+## Layers
+
+`app/game-frontend/src/assets/main.css` is the single global entry point. It
+loads the following layers:
+
+1. `styles/tokens.css`: exact shared font, color, and `/image/game` texture
+   values. These are value aliases only and must resolve to the same computed
+   value as the ref page.
+2. `styles/game-shell.css`: the flexible shell shared by the main dashboard,
+   public dashboard, and chief center. Only declarations proven identical
+   across those screens belong here.
+3. `styles/ref-shell.css`: fixed ref geometry, including the 1000px desktop /
+   500px mobile family used by the battle center. Its namespace stays separate
+   from the flexible shell so a generic responsive rule cannot override it.
+4. Scoped SFC styles: page-specific grids, fixed table dimensions, selectors,
+   and state styling. These remain closest to the DOM contract they implement.
+
+## Class naming
+
+- `.game-shell`, `.game-shell__header`, `.game-shell__actions`: flexible
+  application shell.
+- `.ref-shell`, `.ref-shell__topbar`, `.ref-shell__control`: measured legacy
+  shell and controls.
+- `.game-feedback--error`, `.ref-feedback--error`: feedback scoped to its
+  visual family.
+- Feature-specific classes stay namespaced by their feature or component.
+  Generic names such as `.title`, `.error`, `.ghost`, `.stack`, and
+  `.layout-grid` must not be promoted from a scoped SFC merely because the same
+  spelling appears elsewhere.
+
+Existing feature hooks may remain while a screen is migrated, but new shared
+presentation must be selected through one of the explicit shell namespaces.
+
+## Consolidation rule
+
+Before moving declarations out of an SFC:
+
+1. Compare every same-named selector's declarations and semantic role.
+2. Confirm the affected pages use the same layout family.
+3. Record desktop and mobile `getBoundingClientRect()` and
+   `getComputedStyle()` values before the move.
+4. Move only identical declarations; keep exceptions in the owning SFC.
+5. Re-run Chromium geometry plus hover, focus, active, and disabled states.
+
+The main page and chief center are the flexible-shell references. The battle
+center is the fixed ref-shell reference. If another page has a measured ref
+contract that differs from both, preserve that page's local contract rather
+than forcing it into either family.
+
+## Asset boundary
+
+The CSS variables contain `/image/game/*` URLs but do not import or copy image
+files. Caddy continues to own `/image/*`; Vite must not rewrite the image tree
+as application assets.