Prepare reusable Vapor theme bundle and canonical design map for cross-project integration

CHANGELOG.md

@@ -10,4 +10,12 @@ All notable changes to the public design kit surface are documented here.
 - Initial bundle manifests (`ai-rules`, `bible-core`, `go-web-skeleton`, `ui-pattern-table`, `ui-pattern-modal`)
 - `designsync` MVP CLI (`list`, `validate`, `plan`, `apply`)
 - Demo app (`demo/`) with bundle catalog UI
+- Design single-source index: `bible/architecture/design-canon-map.md`
+- Active reusable Vapor theme module in `kit/patterns/theme-vapor` (CSS + icon sprite)
+- New export bundle: `ui-theme-vapor`
 
+### Changed
+
+- Canonical baseline docs aligned to `Vapor Soft` / `Vapor Night` as active demo/scaffold style.
+- Aqua module/docs clarified as legacy archive/reference (not active baseline).
+- Table-management docs clarified as theme-agnostic geometry/semantics contract.

bible/README.md

@@ -24,6 +24,7 @@ it quickly.
 | [architecture/system-overview.md](architecture/system-overview.md) | Product purpose, scope, repository composition |
 | [architecture/submodule-integration-contract.md](architecture/submodule-integration-contract.md) | How host repositories consume this kit |
 | [architecture/ui-pattern-catalog.md](architecture/ui-pattern-catalog.md) | Canonical pattern taxonomy and bundle status |
+| [architecture/design-canon-map.md](architecture/design-canon-map.md) | Single-source map for canonical UI contracts and assets |
 
 ### 2. Runtime & Delivery
 

bible/architecture/design-canon-map.md

@@ -0,0 +1,41 @@
+# Design Canon Map (Single Source Index)
+
+This file defines where each reusable design element is specified exactly once.
+Use it to prevent duplicated contracts and drift across demo, kit, and exports.
+
+## Active Visual Baseline
+
+- Active baseline: `Vapor Soft` / `Vapor Night` (system-driven mode selection).
+- Canonical runtime statement: `bible/architecture/demo-runtime-flows.md`.
+- Aqua assets are archive-only: `bible/architecture/legacy-aqua-freeze.md`.
+
+## Canonical Component Contracts
+
+- Table management geometry + semantics (toolbar groups, icon semantics, select/actions columns):
+  `kit/patterns/table-management/contract.md`
+- Controls + selection additions:
+  `kit/patterns/controls-selection/contract.md`
+- Operator tools additions:
+  `kit/patterns/operator-tools/contract.md`
+- Table pagination/filter contract:
+  `kit/patterns/table-pagination/contract.md`
+- Forms + validation:
+  `kit/patterns/forms-validation/contract.md`
+- Import/export flow:
+  `kit/patterns/import-export/contract.md`
+- Modal workflow:
+  `kit/patterns/modal-workflows/contract.md`
+
+## Canonical Asset Sources
+
+- Active icon sprite source: `kit/patterns/theme-vapor/templates/icon_sprite.html`
+- Active stylesheet source: `kit/patterns/theme-vapor/static/vapor.css`
+- Demo runtime icon usage mirror: `demo/web/templates/base.html`
+- Demo runtime stylesheet mirror: `demo/web/static/css/app.css`
+
+## Reuse Rules
+
+- Do not redefine shared toolbar/table geometry in pattern-specific contracts.
+- Do not redefine icon semantics outside `table-management/contract.md`.
+- When a pattern needs exceptions, document only additive overrides in its own contract.
+- Keep bundle manifests in `exports/bundles/` aligned with canonical contract locations.

bible/architecture/legacy-aqua-freeze.md

@@ -16,8 +16,9 @@ This document records the outcome of the Aqua-style exploration and its freeze s
 
 ## Current Direction
 
-- Active visual baseline for the demo and shared styling is **Aqua-first (macOS Aqua-inspired)**.
+- Active visual baseline for the demo/scaffold is **Vapor Soft / Vapor Night**.
-- This document remains as an archive record of the freeze/snapshot event and stored artifacts.
+- Aqua artifacts remain archived in this module and are not the active baseline.
+- This document remains an archive record of the freeze/snapshot event and stored artifacts.
 
 ## Storage / Bundle
 

bible/architecture/ui-pattern-catalog.md

@@ -2,10 +2,13 @@
 
 Canonical pattern taxonomy for reusable Go web UI patterns.
 
