# KB Signaling Design System V1 roadmap

## Goal and scope

Deliver a unified, working design standard in this repository, reusable theme.css and Sass sources, and a team-ready adoption skill. Teams will later use the skill to update their applications. WSDMM Central and SignalView B are reference sources only; do not migrate them in this initiative. SignalSync is excluded.

Start from the actual WSDMM Central configuration wizard, including typography and field styling. The supplied company guide and control-ui-central skill are supporting sources; record conflicts. Updated direction: match the actual WSDMM wizard page backgrounds and light/dark card surfaces; this supersedes the earlier neutral-only surface direction. Company accents and other component decisions remain separate. Preserve the preferred wizard field treatment; do not introduce dark-blue double borders. Earlier generated previews are not authoritative.

## Progress

Legend: ✅ complete · 🔵 active · ⏳ waiting for review · ⬜ queued · ⛔ blocked

`[✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅]`

**9 of 9 milestones complete. V1 standard, reusable CSS/Sass, local fonts and team skill are accepted and prepared locally. Publication and application adoption are separate work.**

Milestone counts describe completed deliverables, not percentage of effort. Inspected or drafted does not mean implemented or accepted. Review-ready milestones use ⏳ until user feedback is incorporated and the result is accepted. Keep evidence verification distinct from design approval.

| ID | Status | Milestone | Deliverable / completion check |
|---|---|---|---|
| M0 | ✅ Complete | Scope and reference audit | Actual wizard inspected in both themes; guide/skill conflicts documented; reference-only app scope and KB repository deliverables confirmed. |
| M1 | ✅ Complete | Typography baseline | Present actual wizard heading/body/label/value roles visually; settle responsive sizes, weights, line heights and font assets. Implement the agreed typography in KB with a light/dark example and reusable role tokens. No other component migration. |
| M2 | ✅ Complete | Theme and Sass foundation | Agree surface/text/border roles and separate brand/status roles (surface direction updated to wizard matching in R010). Provide Sass token/theme sources that compile to reusable theme.css, with a documented build command and import example. Verify both themes and consistent generated values. |
| M3 | ✅ Complete | Inputs, selects and textareas | Demonstrate agreed geometry and default/hover/focus/invalid/disabled/readonly states where applicable. Preserve native behavior and label/help/error linkage. Keep dense/login variants explicit; don't force every field to one size. |
| M4 | ✅ Complete | Buttons and chips/badges | Agree action hierarchy, sizing, labels, optional icons, button elevation and state behavior. Distinguish passive status badges from interactive chips and selection. Demonstrate both themes and supported states. |
| M5 | ✅ Complete | Cards and shadows | Agree surfaces, borders, radius, spacing and a small elevation scale. Demonstrate cards and overlays with readable content, restrained shadows and responsive layout. |
| M6 | ✅ Complete | Icons and consistency | Use verified Lucide assets, consistent size/stroke roles, contextual exceptions, currentColor and accessible naming. Check alignment and hit targets across the agreed examples. |
| M7 | ✅ Complete | Integrated reference and reusable artifacts | Finish KB navigation/documentation and component examples. Verify typography and required states in both themes, desktop/mobile, keyboard operation and relevant contrast. Verify CSS-only and Sass consumption; document limitations. |
| M8 | ✅ Complete | Skill and team handoff | Update the skill from the accepted implementation, with exact tokens, imports, examples, exceptions and verification steps. Package the reference, theme.css and Sass sources; validate instructions with a minimal consumer. No application migration. |

## Implementation approach

- Update the KB reference incrementally after the relevant design checkpoint, rather than leaving all integration to M7. Preserve its existing functional interactions.
- Keep one editable token source. Recommended approach: Sass maps/modules emit CSS custom properties into theme.css. Runtime light/dark switching uses those properties. Offer a Sass entry point for consumers without requiring them to duplicate values.
- Keep the reusable theme layer limited to tokens/theme scopes. Put component styles in an explicitly documented layer; avoid unsolicited global element resets in consumer apps.
- Decide public file paths, theme selectors and supported Sass API during M2 before treating them as stable. Document source versus generated files and how regeneration works; don't hand-edit generated CSS.
- Use actual component evidence and a small visual review for each area. Do not turn old skill rules or every existing application value into a universal requirement.
- Avoid broad palette replacements, unrelated prototype repairs, application framework changes, or renaming reference app components. Tempest JSON and live backend/MQTT issues remain outside this roadmap.
- Local changes to kbdesignsystem are in scope. Leave WSDMM Central and SignalView B source unchanged. Do not push, merge or publish without explicit authorization.

