ui-style-kit-css 2.2.0 → 2.4.0

package/docs/PUBLISHING.md

@@ -1,28 +1,53 @@
 # Publishing Guide
 
+## 2.4.0 release workflow
+
+The current checkout is a release candidate. [Release preparation notes](RELEASE-2.4.0.md)
+record the current local scope and gates; existing visual-QA documents are historical
+evidence, not proof that subsequent edits passed browser validation. Replace the
+2.4.0 changelog's `Unreleased` marker with the actual release date at approved publication.
+
+Update the tracked `wiki/` sources with the README and docs. Publishing those pages
+to GitHub Wiki is a separate handoff, not a side effect of the CSS build. No jsdoc2md
+documentation generator is configured in this package; reusable JavaScript helpers
+use JSDoc-compatible comments, and the checked-in build owns generated CSS, manifests,
+icons, README size measurements, and demo asset hashes.
+
+Prepare `ui-style-kit-css@2.4.0` on its release branch, open a pull request against `main`, and merge only after the fast automated gate is green and any requested manual demo review is complete. The aligned companion set is `layout-style-css@3.1.0` and `interactive-surface-css@1.7.0`.
+
+Do not push `v2.4.0` before the reviewed release commit is on `main`. A pushed version tag runs Release Version Alignment, which validates the tag/package/changelog contract and creates the GitHub Release; publishing that release triggers the protected npm workflow.
+
+Release Version Alignment owns the fast automated release gate: lint, build, unit checks, the tagged Chromium release-smoke Playwright suite, and packed ecosystem preflight with `--skip-clean-install`. The visual-baseline suite, full UI matrix, and clean-install ecosystem matrix are manual escalation tools, not default push or publish blockers. The protected npm workflow intentionally does not rerun browser gates; it revalidates the immutable tag, package contracts, browser-free compatibility checks, companion commit reachability, the explicit release preflight with `--skip-clean-install`, npm token presence, npm owner authorization, and registry state before publishing.
+
 ## Dry run
 
 ```bash
 npm run release:verify
 ```
 
-`npm run release:verify` is the non-publishing release gate. It runs `npm run check`, `npm run test:e2e`, `npm run test:axe`, `npm run test:visual`, `npm run test:matrix`, the explicit UI-candidate release preflight, `npm audit --audit-level=moderate`, and `npm run pack:dry-run`.
+`npm run release:verify` is the non-publishing default release gate. It runs `npm run check`, the curated `npm run test:e2e` Chromium release smoke suite, the explicit UI-candidate release preflight with `--skip-clean-install`, `npm audit --audit-level=moderate`, and `npm run pack:dry-run`.
 
-`npm run release:preflight` validates the shared manifests and compatibility contract, queries npm for every exact minimum/current version, resolves every export from the candidate tarball, checks maintained documentation against installed packages, and reuses the current/minimum clean-install browser matrix. Normal UI preflight remains strict and queries `ui-style-kit-css@2.2.0` alongside every other documented exact version. The release workflows pass `--candidate-package ui-style-kit-css`, which excludes only that exact current version while it is absent from npm and still requires every published minimum and companion version. The gate performs no publish, tag, release, or deployment mutation and is therefore safe to execute on pull requests.
+`npm run release:verify:full` preserves the exhaustive historical gate for deliberate manual use. It runs `npm run check`, `npm run test:e2e:full`, `npm run test:axe:full`, `npm run test:visual:full`, the 36-block `npm run test:matrix` sequence, the full explicit UI-candidate release preflight, `npm audit --audit-level=moderate`, and `npm run pack:dry-run`.
 
-`npm run check` rebuilds dist CSS, runs stylelint, executes package, class API, shared theme-color, and vendor-prefix unit checks, validates core text/link contrast pairs and filled component `on-*` contrast pairs, and confirms package metadata. Browser gates cover regular demo flows, representative Axe scans, curated visual smoke checks, and the sharded 990-combination matrix. `npm run check:ecosystem:packs` verifies standalone, pairwise, and all-three packed package compatibility for the canonical visual/theme/state/layout imports and the deprecated bridge imports in both supported matrices. `npm run pack:dry-run` shows the exact files that would publish.
+Manual release review should open the checked-in demo, exercise the changed presets and responsive widths, and run `npm run test:visual:full` only when a visual-baseline audit is explicitly requested. The default PR, tag, and npm publish gates do not run the historical visual-baseline stack.
+
+The local UI matrix stops after the first failing 100-case block. Every case has a stable global number, so diagnose each failure with `npm run test:matrix:case -- --case N`. The rest of that block has already completed; after its targeted failures pass, continue at the next untested block with `npm run test:matrix -- --from-block B`. Already green blocks do not run again. `npm run test:matrix:block -- --block B` and `npm run test:matrix:range -- --from N --to M` provide bounded alternatives. `test:matrix:raw` is reserved for the manual sharded automation workflow.
+
+`npm run release:preflight` validates the shared manifests and compatibility contract, queries npm for every exact minimum/current version, resolves every export from the candidate tarball, checks maintained documentation against installed packages, and can run the current/minimum clean-install browser matrix when `--skip-clean-install` is omitted. Normal UI preflight remains strict and queries `ui-style-kit-css@2.4.0` alongside every other documented exact version. The release workflows pass `--candidate-package ui-style-kit-css`, which excludes only that exact current version while it is absent from npm and still requires every published minimum and companion version. The default PR and release workflows also pass `--skip-clean-install`; run `release:verify:full` or `check:ecosystem:packs` when clean-install browser proof is explicitly requested. The gate performs no publish, tag, release, or deployment mutation and is therefore safe to execute on pull requests.
+
+`npm run check` rebuilds dist CSS, runs stylelint, executes package and API contracts, validates all theme/mode contrast pairs, enforces the Browserslist compatibility contract through `check:compat`, verifies CSS ownership, and confirms package metadata. Default browser gates cover the release-smoke Playwright set; visual-baseline and full matrix checks are explicit manual gates. `npm run check:ecosystem:packs` remains the full standalone, pairwise, and all-three packed package compatibility proof for canonical visual/theme/state/layout imports and deprecated bridge imports in both supported matrices. `npm run pack:dry-run` shows the exact files that would publish without re-entering `prepack`.
 
 `npm run check:ecosystem:current` packs this repository and the sibling `../Layout-Style-CSS` and `../Interactive-Surface-CSS` checkouts. It extracts imports from the explicitly maintained current documentation in all three repositories and resolves every documented specifier from the installed tarballs. Deprecated UI bridge guides are validated as a separate supported-compatibility class; changelogs and Layout migration guides are reviewed historical material rather than current setup. Use `-- --ui-spec <specifier>`, `-- --layout-repo <path>`, `-- --layout-spec <specifier>`, `-- --interactive-spec <specifier>`, `-- --interactive-repo <path>`, `-- --layout-docs-repo <path>`, or `-- --interactive-docs-repo <path>` when validating different package or documentation sources.
 
 `npm run check:ecosystem:minimum` downloads and repacks the declared minimum published runtime versions: `ui-style-kit-css@2.1.0`, `interactive-surface-css@1.5.0`, and `layout-style-css@3.0.0`. Those tarballs predate the additive shared-manifest policy introduced on the coordinated branches, so the minimum matrix validates their exact installed versions and published CSS entry points; current packed heads retain the stricter manifest-schema and current-documentation checks. `npm run check:ecosystem:packs` runs current first and minimum second.
 
