diff --git a/demo/web/templates/base.html b/demo/web/templates/base.html index 16c2a12..9b8483b 100644 --- a/demo/web/templates/base.html +++ b/demo/web/templates/base.html @@ -60,6 +60,19 @@ + + + + + + + + + + + + + diff --git a/demo/web/templates/controls_pattern.html b/demo/web/templates/controls_pattern.html index 5f5573d..b795e0b 100644 --- a/demo/web/templates/controls_pattern.html +++ b/demo/web/templates/controls_pattern.html @@ -69,7 +69,7 @@
Import/Export
- +
diff --git a/demo/web/templates/operator_tools_pattern.html b/demo/web/templates/operator_tools_pattern.html index 1522835..cc99f43 100644 --- a/demo/web/templates/operator_tools_pattern.html +++ b/demo/web/templates/operator_tools_pattern.html @@ -26,15 +26,16 @@
-
+
-

Operator Tooling Actions

-
Batch controls must keep scope/filter context explicit
+

Operations Queue

+
Complex dashboards may include multiple tables; standardize row actions and statuses first.
{{ if .ActionMessage }}
{{ .ActionMessage }}
{{ end }}

Selected on this view: {{ .SelectedVisible }}{{ if gt .SelectionOutside 0 }} · Selected outside current filter: {{ .SelectionOutside }}{{ end }}

+
Batch controls must keep scope/filter context explicit.
-
- -
-
-

Operations Queue