## Run and review cadence

Each run should complete a concrete, bounded task within the current milestone. A milestone can take multiple runs; do not force a component area into a single turn.

After every substantive run:

1. Update this file's status strip, milestone table, next-run item, blockers and run log.
2. Report progress in chat using the same visual strip and completed milestone count.
3. State what changed, what was verified, what remains for review, and the next concrete action.
4. Link the relevant visual/example and changed artifacts. Mark blocked/unrun checks explicitly.
5. Use user feedback as the checkpoint before expanding to the next component area. Continue already authorized work within the current area without repeated permission requests.

Chat format:

```text
V1 progress: [✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅] — 3/9 complete
This run: <concrete result>
Verified: <checks and material limits>
Review: <artifact or decision, if needed>
Next: <one bounded task>
```

## Current checkpoint and next run

**V1 complete and accepted locally.** Start with the [integrated reference](examples/components/css.html), [scoped Sass consumer](examples/components/sass.html), [adoption guide](docs/adoption.md), [team skill](skills/kb-design-standard/SKILL.md) and [handoff](docs/handoff.md).

Current field borders/focus are the R027 source roles, verified in [rendered checks](docs/reference/field-border-verification.json) and [native behavior checks](docs/reference/field-border-functional.json). Current action colors are R025, with 108 sampled state/text cases and a 4.80:1 minimum at measured points in [current contrast evidence](docs/reference/button-colors-contrast.json). Earlier stronger-contour/focus contrast results are historical and do not apply to restored subtle source borders. Text, placeholder and error refinements remain documented by component.

Six Sass contracts and generated CSS drift checks pass. Integrated CSS/Sass parity, local-font rendering with external requests blocked and local links are verified. Browser evidence is Chromium-specific, with explicit integration limits; it is not a general accessibility or cross-browser certification.

The user has now requested an organization demo and landing/library audit. See the follow-up below. Application adoption/publication remains separate. Reference applications remain unchanged. Local acceptance preceded the user-authorized GitHub submission in R035; no global skill installation or application deployment is included.

## Open items

- Current field documentation and tokens are authoritative: R027 supersedes R013 border/focus choices; accepted placeholder/error refinements remain. Older images are historical.
- R027 supersedes the stronger M3 contour/focus refinement with source wizard border roles. Preserve one 1px contour and source-specific 2px focus halo; historical contrast claims do not apply to the restored subtle borders.

- The pasted company HTML still lacks kb-standards-stylesheet.css. This blocks claims about that stylesheet, not the wizard-based typography work. Do not invent a replacement.
- The user has superseded the neutral-only surface direction with source wizard backgrounds/cards. R010 implements the gradient, transparency and blur roles; R027 supplies the current field borders/focus.
- R028 supplies seven local Noto Sans normal faces and the upstream OFL notice/provenance. Keep these assets together when distributing; broader language/italic coverage and supported-browser testing remain consumer checks.
- The draft CSS/Sass API is implemented in M2 with a pinned Sass devDependency and lockfile. Public package publishing/versioning remains separate. Local font assets, licenses and copying requirements are supplied in the handoff.

## Reference evidence

Current portable evidence is under docs/reference/ and linked from the component documents. The workspace paths below identify the initial supporting uploads; they are historical provenance, not dependencies of the team skill.

- `/workspace/design-system-v1-review/wizard-typography-baseline.md`
- `/workspace/design-system-v1-review/wizard-typography.json`
- `/workspace/design-system-v1-review/wizard-reference.html`
- `/workspace/design-system-v1-review/wizard-reference.md`
- `/workspace/design-system-v1-review/audit-and-plan.md`
- `/workspace/design-system-v1-review/control-ui-skill-audit.md`
- `/workspace/design-system-v1-review/SKILL.md` — review draft, not installed governance

This roadmap is the current delivery plan. Earlier audit plans remain evidence/backlog; their application migration stages do not define this initiative's scope.

## Run log

