Level 18.5 CSS/UI Normalization (Overlay Slice)

DavidQ · DavidQ · commit b5c03cfb6ed0 · 2026-04-16T21:06:13.000-04:00
- Flattened CSS layers
- Removed redundant styles
- Aligned UI classes to shared system
diff --git a/docs/dev/CODEX_COMMANDS.md b/docs/dev/CODEX_COMMANDS.md
@@ -2,11 +2,10 @@ MODEL: GPT-5.3-codex
 REASONING: high
 
 COMMAND:
-- Scan overlay runtime files only
-- Normalize naming conventions
-- Deduplicate helpers
-- Fix import/export patterns
-- Validate tests
+- Inspect overlay CSS only
+- Flatten CSS structure
+- Replace redundant styles with shared classes
+- Validate rendering + tests
 
 Output:
-<project folder>/tmp/BUILD_PR_LEVEL_18_4_CODEBASE_CONSISTENCY_OVERLAY_SLICE.zip
+<project folder>/tmp/BUILD_PR_LEVEL_18_5_CSS_UI_NORMALIZATION_OVERLAY_SLICE.zip
diff --git a/docs/dev/COMMIT_COMMENT.txt b/docs/dev/COMMIT_COMMENT.txt
@@ -1,6 +1,5 @@
-Level 18.4 Codebase Consistency (Overlay Slice)
+Level 18.5 CSS/UI Normalization (Overlay Slice)
 
-- Normalized naming
-- Removed duplicate helpers
-- Fixed import/export anti-patterns
-- Enforced consistency rules
+- Flattened CSS layers
+- Removed redundant styles
+- Aligned UI classes to shared system
diff --git a/docs/dev/reports/validation_checklist.txt b/docs/dev/reports/validation_checklist.txt
@@ -1,4 +1,4 @@
-[ ] naming consistent
-[ ] no duplicate helpers
-[ ] imports clean
+[ ] no visual regressions
+[ ] CSS flattened
+[ ] shared classes used
 [ ] tests pass
diff --git a/docs/pr/BUILD_PR_LEVEL_18_5_CSS_UI_NORMALIZATION_OVERLAY_SLICE.md b/docs/pr/BUILD_PR_LEVEL_18_5_CSS_UI_NORMALIZATION_OVERLAY_SLICE.md
@@ -0,0 +1,19 @@
+# BUILD PR LEVEL 18.5 — CSS & UI Normalization (Overlay Slice)
+
+Purpose:
+Normalize overlay UI styling and CSS structure.
+
+Scope:
+- Overlay UI only
+- No global CSS refactor
+
+Changes:
+- Flatten CSS layers for overlay
+- Enforce shared UI class usage
+- Remove redundant styles
+- Align overlay styling with shared conventions
+
+Validation:
+- Overlay renders correctly
+- No visual regressions
+- Tests pass
diff --git a/samples/phase-17/1708/index.html b/samples/phase-17/1708/index.html
@@ -10,16 +10,17 @@
   <meta charset="UTF-8" />
   <title>Sample 1708 - Real Gameplay Mini-Game</title>
   <link rel="stylesheet" href="../../../src/engine/ui/baseLayout.css" />
+  <link rel="stylesheet" href="../shared/overlaySampleLayout.css" />
 </head>
 <body>
-  <main>
-    <h1>Sample 1708 - Real Gameplay Mini-Game</h1>
-    <p>Playable 3D mini-game using existing engine systems: movement, hazards, objective scoring, camera follow, and debug panels.</p>
-    <canvas id="game" width="960" height="540"></canvas>
+  <main class="overlay-sample-main">
+    <h1 class="overlay-sample-title">Sample 1708 - Real Gameplay Mini-Game</h1>
+    <p class="overlay-sample-summary">Playable 3D mini-game using existing engine systems: movement, hazards, objective scoring, camera follow, and debug panels.</p>
+    <canvas id="game" class="overlay-sample-canvas" width="960" height="540"></canvas>
 
-    <section>
-      <h3>Engine Classes Used</h3>
-      <ul>
+    <section class="overlay-sample-engine-section">
+      <h3 class="overlay-sample-engine-title">Engine Classes Used</h3>
+      <ul class="overlay-sample-engine-list">
         <li>Engine</li>
         <li>Scene</li>
       </ul>
diff --git a/samples/phase-17/1709/index.html b/samples/phase-17/1709/index.html
@@ -10,16 +10,17 @@
   <meta charset="UTF-8" />
   <title>Sample 1709 - Movement Models Lab</title>
   <link rel="stylesheet" href="../../../src/engine/ui/baseLayout.css" />
+  <link rel="stylesheet" href="../shared/overlaySampleLayout.css" />
 </head>
 <body>
-  <main>
-    <h1>Sample 1709 - Movement Models Lab</h1>
-    <p>Compares direct axis movement, tank rotation controls, and weighted movement using existing engine systems.</p>
-    <canvas id="game" width="960" height="540"></canvas>
+  <main class="overlay-sample-main">
+    <h1 class="overlay-sample-title">Sample 1709 - Movement Models Lab</h1>
+    <p class="overlay-sample-summary">Compares direct axis movement, tank rotation controls, and weighted movement using existing engine systems.</p>
+    <canvas id="game" class="overlay-sample-canvas" width="960" height="540"></canvas>
 