-
Complex dashboards may include multiple tables; standardize row actions and statuses first.
-
diff --git a/exports/bundles/ui-pattern-controls.yaml b/exports/bundles/ui-pattern-controls.yaml index f502342..26e176e 100644 --- a/exports/bundles/ui-pattern-controls.yaml +++ b/exports/bundles/ui-pattern-controls.yaml @@ -4,7 +4,7 @@ "description": "Buttons, checkboxes, segmented filters, and bulk-selection control patterns.", "conflict_policy": "merge-manual", "entries": [ - { "from": "patterns/controls-selection", "to": "docs/ui-patterns/controls-selection", "mode": "dir" } + { "from": "patterns/controls-selection", "to": "docs/ui-patterns/controls-selection", "mode": "dir" }, + { "from": "patterns/table-management", "to": "docs/ui-patterns/table-management", "mode": "dir" } ] } - diff --git a/exports/bundles/ui-pattern-operator-tools.yaml b/exports/bundles/ui-pattern-operator-tools.yaml index 9646b52..6cdbfd3 100644 --- a/exports/bundles/ui-pattern-operator-tools.yaml +++ b/exports/bundles/ui-pattern-operator-tools.yaml @@ -4,6 +4,7 @@ "description": "Universal operator/admin dashboard pattern: queue tables, batch actions, and safety guardrails.", "conflict_policy": "merge-manual", "entries": [ - { "from": "patterns/operator-tools", "to": "docs/ui-patterns/operator-tools", "mode": "dir" } + { "from": "patterns/operator-tools", "to": "docs/ui-patterns/operator-tools", "mode": "dir" }, + { "from": "patterns/table-management", "to": "docs/ui-patterns/table-management", "mode": "dir" } ] } diff --git a/exports/bundles/ui-theme-aqua-legacy.yaml b/exports/bundles/ui-theme-aqua-legacy.yaml index be97f05..b1160f3 100644 --- a/exports/bundles/ui-theme-aqua-legacy.yaml +++ b/exports/bundles/ui-theme-aqua-legacy.yaml @@ -1,7 +1,7 @@ { "id": "ui-theme-aqua-legacy", "version": 1, - "description": "Legacy snapshot bundle of the Aqua-style visual exploration (reference only, not active baseline).", + "description": "Canonical Aqua theme layer for shared UI primitives, including icon sprite and reusable component chrome.", "conflict_policy": "merge-manual", "entries": [ { "from": "patterns/theme-aqua-legacy", "to": "docs/ui-themes/aqua-legacy", "mode": "dir" } diff --git a/kit/patterns/controls-selection/contract.md b/kit/patterns/controls-selection/contract.md index d877d5f..af2c067 100644 --- a/kit/patterns/controls-selection/contract.md +++ b/kit/patterns/controls-selection/contract.md @@ -1,5 +1,12 @@ # Contract: Controls + Selection +## Shared Base + +- This pattern inherits the shared `table-management` contract: + `kit/patterns/table-management/contract.md`. +- Reuse shared toolbar/table/icon geometry from the base contract first, then define only + controls-specific additions below. + ## Buttons - Use a small stable button taxonomy: `primary`, `secondary`, `ghost`, `danger`, `disabled`. diff --git a/kit/patterns/operator-tools/contract.md b/kit/patterns/operator-tools/contract.md index 2e66936..4568912 100644 --- a/kit/patterns/operator-tools/contract.md +++ b/kit/patterns/operator-tools/contract.md @@ -1,5 +1,12 @@ # Contract: Operator Tools Dashboard +## Shared Base + +- This pattern inherits the shared `table-management` contract: + `kit/patterns/table-management/contract.md`. +- Reuse shared toolbar/table/icon geometry from the base contract first, then define only + operator-specific behavior. + ## Purpose Provide a canonical structure for high-density operator/admin screens without encoding diff --git a/kit/patterns/table-management/README.md b/kit/patterns/table-management/README.md new file mode 100644 index 0000000..130f9d7 --- /dev/null +++ b/kit/patterns/table-management/README.md @@ -0,0 +1,25 @@ +# Table Management Pattern (Shared Module) + +Shared reusable module for high-density table screens across patterns. + +This module is the canonical source for: + +- unified table toolbar layout (single container, grouped actions, vertical separators) +- icon-first action buttons with deterministic semantics +- 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) + +Use this module as the base interaction contract for: + +- `controls-selection` +- `operator-tools` + +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` +- Global Aqua stylesheet: `../theme-aqua-legacy/demo-aqua-freeze.css` diff --git a/kit/patterns/table-management/contract.md b/kit/patterns/table-management/contract.md new file mode 100644 index 0000000..1cb64cf --- /dev/null +++ b/kit/patterns/table-management/contract.md @@ -0,0 +1,84 @@ +# Contract: Table Management (Shared) + +## Scope + +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: +`kit/patterns/theme-aqua-legacy`. + +## Canonical Regions + +1. Selection summary line (visible/selected counts). +2. Unified table toolbar (single module container). +3. Data table body. +4. Pagination. + +Toolbar and table must read as one continuous module: + +- toolbar directly above table, +- no double borders/rounded-corner seams at the join, +- table horizontal overflow remains enabled when needed. + +## Toolbar Geometry + +- One outer toolbar container for all groups. +- Groups are separated with vertical separators. +- Group title + icon buttons are inline and compact. +- Group order is fixed: + 1. `Selection` + 2. `Actions` + 3. `Import/Export` + 4. `Task Actions` + 5. `Misc` + +## Button Model + +- Buttons are icon-first inside toolbar groups. +- Each button must expose deterministic semantics via `title` and `aria-label`. +- Keep primary and destructive variants explicit via style tokens, not by icon ambiguity alone. + +## Icon Semantics (One Action = One Icon) + +Do not reuse the same icon for semantically different actions in this module. + +Canonical mapping: + +- `select visible` -> checked square +- `select filtered` -> filter + plus +- `clear visible` -> square + minus +- `clear filtered` -> filter + close +- `clear selection` -> clear selection icon (distinct from remove/cancel/archive) +- `run` -> play/execute +- `edit` -> pencil +- `remove` -> remove/delete row +- `cancel` -> cancel task (distinct from remove/archive) +- `archive` -> archive box/tray +- `import` -> arrow into container +- `export` -> arrow out of container +- `export filtered` -> export + filter marker +- `export selected` -> export + checkbox marker +- `retry/sync` -> circular refresh (two arrows along path) +- `review` -> info/review marker +- `confirm` -> confirm/check marker +- `inspect` -> inspect/zoom marker + +## Table Columns + +- Left `select` column: + - no text header label, + - minimal fixed width, + - centered checkbox control. +- Right `actions` column: + - no text header label, + - minimal width, + - right-aligned action icons. +- Row action icons in `actions` column are intentionally smaller than toolbar icons. + +## Reuse Rule + +If a pattern needs table selection + bulk actions, it must: + +1. Reuse this module unchanged by default. +2. Document only additive overrides in the pattern-specific contract. +3. Avoid redefining shared geometry/icon semantics locally. diff --git a/kit/patterns/theme-aqua-legacy/README.md b/kit/patterns/theme-aqua-legacy/README.md index fd924f0..9269ef2 100644 --- a/kit/patterns/theme-aqua-legacy/README.md +++ b/kit/patterns/theme-aqua-legacy/README.md @@ -1,14 +1,17 @@ -# macOS Aqua Theme Snapshot (Legacy) +# Aqua Theme Module (Canonical Design Layer) -Status: legacy reference only (not active baseline) +Status: canonical Aqua design layer for reusable UI primitives. -This directory preserves the Aqua-style visual exploration snapshot that was developed during demo -refinement. It is stored as a reusable archive bundle so it can be referenced later without -driving the active baseline. +This directory defines the shared Aqua visual language for the design code: -Active visual baseline for the demo/scaffold is Aqua-first. This package is a frozen snapshot for archival/reference use. +- 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. Contents: -- `demo-aqua-freeze.css` — frozen snapshot of the demo stylesheet at the time of the freeze -- `notes.md` — summary of what was explored and how to treat the snapshot +- `demo-aqua-freeze.css` — canonical Aqua stylesheet baseline used by demo/scaffold references +- `templates/icon_sprite.html` — canonical icon sprite for reusable action semantics +- `notes.md` — scope and usage policy for this theme module diff --git a/kit/patterns/theme-aqua-legacy/notes.md b/kit/patterns/theme-aqua-legacy/notes.md index 3df4332..cfab227 100644 --- a/kit/patterns/theme-aqua-legacy/notes.md +++ b/kit/patterns/theme-aqua-legacy/notes.md @@ -1,22 +1,22 @@ -# Aqua Legacy Snapshot Notes +# Aqua Theme Notes -This snapshot is kept for historical reference and selective reuse. +This module is the reusable Aqua style source for design-code consumers. ## What it captures - Aqua-style control surfaces and button hierarchy -- segmented controls and tab-like grouped buttons -- modal window chrome experiments (titlebar + close button) -- table/filter visual refinements and dot-pager styling -- style-playground Aqua preset refinements +- segmented controls and grouped tab geometry +- table/filter/toolbars visual primitives +- icon rendering baseline and shared icon sprite usage +- modal and status component style language -## What it is not +## How to use -- Not a required dependency for host projects -- Not the live source of truth for the current Aqua baseline (the live baseline is in demo/scaffold CSS) -- Not the target for normal iterative styling work unless explicitly requested +- Treat this module as the visual baseline for reusable UI components in this repository. +- Pattern contracts should reference this module instead of redefining shared visual primitives. +- When visual behavior changes in demo/scaffold, sync the canonical rules here so host projects can reproduce the same output deterministically. -## Current policy +## Boundary -- Active baseline styling remains Aqua-first in the live demo/scaffold assets. -- Use this snapshot only when explicitly needed for archival comparison or extraction. +- This module standardizes visual language only. +- Domain behavior, labels, and business workflow semantics belong to pattern contracts. diff --git a/kit/patterns/theme-aqua-legacy/templates/icon_sprite.html b/kit/patterns/theme-aqua-legacy/templates/icon_sprite.html new file mode 100644 index 0000000..eff1d2c --- /dev/null +++ b/kit/patterns/theme-aqua-legacy/templates/icon_sprite.html @@ -0,0 +1,103 @@ + +