| Run | Outcome | Verification | Progress after run | Next |
|---|---|---|---|---|
| R001 — roadmap established | Consolidated confirmed scope, staged deliverables and run/review cadence. Recognized existing audit as M0; kept M1 active because measurement alone isn't design approval or KB implementation. | Rechecked KB manifest/worktree and presence of typography/skill evidence. This run changes documentation only; no application/Sass build claimed. | 1/9 complete; M1 active | Typography-only visual checkpoint in KB. |
| R002 — typography visual checkpoint | Added typography.html/css/js, original wizard comparison captures, portable measured evidence and source/scope documentation; linked from the existing Typography section. | Six roles match at 1440/390px and source breakpoints at 768px in both themes. Custom Noto Sans observed; theme persistence/keyboard toggle, source-image matching, long-text/320px reflow, font-blocked usability and existing KB smoke checks passed. Initial source-image check failed when the server stopped; restarted and verified successfully. | 1/9 complete; M1 ready for review | Incorporate typography feedback; then theme/Sass foundation after acceptance. |

| R003 — reusable theme/Sass foundation | User approved continuation from typography. Added namespaced neutral/brand-anchor/type maps, theme()/type() Sass API, generated theme.css, pinned Sass/lockfile, build/drift scripts, two consumer examples and usage docs. Typography review now consumes the generated theme without changing the visual baseline. | Build/drift checks and 3 Sass contract tests passed. CSS-only and scoped consumers passed at 1440/768/390px; existing typography and KB functional checks passed. No WSDMM/SignalView edits or pushes. | 2/9 complete; M2 ready for review | Review foundation/API, then M3 wizard-based inputs/selects/textareas. |

| R004 — field state checkpoint | User approved foundation continuation. Added generated optional fields.css/Sass mixin, source-based geometry/color roles, native field/state examples and local validation demo; linked from the showcase/typography review. | Both themes/desktop/mobile geometry and native keyboard/validation/reset/FormData checks passed, with no writes or page exceptions. Generated CSS and 4 Sass tests pass; typography and original KB smoke checks pass. Low resting/focus contrast from the source is documented and remains open. | 3/9 complete; M3 review ready with contrast refinement pending | Refine/review field contrast and appearance before M4. |

| R005 — direct wizard fidelity audit | Compared actual Network/Location/Add Device controls against KB; documented exact matches, near-equivalent values, unintended palette drift, modal variant differences and deliberate neutral/semantic adaptations. No styling changes. | Both themes at 1440/390px; default/hover/focus, invalid/focus, select and actual modal textarea measured. Zero page exceptions or attempted writes. Reference app sources unchanged. | 3/9 complete; M3 active, fidelity reconciliation pending | Reconcile source colors and explicit variants before contrast review or M4. |

| R006 — source colors and explicit modal variant | Replaced older palette approximations with verified Tailwind 4 source values; added opt-in 10px/20% modal modifier with non-resizable textarea and modal-select focus border. Preserved neutral themes and documented adaptations. | Generated CSS checks and four Sass contracts passed; native field behavior and modal states verified in both themes at desktop/mobile. Direct wizard remeasurement recorded separately. Reference repositories untouched. | 3/9 complete; M3 active, visual/contrast review pending | Review corrected variants and resolve contrast before M4. |

| R007 — primary focus/font presentation correction | User reported focus/font mismatch. Prior previews highlighted the weaker modal variant. Relabeled that variant and captured actual wizard versus primary KB fields at equal widths. | Chromium platform-font inspection confirms custom Noto Sans Regular in all four light/dark controls. Focus tokens match; dark backdrop/text differences remain visible and unresolved as a visual match. No font asset or field CSS change claimed. | 3/9 complete; M3 active, user visual feedback unresolved | Review direct primary comparison before changing focus or typography. |

| R008 — full UI comparison | Captured actual Network configuration screen and current KB form in light/dark at 1200×900, with hostname focused and matching entered text. Created side-by-side UI evidence. No styling changes. | Custom Noto Sans rendering verified through Chromium for all four fields. WSDMM source unchanged. | 3/9 complete; M3 active | Resolve visual direction from full-screen comparison before further styling. |

| R009 — surface audit and implementation plan | Recorded source light slate/dark blue gradients, white/translucent card layers, inset/chrome roles, and blur. Documented superseding the neutral-only surface constraint and separating decorative effects from tokens. No styling changes. | Actual wizard ancestor layers/footer measured at 1200×900 in both themes; remaining roles source-traced. Raw evidence saved. | 3/9 complete; M3 active, surface implementation pending | Implement the surface plan locally, then verify full UI and field contrast. |

| R010 — wizard surface implementation | Added source-aligned page/card/chrome/inset tokens, generated theme output, static decorative glows and primary field blur; applied main card/chrome to KB reference. | Both themes: surface values, actual Noto Sans rendering, desktop/mobile field functionality and 320px reflow verified. Four Sass contracts and CSS drift checks pass. Remaining layout/text/decorative differences documented. | 3/9 complete; M3 active, surface review/contrast pending | Review side-by-side surfaces and resolve field contrast before M4. |

