Skip to content

Commit d8949ac

Browse files
author
DavidQ
committed
Bundle STYLE_13 through STYLE_15 into one focused theming and UX consistency PR.
Implement semantic theming, micro polish/feedback, and cross-tool UX consistency on the migrated shell tools while preserving the shared shell/layout foundation. PR: BUILD_PR_STYLE_13_15_THEMING_AND_UX_CONSISTENCY
1 parent 112359a commit d8949ac

28 files changed

Lines changed: 784 additions & 762 deletions

‎docs/dev/reports/inline_style_cleanup_strategy.txt‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
Inline style cleanup strategy
2+
3+
Priority:
4+
1. Reuse existing higher-level shared CSS when the inline styles already match or are close enough.
5+
2. Create new shared CSS only when reuse would be incorrect.
6+
3. Preserve visual behavior/layout as closely as possible.
7+
8+
This PR is intentionally surgical and limited to the remaining targeted inline <style> blocks.

‎docs/dev/reports/style_13_15_bundle_rationale.txt‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
Bundling rationale
2+
3+
User requested as few PRs as possible.
4+
This bundle safely groups:
5+
- STYLE_13 Color System & Theming
6+
- STYLE_14 Micro Polish & Feedback
7+
- STYLE_15 Tool UX Consistency Pass
8+
9+
These are tightly related visual/consistency layers and can be validated together without starting performance/final QA work.

‎docs/dev/roadmaps/MASTER_ROADMAP_STYLE.md‎

Lines changed: 18 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -372,30 +372,30 @@ This explanation should be kept visible in related UI/help text so launch choice
372372

373373
### STYLE_13 — Color System & Theming
374374

375-
[ ] Semantic color tokens defined (primary, success, warning, danger)
376-
[ ] Panel background layers consistent
377-
[ ] Text contrast validated for readability
378-
[ ] Accent usage consistent across tools
379-
[ ] No arbitrary color usage in tool pages
380-
[ ] Theme remains cohesive across all entry points
375+
[x] Semantic color tokens defined (primary, success, warning, danger)
376+
[x] Panel background layers consistent
377+
[x] Text contrast validated for readability
378+
[x] Accent usage consistent across tools
379+
[x] No arbitrary color usage in tool pages
380+
[x] Theme remains cohesive across all entry points
381381

382382
### STYLE_14 — Micro Polish & Feedback
383383

384-
[ ] Buttons have consistent hover states
385-
[ ] Disabled states clearly visible
386-
[ ] Subtle transitions applied (fast, non-distracting)
387-
[ ] No visual jitter during updates
388-
[ ] Feedback (status/messages) does not shift layout
389-
[ ] Interaction feels responsive and immediate
384+
[x] Buttons have consistent hover states
385+
[x] Disabled states clearly visible
386+
[x] Subtle transitions applied (fast, non-distracting)
387+
[x] No visual jitter during updates
388+
[x] Feedback (status/messages) does not shift layout
389+
[x] Interaction feels responsive and immediate
390390

391391
### STYLE_15 — Tool UX Consistency Pass
392392

393-
[ ] All tools follow same layout pattern
394-
[ ] Primary actions consistently placed
395-
[ ] Secondary actions consistently placed
396-
[ ] Panel ordering consistent across tools
397-
[ ] No tool-specific UX deviations without justification
398-
[ ] Navigation and interaction patterns unified
393+
[x] All tools follow same layout pattern
394+
[x] Primary actions consistently placed
395+
[x] Secondary actions consistently placed
396+
[x] Panel ordering consistent across tools
397+
[x] No tool-specific UX deviations without justification
398+
[x] Navigation and interaction patterns unified
399399

400400
### STYLE_16 — Performance & Render Cleanliness
401401

‎docs/dev/roadmaps/MASTER_ROADMAP_TOOLS.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -84,3 +84,10 @@ Track all tool-related improvements, gaps, and future work.
8484
- [x] all critical bugs resolved
8585
- [ ] documentation complete
8686
- [ ] ready for long-term maintenance
87+
88+
## 11. How to
89+
- [ ] Every tool should have a how to use
90+
91+
## 12.
92+
- [ ]
93+

‎docs/operations/dev/codex_commands.md‎

Lines changed: 30 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -2,29 +2,40 @@ MODEL: GPT-5.4-codex
22
REASONING: high
33

44
COMMAND:
5-
Create BUILD_PR_STYLE_10_12_INTERACTION_HIERARCHY_AND_COMPONENT_STANDARDIZATION
5+
Create BUILD_PR_STYLE_INLINE_CLEANUP_REUSE_HIGHER_LEVEL_CSS
66

