ui-style-kit-css 2.2.0 → 2.4.0

package/docs/superpowers/plans/2026-09-04-library-wide-theme-fallback-and-fidelity.md

@@ -0,0 +1,331 @@
+# Library-wide Theme Fallback and Fidelity Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make all 20 presets use design-reference fallback colors only when no color theme is selected while preserving theme ownership, accessibility, and reference-specific light, dark, and contrast identities.
+
+**Architecture:** Each preset publishes mode-specific fallback RGB channels and resolves its public color roles with `var(--usk-*-rgb, var(--<prefix>-fallback-*-rgb))`. Shared native, semantic, and overflow layers activate for `[data-ui][data-mode]`; explicit themes continue to define the `--usk-*` producer channels and therefore override every preset fallback without changing preset geometry or material recipes.
+
+**Tech Stack:** CSS custom properties and cascade layers, Node.js test runner, css-tree, Stylelint, Lightning CSS, Playwright, axe-core.
+
+**Spec:** `docs/superpowers/specs/2026-09-04-library-wide-theme-fallback-and-fidelity-design.md`
+
+## Global Constraints
+
+- Preserve all public preset IDs, prefixes, class names, entrypoints, manifest schema, and cascade layer order.
+- Preserve unrelated dirty working-tree changes.
+- `data-ui` and `data-mode` remain required; `data-theme` becomes optional.
+- Explicit themes own every visible paint role; no-theme fallbacks match the retained design references.
+- Run focused tests during implementation and the full verification chain only after all implementation tasks are complete.
+- Write production JavaScript comments as professional JSDoc parseable by jsdoc2md.
+- Update generated CSS only with `npm.cmd run build`.
+- Do not deploy, publish, push, or rewrite the branch.
+
+---
+
+### Task 1: Lock the optional-theme semantic contract
+
+**Files:**
+- Create: `tests/theme-fallbacks.test.js`
+- Modify: `tests/theme-colors.test.js`
+- Modify: `scripts/check-contrast.mjs`
+
+**Interfaces:**
+- Consumes: `manifest.presets`, `manifest.modes`, and the existing 23-role semantic color list.
+- Produces: static assertions for fallback resolution and exported `validateFallbackContrast(cssByPreset)` coverage used by the contrast CLI.
+
+- [ ] **Step 1: Write the failing static contract test**
+
+Create a manifest-driven test that requires every preset/mode to expose all 23 `--<prefix>-fallback-*-rgb` channels, requires each resolved public role to use the corresponding `--usk-*` channel with the preset fallback as the second argument, and requires themed direct aliases to remain present for build-time extraction.
+
+```js
+test('every preset resolves explicit themes before its mode fallback palette', () => {
+  for (const { id, prefix } of manifest.presets) {
+    const css = read(`styles/${id}.css`);
+    for (const mode of manifest.modes) {
+      const block = exactBlock(css, `[data-ui="${id}"][data-mode="${mode}"]`);
+      for (const role of colorRoles) {
+        assert.match(block, new RegExp(`--${prefix}-fallback-${role}-rgb:\\s*\\d+ \\d+ \\d+;`));
+      }
+    }
+    const resolver = exactBlock(css, `[data-ui="${id}"][data-mode]`);
+    for (const role of colorRoles) {
+      assert.match(
+        resolver,
+        new RegExp(`--${prefix}-${role}-rgb:\\s*var\\(--usk-${role}-rgb,\\s*var\\(--${prefix}-fallback-${role}-rgb\\)\\);`)
+      );
+    }
+  }
+});
+```
+
+- [ ] **Step 2: Run only the new test and verify RED**
+
+Run: `node --test tests/theme-fallbacks.test.js`
+
+Expected: FAIL because most presets do not expose fallback role blocks or a fallback-aware resolver.
+
+- [ ] **Step 3: Extend the contrast checker test seam**
+
+Add a failing unit assertion in `tests/contrast-contract.test.js` for an exported fallback validator that rejects a no-theme palette whose text/background ratio is below the existing threshold.
+
+- [ ] **Step 4: Run the single contrast contract test and verify RED**
+
+Run: `node --test tests/contrast-contract.test.js`
+
+Expected: FAIL because `validateFallbackContrast` is not exported.
+
+- [ ] **Step 5: Implement the minimal fallback contrast validator**
+
+Reuse the existing RGB parser and contrast functions. Validate the same text/surface, action/foreground, status/foreground, border, and control-edge pairs for the 60 preset/mode fallback states. Document the exported function with JSDoc.
+
+- [ ] **Step 6: Run the contrast contract test and verify GREEN**
+
+Run: `node --test tests/contrast-contract.test.js`
+
+Expected: PASS.
+
+### Task 2: Make shared accessibility layers independent of `data-theme`
+
+**Files:**
+- Modify: `styles/native-elements.css`
+- Modify: `styles/components.css`
+- Modify: `styles/content-overflow.css`
+- Modify: `tests/native-elements-contract.test.js`
+- Modify: `tests/semantic-component-contract.test.js`
+
+**Interfaces:**
+- Consumes: resolved `--usk-native-*` and preset-prefixed roles from Task 1.
+- Produces: shared native and semantic behavior under `[data-ui][data-mode]` for themed and no-theme roots.
+
+- [ ] **Step 1: Write the failing shared-selector test**
+
+Require native foundations, focus-visible rules, reduced-motion rules, contrast reinforcement, forced-colors rules, component containment, and overflow guards to activate through `[data-ui][data-mode]` without a `data-theme` dependency.
+
+- [ ] **Step 2: Run the native contract test and verify RED**
+
+Run: `node --test tests/native-elements-contract.test.js`
+
+Expected: FAIL on the current `[data-ui][data-theme][data-mode]` selectors.
+
+- [ ] **Step 3: Broaden only shared activation selectors**
+
+Replace theme-required shared roots with `[data-ui][data-mode]`. Keep theme producer selectors in `styles/theme-colors.css` unchanged so no fallback leaks into explicit schemes.
+
+- [ ] **Step 4: Run the native contract test and verify GREEN**
+
+Run: `node --test tests/native-elements-contract.test.js`
+
+Expected: PASS.
+
+- [ ] **Step 5: Run the semantic component contract test once**
+
+Run: `node --test tests/semantic-component-contract.test.js`
+
+Expected: PASS after selector fingerprints are regenerated at the final build; if the only failure is the known generated artifact fingerprint, defer that fingerprint update to Task 6.
+
+### Task 3: Add reference-derived fallbacks and resolvers to the first ten presets
+
+**Files:**
+- Modify: `styles/minimal-saas.css`
+- Modify: `styles/bento.css`
+- Modify: `styles/maximalist.css`
+- Modify: `styles/bauhaus.css`
+- Modify: `styles/tactile.css`
+- Modify: `styles/neumorphism.css`
+- Modify: `styles/retrofuturism.css`
+- Modify: `styles/brutalism.css`
+- Modify: `styles/cyberpunk.css`
+- Modify: `styles/y2k.css`
+
+**Interfaces:**
+- Consumes: the Task 1 resolver contract and the retained template references.
+- Produces: complete light/dark/contrast fallback palettes and theme-derived material paint for presets 1–10.
+
+- [ ] **Step 1: Add one failing preset assertion at a time**
+
+For each preset, add its three fallback blocks to the shared test fixture expectations before editing production CSS. Each role must use explicit RGB integers and include paired foreground roles.
+
+- [ ] **Step 2: Run only that preset's test case and verify RED**
+
+Run these exact commands in order, stopping at the first failure:
+
+```powershell
+node --test --test-name-pattern="minimal-saas" tests/theme-fallbacks.test.js
+node --test --test-name-pattern="bento" tests/theme-fallbacks.test.js
+node --test --test-name-pattern="maximalist" tests/theme-fallbacks.test.js
+node --test --test-name-pattern="bauhaus" tests/theme-fallbacks.test.js
+node --test --test-name-pattern="tactile" tests/theme-fallbacks.test.js
+node --test --test-name-pattern="neumorphism" tests/theme-fallbacks.test.js
+node --test --test-name-pattern="retrofuturism" tests/theme-fallbacks.test.js
+node --test --test-name-pattern="brutalism" tests/theme-fallbacks.test.js
+node --test --test-name-pattern="cyberpunk" tests/theme-fallbacks.test.js
+node --test --test-name-pattern="y2k" tests/theme-fallbacks.test.js
+```
+
+Expected: FAIL because the selected preset is missing the new contract.
+
+- [ ] **Step 3: Implement that preset's fallback and resolver**
+
+Add mode-specific fallback channels, move runtime aliases/native mappings to `[data-ui="<preset>"][data-mode]`, retain a small direct themed alias seam, and derive material paint from resolved prefixed roles.
+
+- [ ] **Step 4: Run only that preset's test case and verify GREEN**
+
+Rerun only the exact preset command from Step 2.
+
+Expected: PASS.
+
+- [ ] **Step 5: Repeat Steps 1–4 sequentially for all ten listed presets**
+
+Do not rerun a green preset case unless a later shared resolver refactor can affect it.
+
+### Task 4: Add reference-derived fallbacks and resolvers to the remaining ten presets
+
+**Files:**
+- Modify: `styles/retro-glass.css`
+- Modify: `styles/editorial-luxe.css`
+- Modify: `styles/organic-modern.css`
+- Modify: `styles/industrial-utility.css`
+- Modify: `styles/technical-blueprint.css`
+- Modify: `styles/art-deco.css`
+- Modify: `styles/clay.css`
+- Modify: `styles/data-terminal.css`
+- Modify: `styles/paper-editorial.css`
+- Modify: `styles/neo-noir.css`
+
+**Interfaces:**
+- Consumes: the Task 1 resolver contract and the retained paired or combined template references.
+- Produces: complete light/dark/contrast fallback palettes and theme-derived material paint for presets 11–20.
+
+- [ ] **Step 1: Add one failing preset assertion at a time**
+
+Use the same executable contract as Task 3. Preserve existing in-progress fidelity work in these dirty files and add only the missing fallback/theme boundary.
+
+- [ ] **Step 2: Run only that preset's test case and verify RED**
+
+Run these exact commands in order, stopping at the first failure:
+
+```powershell
+node --test --test-name-pattern="retro-glass" tests/theme-fallbacks.test.js
+node --test --test-name-pattern="editorial-luxe" tests/theme-fallbacks.test.js
+node --test --test-name-pattern="organic-modern" tests/theme-fallbacks.test.js
+node --test --test-name-pattern="industrial-utility" tests/theme-fallbacks.test.js
+node --test --test-name-pattern="technical-blueprint" tests/theme-fallbacks.test.js
+node --test --test-name-pattern="art-deco" tests/theme-fallbacks.test.js
+node --test --test-name-pattern="clay" tests/theme-fallbacks.test.js
+node --test --test-name-pattern="data-terminal" tests/theme-fallbacks.test.js
+node --test --test-name-pattern="paper-editorial" tests/theme-fallbacks.test.js
+node --test --test-name-pattern="neo-noir" tests/theme-fallbacks.test.js
+```
+
+Expected: FAIL on the missing or incomplete fallback resolver.
+
+- [ ] **Step 3: Implement that preset's fallback and resolver**
+
+Where Technical Blueprint or Data Terminal already contain no-theme work, reconcile it into the shared contract without deleting reference-fidelity declarations or weakening direct alias extraction.
+
+- [ ] **Step 4: Run only that preset's test case and verify GREEN**
+
+Rerun only the exact preset command from Step 2.
+
+Expected: PASS.
+
+- [ ] **Step 5: Repeat Steps 1–4 sequentially for all ten listed presets**
+
+Do not rerun green cases unnecessarily.
+
+### Task 5: Prove runtime theme ownership and accessibility states
+
+**Files:**
+- Modify: `tests/e2e/demo.spec.js`
+- Modify: `tests/e2e/accessibility.spec.js`
+- Modify: `tests/demo-visual.spec.mjs`
+- Modify: `scripts/preset-identities.mjs`
+- Modify: `design-qa.md`
+
+**Interfaces:**
+- Consumes: all 20 fallback-aware preset styles and the existing component/native demo specimens.
+- Produces: computed-style and visual evidence for themed, fallback, light, dark, contrast, focus, disabled, reduced-motion, and forced-colors states.
+
+- [ ] **Step 1: Write a failing computed-style matrix case**
+
+For each preset and mode, capture representative prefixed card/button/input/range/progress paint, semantic `.ui-*` paint, and native element paint without `data-theme`; then apply two materially different themes and assert that semantic paint changes while geometry remains stable.
+
+- [ ] **Step 2: Run only the new Chromium matrix case and verify RED**
+
+Run: `npm.cmd exec playwright test -- --config playwright.config.js tests/e2e/demo.spec.js --project=chromium --grep "fallback and explicit theme ownership"`
+
+Expected: FAIL for presets whose shared or authored selectors still require `data-theme` or whose material paint is fixed.
+
+- [ ] **Step 3: Repair only reported cascade leaks**
+
+Change fixed visible paint to resolved semantic channels, preserve neutral optical overlays, and add later preset-specific native overrides only where shared selector order wins unexpectedly.
+
+- [ ] **Step 4: Rerun the single Chromium matrix case and verify GREEN**
+
+Run the exact command from Step 2.
+
+Expected: PASS.
+
+- [ ] **Step 5: Add and run the focused accessibility case**
+
+Verify focus visibility, labels, disabled states, and axe results for one fallback and one explicit theme in each mode. Run only the new named accessibility case until it passes.
+
+- [ ] **Step 6: Update executable identity traits and the QA ledger**
+
+Record each template's typography, density, geometry, material, feedback, and data evidence. Keep paint traits semantic so theme switching cannot erase identity.
+
+### Task 6: Regenerate artifacts and run the final verification chain
+
+**Files:**
+- Generated: `dist/ui-style-kit.css`
+- Generated: `dist/ui-style-kit.min.css`
+- Generated: `dist/ui-style-kit.visual.css`
+- Generated: `dist/ui-style-kit.visual.min.css`
+- Generated: `dist/ui-style-kit.with-bridge.css`
+- Generated: `dist/ui-style-kit.with-bridge.min.css`
+- Generated: `dist/visual/*.css`
+- Modify if generated fingerprint changes: `tests/semantic-component-contract.test.js`
+- Modify if bundle sizes change: `README.md`
+
+**Interfaces:**
+- Consumes: all authored source and tests from Tasks 1–5.
+- Produces: publishable generated bundles and final local verification evidence.
+
+- [ ] **Step 1: Build once**
+
+Run: `npm.cmd run build`
+
+Expected: all default, visual-only, focused visual, and compatibility entrypoints regenerate successfully.
+
+- [ ] **Step 2: Update generated artifact fingerprints if required**
+
+Use the build output as the only source of truth. Update the exact declaration count and SHA-256 expectations, then run only `tests/semantic-component-contract.test.js`.
+
+- [ ] **Step 3: Run the final static chain sequentially**
+
+Run, in order, stopping at the first failure:
+
+```powershell
+npm.cmd run lint
+npm.cmd run test:unit
+npm.cmd run check:contrast
+npm.cmd run check:compat
+npm.cmd run check:ownership
+npm.cmd run check:package
+git diff --check
+```
+
+- [ ] **Step 4: Run focused browser and accessibility verification**
+
+Run the new theme-ownership case, reference-fidelity cases, and axe case. Do not claim cross-browser success for an engine that was not freshly exercised.
+
+- [ ] **Step 5: Run the visual suite once at the end**
+
+Run: `npm.cmd run test:visual`
+
+Expected: approved snapshots pass or are updated only after direct reference/prototype comparison confirms the intended differences.
+
+- [ ] **Step 6: Review the integrated diff**
+
+Confirm that only approved source, tests, documentation, generated bundles, and reviewed snapshots changed. Report unrelated pre-existing dirty files separately and do not stage, revert, or overwrite them.