-The current matrix checks `ui-style-kit-css@2.2.0` as the active candidate only while its exact npm version is absent, `interactive-surface-css@1.6.0` as a published release, and `layout-style-css@3.0.1` as a published release. UI Style Kit `2.2.0` remains the current package version. The minimum published matrix remains `ui-style-kit-css@2.1.0`, `interactive-surface-css@1.5.0`, and `layout-style-css@3.0.0`.
+The current matrix checks `ui-style-kit-css@2.4.0` as the active candidate only while its exact npm version is absent, `interactive-surface-css@1.7.0` as a published release, and `layout-style-css@3.1.0` as a published release. The minimum published matrix remains `ui-style-kit-css@2.1.0`, `interactive-surface-css@1.5.0`, and `layout-style-css@3.0.0`.
 
 Both matrices install fresh tarball consumers for UI only, Interaction only, Layout only, every pair, and all three. Chromium then checks selected theme paint, native and prefixed components, interaction focus/disabled/loading/selected/persistent states, Layout wrappers/primitives/recipes/personalities, console cleanliness, and an empty external-request log. Three text-free baselines under `tests/snapshots/clean-install/` cover the highest-risk integrated combinations.
 
 Snapshot verification decodes PNG pixels, requires exact dimensions, ignores pixelmatch-classified antialias noise, uses a `0.1` color threshold, and permits at most `0.25%` differing pixels. The committed fixtures render at 720-721 by 261 pixels and therefore allow 469-470 changed pixels while rejecting the tested 42% meaningful change. A mismatch retains both `SCENARIO-actual.png` and `SCENARIO-diff.png` in the reported safe temporary directory. CI only validates committed baselines and never passes the generation flag. To intentionally refresh them locally, run the current checker with `--update-snapshots`, inspect all three images, and rerun without that flag.
 
-The PR integration and npm-publish workflows read the companion repository and immutable revision pins from `ecosystem-compatibility.json`, then pack those coordinated reviewed artifacts. Advance those pins whenever a later release changes a companion contract. The current values pin the published Interactive Surface CSS merge at `b50a60d8ffd804d8227b1a16903c394556b88511` and the published Layout Style CSS merge at `44c34693554879790c54a6205b37160ff63a1747`.
+The PR integration and npm-publish workflows read the companion repository and immutable revision pins from `ecosystem-compatibility.json`, then pack those coordinated reviewed artifacts. Advance those pins whenever a later release changes a companion contract. The current values pin the published Interactive Surface CSS merge at `b48b8b9080e4b1d4e344b6749ab1969a2863b3d1` and the published Layout Style CSS merge at `afcb1fdf70d4635e35739e621ee1598400fed103`.
 
 Use this exact bootstrap and merge sequence:
 
@@ -33,15 +58,13 @@ Use this exact bootstrap and merge sequence:
 
 The workflows enforce immutable remote-object reachability and do not fall back to mutable branches or registry packages. The stable bootstrap ref lets companion workflows load the reviewed preflight implementation before the final UI commit references their heads.
 
-`npm run build` uses exactly pinned CSS Tree parsing and Lightning CSS formatting/minification. Generated minified bundles retain the release banner while preserving grammar-sensitive selector and `calc()` whitespace.
+`npm run build` synchronizes manifest-driven component and overflow inventories and uses exactly pinned CSS Tree parsing and Lightning CSS formatting/minification. Every transform resolves the package Browserslist policy through `browserslistToTargets`. Generated minified bundles retain the release banner while preserving grammar-sensitive selector and `calc()` whitespace.
 
 The npm artifact is library-focused: `dist/`, `styles/`, docs, and metadata. Demo pages, favicon source assets, and social preview images remain checked in for GitHub Pages but are excluded from the tarball to keep package installs small.
 
 ## Publish
 
-No package, tag, or registry release occurs without explicit approval.
-
-The completed 2.0.4 correctness hotfix is historical context. Do not create replacement tags or registry releases merely to verify the coordinated compatibility contract.
+No package, tag, or registry release occurs without explicit approval. Release tags must use the `v<package-version>` form and point to the reviewed commit on `main`.
 
 Run the coordinated checked-out ecosystem proof from this repository:
 