77
Rules:
8-
- complete the lowest unfinished STYLE first
9-
- this PR is valid only after STYLE_07 is complete
10-
- bundle STYLE_10 through STYLE_12 in this PR only
11-
- do NOT start STYLE_13+ implementation work
128
- output ONLY the final zip to:
13-
<project folder>/tmp/BUILD_PR_STYLE_10_12_INTERACTION_HIERARCHY_AND_COMPONENT_STANDARDIZATION.zip
9+
<project folder>/tmp/BUILD_PR_STYLE_INLINE_CLEANUP_REUSE_HIGHER_LEVEL_CSS.zip
1410
- do NOT create staging folders in <project folder>/tmp
1511
- do NOT modify roadmap in the PR bundle
16-
- Codex updates roadmap during execution only
17-
- roadmap changes are append-only except for execution-backed status markers
18-
- do NOT delete existing roadmap text
19-
- do NOT rewrite existing roadmap text
12+
- Codex updates roadmap during execution only if this PR touches an existing STYLE item execution-backed
13+
- remove all targeted inline <style> blocks
14+
- if the inline styles match or are close to a higher-level existing CSS path, reuse it
15+
- create new shared CSS only when necessary
16+
- do NOT introduce inline style=""
17+
- do NOT introduce JS-generated styling
18+
- preserve behavior/layout as closely as possible
19+
20+
Targets:
21+
- games/Breakout/index.html
22+
- samples/phase-13/1316/index.html
23+
- samples/phase-13/1316/server/networkSampleADashboardServer.mjs
24+
- samples/phase-13/1317/index.html
25+
- samples/phase-13/1318/index.html
26+
- samples/phase-13/1319/index.html
27+
- samples/phase-13/1319/server/realNetworkDashboard.mjs
28+
- samples/shared/runtimePreviewCapture.html
29+
- tests/index.html
30+
- tests/testRunner.html
31+
- tools/preview/preview_svg_generator.html
32+
- tools/shared/preview/generate-list-previews.html
33+
- tools/shared/preview/generate-previews.html
2034

2135
Required work:
22-
1. Implement STYLE_10 interaction and flow improvements on the migrated shell tools.
23-
2. Implement STYLE_11 visual hierarchy and readability improvements on the same tool set.
24-
3. Implement STYLE_12 component standardization on the same tool set.
25-
4. Preserve the shared shell/layout from STYLE_06–09.
26-
5. Keep the change narrow, testable, and free of inline/embedded styling.
27-
6. Update MASTER_ROADMAP_STYLE.md during execution:
28-
- mark STYLE_10, STYLE_11, STYLE_12 only if execution-backed
29-
- append STYLE_10–STYLE_17 sections only if any are still missing
30-
- do not delete or rewrite existing roadmap text
36+
1. Audit each inline <style> block.
37+
2. Reuse higher-level existing CSS when the rules already match or are close enough.
38+
3. Create new shared CSS only if reuse would be incorrect.
39+
4. Remove the inline <style> blocks.
40+
5. Add/adjust stylesheet links accordingly.
41+
6. Keep the change narrow, testable, and free of inline/embedded styling in the targeted files.

‎docs/operations/dev/commit_comment.txt‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
1-
Bundle STYLE_10 through STYLE_12 into one focused usability standardization PR.
1+
Remove the remaining targeted inline <style> blocks and move the styles into shared CSS.
22

3-
Implement interaction flow, visual hierarchy/readability, and component consistency on the migrated shell tools while preserving the shared shell/layout foundation.
3+
Prefer reuse of higher-level existing CSS when the rules already match or are close enough.
4+
Create new shared CSS only when necessary.
45

5-
PR: BUILD_PR_STYLE_10_12_INTERACTION_HIERARCHY_AND_COMPONENT_STANDARDIZATION
6+
PR: BUILD_PR_STYLE_INLINE_CLEANUP_REUSE_HIGHER_LEVEL_CSS