-    <section>
-      <h3>Engine Classes Used</h3>
-      <ul>
+    <section class="overlay-sample-engine-section">
+      <h3 class="overlay-sample-engine-title">Engine Classes Used</h3>
+      <ul class="overlay-sample-engine-list">
         <li>Engine</li>
         <li>Scene</li>
       </ul>
diff --git a/samples/phase-17/1710/index.html b/samples/phase-17/1710/index.html
@@ -10,16 +10,17 @@
   <meta charset="UTF-8" />
   <title>Sample 1710 - Real Gameplay Mini-Game</title>
   <link rel="stylesheet" href="../../../src/engine/ui/baseLayout.css" />
+  <link rel="stylesheet" href="../shared/overlaySampleLayout.css" />
 </head>
 <body>
-  <main>
-    <h1>Sample 1710 - Real Gameplay Mini-Game</h1>
-    <p>Playable 3D mini-game using existing engine systems: movement, hazards, objective scoring, camera follow, and debug panels.</p>
-    <canvas id="game" width="960" height="540"></canvas>
+  <main class="overlay-sample-main">
+    <h1 class="overlay-sample-title">Sample 1710 - Real Gameplay Mini-Game</h1>
+    <p class="overlay-sample-summary">Playable 3D mini-game using existing engine systems: movement, hazards, objective scoring, camera follow, and debug panels.</p>
+    <canvas id="game" class="overlay-sample-canvas" width="960" height="540"></canvas>
 
-    <section>
-      <h3>Engine Classes Used</h3>
-      <ul>
+    <section class="overlay-sample-engine-section">
+      <h3 class="overlay-sample-engine-title">Engine Classes Used</h3>
+      <ul class="overlay-sample-engine-list">
         <li>Engine</li>
         <li>Scene</li>
       </ul>
diff --git a/samples/phase-17/1711/index.html b/samples/phase-17/1711/index.html
@@ -10,16 +10,17 @@
   <meta charset="UTF-8" />
   <title>Sample 1711 - Movement Models Lab</title>
   <link rel="stylesheet" href="../../../src/engine/ui/baseLayout.css" />
+  <link rel="stylesheet" href="../shared/overlaySampleLayout.css" />
 </head>
 <body>
-  <main>
-    <h1>Sample 1711 - Movement Models Lab</h1>
-    <p>Compares direct axis movement, tank rotation controls, and weighted movement using existing engine systems.</p>
-    <canvas id="game" width="960" height="540"></canvas>
+  <main class="overlay-sample-main">
+    <h1 class="overlay-sample-title">Sample 1711 - Movement Models Lab</h1>
+    <p class="overlay-sample-summary">Compares direct axis movement, tank rotation controls, and weighted movement using existing engine systems.</p>
+    <canvas id="game" class="overlay-sample-canvas" width="960" height="540"></canvas>
 
-    <section>
-      <h3>Engine Classes Used</h3>
-      <ul>
+    <section class="overlay-sample-engine-section">
+      <h3 class="overlay-sample-engine-title">Engine Classes Used</h3>
+      <ul class="overlay-sample-engine-list">
         <li>Engine</li>
         <li>Scene</li>
       </ul>
diff --git a/samples/phase-17/1712/index.html b/samples/phase-17/1712/index.html
@@ -10,16 +10,17 @@
   <meta charset="UTF-8" />
   <title>Sample 1712 - Gameplay Metrics & Telemetry</title>
   <link rel="stylesheet" href="../../../src/engine/ui/baseLayout.css" />
+  <link rel="stylesheet" href="../shared/overlaySampleLayout.css" />
 </head>
 <body>
-  <main>
-    <h1>Sample 1712 - Gameplay Metrics & Telemetry</h1>
-    <p>Adds live gameplay metrics and telemetry overlay to a real mini-game using existing debug systems only.</p>
-    <canvas id="game" width="960" height="540"></canvas>
+  <main class="overlay-sample-main">
+    <h1 class="overlay-sample-title">Sample 1712 - Gameplay Metrics & Telemetry</h1>
+    <p class="overlay-sample-summary">Adds live gameplay metrics and telemetry overlay to a real mini-game using existing debug systems only.</p>
+    <canvas id="game" class="overlay-sample-canvas" width="960" height="540"></canvas>
 
-    <section>
-      <h3>Engine Classes Used</h3>
-      <ul>
+    <section class="overlay-sample-engine-section">
+      <h3 class="overlay-sample-engine-title">Engine Classes Used</h3>
+      <ul class="overlay-sample-engine-list">
         <li>Engine</li>
         <li>Scene</li>
       </ul>
diff --git a/samples/phase-17/1713/index.html b/samples/phase-17/1713/index.html
@@ -10,16 +10,17 @@
   <meta charset="UTF-8" />
   <title>Sample 1713 - Final Reference Game</title>
   <link rel="stylesheet" href="../../../src/engine/ui/baseLayout.css" />