package/docs/superpowers/specs/2026-08-29-preset-identity-system-refinement-design.md

@@ -0,0 +1,212 @@
+# Preset Identity System Refinement Design
+
+Date: 2026-08-29
+Status: Approved and implemented for the 2.3.0 release candidate
+Target release: `ui-style-kit-css@2.3.0`
+
+## Purpose
+
+Refine all 20 UI presets so their public components and native-element fallbacks read as coherent design systems rather than a shared component library with isolated `clip-path` changes. The work corrects the demo regressions shown in the August 29 screenshots while preserving the existing public class API, theme names, modes, token roles, and companion-library compatibility.
+
+## Problem Statement
+
+The current 2.3.0 candidate gives many presets a distinct cut-button polygon, spinner, or card decoration, but the identity is not carried consistently across the rest of the component vocabulary.
+
+The most visible mechanisms are:
+
+- The demo combines `button-outline-heavy` and `button-cut` on every `View Usage` action. This makes the outlined action inherit the same polygon-first treatment as the filled service-card action.
+- Most `button-outline-heavy` rules share the same transparent background, two-pixel primary border, and hover fill. Only a few presets add meaningful material or depth differences.
+- Native buttons and dialogs are driven by one shared geometry recipe. Preset variables alter radius and color, but do not establish a complete preset-specific control or surface identity.
+- Most metrics use one generic card recipe. Bento's six-column tile helper can become too narrow inside the demo container, causing labels to wrap into unreadable columns.
+- Several service-card actions stretch across the card because grid items stretch by default. A different polygon on the same full-width bar does not create a meaningfully different component.
+- The existing tests require a clipped CTA and distinct composite signatures, but do not prove that the same identity vocabulary appears across filled actions, outlined actions, surfaces, metrics, and native fallbacks.
+
+## Goals
+
+1. Give every preset a recognizable and internally consistent component identity.
+2. Keep filled and outlined CTAs visibly related without making them identical.
+3. Make CTA width and alignment intentional for each preset family.
+4. Carry the identity into service cards, media scrims, metrics or tiles, feature strips, callout bars, dialogs, and native buttons.
+5. Correct Bento metric wrapping and other demo containment problems without changing consumer heading scales.
+6. Preserve all public classes, modes, themes, focused exports, deprecated structural helpers, bridge exports, and companion ownership order.
+7. Prevent future drift with a manifest-complete identity registry and focused contracts.
+
+## Non-Goals
+
+- No new public class names.
+- No removed or renamed classes, tokens, themes, modes, or exports.
+- No color-theme redesign. Components continue to consume the active theme tokens.
+- No changes to companion-library ownership or bridge activation.
+- No commit, push, tag, GitHub release, or npm publication.
+- No broad demo redesign outside the affected component specimens.
+
+## Design Principles
+
+Each preset is defined across four connected axes:
+
+1. **Silhouette:** corner logic, contour, framing, and control proportion.
+2. **Border rhythm:** weight, doubling, offset, technical marks, or restrained hairlines.
+3. **Material and depth:** flat, raised, inset, frosted, glossy, printed, metallic, or luminous treatment.
+4. **Composition:** content alignment, action width, density, and placement.
+
+Color remains independent. The active color scheme supplies semantic tokens; the UI preset supplies the geometry and material treatment.
+
+## Architecture
+
+### Manifest-driven identity registry
+
+Add a JavaScript identity registry keyed by the 20 `manifest.json` preset IDs. Each entry records:
+
+- preset ID and prefix;
+- human-readable identity description;
+- CTA composition family;
+- required component selectors;
+- stable identity markers for silhouette, border, depth, and alignment;
+- expected native-element treatment markers.
+
+The registry is an internal build and test source of truth, not a new public API. JavaScript exports and helpers will use JSDoc-compatible comments.
+
+The registry will be validated against `manifest.json` in both directions: every manifest preset must have exactly one identity entry, and no identity entry may reference a removed preset. Tests will compute a normalized identity signature from the authored CSS and reject duplicate signatures.
+
+Authored CSS remains in `styles/`. The registry will not hide arbitrary CSS declaration strings inside JavaScript. Instead, it describes the required design vocabulary and lets focused contracts validate the explicit rules in each preset stylesheet. Generated `dist/` files continue to come only from the existing build pipeline.
+
+### CTA role separation
+
+The commercial demo will use:
+
+- `button-primary button-cut` for the filled `Explore` service action;
+- `button-outline-heavy` for the outlined `View Usage` callout action.
+
+The outlined action will no longer stack `button-cut`. Each preset's `button-outline-heavy` rule will receive its own related geometry, border, material, and alignment treatment. The filled and outlined actions will share a motif, not an identical silhouette.
+
+The public modifiers remain independently composable. Existing consumer markup that intentionally combines them will continue to work.
+
+### CTA composition families
+
+CTA size and placement will follow the component identity rather than default grid stretching:
+
+- **Precise and compact:** Minimal SaaS, Editorial Luxe, Industrial Utility, Technical Blueprint, Data Terminal, and Paper Editorial use content-sized actions aligned to the reading edge.
+- **Tile and block:** Bento, Bauhaus, and Brutalism use deliberate block treatments with bounded widths, hard alignment, and stronger structural weight.
+- **Soft and sculpted:** Neumorphism, Organic Modern, Clay, and Y2K use compact centered actions with raised, inset, pebble, inflated, or glossy material cues.
+- **Elongated and atmospheric:** Retrofuturism, Cyberpunk, Retro Glass, and Neo Noir use controlled console or cinematic proportions without defaulting to the full card width.
+- **Expressive and physical:** Maximalist and Tactile use offset poster-like or keycap-like actions with deliberate depth.
+
+Mobile layouts may stretch actions only when the available width requires it. The action height, label flow, and focus indicator must remain intact.
+
+## Preset Identity Matrix
+
+| Preset | Connected component identity |
+| --- | --- |
+| Minimal SaaS | Restrained single-corner fold, fine outline, low elevation, compact left-aligned controls. |
+| Bento | Stepped tile corners, compact block proportions, nested tile borders, bounded block actions. |
+| Maximalist | Skewed poster silhouette, layered fill, offset decoration, pronounced playful shadow. |
+| Bauhaus | Asymmetric primary geometry, hard edges, opposing cuts, high-contrast structural blocks. |
+| Tactile | Shallow chamfered keycap, bevel highlight, pressed depth, physical control spacing. |
+| Neumorphism | Soft clipped surface, raised and inset paired shadows, quiet borders, centered controls. |
+| Retrofuturism | Elongated console geometry, metallic rim, instrument-like framing, compact display labels. |
+| Brutalism | Blunt cut, thick border, hard offset shadow, dense block alignment. |
+| Cyberpunk | Multi-notch technical polygon, neon edge, console framing, luminous action emphasis. |
+| Y2K | Glossy hexagonal capsule, reflective highlight, playful centered composition. |
+| Retro Glass | Frosted angular tab, inner highlight, translucent framing, restrained glass depth. |
+| Editorial Luxe | Slim bookplate, hairline or double framing, serif-led hierarchy, compact reading-edge action. |
+| Organic Modern | Asymmetric pebble or leaf contour, soft layered depth, relaxed centered composition. |
+| Industrial Utility | Octagonal hazard-control geometry, equipment border, compact operational density. |
+| Technical Blueprint | Drafting-corner outline, technical ticks or inset rules, precise left alignment. |
+| Art Deco | Symmetric chevron ends, double-rule framing, centered ornamental composition. |
+| Clay | Inflated clipped pill, chunky soft shadow, compact centered action, sculpted surfaces. |
+| Data Terminal | Terminal-bracket silhouette, luminous outline, monospace density, reading-edge command action. |
+| Paper Editorial | Ticket or tab notch, inked offset edge, print rules, compact editorial action. |
+| Neo Noir | Cinematic slant, high-contrast edge light, atmospheric framing, controlled elongated action. |
+
+## Component Treatment
+
+### Service cards and media scrims
+
+Service cards will use the preset's silhouette, border rhythm, and depth treatment. The action will be explicitly sized and aligned. Media scrims will share the card contour and border treatment while retaining the proven high-contrast caption gradient and inherited caption foreground.
+
+### Metrics and Bento tiles
+
+Metrics will preserve semantic value and label elements while applying preset-specific alignment and framing. Labels must remain readable without character-by-character wrapping.
+
+Bento keeps its large/small tile hierarchy, but the six-column layout will activate only where its container can support it. At smaller container widths it will collapse to a balanced two-column layout, then one column. Tile minimum sizes and text wrapping rules will prevent the narrow cards shown in the screenshot.
+
+### Feature strips and callout bars
+
+Feature strips and callout bars will use the same border and surface language as their preset's service card. The callout action remains visually subordinate to the filled service action but must still be a recognizable member of the same preset.
+
+### Native buttons and dialogs
+
+Preset-scoped native overrides will extend the shared native foundation rather than replace it. They will adjust safe geometry, border, depth, typography, and alignment for unclassed buttons and dialogs.
+
+Aggressive clipping will not be applied to text inputs or to dialog containers when it could cut content or focus indicators. Native controls retain minimum target size, visible focus, contrast roles, disabled behavior, busy-spinner containment, and bridge ownership rules.
+
+## Demo Changes
+
+- Remove `button-cut` from the `View Usage` action.
+- Add demo-only test hooks for primary and secondary commercial actions where needed.
+- Preserve the two-column commercial grid at desktop and one-column layout on mobile.
+- Make style-specific metric specimens container-aware.
+- Keep native markup semantic and unclassed so the fallback selectors remain visible.
+- Preserve the active color-scheme token artwork and media-scrim contrast fix.
+
+## Compatibility
+
+- Existing class names and combined modifier markup remain valid.
+- Preset styles continue to live in the `ui-style-kit.presets` cascade layer and override shared native foundations through scoped selectors.
+- Interactive Surface remains responsible for state-core behavior when the bridge is attached.
+- Layout Style remains responsible for layout composition outside component-owned internals.
+- Focused preset exports and bridge bundles are regenerated from authored styles.
+- No theme token role changes are expected.
+
+## Verification Strategy
+
+### Focused static and unit contracts
+
+1. Registry coverage exactly matches all 20 manifest presets and prefixes.
+2. Each preset exposes a complete identity signature across:
+   - `button-cut`;
+   - `button-outline-heavy`;
+   - service card or media surface;
+   - metric or preset-specific tile;
+   - callout bar;
+   - native button and dialog treatment.
+3. No two presets have the same normalized composite signature.
+4. The demo does not stack `button-cut` on `View Usage`.
+5. CTA composition declares an intentional width and alignment strategy.
+6. Bento contains container-aware large/small tile fallbacks.
+7. Public API, containment inventory, contrast, package, and generated-bundle contracts remain green.
+
+### Rendered geometry and accessibility
+
+When the approved browser surface is available, verify all 20 presets at 1440px, 1024px, and 390px:
+
+- filled and outlined actions are visibly related but distinct;
+- action labels do not become vertical or overflow;
+- metrics and Bento tiles do not collapse into narrow columns;
+- dialogs and native buttons remain contained;
+- focus indicators remain visible around clipped or framed controls;
+- light, dark, contrast, reduced-motion, disabled, busy, and keyboard states remain usable;
+- no page-level horizontal overflow is introduced.
+
+If browser access remains blocked by the active browser policy, static and build evidence will be reported separately and rendered acceptance will remain explicitly unverified.
+
+### Final release gate
+
+After focused checks and distribution regeneration, run the complete release gate only once at the end:
+
+1. `npm.cmd run release:verify`
+2. `git diff --check`
+3. package tarball inspection
+4. version-surface and generated-size synchronization checks
+5. final working-tree report
+
+## Acceptance Criteria
+
+- All 20 presets have intentional, recognizable, and internally consistent component identities.
+- The `Explore` and `View Usage` actions no longer look like the same generic clipped CTA.
+- The five screenshot regressions are addressed at their underlying library or demo mechanism.
+- Bento metrics remain readable at desktop, tablet, and mobile container widths.
+- Native buttons and dialogs visibly inherit preset identity without losing accessibility.
+- No public API is removed or renamed.
+- Focused tests and the final local release gate pass, with rendered-browser limitations reported honestly.
+- The final handoff remains an uncommitted local 2.3.0 release candidate.

