# Architectural Decision Log ## ADL-001 — Submodule-first repository layout **Date:** 2026-02-23 **Context:** The repository must be consumable by multiple host projects with minimal coupling. **Decision:** The root repository is the reusable kit surface (`kit/`, `exports/`, `tools/designsync`), while the runnable reference app lives in `demo/` as a separate module. **Consequences:** - Host repositories can pin and sync shared artifacts without depending on demo runtime code. - Public compatibility boundaries are clearer. - Documentation and changelog discipline are required for bundle contracts. ## ADL-002 — Copy/sync is the default integration model **Date:** 2026-02-23 **Context:** Host repositories need stable, reviewable changes and should avoid hidden runtime dependency on submodule internals. **Decision:** Canonical integration is copy/sync from submodule bundles using `designsync`. **Consequences:** - Host repos review concrete file changes in their own tree. - Runtime coupling to submodule paths is avoided. - Bundle manifests and sync tooling become a critical public interface. ## ADL-003 — Scope expansion requires explicit user direction **Date:** 2026-02-23 **Context:** The repository can easily grow from UI/UX design code into broader application architecture standards, which risks losing focus and slowing delivery. **Decision:** Keep the repository focused on the currently approved scope. Do not expand into new design-code domains unless the user explicitly requests that expansion. **Consequences:** - Work remains concentrated on current deliverables and consistency. - New domains are added intentionally instead of opportunistically. - Agents should prefer improving existing patterns/docs over inventing adjacent scope. ## ADL-004 — Aqua style work is frozen as legacy; active rewrite direction is Win9x Superseded by ADL-005. **Date:** 2026-02-23 **Context:** A substantial Aqua-inspired visual exploration was implemented during demo refinement. The result is useful as a reference archive, but it should not continue to drive the active baseline. The next visual rewrite direction is a simpler classic Windows 95-2000 (Win9x-style) baseline. **Decision:** Freeze Aqua-related visual work as a legacy snapshot bundle. Keep it documented for reference, but do not treat it as the active baseline for ongoing demo/scaffold styling. Continue visual work on the Win9x rewrite path. **Consequences:** - Aqua styles remain available for legacy reference and extraction. - New styling changes should target the Win9x baseline instead of extending Aqua. - Documentation must clearly mark Aqua as legacy / not active to avoid ambiguity. ## ADL-005 — Restore Aqua as the active visual baseline Superseded by ADL-006. **Date:** 2026-02-23 **Context:** The temporary Win9x-wide rewrite pass was evaluated and rejected for the current demo catalog. The team decided to continue from the existing Aqua-based visual work. **Decision:** Restore Aqua-first styling as the active baseline for the demo/scaffold and keep the Win9x attempt as a discarded experiment. Preserve the Aqua snapshot bundle/docs as archive artifacts, but continue active iteration on the live Aqua baseline. **Consequences:** - Demo pages continue to evolve on top of Aqua-first styles. - Legacy bundle artifacts remain available for archival reference. - Documentation should describe Aqua as active baseline and avoid marking Win9x as current direction. ## ADL-006 — Main demo shell baseline is Vapor Soft / Vapor Night with system-only mode selection **Date:** 2026-02-23 **Context:** The demo catalog visual work moved from Aqua-first experimentation to a new Vaporwave inspired UI direction intended to remain usable for day-long operation. Manual day/night toggles in the shell caused state conflicts and inconsistent rendering relative to system color-scheme. **Decision:** Use a dual baseline in the main demo shell: - `Vapor Soft` for light mode - `Vapor Night` for dark mode Mode selection follows system settings only (`prefers-color-scheme`). The style playground may remain available as an internal route for visual experimentation, but it is hidden from the main demo navigation/catalog while the baseline is actively refined. **Consequences:** - The main demo shell keeps one stable visual contract while still supporting light/dark operation. - Manual theme override UI/state is removed from the main shell to avoid visual mismatches. - Vapor-themed background composition (including dark-mode retro-grid variant) becomes part of the canonical demo presentation and must remain subordinate to UI readability. ## ADL-007 — Canonical design contracts must resolve through a single-source map **Date:** 2026-02-28 **Context:** Table-management and operator/controls patterns evolved quickly during iterative demo refinement. Without an explicit source map, repeated definitions across contracts/documents risk semantic drift (toolbar groups, icon semantics, active baseline references). **Decision:** Maintain one explicit single-source index for design contracts and assets in `bible/architecture/design-canon-map.md`, with Vapor as active baseline and Aqua marked archive-only. Pattern-specific contracts must reference shared base contracts and document only additive overrides. **Consequences:** - Contract ownership is explicit and reviewable in one place. - Repeated component semantics are less likely to diverge across patterns. - Release preparation can validate canonical sources first, then dependent pattern docs/manifests. ## ADL-008 — Vapor shell uses preset-driven header/accent palette contract **Date:** 2026-02-28 **Context:** Host repositories that consume this kit need a stable way to keep the app header height and color treatment consistent with Vapor aesthetics. Ad-hoc local overrides caused drift in header height and non-Vapor accent choices. **Decision:** Introduce reusable shell palette presets in `theme-vapor` with stable preset IDs and document them in `kit/patterns/theme-vapor/palette-catalog.md`. Presets are selected by `data-vapor-shell` on the root element and resolve shared shell tokens for light/dark backgrounds, accent gradients, accent borders, and shell height. Runtime selection precedence is standardized as query `vapor_shell` → local storage key `vapor_shell` → markup default preset. **Consequences:** - Host projects can switch shell look without modifying component markup. - Header height is tokenized (`--shell-height`) and no longer depends on one-off CSS edits. - Palette ID compatibility becomes part of the reusable visual contract for `ui-theme-vapor`.