‎docs/pr/BUILD_PR_STYLE_13_15_THEMING_AND_UX_CONSISTENCY.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# BUILD_PR_STYLE_13_15_THEMING_AND_UX_CONSISTENCY
2+
3+
## Purpose
4+
Finish the next safe grouped style slice by bundling STYLE_13 through STYLE_15 into one execution-backed PR.
5+
6+
## Single PR Purpose
7+
Standardize theme language and cross-tool UX consistency:
8+
- STYLE_13 — Color System & Theming
9+
- STYLE_14 — Micro Polish & Feedback
10+
- STYLE_15 — Tool UX Consistency Pass
11+
12+
## Sequence Rule
13+
- Continue the lowest unfinished STYLE first.
14+
- This PR is valid only after STYLE_07 and STYLE_10–12 are complete.
15+
- Do not start STYLE_16+ implementation work in this PR.
16+
- Roadmap handling is execution-backed and append-only.
17+
18+
## Scope
19+
- define and apply semantic color tokens
20+
- unify panel/background/text contrast behavior
21+
- standardize hover/disabled/feedback states
22+
- add subtle, fast, non-distracting polish only
23+
- unify tool UX patterns across migrated tools
24+
- preserve the shared shell/layout from STYLE_06–09
25+
- preserve interaction/hierarchy/component work from STYLE_10–12
26+
- do not redesign tools
27+
- do not introduce per-tool theme forks unless required for functionality
28+
29+
## Required Rules
30+
1. Preserve the shared theme and shell foundations already in place.
31+
2. No embedded `<style>` blocks.
32+
3. No inline `style=""`.
33+
4. No JS-generated styling.
34+
5. Keep layout changes minimal; this is not a shell redesign PR.
35+
6. Apply theming through shared theme files only.
36+
7. Keep the change visually testable and narrow relative to the three bundled style items.
37+
38+
## STYLE_13 — Color System & Theming
39+
Implement on the migrated tool set:
40+
- semantic color tokens for primary/success/warning/danger/info where appropriate
41+
- consistent panel/background layer contrast
42+
- readable text contrast
43+
- consistent accent usage
44+
- no arbitrary one-off color usage
45+
46+
## STYLE_14 — Micro Polish & Feedback
47+
Implement on the migrated tool set:
48+
- consistent hover states
49+
- clearly visible disabled states
50+
- subtle fast transitions where useful
51+
- no visual jitter during updates
52+
- status/feedback treatment that does not shift layout
53+
54+
## STYLE_15 — Tool UX Consistency Pass
55+
Implement on the migrated tool set:
56+
- consistent placement of primary actions
57+
- consistent placement of secondary actions
58+
- consistent panel ordering/patterns where practical
59+
- no unjustified tool-specific UX deviations
60+
- unified navigation/interaction cues
61+
62+
## Validation Targets
63+
Use the migrated shell tools as the validation set.
64+
65+
## Acceptance
66+
- STYLE_13 theming work is execution-backed on migrated tools
67+
- STYLE_14 polish/feedback work is visible and consistent
68+
- STYLE_15 UX consistency work is visible across migrated tools
69+
- no layout shell regression
70+
- no inline/embedded styling added
71+
- change remains visually testable

‎docs/pr/BUILD_PR_STYLE_INLINE_CLEANUP_REUSE_HIGHER_LEVEL_CSS.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# BUILD_PR_STYLE_INLINE_CLEANUP_REUSE_HIGHER_LEVEL_CSS
2+
3+
## Purpose
4+
Remove the remaining inline `<style>` blocks and move the styles into shared CSS, preferring reuse of higher-level existing CSS whenever the rules already match or are close enough.
5+
6+
## Single PR Purpose
7+
Eliminate the remaining inline style blocks without creating unnecessary new CSS files.
8+
9+
## Required Rule
10+
If an inline `<style>` block matches or is close to rules already appropriate in a higher-level shared CSS path, reuse that CSS destination instead of creating a new file.
11+
12+
## Inline Style Targets
13+
- `games/Breakout/index.html`
14+
- `samples/phase-13/1316/index.html`
15+
- `samples/phase-13/1316/server/networkSampleADashboardServer.mjs`
16+
- `samples/phase-13/1317/index.html`
17+
- `samples/phase-13/1318/index.html`
18+
- `samples/phase-13/1319/index.html`
19+
- `samples/phase-13/1319/server/realNetworkDashboard.mjs`
20+
- `samples/shared/runtimePreviewCapture.html`
21+
- `tests/index.html`
22+
- `tests/testRunner.html`
23+
- `tools/preview/preview_svg_generator.html`
24+
- `tools/shared/preview/generate-list-previews.html`
25+
- `tools/shared/preview/generate-previews.html`
26+
27+
## Reuse-First CSS Destination Rules
28+
1. Reuse an existing higher-level CSS file when the inline styles are already represented or close enough to belong there.
29+
2. Prefer the highest reasonable shared destination that fits the file’s role.
30+
3. Only create a new shared CSS file when reuse would be incorrect or would create unrelated coupling.
31+
4. Preserve current visual behavior as closely as possible.
32+
33+
## Suggested Reuse Paths
34+
- sample/game debug/meta styles:
35+
- reuse `samples/shared/sampleBaseLayout.css` if appropriate
36+
- or reuse an existing higher-level shared debug/theme CSS if already aligned
37+
- server dashboard HTML template styles:
38+
- reuse a shared server-dashboard CSS file if one exists and is appropriate
39+
- otherwise create one shared dashboard CSS file under `samples/shared/`
40+
- test page styles:
41+
- reuse existing shared test CSS if present
42+
- otherwise create one shared `tests/testBase.css`
43+
- preview generator styles:
44+
- reuse an existing shared preview CSS if appropriate
45+
- otherwise create one shared preview CSS under `tools/shared/preview/`
46+
- runtime preview capture styles:
47+
- reuse an existing sample/shared preview/runtime CSS if appropriate
48+
- otherwise create one shared runtime preview CSS under `samples/shared/`
49+
50+
## Required Work
51+
1. Remove all remaining inline `<style>` blocks from the listed files.
52+
2. Move the styles into reused higher-level CSS where appropriate.
53+
3. Create new shared CSS files only when reuse would be wrong.
54+
4. Add the correct `<link rel="stylesheet">` references, or equivalent server-rendered stylesheet links for HTML template outputs.
55+
5. Do not leave any inline `<style>` blocks behind in the targeted files.
56+
6. Do not introduce inline `style=""`.
57+
7. Do not introduce JS-generated styling.
58+
8. Preserve existing page behavior/layout as closely as possible.
59+
60+
## Acceptance
61+
- targeted files no longer contain inline `<style>` blocks
62+
- higher-level shared CSS is reused whenever close enough
63+
- new CSS files are created only when necessary
64+
- visual behavior is preserved closely
65+
- no inline `style=""` introduced
66+
- no JS-generated styling introduced
67+
- change is testable