-Visual baseline for the canonical demo and scaffold is Vapor Soft (light) / Vapor Night (dark),
+Visual baseline for the canonical demo and scaffold is Vapor:
-with system color-scheme detection as the active mode selection mechanism. The hidden style
+
-playground remains a comparative laboratory and not part of the main demo navigation. A frozen
+- `Vapor Soft` for light mode
-Aqua snapshot bundle is still kept as a legacy archive for reference.
+- `Vapor Night` for dark mode
+
+Pattern-level interaction contracts inherit the active baseline component language rather than
+redefining primitives locally. The Aqua bundle remains archive/reference only.
 
 ## Pattern Families
 
@@ -29,6 +32,13 @@ Aqua snapshot bundle is still kept as a legacy archive for reference.
 | Status indicators | bundled inside controls/table demos | partial |
 | Timeline cards | `ui-pattern-timeline` | contract + files |
 
+## Theme Bundles
+
+| Theme | Bundle | Status |
+|---|---|---|
+| Vapor (active baseline) | `ui-theme-vapor` | active |
+| Aqua legacy snapshot | `ui-theme-aqua-legacy` | archive/reference |
+
 ## Synthesis Direction
 
 Initial canonical behaviors are synthesized from multiple existing Go web applications with:
@@ -40,7 +50,8 @@ Initial canonical behaviors are synthesized from multiple existing Go web applic
 ## Component Baseline Notes
 
 - Buttons, segmented controls, status badges, filter inputs, and table surfaces share one baseline component language.
-- Canonical demo visuals target a two-mode baseline (`Vapor Soft` and `Vapor Night`) and should
+- Canonical demo visuals target the active Vapor baseline (`Vapor Soft` / `Vapor Night`).
-  not expose ad-hoc per-page visual toggles in the main demo shell.
 - Segmented controls use joined-button geometry (shared shell, rounded outer edges only, straight internal separators).
 - Context-specific active-state color is allowed (for example dark scope tabs vs blue theme preset selector) without changing segmented geometry.
+- Table-management behavior and toolbar icon semantics are defined once in
+  `kit/patterns/table-management/contract.md`.

bible/decisions/10-decisions.md

@@ -48,6 +48,8 @@ design-code domains unless the user explicitly requests that expansion.
 
 ## 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.
@@ -66,6 +68,8 @@ visual work on the Win9x rewrite path.
 
 ## 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
@@ -104,3 +108,21 @@ demo navigation/catalog while the baseline is actively refined.
 - 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.

demo/README.md

@@ -5,3 +5,5 @@ Runnable reference app for shared UI patterns and bundle catalog.
 This app is not the public submodule contract; host repositories should consume `kit/` via
 `tools/designsync`.
 
+Active shared theme assets for host integration are published in `kit/patterns/theme-vapor`
+and exported as bundle `ui-theme-vapor`.

exports/bundles/ui-theme-aqua-legacy.yaml

@@ -1,7 +1,7 @@
 {
   "id": "ui-theme-aqua-legacy",
   "version": 1,
-  "description": "Canonical Aqua theme layer for shared UI primitives, including icon sprite and reusable component chrome.",
+  "description": "Legacy Aqua theme snapshot bundle for reference/migration, including icon sprite and component chrome archive.",
   "conflict_policy": "merge-manual",
   "entries": [
     { "from": "patterns/theme-aqua-legacy", "to": "docs/ui-themes/aqua-legacy", "mode": "dir" }

exports/bundles/ui-theme-vapor.yaml

@@ -0,0 +1,9 @@
+{
+  "id": "ui-theme-vapor",
+  "version": 1,
+  "description": "Active Vapor theme layer for shared UI primitives, including icon sprite and reusable component chrome.",
+  "conflict_policy": "merge-manual",
+  "entries": [
+    { "from": "patterns/theme-vapor", "to": "docs/ui-themes/vapor", "mode": "dir" }
+  ]
+}

exports/index.yaml

@@ -10,6 +10,7 @@
     { "id": "ui-pattern-table", "manifest": "exports/bundles/ui-pattern-table.yaml" },
     { "id": "ui-pattern-modal", "manifest": "exports/bundles/ui-pattern-modal.yaml" },
     { "id": "ui-pattern-timeline", "manifest": "exports/bundles/ui-pattern-timeline.yaml" },
+    { "id": "ui-theme-vapor", "manifest": "exports/bundles/ui-theme-vapor.yaml" },
     { "id": "ui-theme-aqua-legacy", "manifest": "exports/bundles/ui-theme-aqua-legacy.yaml" }
   ]
 }

