149 lines
6.5 KiB
Markdown
149 lines
6.5 KiB
Markdown
# 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`.
|