| R011 — placeholders and dropdown carets | Aligned light/dark placeholder tokens with source; replaced reference select browser arrows with one consistent Lucide ChevronDown via opt-in wrapper. Documented native-source arrow versus shared-icon refinement and empty-option semantics. | Sass/build checks and field functionality verified; caret geometry, keyboard selection, forced-colors fallback and desktop/mobile checks recorded. | 3/9 complete; M3 active, visual/contrast review pending | Review placeholders/carets on matched surfaces before concluding M3. |

| R012 — field contrast checkpoint | Measured rendered typography/contrast on the real layered backgrounds; preserved source-matched defaults and added a separate contrast proposal with side-by-side captures. | Both themes/1200/390px: custom Noto Sans verified for all sampled fields, pixel-based contrast samples recorded. Proposal geometry/native keyboard/validation/readonly/disabled/reflow checks passed; no writes/errors. | 3/9 complete; M3 active, contrast proposal ready for review | Settle proposal versus fidelity, then integrate accepted values and finish M3 checks. |

| R013 — accepted field standard | Adopted reviewed contrast tokens into shared Sass, retired duplicate proposal styling/page, strengthened measured modal focus and dark error-border gaps, consolidated current usage rules with historical evidence retained. | All 96 sampled enabled primary/modal state cases passed selected text/boundary/ring thresholds at desktop/mobile in both themes. Native behavior/caret checks, four Sass contracts and generated CSS checks passed. No reference repo changes or pushes. | 4/9 complete; M3 complete | M4 button/chip source audit and bounded comparison. |

| R014 — wizard button/badge audit | Traced actual inline/native wizard actions versus unused generic CVA variants; measured toolbar/navigation/add/apply and passive counts in both themes and widths. Prepared source-control gallery, conflicts and implementation guidance. No shared styling changes. | Default/hover/focus/held-active, disabled Back/Next, mobile hidden actions, icon/label geometry and passive badges recorded; no apply/export/import actions, attempted non-GET requests or page exceptions. Loading/type-chip states remain source-only. | 4/9 complete; M4 active | Implement a bounded action/badge checkpoint and verify focus/accessibility/contrast before completion. |

| R015 — shared action/badge checkpoint | Added opt-in actions.css/Sass mixin and action/badge theme roles; live source comparisons, named icon actions, accessible mobile labels, passive counts, local busy/pressed demonstrations and links from KB/fields. Documented contrast/source differences. | Source geometry at desktop/mobile in both themes; real keyboard and native-link behavior, local loading/repeat exclusion, chip states, fonts, accessible names, inactive/passive semantics, forced colors/reduced motion and 320px reflow passed. Sampled enabled text ≥5.85:1 and button contours ≥3.20:1. Five Sass contracts/CSS drift checks pass. | 4/9 complete; M4 review ready | Review comparisons, incorporate feedback, then finish M4 before M5. |

| R016 — optional button icon guidance | Incorporated user direction: icons depend on use case and are not a default requirement. Added primary/secondary text-only examples and explicit usage guidance; icon-only actions still need accessible names. | Confirmed text-only markup uses native type=button controls and existing shared styles; local handlers provide demo feedback. No shared CSS changes or browser verification claimed this run. | 4/9 complete; M4 review ready | Review action hierarchy and optional-icon usage before M5. |

| R017 — optional-icon visual refresh | Captured current text-only and optional-icon examples in light/dark for review. | Browser captures completed; text-only Save/Cancel feedback verified locally. | 4/9 complete; M4 review ready | Review optional-icon examples and action checkpoint. |

| R018 — button shadow/interaction UX review | Recaptured actual Apply shadow with surrounding context; documented flat routine actions, optional small primary elevation, quieter pressed feedback and independent keyboard focus. Added review-only live before/after examples; no shared styling changes. | Source captured in both themes without invoking Apply; proposal hover/held-active/focus/disabled and stable geometry verified at desktop/mobile, plus reduced motion, forced colors and 320px reflow. No writes/errors; source repos clean. | 4/9 complete; M4 active, button UX review pending | Adopt chosen button elevation/pressed rules and verify affected roles before M4 completion. |