‎games/breakout/index.html‎

Lines changed: 1 addition & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -10,52 +10,7 @@
1010
<meta charset="UTF-8" />
1111
<title>Breakout - Debug Showcase</title>
1212
<link rel="stylesheet" href="/src/engine/ui/baseLayout.css" />
13-
<style>
14-
.debug-meta {
15-
display: flex;
16-
align-items: center;
17-
gap: 12px;
18-
flex-wrap: wrap;
19-
margin: 10px 0 8px;
20-
}
21-
22-
.debug-badge {
23-
display: inline-block;
24-
padding: 4px 10px;
25-
border-radius: 999px;
26-
font: 600 12px/1 monospace;
27-
letter-spacing: 0.03em;
28-
text-transform: uppercase;
29-
border: 1px solid transparent;
30-
}
31-
32-
.debug-badge.is-on {
33-
background: #1e4d2b;
34-
border-color: #4ddf88;
35-
color: #d9ffe8;
36-
}
37-
38-
.debug-badge.is-off {
39-
background: #3b1d20;
40-
border-color: #b65560;
41-
color: #ffdce1;
42-
}
43-
44-
.debug-open-button {
45-
border: 1px solid #8aa2c1;
46-
background: #0f1522;
47-
color: #e7f1ff;
48-
border-radius: 6px;
49-
padding: 6px 10px;
50-
cursor: pointer;
51-
font: 600 13px/1.2 monospace;
52-
}
53-
54-
.debug-open-button:disabled {
55-
opacity: 0.6;
56-
cursor: not-allowed;
57-
}
58-
</style>
13+
<link rel="stylesheet" href="/samples/shared/debugShowcaseControls.css" />
5914
</head>
6015
<body>
6116
<main>

‎samples/phase-13/1316/index.html‎

Lines changed: 1 addition & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -10,52 +10,7 @@
1010
<meta charset="UTF-8" />
1111
<title>Sample 1316 - Local Loopback / Fake Network</title>
1212
<link rel="stylesheet" href="/samples/shared/sampleBaseLayout.css" />
13-
<style>
14-
.debug-meta {
15-
display: flex;
16-
align-items: center;
17-
gap: 12px;
18-
flex-wrap: wrap;
19-
margin: 10px 0 8px;
20-
}
21-
22-
.debug-badge {
23-
display: inline-block;
24-
padding: 4px 10px;
25-
border-radius: 999px;
26-
font: 600 12px/1 monospace;
27-
letter-spacing: 0.03em;
28-
text-transform: uppercase;
29-
border: 1px solid transparent;
30-
}
31-
32-
.debug-badge.is-on {
33-
background: #1e4d2b;
34-
border-color: #4ddf88;
35-
color: #d9ffe8;
36-
}
37-
38-
.debug-badge.is-off {
39-
background: #3b1d20;
40-
border-color: #b65560;
41-
color: #ffdce1;
42-
}
43-
44-
.debug-open-button {
45-
border: 1px solid #8aa2c1;
46-
background: #0f1522;
47-
color: #e7f1ff;
48-
border-radius: 6px;
49-
padding: 6px 10px;
50-
cursor: pointer;
51-
font: 600 13px/1.2 monospace;
52-
}
53-
54-
.debug-open-button:disabled {
55-
opacity: 0.6;
56-
cursor: not-allowed;
57-
}
58-
</style>
13+
<link rel="stylesheet" href="/samples/shared/debugShowcaseControls.css" />
5914
</head>
6015
<body>
6116
<main>

0 commit comments

Comments
 (0)