package/docs/superpowers/specs/2026-09-04-library-wide-theme-fallback-and-fidelity-design.md

@@ -0,0 +1,113 @@
+# Library-wide Theme Fallback and Fidelity Design
+
+## Status
+
+Approved on 2026-09-04. The user selected the shared semantic resolver with preset-owned no-theme fallback palettes.
+
+## Objective
+
+Make all 20 public UI presets satisfy one predictable color contract while preserving their reference-specific visual identities:
+
+- An explicit `data-theme` owns every visible paint role.
+- Without `data-theme`, each preset supplies an accessible light, dark, or contrast fallback palette derived from its retained design reference.
+- Typography, geometry, density, texture, elevation, and interaction behavior remain preset-owned in every color scheme.
+- Shared native-element, semantic-component, overflow, accessibility, reduced-motion, high-contrast, and forced-colors behavior works with or without `data-theme`.
+
+## Public Contract
+
+The supported root states are:
+
+```html
+<body data-ui="minimal-saas" data-mode="light">
+<body data-ui="minimal-saas" data-theme="arctic-indigo" data-mode="light">
+<body data-ui="minimal-saas" data-mode="dark">
+<body data-ui="minimal-saas" data-theme="arctic-indigo" data-mode="dark">
+<body data-ui="minimal-saas" data-mode="contrast">
+<body data-ui="minimal-saas" data-theme="arctic-indigo" data-mode="contrast">
+```
+
+`data-ui` and `data-mode` remain required. `data-theme` becomes optional.
+
+## Color Ownership
+
+Each preset resolves its public RGB roles through the same fallback-aware expression:
+
+```css
+--<prefix>-primary-rgb: var(--usk-primary-rgb, var(--<prefix>-fallback-primary-rgb));
+```
+
+The shared theme registry defines `--usk-*` only for explicit theme/mode combinations. Therefore:
+
+1. An explicit theme always wins.
+2. A missing theme activates the preset fallback.
+3. Preset component rules consume only resolved prefixed roles or material recipes derived from those roles.
+4. Direct compatibility aliases remain available where the build and contrast tooling require literal `var(--usk-*-rgb)` declarations.
+
+Opaque surfaces, highlights, shadows, grids, ornaments, glass, enamel, paper, clay, metal, terminal cells, and other material paint must derive from resolved semantic channels. Fixed neutral overlays are permitted only for optical lighting or forced-colors interoperability and must not prevent a theme change from visibly recoloring the element.
+
+## Reference Fidelity
+
+The retained artifact-template references are authoritative for no-theme fallback identity and for non-color visual construction.
+
+| Preset | Reference identity to preserve |
+| --- | --- |
+| Minimal SaaS | restrained indigo actions, thin cool borders, compact radii, calm low-shadow panels |
+| Bento UI | soft mosaic tiles, rounded modular cards, friendly blue actions, pastel feedback |
+| Maximalist | loud collage geometry, heavy display type, layered cut-paper controls, multi-accent feedback |
+| Bauhaus | rigid workshop grid, black rules, primary geometric accents, condensed typography |
+| Tactile | warm paper, dark sidebar, copper action, olive gauges, shallow bevels and recessed tracks |
+| Neumorphism | soft continuous canvas, paired raised/inset shadows, blue controls, rounded molded geometry |
+| Retrofuturism | enamel shells, metallic double keylines, coral actions, teal bays, ringed controls |
+| Brutalism | hard black rules, square controls, blue/yellow/red utility accents, dense condensed type |
+| Cyberpunk | clipped technical frames, cyan/magenta signals, black or pale command surfaces |
+| Y2K | dense window chrome, classic blue selection, square native controls, pixel-era hierarchy |
+| Retro Glass | brushed application chrome, glossy navigation, inset glass panes, striped gauges, dark dock |
+| Editorial Luxe | double rules, Didone display type, forest actions, antique gold, oxblood danger |
+| Organic Modern | warm natural surfaces, olive hairlines, rust alerts, restrained rounded geometry |
+| Industrial Utility | squared metal panels, recessed instruments, amber controls, calibrated safety states |
+| Technical Blueprint | graph-paper grid, cyan or technical-blue linework, square measured controls |
+| Art Deco | symmetrical stepped frames, metallic keylines, teal/gold/oxblood jewel controls |
+| Clay | continuous sculpted slab, shallow seams, mineral pigments, hand-pressed components |
+| Data Terminal | one-pixel cells, monospaced type, strict semantic command colors, bracketed actions |
+| Paper Editorial | physical manual sheet, ruled print grid, cream or ink stock, limited spot colors |
+| Neo Noir | cinematic rules, skewed trapezoids, amber/teal/red/violet signals, film-grain material |
+
+For templates containing both light and dark reference panels, both panels define the paired fallback modes. For single-mode references, the dark or light counterpart must preserve the same geometry and semantic hierarchy while using an accessible inverse material treatment. Contrast mode intensifies the same identity rather than becoming a third unrelated design.
+
+## Shared Accessibility Behavior
+
+The shared selectors in `native-elements.css`, generated components, and content-overflow coverage must target `[data-ui][data-mode]`, not require `[data-theme]`.
+
+Every supported state must retain:
+
+- visible `:focus-visible` indicators;
+- readable disabled, read-only, valid, invalid, loading, selected, and indeterminate states;
+- reduced-motion behavior;
+- `prefers-contrast: more` reinforcement;
+- `forced-colors: active` interoperability;
+- native controls that inherit the active preset geometry and resolved semantic paint;
+- semantic `.ui-*` components that match their prefixed counterparts.
+
+WCAG contrast gates remain at the repository's existing thresholds. The contrast matrix must cover explicit themes and every no-theme fallback state.
+
+## Implementation Boundaries
+
+- Preserve all public preset IDs, prefixes, class names, entrypoints, manifest schema, and cascade layer order.
+- Preserve unrelated dirty working-tree changes.
+- Do not introduce a new runtime dependency or JavaScript theming requirement.
+- Do not create new artwork; retained references and existing real assets remain the visual source.
+- Generated distribution files are updated only through `npm.cmd run build`.
+- No deployment, publication, push, or branch rewrite is part of this work.
+
+## Verification Evidence
+
+Completion requires fresh evidence for:
+
+1. Static fallback/theme ownership contracts for all 20 presets and 23 semantic color roles.
+2. Shared native and semantic coverage with and without `data-theme`.
+3. WCAG contrast for 1,200 explicit theme states plus 60 fallback states.
+4. Focus, reduced-motion, `prefers-contrast`, and forced-colors behavior.
+5. Per-preset computed-style theme switching across representative prefixed, semantic, and native elements.
+6. Reference-fidelity traits across typography, density, geometry, material, feedback, and data surfaces.
+7. Regenerated default, visual-only, focused visual, and compatibility bundles.
+8. Final lint, unit, contrast, compatibility, ownership, package, focused browser, axe, and visual checks.