@@ -53,7 +76,9 @@ npm run check:ecosystem:packs -- --layout-repo ../Layout-Style-CSS --interactive
 npm publish
 ```
 
-`prepublishOnly` runs `npm run release:verify`, so a direct `npm publish` still has the full release gate. For GitHub releases, create or dispatch a release for the matching package tag, such as `v2.2.0`. The release workflows verify that `package.json`, `package-lock.json`, `CHANGELOG.md`, and generated dist banners are aligned before publishing.
+`prepublishOnly` runs `npm run release:verify`, so a direct `npm publish` still has the default fast release gate. For GitHub releases, push or dispatch the matching package tag, such as `v2.4.0`, only after the release PR is merged. The release workflows verify that `package.json`, `package-lock.json`, `CHANGELOG.md`, generated dist banners, and ecosystem pins are aligned before publishing. Dispatch the protected npm workflow from the current `main` workflow file when recovering publication for a release that has already passed Release Version Alignment.
+
+The repository `NPM_TOKEN` secret must authenticate to npm as a user that appears in `npm owner ls ui-style-kit-css`. If the token belongs to another npm account or lacks package publish rights, npm may report a misleading registry `E404` at publish time.
 
 ## Versioning
 
@@ -63,4 +88,4 @@ npm run release:minor
 npm run release:major
 ```
 
-Use patch for fixes, minor for new themes/styles, and major for breaking public API changes. The 2.x release line is major because color-scheme authoring moved from per-UI `--<prefix>-*-rgb` blocks to shared `--usk-*-rgb` roles in `styles/theme-colors.css`.
+Use patch for compatible fixes, minor for new themes, presets, component capabilities, or browser-support contracts, and major for incompatible public API changes. The complete preset-specific native-control identity and browser coverage contract make `2.4.0` a minor release.

package/docs/RELEASE-2.4.0.md