| R019 — accepted button elevation and pressed feedback | Adopted optional primary elevation, per-role pressed fills and soft inset feedback into shared Sass; routine actions/chips remain flat. Busy/disabled elevation disappears immediately. Updated source Apply captures to retain exterior shadow and consolidated current guidance. | 108 sampled role/state/theme/width cases passed 4.5:1 text contrast at measured points. Elevation/hover/press/focus, native behavior, stable geometry, inactive states and forced colors checked; five Sass contracts and generated CSS checks passed. No source app changes or pushes. | 5/9 complete; M4 complete | M5 card/overlay source audit and bounded surface/elevation checkpoint. |

| R020 — card/dialog source audit | Measured actual main card, DHCP/table panels, dense Add Device and glass Template Library dialog families. Recorded radius/padding, alpha/blur, shadow/scrim differences and local Escape/initial-focus gaps. Added source gallery and implementation guidance; no shared styling changes. | Light/dark at 1200/768/390px; DAU choice selection observed locally; no device save/apply, attempted writes or page exceptions. Review summaries/populated library/confirmation states remain source-only. | 5/9 complete; M5 active | Implement shared surface/dialog checkpoint with native semantics and verified geometry/contrast. |

| R021 — shared cards/panels/dialog checkpoint | Added opt-in surfaces.css/Sass, source geometry and dense/glass roles, local named native-dialog examples and source comparisons. Added radio semantics, keyboard focus/return, background scroll handling and readable new surface-description role. | Both themes/1200/768/390 geometry, modal Tab/Escape/restore, local form/selection/reset, long-content header/footer stability and 320px reflow passed. Actual font/name, forced colors, scrim policy and token overrides checked. Sampled text ≥4.69:1. Six Sass contracts/generated checks pass; no reference edits or pushes. | 5/9 complete; M5 review ready | Review comparisons and incorporate feedback before M6. |

| R022 — source border correction | Fixed choice cards incorrectly borrowing strong field borders; split 2px device / 1px template borders, source resting alpha, hover/selected roles and dialog dividers. Preserved independent keyboard focus and accepted M3/M4 borders. | Rendered width/radius/color/opacity and hover/selected checks pass in both themes; native dialog/geometry/scrolling regression checks and six Sass contracts pass. No source app changes. | 5/9 complete; M5 review ready, glass composite still open | Reconcile glass compositing, then review M5. |

| R023 — native dialog color correction | Reproduced native-versus-nested overlay compositing; layered the existing family scrim below the translucent panel fill without changing palette tokens or source repositories. Captured updated source comparisons in both themes. | Controlled corrected sample within 2 RGB levels of nested source-style overlay (original blue channel difference 31). Both-theme/three-width modal regressions, 44 contrast samples (minimum 4.69:1), six Sass contracts and generated surface drift check pass. | 5/9 complete; M5 review ready | Review corrected surface colors before closing M5. |

| R024 — icon consistency reference | Accepted R023 surface correction from user feedback; documented source 16px/20px Lucide roles, optional button icons, currentColor/stroke 2, accessible naming and distinct hit targets. Added a reference using existing shared components; no shared styling replacement. | Rendered icon roles, names, SVG semantics, 40px icon-action targets and no overflow checked in both themes at 1200/390/320; local demo actions checked. | 6/9 complete; M5 complete, M6 review ready | Review icon reference, then M7 integration. |

| R025 — button color feedback | Replaced black dark fills and bright cyan/white contours with source-style white-alpha fills and role-specific borders; retained readable text, optional icons and accepted geometry/elevation. Corrected preview timing to capture settled themes. | First source-hover test found 4.34:1 text; refined white hover from 20% to 15%. All 108 final rest/hover/pressed samples pass, minimum 4.80:1. Functional/icon regressions and six Sass contracts pass. Source application repos unchanged. | 6/9 complete; button color correction under review, M6 review ready | Review settled button colors before M7. |

| R026 — integrated CSS/Sass consumers | Accepted button color/icon feedback. Added identical native component examples through generated CSS and scoped Sass; linked the unified reference from the landing page and updated adoption guidance. | Both-theme/desktop/mobile parity and native form verification recorded separately; existing full component state audits remain the basis for states. Offline font packaging and broader browser coverage remain open. | 7/9 complete; M6 complete, M7 active | Complete font/distribution audit and integrated navigation verification before M7 review. |

| R027 — wizard field border correction | Restored source gray-300/light and white-20/dark contours and source primary/modal focus families. Isolated field-control focus variables so accepted button/chip focus stays unchanged. | Browser checks cover all three controls and both variants/themes; geometry/native behavior regression retained. Historical stronger-border contrast evidence superseded for these roles. | 7/9 complete; M7 active, field correction ready for review | Review corrected borders before continuing integration. |