+  <link rel="stylesheet" href="../shared/overlaySampleLayout.css" />
 </head>
 <body>
-  <main>
-    <h1>Sample 1713 - Final Reference Game</h1>
-    <p>Final reference mini-game that combines gameplay loop, camera debug panels, collision overlays, and telemetry in one bounded sample.</p>
-    <canvas id="game" width="960" height="540"></canvas>
+  <main class="overlay-sample-main">
+    <h1 class="overlay-sample-title">Sample 1713 - Final Reference Game</h1>
+    <p class="overlay-sample-summary">Final reference mini-game that combines gameplay loop, camera debug panels, collision overlays, and telemetry in one bounded sample.</p>
+    <canvas id="game" class="overlay-sample-canvas" width="960" height="540"></canvas>
 
-    <section>
-      <h3>Engine Classes Used</h3>
-      <ul>
+    <section class="overlay-sample-engine-section">
+      <h3 class="overlay-sample-engine-title">Engine Classes Used</h3>
+      <ul class="overlay-sample-engine-list">
         <li>Engine</li>
         <li>Scene</li>
       </ul>
diff --git a/samples/phase-17/shared/overlaySampleLayout.css b/samples/phase-17/shared/overlaySampleLayout.css
@@ -0,0 +1,42 @@
+/*
+Overlay sample page layout normalization.
+Scope is intentionally limited to phase-17 overlay sample pages.
+*/
+
+.overlay-sample-main {
+  width: min(100%, 1000px);
+  margin: 0 auto;
+  padding: 20px;
+  box-sizing: border-box;
+}
+
+.overlay-sample-title {
+  margin: 0 0 10px;
+}
+
+.overlay-sample-summary {
+  margin: 0 0 14px;
+  line-height: 1.5;
+}
+
+.overlay-sample-canvas {
+  display: block;
+  width: 100%;
+  max-width: 960px;
+  height: auto;
+  border: 1px solid #334155;
+}
+
+.overlay-sample-engine-section {
+  margin-top: 14px;
+  color: #dddddd;
+}
+
+.overlay-sample-engine-title {
+  margin: 0 0 6px;
+}
+
+.overlay-sample-engine-list {
+  margin: 0;
+  padding-left: 20px;
+}
diff --git a/tests/runtime/Phase18OverlayCssUiNormalizationSlice.test.mjs b/tests/runtime/Phase18OverlayCssUiNormalizationSlice.test.mjs
@@ -0,0 +1,85 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/16/2026
+Phase18OverlayCssUiNormalizationSlice.test.mjs
+*/
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const repoRoot = path.resolve(__dirname, '..', '..');
+
+const overlaySampleIds = ['1708', '1709', '1710', '1711', '1712', '1713'];
+
+function readOverlaySampleIndex(sampleId) {
+  return fs.readFileSync(
+    path.join(repoRoot, 'samples', 'phase-17', sampleId, 'index.html'),
+    'utf8'
+  );
+}
+
+function assertSharedOverlayCssClasses(sampleId) {
+  const text = readOverlaySampleIndex(sampleId);
+  assert.equal(
+    text.includes('../shared/overlaySampleLayout.css'),
+    true,
+    `Sample ${sampleId} should include shared overlay sample stylesheet.`
+  );
+  assert.equal(
+    text.includes('class="overlay-sample-main"'),
+    true,
+    `Sample ${sampleId} should use normalized main container class.`
+  );
+  assert.equal(
+    text.includes('class="overlay-sample-summary"'),
+    true,
+    `Sample ${sampleId} should use normalized summary class.`
+  );
+  assert.equal(
+    text.includes('class="overlay-sample-canvas"'),
+    true,
+    `Sample ${sampleId} should use normalized canvas class.`
+  );
+  assert.equal(
+    text.includes('class="overlay-sample-engine-section"'),
+    true,
+    `Sample ${sampleId} should use normalized engine section class.`
+  );
+  assert.equal(
+    text.includes('class="overlay-sample-engine-list"'),
+    true,
+    `Sample ${sampleId} should use normalized engine list class.`
+  );
+}
+
+function assertSharedOverlayCssFile() {
+  const cssPath = path.join(repoRoot, 'samples', 'phase-17', 'shared', 'overlaySampleLayout.css');
+  const css = fs.readFileSync(cssPath, 'utf8');
+  const requiredTokens = [
+    '.overlay-sample-main',
+    '.overlay-sample-title',
+    '.overlay-sample-summary',
+    '.overlay-sample-canvas',
+    '.overlay-sample-engine-section',
+    '.overlay-sample-engine-title',
+    '.overlay-sample-engine-list',
+  ];
+  for (const token of requiredTokens) {
+    assert.equal(
+      css.includes(token),
+      true,
+      `Shared overlay sample stylesheet should define ${token}.`
+    );
+  }
+}
+
+export function run() {
+  assertSharedOverlayCssFile();
+  for (const sampleId of overlaySampleIds) {
+    assertSharedOverlayCssClasses(sampleId);
+  }
+}