@@ -0,0 +1,88 @@
+# v2.4.0 release preparation
+
+Status: local release candidate; not published by this task.
+
+## Compatibility contract
+
+- Package, lockfile, and manifest remain version `2.4.0`.
+- All 20 presets, 20 shared themes, three modes, 29 semantic selectors, and v2 import paths remain supported.
+- `data-ui` and `data-mode` are required; omit `data-theme` for a native palette.
+- Named themes retain shared `--usk-*` color ownership. Native demo edits target actual preset RGB variables, including material-specific colors.
+- The typed `--ui-color-bg` resolves through `--usk-native-bg` to the active preset background.
+- Existing companion compatibility pins remain unchanged; this task does not upgrade sibling libraries.
+
+## Prepared changes
+
+The accumulated candidate includes reference-driven preset refinements and native
+control coverage. This audit adds shared trust-seal text inheritance, the native
+background handshake fix, material-aware palette editing, validated demo deep
+links, and Organic Modern native-light contrast corrections. Recent Maximalist and
+Tactile annotation corrections remain included. Generated documentation and demo
+entrypoints now use the same bounded file-lock retries as distribution CSS.
+The manifest now inventories existing Bento, Bauhaus, Clay, and Tactile workspace
+classes that were absent from capability metadata. Organic's duplicate `field`
+entry was removed from preset extras because it remains a universal capability;
+authored component behavior is unchanged by these metadata corrections.
+
+The default demo presents one unified kit with a style-specific gallery. Industrial
+Utility's instruments and local alarm flow remain visible. Original complete boards
+are available through `?view=reference`, not duplicated above the public showcase.
+
+README, token/native/style guides, changelog, contributor/publishing instructions,
+and tracked wiki sources describe the same native/theme model. Focused CSS bundle
+sizes and demo asset hashes are regenerated from actual build output.
+
+## Verification boundary
+
+Focused regression checks are run per changed behavior. Final local checks cover
+build output, lint, syntax, documented imports, semantic and package contracts,
+contrast, browser-free compatibility, and ownership. Record actual results below;
+do not infer current results from old snapshots or prior design-QA reports.
+
+Browser navigation was blocked by an admin-policy verification error in the Codex
+browser path. No alternate browser or file-URL workaround was used. Rendered
+desktop/mobile comparisons, browser interactions, Axe, the 3,600-case engine
+matrix, and packed-browser ecosystem verification remain unverified in this audit.
+
+### Final local results
+
+- Build: passed; default, visual, all 20 focused, and bridge bundles regenerated, together with manifest snapshots, README measurements, and asset hashes.
+- CSS lint: passed after the final source and tooling changes.
+- Contrast: passed all 1,200 named-theme combinations and 60 native fallback palettes. This is token-pair arithmetic, not rendered accessibility certification.
+- CSS compatibility: passed 26 generated entrypoints against 60 resolved browser targets; this is a parser/policy check, not execution in those browsers.
+- CSS ownership: passed 35,799 declarations with zero reviewed exceptions.
+- Package integrity: passed; exports, tracked documentation links, wiki routes, release-version surfaces, semantic producer contracts, measured bundle sizes, and demo asset hashes have focused checks.
+- Focused regressions: passed native-material inventory/edit/export/reset isolation, None/null selection, deep links, seal foreground inheritance, all-preset background mapping, Organic contrast, and generated-file retry/error handling. Checks were run individually; no full unit or CI suite was run.
+- Dependency audit: `npm audit --audit-level=moderate` passed with zero reported vulnerabilities after the targeted `fast-uri` patch below.
+- Packaging dry run: `npm pack --dry-run --ignore-scripts --json` passed with 125 files (approximately 12.6 MiB packed / 31.4 MiB unpacked). The release/demo/Tactile guides are included; demo, test, wiki, and temporary output directories are excluded. Lifecycle hooks were disabled, so this was inventory validation, not the full prepublish chain.
+
+### Development-tooling security correction
+
+The installed chain was `stylelint → table → ajv → fast-uri@3.1.5`. AJV uses the
+URI resolver for schema references; no URI fetch path or runtime JavaScript
+dependency was established in this CSS package. The confirmed finding was the
+vulnerable installed tooling and failed audit gate, not a demonstrated application
+SSRF endpoint.
+
+The security-fix checklist kept this change to the existing override, lockfile,
+and focused regression coverage: `fast-uri@3.1.6`, within AJV's supported v3 range.
+The upstream patch addresses [URI canonicalization advisories](https://github.com/fastify/fast-uri/releases/tag/v3.1.6).
+The malformed-IPv6 regression failed before the update and passed afterward;
+encoded schemes, nested host escapes, and scheme-relative IDN normalization also
+passed. Ordinary URI resolution, AJV schema references, the exact override
+contract, and CSS lint passed. No network requests were made by these URI fixtures.
+
+Only one installed package changed. Other overrides, direct dependencies, public
+CSS imports, and consumer APIs were preserved. Browser and packed-consumer proof
+remain outside this narrow tooling fix and are still pending for the release.
+
+## Publication handoff
+
+Do not tag, publish, or merge on the strength of static checks alone. Complete the
+required browser and packed-consumer gates using [Publishing](PUBLISHING.md), review
+the full candidate diff, and obtain the requested release authority. Set the real
+release date in the changelog at that handoff. The tracked `wiki/` sources still
+need a separate hosted-wiki publication step.
+
+No commit, push, release tag, GitHub Release, npm publication, or deployment is part
+of this local preparation task.

package/docs/RETRO-GLASS.md

@@ -0,0 +1,105 @@
+# Retro Glass
+
+The `retro-glass` preset implements the retained RetroGlass light and dark element
+boards with rounded glass surfaces, brushed chrome, inset inputs, and glossy actions.
+All components use the `rg-*` API. The shared semantic API remains unchanged.
+
+```html
+<link rel="stylesheet" href="ui-style-kit-css/retro-glass.css">
+<main data-ui="retro-glass" data-mode="dark">
+  <section class="rg-panel">
+    <h2 class="rg-section-title">Library</h2>
+    <label class="rg-field">
+      <span class="rg-label">Search documents</span>
+      <input class="rg-input" type="search">
+    </label>
+    <button class="rg-button rg-button-primary">Apply</button>
+  </section>
+</main>
+```
+
+## Themes
+
+Omit `data-theme` for the reference palette. Set `data-theme` to any supported
+scheme, such as `arctic-indigo`, to use semantic `--usk-*-rgb` colors. Switch
+`data-mode` between `light`, `dark`, and `contrast` without changing markup.
+Custom semantic tokens continue to override preset fallbacks.
+
+The demo's mode pill activates the reference palette and updates the color-theme
+selector. Choosing a shared theme restores that scheme. The token editor supports
+both paths; reference overrides are scoped to the active preset and mode.
+
+Default controls follow a 36px rhythm with 6px corners. Panels use 10px corners,
+window chrome uses 14px, and badges, switches, and tracks use pills. Touch input
+expands interactive targets to at least 44px. Application text defaults to 14px;
+the desktop specimen uses compact documentation typography from the reference.
+
+Reference accent channels are retained. Muted text and essential borders use
+stronger foregrounds for contrast. Glossy actions have a dedicated foreground
+because their shaded material differs from a flat semantic swatch.
+
+## Component Coverage
+
+| Board group | Public classes and states |
+| --- | --- |
+| Action states | `rg-button`, `rg-button-primary`, `rg-button-secondary`, `rg-button-ghost`, `rg-button-danger`, `rg-icon-button`; default, hover, pressed, loading, disabled |
+| Form inputs | `rg-field`, `rg-label`, `rg-input`, `rg-select`, `rg-textarea`, `rg-input-wrap`, `rg-input-icon`, `rg-helper`, `rg-error-text` |
+| Choices and tags | `rg-choice`, `rg-switch`, `rg-switch-track`, `rg-switch-thumb`, `rg-segmented`, `rg-segment`, `rg-chip`, `rg-chip-danger`, `rg-chip-warning` |
+| Select and upload | `rg-dropdown`, `rg-option`, `rg-tags`, `rg-file` |
+| Ranges and progress | `rg-range`, `rg-range-critical`, `rg-progress`, `rg-progress-bar`, `rg-progress-danger`, `rg-meter`, `rg-stepper`, `rg-step` |
+| Feedback | `rg-alert` and success/warning/danger modifiers, `rg-toast`, `rg-spinner`, `rg-skeleton` |
+| Navigation | `rg-breadcrumb`, `rg-tabs`, `rg-tab`, `rg-nav`, `rg-nav-link`, `rg-pagination`, `rg-pagination-page` |
+| Data | `rg-table`, `rg-badge` and semantic modifiers, `rg-avatar`, `rg-avatar-danger`, `rg-avatar-neutral`, `rg-avatar-group` |
+| Overlays and disclosure | `rg-tooltip`, `rg-popover`, `rg-modal`, `rg-modal-actions`, `rg-accordion` |
+| Foundations | `rg-title`, `rg-heading`, `rg-section-title`, `rg-overline`, `rg-token-swatch`, `rg-code`, `rg-list`, `rg-quote`, existing `rg-console` |
+
+The library keeps canonical single-hyphen modifiers, translating reference names
+such as `rg-button--primary` to `rg-button-primary`. The template's pagination
+item becomes `rg-pagination-page`; the existing `rg-page` layout shell is preserved.
+Every published preset extra is listed in `manifest.json`.
+
+## State And Interaction Contracts
+
+- Use native `disabled`, `aria-busy`, `aria-invalid`, `aria-selected`, and
+  `aria-current` attributes. Static `.is-hover`, `.is-focus`, `.is-pressed`,
+  `.is-loading`, and `.is-disabled` classes are available for specimens.
+- Associate visible error text with its input using `aria-describedby`.
+- Keep switch inputs focusable. Include the `rg-switch-thumb` inside the track.
+- Set `--rg-value` to a percentage for range fill and meter position. Update it
+  alongside the native input value and an accessible `output`.
+- Set `--rg-progress-value` on `rg-progress-bar`. Supply the progressbar name and
+  `aria-valuemin`, `aria-valuemax`, and `aria-valuenow` on the track.
+- Use native `dialog.showModal()` for modal behavior and native `details` for
+  disclosure. A visual `rg-modal` class alone does not create a focus trap.
+- Set `--rg-token-swatch-color` to the semantic color shown by a token swatch.
+- Standalone, semantic, and native busy indicators share a complete circular
+  track with one highlighted quadrant. Busy controls reserve a non-shrinking
+  16px indicator; reduced-motion preferences stop rotation.
+- Disabled choices retain readable labels and use dashed outlines to distinguish
+  their state without relying on faded text. Keep the native `disabled` attribute.
+- Anchor buttons retain the same contrast-safe foreground as button elements.
+  Marketing seals use opaque chrome with inherited text color.
+
+CSS supplies visual states; applications own interaction behavior. The demo adds
+roving keyboard focus for tabs and listbox options, file selection and drop,
+range output, filter chips, pagination, a menu, and a native modal dialog.
+Examples use inert local data and do not upload or delete real documents.
+
+## Preset Isolation
+
+The demo renders preset extras only for their owner. All exclusive regions use
+`data-preset-only` and a shared visibility synchronizer. Changing the style removes
+the prior preset's generated markup; presets with no extras show no extras region.
+This rule applies to all presets, including the Cyberpunk and Retro Glass boards.
+
+## Assets
+
+The demo vendors Lucide 0.468.0 icons in `demo/assets/lucide`, including the upstream
+license. The build generates `demo/demo-icons.js` from those source files so icons
+work offline through either HTML entry point, including `file:` URLs.
+
+The semantic demo settings icon uses a 24px SVG in a stable 44px control across
+presets. Retro Glass feature checks use a heavier SVG stroke inside the medallion.
+
+`npm run build` regenerates the default, visual, focused, and bridge bundles,
+containment foundations, demo icon asset, and README bundle-size metadata.

package/docs/STYLE-GUIDE.md

@@ -2,22 +2,77 @@
 
 | UI style | Best for |
 |---|---|
-| Minimal SaaS | Dashboards, admin tools, SaaS apps, documentation, internal systems |
-| Bento UI | Landing pages, portfolio sections, feature pages, product showcases |
-| Maximalist / Playful | Creators, entertainment brands, events, bold client sites |
-| Bauhaus / Swiss Modern | Agencies, artists, editorial pages, design-forward brands |
-| Tactile / Skeuomorphic | Premium sites, distinctive client interfaces, control-panel metaphors |
-| Neumorphism | Soft dashboards, experimental UI, visual demos |
-| Retrofuturism | Futuristic product pages, portfolios, technology showcases |
-| Brutalism | Bold landing pages, anti-template websites, creative brands |
-| Cyberpunk | Security, gaming, encryption, developer demos, nightlife/tech branding |
-| Y2K | Nostalgic, playful, music/fashion/event sites |
-| Retro Glass | Futuristic premium apps, glass dashboards, hero sections |
-
-All styles share the same 10 color schemes through `styles/theme-colors.css`, so changing `data-theme` affects the active color scheme independently from the selected UI treatment.
+| Minimal SaaS | Dense dashboards, admin tools, and focused SaaS workflows |
+| Bento UI | Friendly product surfaces, feature mosaics, and showcase dashboards |
+| Maximalist / Playful | Creators, entertainment, bold client sites |
+| Bauhaus / Swiss Modern | Agencies, editorial layouts, design-forward brands |
+| Skeuomorphic / Tactile | Physical workspace configuration, control panels and instrument-like product UI |
+| Neumorphism | Sculpted same-surface dashboards and quiet configuration workflows |
+| Retrofuturism | Atomic-age dashboards, instrument panels, and configuration workspaces |
+| Brutalism | Bold creative websites |
+| Cyberpunk | Security, gaming, encryption, tech demos |
+| Y2K | Nostalgic, playful, fashion/music/event sites |
+| Retro Glass | Futuristic glass dashboards and hero sections |
+| Editorial Luxe | Luxury brands, architecture, hospitality, premium editorial sites |
+| Organic Modern | Wellness, sustainability, hospitality, natural product brands |
+| Industrial Utility | Operations software, manufacturing, logistics, fleet and equipment systems |
+| Technical Blueprint | Engineering, architecture, technical documentation, scientific tools |
+| Art Deco | Luxury, hospitality, heritage brands, events and distinctive showcases |
+| Clay | Friendly SaaS, collaborative tools, education and approachable product sites |
+| Data Terminal | Operator consoles, telemetry, infrastructure, monitoring and developer tools |
+| Paper Editorial | News, magazines, journals, cultural sites and story-led publishing |
+| Neo-Noir | Cinematic portfolios, nightlife, premium creative studios and dramatic product sites |
+
+All styles share the same 20 color schemes through `styles/theme-colors.css`, so changing `data-theme` affects the active color scheme independently from the selected UI treatment.
+
+Omit `data-theme` to use the chosen preset's native light, dark, or contrast colors.
+The [demo guide](DEMO-SHOWCASE.md) explains the unified style-specific gallery and
+optional reference boards. Native material colors can be edited in the workbench
+without assigning a shared theme or changing geometry.
 
 Use `data-mode="contrast"` for high-contrast variants and pair it with semantic HTML for best accessibility outcomes.
 
+## Preset identity and component roles
+
+UI presets own geometry, material, spacing, depth, and typographic character. Color schemes own semantic color roles. A preset should therefore remain recognizable when its `data-theme` changes, while every component continues to consume the active theme tokens instead of fixed artwork colors.
+
+| UI style | Repeated component identity |
+|---|---|
+| Minimal SaaS | Flat neutral modules, fine rules, tight radii, compact controls and negligible elevation |
+| Bento UI | Large rounded tiles, theme-tinted mosaic washes, nested highlights, friendly typography and soft elevation |
+| Maximalist / Playful | Punk-collage paper panels, hard ink strokes and loud condensed type |
+| Bauhaus / Swiss Modern | Strict grids, heavy rules, primary geometry, flat construction and condensed uppercase type |
+| Skeuomorphic / Tactile | Paper plates, serif headings, compact uppercase labels, dark instrument navigation, hard keylines, chamfered keycaps, squared lever thumbs and segmented gauges |
+| Neumorphism | Borderless same-surface shells, generous radii, quiet modern type, opposing light/dark extrusion, deeply concave fields and tracks, and visibly pressed actions |
+| Retrofuturism | Rounded enamel shells, nested metallic rims, recessed instrument bays, oval actions, jewel-light feedback, condensed display type, calibrated ranges and segmented progress gauges |
+| Brutalism | Square full-bleed grids, heavy rules, numbered modules, blunt controls and segmented meters |
+| Cyberpunk | Chamfered HUD panels, clipped controls, technical condensed type and signal-colored edges |
+| Y2K | Dense portal panels, 1px bevels, title bars, system typography and segmented indicators |
+| Retro Glass | Brushed application chrome, glossy navigation, beveled controls, glass panes and dark dock treatment |
+| Editorial Luxe | Didone hierarchy, double rules, rigid editorial geometry and restrained couture material |
+| Organic Modern | Warm material surfaces, serif identity type, fine hairlines, asymmetry and leaf-tipped details |
+| Industrial Utility | Metal-framed panels, recessed instruments, mechanical actions, safety gauges and technical type |
+| Technical Blueprint | Drafting grids, technical linework, square measured controls, annotations and calibrated geometry |
+| Art Deco | Stepped symmetry, metallic double keylines, fanburst geometry, elegant display type and jewel controls |
+| Clay | A continuous sculpted slab with soft mineral surfaces, raised rounded controls and carved seams |
+| Data Terminal | A dense 1px command grid with mono typography, bracketed actions and strict semantic signals |
+| Paper Editorial | A physical field-manual sheet with binder details, index tabs, print rules, condensed headings and monospaced data |
+| Neo-Noir | Cinematic slants, trapezoid controls, diagonal cuts, subtle grain and amber, teal and red semantic signaling |
+
+For filled service actions, compose `<prefix>-button`, `<prefix>-button-primary`, and `<prefix>-button-cut`. For framed callout actions, compose `<prefix>-button` and `<prefix>-button-outline-heavy`. These modifiers are independent; the library does not expose a `button-cta` class. Carry the same preset identity into service cards, media scrims, feature strips, callout bars, native actions, and dialogs rather than treating each specimen as isolated artwork.
+
+Minimal SaaS and Bento deliberately share semantic roles but not presentation. Minimal SaaS keeps controls near `2.375rem`, uses narrow spacing and flat bordered modules, and reserves theme color for action and state emphasis. Bento uses `2.75rem` controls and `1.5rem` tiles, applies theme-derived primary, accent and secondary washes, and reinforces the mosaic hierarchy with inset highlights and soft shadows. This distinction must remain visible in every theme and mode.
+
+Neumorphism and Tactile also share component roles without sharing material. Neumorphism removes visible keylines and sculpts cards and actions outward from one theme-derived surface while fields, tracks, table cells, and pressed states sink inward through paired light and dark shadows. Tactile keeps a denser paper-workspace rhythm: serif headings sit above compact uppercase labels, framed plates use visible rules and shallow chamfers, actions behave like raised keycaps, and dark troughs hold squared thumbs and segmented progress gauges. Theme channels may recolor both systems, but those geometry, typography, elevation, inset-depth, feedback, and table contracts remain stable.
+
+Retrofuturism uses a mid-century atomic appliance language rather than cyberpunk scanlines or generic neon glass. Light mode reads as bright enamel with softly recessed instrument wells; dark mode reads as deep enamel with stronger recess depth. Both retain nested metallic keylines, rounded equipment housings, condensed display typography, compact uppercase labels, oval mechanical actions, dial-like range thumbs, and segmented jewel-lamp progress. Theme channels recolor the enamel, instruments, actions, and status lamps without changing that material or geometry contract.
+
+Every preset must carry its contract through the same complete role set: buttons, fields, choices, navigation, cards, panels, tables, badges, alerts, tooltips, dialogs, ranges, progress, meters, service cards, feature strips, callouts, loading, disabled, focus and pressed states. The registry and regression suite compare typography, density, geometry, material, feedback and data presentation pairwise; theme changes are expected to alter paint while those structural identity axes remain stable.
+
+The registry also exposes executable reference traits for all six identity axes. Each trait identifies an authored selector, property, and required value fragment, so the tests verify real CSS rather than descriptive metadata. Browser identity checks are split by preset, viewport, mode, and pair to support exact reruns without replaying unrelated passing cases.
+
+Preset-specific grids must size from their own container. Bento feature tiles, for example, use intrinsic columns and only introduce a feature span when their container can support it, preventing metric labels from collapsing into vertical text.
+
 ## Visual regression baseline
 
 The repository includes optional Playwright visual smoke checks:

package/docs/TACTILE.md

@@ -0,0 +1,38 @@
+# Tactile workspace components
+
+Use `data-ui="tactile"` and `data-mode="light"`, `dark`, or `contrast` on the
+owning root. Omit `data-theme` for the native material palette; a named theme
+repaints the existing materials through shared `--usk-*-rgb` roles.
+
+Import `ui-style-kit-css/tactile.css` for the complete preset or
+`ui-style-kit-css/visual/tactile.css` for the focused visual distribution.
+Existing semantic `.ui-*` components, native controls, and `tactile-*` classes
+remain available without the workspace composition.
+
+## Advanced workspace inventory
+
+The authored workspace classes are listed in
+`manifest.classApi.presetExtras.tactile` so consuming tools can discover them.
+They are an optional preset-specific composition, not new universal `.ui-*` aliases.
+
+| Area | Classes (with the `tactile-` prefix) |
+| --- | --- |
+| Frame and navigation | `workspace-shell`, `workspace-sidebar`, `workspace-menu`, `workspace-link`, `workspace-icon`, `workspace-sidebar-note` |
+| Identity | `workspace-brand`, `workspace-brand-mark`, `workspace-header`, `workspace-title` |
+| Main settings | `workspace-main`, `workspace-body`, `workspace-settings`, `workspace-row`, `workspace-fields`, `workspace-switches` |
+| Instrument panels | `workspace-security`, `workspace-readiness`, `workspace-gauge`, `workspace-gauge-key`, `workspace-shelf`, `workspace-progress` |
+
+Keep real links, labels, inputs, and buttons inside these visual containers.
+Use `aria-current="page"` for an active workspace link. CSS supplies appearance;
+application code owns navigation, settings persistence, and instrument values.
+
+## Material colors and accessibility
+
+Native mode exposes preset material RGB channels such as paper and ink in the
+[demo workbench](DEMO-SHOWCASE.md). Native exports target `--tactile-*-rgb`;
+named-theme exports retain `--usk-*-rgb`. The shared background token resolves
+to the final Tactile background instead of requiring an explicit theme.
+
+Trust-seal captions inherit their paired foreground, including the dark
+instrument treatment. Recheck contrast after custom palette edits. Passing token
+checks does not replace keyboard, zoom, screen-reader, and rendered contrast QA.

package/docs/TECHNICAL-BLUEPRINT.md

@@ -0,0 +1,60 @@
+# Technical Blueprint
+
+The Technical Blueprint preset follows the retained Technical Blueprint element
+boards and design guide: square controls, a 16px construction grid, drafting
+registration marks, calibrated line weights, and restrained semantic ink colors.
+The canonical public prefix is `blueprint-`; source-template `tb-` aliases are
+not exported.
+
+## Theme and Material
+
+Set `data-ui="technical-blueprint"` and `data-mode="light"` or `"dark"` on the
+containing element. Existing `--usk-*` semantic tokens feed the `--blueprint-*`
+aliases, so changing `data-theme` changes color without replacing drafting
+geometry. In the demo, **Use reference palette** selects the guide's fallback
+colors instead of a named color theme. Primary action fill and foreground are
+paired separately from annotation ink for readable labels in both modes.
+
+## Component Surface
+
+The manifest is the authoritative class inventory. Alongside the shared button,
+input, card, table, alert, badge, tooltip, progress, spinner, and switch families,
+Technical Blueprint exports these preset-only components:
+
+- Sheet frame, datum marker, line sample, section title, overline, token swatch.
+- Choice, input wrapper/icon, helper/error text, range, critical range, meter.
+- Dropdown/option, file upload surface, tags, chips and semantic chip variants.
+- Segmented controls, tabs, breadcrumb, pagination and pagination page.
+- Stepper/step, revision progress, toast, skeleton.
+- Avatars and groups, code, quote, list, metric, empty state.
+- Popover, modal/actions, accordion.
+
+`blueprint-page` remains the page shell. Pagination items use
+`blueprint-pagination-page` to avoid changing that existing API.
+
+## Demo and Accessibility
+
+The demo includes all ten reference groups: actions, forms, choices, selects and
+upload, ranges and progress, alerts and loading, navigation, data display,
+overlays, and foundations. Additional code, quote, metric, and empty-state
+examples live in the preset-specific extras section. Every preset-owned demo
+region is hidden when a different preset is selected.
+
+The specimen uses labeled native inputs, named icon buttons, keyboard-operated
+tabs and listboxes, a native dialog, file selection, and live range outputs.
+Sample actions are local demonstrations; they do not upload or delete data.
+CSS alone provides presentation, not dialog/listbox application behavior.
+Controls retain visible focus, disabled-state cues, reduced-motion handling,
+forced-color fallbacks, and 44px touch targets on coarse-pointer devices.
+
+Native date/time formatting, file pickers, font rasterization, and responsive
+reflow follow the browser rather than reproducing static illustration pixels.
+
+## Focused Verification
+
+- `node --test tests/technical-blueprint-template.test.js`
+- `npx playwright test tests/e2e/technical-blueprint-template.spec.js --project=chromium`
+
+The browser checks use the generated bundle, verify all preset-only regions,
+audit both reference modes with axe, and exercise keyboard behavior, token
+overrides, and mobile overflow. Rebuild distribution CSS before browser checks.

package/docs/TOKENS.md

@@ -8,13 +8,44 @@ shared scheme channels -> prefixed aliases -> UI rules
 
 `styles/theme-colors.css` defines the active scheme and mode once as `--usk-*` RGB channels. Each UI style maps those shared channels to its public prefix, then component rules consume prefixed functional variables. `styles/native-elements.css` owns native HTML fallback selectors and consumes `--usk-native-*` tokens that each preset maps back to its own public variables.
 
+## Demo palette workbench
+
+The demo starts with **Color Theme: None — style defaults**. This omits `data-theme`
+and displays the selected preset's native light, dark, or contrast palette. All 20
+named color themes remain available; selecting one applies the shared color roles
+without changing component classes or preset geometry.
+
+```js
+document.body.dataset.ui = "minimal-saas";
+document.body.dataset.mode = "light";
+document.body.removeAttribute("data-theme");
+```
+
+The named-theme color table reads 23 shared RGB roles. Native mode reads the preset's
+RGB inventory, including material channels such as paper, ink, brass, and enamel.
+Native exports use `--<prefix>-*-rgb`; named-theme exports use `--usk-*-rgb`.
+Native-palette edits are isolated by preset and mode; named-theme edits are shared
+across presets using the same theme and mode. Native exports are
+scoped to the selected `[data-ui]:not([data-theme])[data-mode]` combination, so they
+do not override a subsequently selected named theme.
+
+Reset a single role or use **Reset palette edits** to restore only the active
+palette. Edits are temporary until reload. Invalid values leave the last valid
+preview intact. Custom colors can reduce contrast; validate edited palettes before
+using them in production. The library's CSS expects `data-theme` to be absent, not
+the literal strings `"None"` or `"null"`; the demo normalizes empty/null selections.
+
 ## Shared semantic token handshake
 
-The existing `[data-ui][data-theme][data-mode]` native-token root publishes 12 fully typed `--ui-*` values. UI Style Kit is the primary producer, but the names are intentionally package-neutral so a third-party theme can produce the same contract. Consumer libraries treat these values as optional fallbacks: a package-specific override wins first, then the shared semantic value, then the consumer's legacy token and literal default.
+The background handshake resolves through `--usk-native-bg`, which each preset
+maps to its functional `--<prefix>-bg`. It therefore follows the actual native
+material even when shared `--usk-bg-rgb` channels are absent.
+
+The `[data-ui][data-mode]` native-token root publishes 12 fully typed `--ui-*` values whether or not `data-theme` is present. UI Style Kit is the primary producer, but the names are intentionally package-neutral so a third-party theme can produce the same contract. Consumer libraries treat these values as optional fallbacks: a package-specific override wins first, then the shared semantic value, then the consumer's legacy token and literal default.
 
 | Shared token | CSS type | UI Style Kit source |
 |---|---|---|
-| `--ui-color-bg` | `<color>` | `rgb(var(--usk-bg-rgb))` |
+| `--ui-color-bg` | `<color>` | `var(--usk-native-bg)` |
 | `--ui-color-surface` | `<color>` | `var(--usk-native-surface-strong)` |
 | `--ui-color-text` | `<color>` | `var(--usk-native-text)` |
 | `--ui-color-muted` | `<color>` | `var(--usk-native-text-muted)` |
@@ -63,6 +94,15 @@ UI Style Kit entrypoints publish all 12 values. Standalone consumer packages mus
 | Cyberpunk | `cyber` |
 | Y2K | `y2k` |
 | Retro Glass | `rg` |
+| Editorial Luxe | `luxe` |
+| Organic Modern | `organic` |
+| Industrial Utility | `utility` |
+| Technical Blueprint | `blueprint` |
+| Art Deco | `deco` |
+| Clay | `clay` |
+| Data Terminal | `terminal` |
+| Paper Editorial | `paper` |
+| Neo-Noir | `noir` |
 
 ## Stable functional tokens
 
@@ -198,9 +238,55 @@ Native HTML coverage is shared in `styles/native-elements.css` to avoid repeatin
 --usk-native-shadow
 --usk-native-shadow-md
 --usk-native-focus-ring
+--usk-native-choice-size
+--usk-native-choice-background
+--usk-native-choice-border
+--usk-native-checkbox-radius
+--usk-native-radio-radius
+--usk-native-choice-shadow
+--usk-native-choice-checked-background
+--usk-native-choice-mark-color
+--usk-native-select-indicator-image
+--usk-native-select-indicator-size
+--usk-native-select-indicator-position
+--usk-native-select-padding-inline-end
+--usk-native-range-track-size
+--usk-native-range-track-background
+--usk-native-range-track-border
+--usk-native-range-track-radius
+--usk-native-range-track-shadow
+--usk-native-range-progress-background
+--usk-native-range-thumb-size
+--usk-native-range-thumb-background
+--usk-native-range-thumb-border
+--usk-native-range-thumb-radius
+--usk-native-range-thumb-shadow
+--usk-native-progress-size
+--usk-native-progress-track-background
+--usk-native-progress-track-border
+--usk-native-progress-track-radius
+--usk-native-progress-track-shadow
+--usk-native-progress-value-background
+--usk-native-progress-value-radius
+--usk-native-progress-value-shadow
+--usk-native-meter-optimum-background
+--usk-native-meter-suboptimum-background
+--usk-native-meter-critical-background
+--usk-native-file-button-background
+--usk-native-file-button-border
+--usk-native-file-button-radius
+--usk-native-file-button-shadow
+--usk-native-color-swatch-border
+--usk-native-color-swatch-radius
+--usk-native-indicator-opacity
+--usk-native-indicator-filter
+--usk-native-scrollbar-size
+--usk-native-scrollbar-track
+--usk-native-scrollbar-thumb
+--usk-native-scrollbar-radius
 ```
 
-Consumers usually override the prefixed public tokens, not these internal bridge tokens. Use `--usk-native-*` only when intentionally customizing native fallback styling across every UI preset.
+Every preset maps the complete identity set. Consumers usually override the prefixed public tokens, not these internal bridge tokens. Use `--usk-native-*` only when intentionally customizing native fallback styling across every UI preset.
 
 Use prefixed RGB aliases for component-local alpha effects:
 
@@ -243,7 +329,7 @@ Loading indicators use theme variables by default:
 --<prefix>-spinner-accent
 ```
 
-The class utilities are `<prefix>-spinner`, `<prefix>-loading-spinner`, `<prefix>-spinner-sm`, and `<prefix>-spinner-lg`. Native buttons and prefixed buttons also render an inline spinner when `aria-busy="true"` is present.
+The class utilities are `<prefix>-spinner`, `<prefix>-loading-spinner`, `<prefix>-spinner-sm`, and `<prefix>-spinner-lg`. Each preset owns its loader silhouette, cadence, and depth while consuming only these active theme roles. Native buttons and prefixed buttons render the matching preset-owned indicator when `aria-busy="true"` is present.
 
 ## Interactive Surface bridge tokens