| R028 — integration links and local fonts | Accepted R027 field borders. Verified 119 local references and added seven unmodified Noto Sans normal faces with upstream URLs, SHA-256 provenance and OFL notice. Current references use optional local fonts.css; no theme/component palette changes. | Seven actual custom font weights verified on nine pages with external requests blocked; no HTTP failures. Font hashes checked; generated CSS/Sass contracts retained. Legacy landing gallery external dependencies remain historical. | 7/9 complete; M7 review ready | Review integrated artifact/adoption guide, then build M8 team skill. |

| R029 — team skill and handoff | Accepted M7 integration. Replaced pasted-skill assumptions with a repository-local KB V1 skill, explicit source conflicts, adoption checklist and reusable-asset handoff. Preserves accepted field/action revisions and scope. | Skill relative links/evidence, frontmatter and Sass example checked against the checkout; existing Sass contracts/generated output checks pass. No application migration, global skill installation or publication. | 8/9 complete; M8 review ready | Review skill/handoff, incorporate feedback and close V1. |

| R030 — V1 acceptance and closure | User accepted M8 skill/handoff. Closed all nine milestones and refreshed the current checkpoint to link final field/action evidence rather than superseded contrast claims. | Documentation/status consistency and diff whitespace checked; no implementation changes since the passing R029 build/contracts. Known adoption limits remain explicit. | 9/9 complete; V1 accepted locally | Application adoption/publication only when separately requested. |

## Organization demo follow-up

The accepted V1 artifacts remain complete. The original landing gallery was not migrated by that scope; the R031 audit identifies example/token drift and demo-authority gaps. Keep its approved layout.

`[✅ audit · ✅ session plan · ✅ layout plan · ✅ UX mockup · ✅ implementation · ✅ browser verification · ⬜ timed rehearsal]`

- [Evidence-based landing/library audit](docs/landing-library-audit.md) and [actual visual comparison](docs/landing-library-comparison.html).
- [Lunch-and-learn plan](docs/lunch-and-learn.md): default30-minute session, truthful scope, live actions, pilot value measures and backup route.
- [Layout update plan](docs/landing-layout-plan.md): preserve the shell, improve the demo entry, embed shared examples, align component destinations, then clean up foundations/adoption.
- [Implemented landing and verification](docs/landing-implementation.md): Runs A–D complete locally, with the technical presentation route verified. Next: timed presenter rehearsal and review of the actual screenshots.

| R031 — organization demo planning and landing audit | Inspected and rendered the current landing and accepted library in both themes; measured field/button differences, separate token systems, dark alias resolution, icon/font and unverified-pattern coverage. Preserved landing layout. Prepared a30-minute lunch-and-learn plan and visual evidence. | No browser page errors in captured run. Confirmed desktop dimensions/states; settled390px reflow recheck; documentation links checked. No shared implementation changes. | V1 remains9/9; demo audit/plan ready, alignment and rehearsal queued | Review plan, then choose minimal landing-demo alignment before rehearsal. |

| R032 — landing layout plan | Defined the retained shell, hero/demo route, dedicated component sections, adoption area and clearly scoped reference patterns. Planned scoped theme integration and preservation of current app.js interactions. Split work into bounded runs with a presentation-safe minimum. | Plan links and existing anchor/behavior assumptions checked against index.html/app.js; no runtime/shared styling change. | V1 remains9/9; layout plan ready, implementation/rehearsal queued | Review plan, then Run A demo entry and Run B real component preview. |

| R033 — desktop/mobile experience mockup | Created a generated UX board preserving the existing header/sidebar/brand character; prioritized the working example, distinct adoption path, one global theme control and single-column mobile form. Saved the concept and source-of-truth limits. | Visual review of hierarchy/mobile arrangement; mockup is not runtime or pixel-style verification. No implementation/palette change. | UX mockup ready; implementation/rehearsal queued | Review hierarchy, then implement the scoped working example with actual shared assets. |

| R034 — landing implementation | Built the planned hero/navigation, scoped real form, current token readouts, dedicated component families, adoption and expandable reference archive. Reused accepted CSS/Sass and local fonts; retained all original IDs and demos. Updated presenter route. | Both themes/four widths match accepted field/action styles; keyboard/forms/dialogs and retained search/menu/legacy interactions verified; mobile focus/inert/persistence/clipboard/download checked; 28 text/action contrast samples ≥4.83:1; six Sass contracts and all generated drift checks pass. No reference app changes or pushes. | V1 remains9/9; implementation and technical verification complete, timed rehearsal remaining | Review actual landing screenshots and rehearse the lunch-and-learn timing. |