kit/examples/integration/greenfield-app/README.md

@@ -4,6 +4,7 @@ Suggested use:
 
 - apply `ai-rules`
 - apply `bible-core` (or merge selectively if a Bible already exists)
+- apply `ui-theme-vapor` for active visual baseline (CSS + icon sprite)
 - copy selected UI patterns into new modules/pages
 
 Keep domain-specific business rules in the host project's own Bible.

kit/patterns/table-management/README.md

@@ -9,7 +9,7 @@ This module is the canonical source for:
 - select/actions narrow edge columns
 - toolbar+table visual seam behavior (single continuous block)
 - canonical SVG icon sprite for table actions (shared at theme layer)
-- canonical Aqua style surface for the module (shared at theme layer)
+- canonical table-management visual/interaction seams independent of host branding
 
 Use this module as the base interaction contract for:
 
@@ -21,5 +21,6 @@ Pattern-specific contracts should only define additions or exceptions.
 ## Canonical Assets
 
 - Behavior/layout contract: `contract.md`
-- Global icon sprite: `../theme-aqua-legacy/templates/icon_sprite.html`
+- Active icon sprite: `../theme-vapor/templates/icon_sprite.html`
-- Global Aqua stylesheet: `../theme-aqua-legacy/demo-aqua-freeze.css`
+- Active stylesheet baseline: `../theme-vapor/static/vapor.css`
+- Legacy icon sprite archive: `../theme-aqua-legacy/templates/icon_sprite.html`

kit/patterns/table-management/contract.md

@@ -4,8 +4,8 @@
 
 Defines one canonical, reusable interaction model for table-driven operator/admin screens.
 All patterns that expose table selection + bulk actions must inherit this contract.
-Visual tokens and icon rendering are inherited from the global Aqua theme module:
+Visual styling is inherited from the active repository baseline (currently Vapor Soft / Vapor Night
-`kit/patterns/theme-aqua-legacy`.
+in demo/scaffold). This contract remains theme-agnostic and defines geometry/semantics only.
 
 ## Canonical Regions
 

kit/patterns/theme-aqua-legacy/README.md

@@ -1,17 +1,18 @@
-# Aqua Theme Module (Canonical Design Layer)
+# Aqua Theme Module (Legacy Archive Layer)
 
-Status: canonical Aqua design layer for reusable UI primitives.
+Status: legacy archive/reference layer (not the active demo/scaffold baseline).
 
-This directory defines the shared Aqua visual language for the design code:
+This directory preserves the Aqua visual language archive for the design code:
 
 - global visual tokens and component surfaces
 - reusable control geometry (buttons, segmented controls, table chrome)
 - icon rendering baseline (stroke style + sprite integration)
 
-Pattern modules consume this theme layer and then define behavior-specific contracts.
+Active pattern contracts should target the current baseline and may reference this module only
+for migration/comparison purposes.
 
 Contents:
 
-- `demo-aqua-freeze.css` — canonical Aqua stylesheet baseline used by demo/scaffold references
+- `demo-aqua-freeze.css` — frozen Aqua stylesheet snapshot
 - `templates/icon_sprite.html` — canonical icon sprite for reusable action semantics
 - `notes.md` — scope and usage policy for this theme module

kit/patterns/theme-aqua-legacy/demo-aqua-freeze.css

@@ -2865,7 +2865,7 @@ code {
   background: linear-gradient(90deg, rgba(245,247,250,0.96), rgba(238,242,247,0.96));
 }
 
