PriceForge/bible-local/bible/decisions/10-decisions.md

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.