## GitHub submission

R035: User authorized committing and pushing the complete KB design-system work. Submission branch: `codex/kb-design-system-v1`. Final build/source checks pass; browser evidence is linked from the implementation documents. Pull-request publication is separate from application adoption or site deployment.

## UX at KB Signaling teaching page

`[✅ story plan · ✅ full desktop mockups · ✅ interactive page · ✅ browser verification · ⬜ timed presenter rehearsal]`

[Two-board experience specification](docs/ux-page-mockup.md): UX definition, featured ketchup comparison, entry points/process, fictional RailLens users/goals/journey, exploration/testing, design-system bridge and optional coding challenge. [Prepared starter prompt](docs/raillens-starter-prompt.md). Images propose layout/content; actual component sources remain authoritative.

| R036 — complete UX teaching-page mockup | Prepared two connected KB-branded boards spanning all nine sections, including classic glass/cap-down ketchup comparison, research hypotheses, user journey constraints and the optional skill-driven UI challenge. Saved full interaction/content notes and a copy-ready starter prompt. | Visually reviewed story continuity and ketchup explanation; specification links checked. Generated controls are not implemented or browser-verified. Existing landing unchanged; nothing newly pushed. | Story/mockup complete; interactive page and rehearsal queued | Review boards, then implement a separate ux.html with native reveals and the RailLens exercise. |

| R037 — interactive UX teaching page | Built separate ux.html/css/js with all nine chapters, ketchup reveal, entry/process choices, role-specific RailLens journeys/constraints, concept discussion, real design-system links, presenter mode and copyable coding prompt. Added an explicitly prepared in-memory demo and local generated bottle image. Existing landing unchanged. | Light/dark at1440/768/390/320, all interactions, presenter keyboard/boundaries, mobile focus/inert, deep links, local font, safe text records/validation/reset/reload and no writes/external requests/errors verified. Clipboard/storage denial, forced colors and reduced motion pass. Existing six Sass contracts and scoped drift check pass. | Interactive experience verified locally; timed rehearsal remains | Review the working page/screenshots and rehearse one role/constraint route. New UX work has not been pushed. |

| R038 — UX page GitHub handoff | User authorized pushing and merging the UX teaching page. Confirmed the earlier V1 work is already on main through PR #1. Prepared the new page, local assets, source mockups, starter prompt, presenter guide and verification evidence as one change. | Six Sass contracts, all generated drift checks, UX JavaScript syntax and diff checks pass; prior browser evidence covers the full UX route. | UX update pushed and merged into main; timed presenter rehearsal remains | Rehearse and confirm the presentation URL. |

R038 result: UX feature commit `da14456` was pushed and merged into `main` as `aa9f63d`. Both branch updates were confirmed by GitHub. The new page is `ux.html`; site deployment/accessibility from the presentation computer is still a separate verification step.

## Dark-theme consistency follow-up

`[✅ source audit · ✅ rendered comparison · ⬜ consumer-scoped correction · ⬜ theme regression verification]`

[Dark-theme audit](docs/dark-theme-audit.md) identifies the split between the legacy documentation shell and shared V1 controls, plus the conflict with the earlier neutral-canvas exception. [Actual comparison](docs/dark-theme-comparison.html). Shared tokens/skill remain the authority; no palette correction was applied during the audit.

| R039 — dark-theme mismatch audit | Traced styles.css/ux.css/landing Sass scope, compared the skill with the earlier documentation-shell exception, and rendered UX/landing/field/consumer pages. Confirmed opaque legacy page/cards/chrome versus accepted gradient/translucent roles; demo field values match. | Actual dark desktop/mobile/presenter captures and measured CSS recorded; no page exceptions. This checks outer-theme consistency missing from earlier behavior/control verification. No CSS, shared token or application changes. | Audit complete; UX consumer-scope correction ready to implement | Apply one shared theme owner and explicit surface roles to the UX page, then verify both themes and behavior. |

### R040 · UX full-page theme correction

**Progress:** [✅ source audit · ✅ rendered comparison · ✅ consumer-scoped correction · ✅ theme regression verification]