-/* Aqua-first authoritative segmented controls for playground modules. */
+/* Legacy Aqua snapshot segmented controls for playground modules. */
 .style-playground.theme-aqua .status-filter-tabs {
   display: inline-flex;
   flex-wrap: nowrap;

kit/patterns/theme-aqua-legacy/notes.md

@@ -1,6 +1,6 @@
 # Aqua Theme Notes
 
-This module is the reusable Aqua style source for design-code consumers.
+This module is a reusable Aqua style archive for design-code consumers.
 
 ## What it captures
 
@@ -12,9 +12,10 @@ This module is the reusable Aqua style source for design-code consumers.
 
 ## How to use
 
-- Treat this module as the visual baseline for reusable UI components in this repository.
+- Treat this module as a legacy reference snapshot, not the active baseline.
-- Pattern contracts should reference this module instead of redefining shared visual primitives.
+- Pattern contracts should inherit the active baseline first and use this module only when a host
-- When visual behavior changes in demo/scaffold, sync the canonical rules here so host projects can reproduce the same output deterministically.
+  project explicitly opts into Aqua-like styling.
+- Do not move new baseline decisions here.
 
 ## Boundary
 

kit/patterns/theme-vapor/README.md

@@ -0,0 +1,16 @@
+# Vapor Theme Module (Active Design Layer)
+
+Status: active visual baseline for reusable UI primitives.
+
+This module defines the shared Vapor visual language used by the demo and intended host-project
+integration:
+
+- baseline tokens and surface treatment
+- reusable component geometry (buttons, segmented controls, table chrome)
+- shared icon sprite for table-management and operator workflows
+
+Contents:
+
+- `static/vapor.css` - active stylesheet baseline
+- `templates/icon_sprite.html` - active icon sprite
+- `notes.md` - usage boundaries and integration rules

kit/patterns/theme-vapor/notes.md

@@ -0,0 +1,22 @@
+# Vapor Theme Notes
+
+This module is the active reusable theme source for design-code consumers.
+
+## What it captures
+
+- Vapor control surfaces and button hierarchy
+- segmented controls and grouped tab geometry
+- table/filter/toolbar primitives
+- icon rendering baseline and shared sprite usage
+- modal and status component style language
+
+## How to use
+
+- Use this module as the visual baseline for host projects that adopt the canonical demo style.
+- Pattern contracts should reference shared behavior contracts and rely on this module for visual primitives.
+- When baseline visuals change, update this module first to keep downstream integration deterministic.
+
+## Boundary
+
+- This module standardizes visual language only.
+- Domain behavior, labels, and business workflow semantics belong to pattern contracts.

kit/patterns/theme-vapor/templates/icon_sprite.html

@@ -0,0 +1,102 @@
+  <svg class="icon-sprite" aria-hidden="true" focusable="false" width="0" height="0">
+    <symbol id="ico-select-visible" viewBox="0 0 16 16">
+      <rect x="2.5" y="2.5" width="11" height="11" rx="2"></rect>
+      <path d="M5 8.2l2 2.1 4-4.3"></path>
+    </symbol>
+    <symbol id="ico-select-filtered" viewBox="0 0 16 16">
+      <path d="M2.5 3h11l-4.2 4.6v3.1l-2.6 1.5V7.6L2.5 3z"></path>
+      <path d="M11.4 10.2h3M12.9 8.7v3"></path>
+    </symbol>
+    <symbol id="ico-clear-visible" viewBox="0 0 16 16">
+      <rect x="2.5" y="2.5" width="11" height="11" rx="2"></rect>
+      <path d="M5 8h6"></path>
+    </symbol>
+    <symbol id="ico-clear-filtered" viewBox="0 0 16 16">
+      <path d="M2.5 3h11L9.3 7.6v3.1l-2.6 1.5V7.6L2.5 3z"></path>
+      <path d="M10.5 10.2l3 3M13.5 10.2l-3 3"></path>
+    </symbol>
+    <symbol id="ico-clear-selection" viewBox="0 0 16 16">
+      <rect x="2.5" y="2.5" width="11" height="11" rx="2"></rect>
+      <path d="M5 5l6 6M11 5l-6 6"></path>
+    </symbol>
+    <symbol id="ico-run" viewBox="0 0 16 16">
+      <path d="M5 3.5l7 4.5-7 4.5z"></path>
+    </symbol>
+    <symbol id="ico-edit" viewBox="0 0 16 16">
+      <path d="M3 13l1.2-3.6L10 3.6l2.4 2.4-5.8 5.8L3 13z"></path>
+      <path d="M8.8 4.8l2.4 2.4"></path>
+    </symbol>
+    <symbol id="ico-remove" viewBox="0 0 16 16">
+      <path d="M4.2 4.2l7.6 7.6M11.8 4.2l-7.6 7.6"></path>
+    </symbol>
+    <symbol id="ico-cancel" viewBox="0 0 16 16">
+      <circle cx="8" cy="8" r="5.5"></circle>
+      <path d="M5.5 5.5l5 5M10.5 5.5l-5 5"></path>
+    </symbol>
+    <symbol id="ico-archive" viewBox="0 0 16 16">
+      <rect x="2.5" y="3" width="11" height="2.8" rx="1"></rect>
+      <path d="M3.5 5.8V13h9V5.8"></path>
+      <path d="M6.2 8h3.6"></path>
+    </symbol>
+    <symbol id="ico-import" viewBox="0 0 16 16">
+      <path d="M3 4.2v8.6h10V4.2"></path>
+      <path d="M8 1.8v6.2"></path>
+      <path d="M5.8 5.8L8 8l2.2-2.2"></path>
+      <path d="M5 10.2h6"></path>
+    </symbol>
+    <symbol id="ico-export" viewBox="0 0 16 16">
+      <path d="M3 4.2v8.6h10V4.2"></path>
+      <path d="M8 8V1.8"></path>
+      <path d="M5.8 4L8 1.8 10.2 4"></path>
+      <path d="M5 10.2h6"></path>
+    </symbol>
+    <symbol id="ico-export-filtered" viewBox="0 0 16 16">
+      <path d="M2 4.2v8.6h10.8"></path>
+      <path d="M7 8V1.8"></path>
+      <path d="M4.8 4L7 1.8 9.2 4"></path>
+      <path d="M10 5.1h5.2L13.1 7.5v3.1l-1.3.7V7.5z"></path>
+    </symbol>
+    <symbol id="ico-export-selected" viewBox="0 0 16 16">
+      <path d="M2 4.2v8.6h10.8"></path>
+      <path d="M7 8V1.8"></path>
+      <path d="M4.8 4L7 1.8 9.2 4"></path>
+      <rect x="10.1" y="5.2" width="5" height="5" rx="0.6"></rect>
+      <path d="M11.2 6.3l2.8 2.8M14 6.3l-2.8 2.8"></path>
+    </symbol>
+    <symbol id="ico-retry" viewBox="0 0 16 16">
+      <path d="M12.2 6A4.8 4.8 0 0 0 4.8 4.4"></path>
+      <path d="M5.6 2.9L4.1 4.6 5.9 5.8"></path>
+      <path d="M3.8 10A4.8 4.8 0 0 0 11.2 11.6"></path>
+      <path d="M10.4 13.1L11.9 11.4 10.1 10.2"></path>
+    </symbol>
+    <symbol id="ico-review" viewBox="0 0 16 16">
+      <circle cx="8" cy="8" r="5.5"></circle>
+      <path d="M8 7.2v3.6"></path>
+      <path d="M8 5.1h.01"></path>
+    </symbol>
+    <symbol id="ico-mark-review" viewBox="0 0 16 16">
+      <path d="M8 2.6l5.2 2v3.7c0 2.3-1.5 4.4-5.2 5.7-3.7-1.3-5.2-3.4-5.2-5.7V4.6l5.2-2z"></path>
+      <path d="M8 6.1v3.2"></path>
+      <path d="M8 11.1h.01"></path>
+    </symbol>
+    <symbol id="ico-confirm" viewBox="0 0 16 16">
+      <path d="M8 2.5l5 2v3.8c0 2.2-1.3 4.1-5 5.3-3.7-1.2-5-3.1-5-5.3V4.5l5-2z"></path>
+      <path d="M5.7 8.3l1.6 1.7 3-3.1"></path>
+    </symbol>
+    <symbol id="ico-inspect" viewBox="0 0 16 16">
+      <circle cx="7" cy="7" r="3.8"></circle>
+      <path d="M9.8 9.8l3.2 3.2"></path>
+    </symbol>
+    <symbol id="ico-scope" viewBox="0 0 16 16">
+      <rect x="2.5" y="2.5" width="4.2" height="4.2"></rect>
+      <rect x="9.3" y="2.5" width="4.2" height="4.2"></rect>
+      <rect x="2.5" y="9.3" width="4.2" height="4.2"></rect>
+      <rect x="9.3" y="9.3" width="4.2" height="4.2"></rect>
+    </symbol>
+    <symbol id="ico-queue" viewBox="0 0 16 16">
+      <path d="M5.4 4h8.1M5.4 8h8.1M5.4 12h8.1"></path>
+      <circle cx="3.2" cy="4" r="0.7"></circle>
+      <circle cx="3.2" cy="8" r="0.7"></circle>
+      <circle cx="3.2" cy="12" r="0.7"></circle>
+    </symbol>
+  </svg>