- UX page owns the shared light/dark theme at its body; generated from existing Sass maps.
- Applied accepted gradient, chrome, main-card and nested-panel roles; themed caption and selection. Preserved photographic content, shared controls and interaction code.
- Passed six Sass tests, landing drift check and Chromium desktop/mobile checks in both themes; presenter lifecycle, demo reveal, font availability and overflow checked.
- Evidence: [audit and correction](docs/dark-theme-audit.md), [dark desktop](docs/reference/ux-theme-fixed-dark-1440.png), [verification](docs/reference/ux-theme-fix-verification.json).
- Local changes only. Landing documentation-shell theme alignment remains a separate follow-up.

### R041 · Recover overview organization and plan one shared frame

**Progress:** [✅ recover overview · ✅ navigation map · ⬜ structural preview · ⬜ shared frame · ⬜ verify]

- Compared pre-V1 `676e7ef` with the current landing page; documented replaced header groups, sidebar hierarchy and content ordering.
- Proposed restoring the original catalog organization and header groups, keeping UX as one sidebar link with chapter navigation inside its content.
- Planned shared generated markup and one frame controller, preserving static hosting, accepted styling, examples, anchors and page behavior.
- Deliverable: [shared navigation plan](docs/shared-navigation-plan.md). Inspection/docs only this run; prior local theme corrections preserved. No push.

### R042 · Shared-frame structural preview

**Progress:** [✅ recover overview · ✅ navigation map · ✅ structural preview · ⬜ shared frame · ⬜ verify]

- Created a side-by-side overview/UX preview using the recovered hero and common header/sidebar.
- Kept UX chapters inside content and one presentation link in global navigation.
- Verified identical desktop frame markup/destinations/geometry, no overflow or browser exceptions. Runtime/mobile behavior remains pending.
- [Review board](docs/navigation-preview/index.html). Review artifacts only; production pages unchanged this run. No push.

### R043 · Whole-site inventory and internal-link audit

**Progress:** [✅ public-page inventory · ✅ static links/assets · ✅ load/theme/reflow audit · ⬜ shared frame on all 7 pages · ⬜ interaction/style acceptance]

- Checked20 HTML pages/330 local HTML+CSS references: zero broken file/anchor targets; external references not network-validated.
- Rendered all7 public pages in both themes at1440/390: no page exceptions, failed HTTP responses or document overflow; local fonts loaded.
- Identified5 standalone review frames plus index/UX frame divergence. All7 public pages are now required integration scope, superseding the optional catalog follow-up.
- Five generated bundle checks and six Sass tests passed. Added reusable `npm run check:links`.
- [Audit and completion criteria](docs/internal-page-integration-audit.md). No UI changes or push in this run; runtime interactions and full visual parity remain pending.

### R044 · Implement one frame across every public page

**Progress:** [✅ recover overview · ✅ navigation map · ✅ structural preview · ✅ all 7 pages integrated · ✅ verification]

- Restored the Design System hero, visible original catalog organization and useful section links; moved the live form into Fields. Retained content IDs, examples and adoption guidance.
- Added generated shared header/sidebar, one navigation/search source and one theme/menu controller across index, UX, typography, fields, actions, cards and icons. Removed per-page frame/theme handlers; source captures follow the shared preference.
- UX chapters and sticky presenter toolbar are content-level; presenter mode suspends/restores the shared sidebar and focus/scroll. Preserved recent theme corrections and accepted component source values.
- Verified all7 pages at1440/390 in both themes, matching frame geometry/fill/blur/destinations, preference persistence, mobile keyboard/backdrop/resize, search/deep links, presenter restoration and sampled demo behavior. Field default/hover/focus equals the accepted isolated consumer in both themes; native states and select/textarea geometry checked.
- Shared-frame build check, five component/theme bundle drift checks, six Sass tests and local links/assets pass. External resources and full cross-browser/accessibility certification remain outside these checks.
- [Actual page gallery](docs/shared-frame-comparison.html) · [verification](docs/shared-frame-verification.md) · [maintenance](docs/shared-frame-maintenance.md). Local only; no push or reference-application changes.

### R045 · Publish the verified integration to main

**Progress:** [✅ implementation · ✅ verification · ✅ publication authorized]

- User authorized publishing the local theme corrections, shared navigation and overview restoration to main.
- Fetched origin/main and confirmed it matched the local base before committing. Includes the audit, preview and browser evidence supporting R039–R044.
- Final shared-frame/component build checks, six Sass tests and 560 local-reference checks passed in R044; no reference application changes.