npm - ui-style-kit-css - Versions diffs - 2.3.0 → 2.4.1 - Mend

ui-style-kit-css 2.3.0 → 2.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (122) hide show

package/CHANGELOG.md +57 -2
package/CONTRIBUTING.md +8 -1
package/README.md +102 -44
package/STYLE-MAP.md +14 -5
package/dist/assets/bauhaus-barlow-OFL.txt +93 -0
package/dist/assets/bauhaus-barlow-semibold.ttf +0 -0
package/dist/assets/bauhaus-barlow.ttf +0 -0
package/dist/assets/bauhaus-condensed-OFL.txt +93 -0
package/dist/assets/bauhaus-condensed-bold.ttf +0 -0
package/dist/assets/bauhaus-condensed-extrabold.ttf +0 -0
package/dist/assets/bento-manrope-OFL.txt +93 -0
package/dist/assets/bento-manrope.ttf +0 -0
package/dist/assets/clay-grain.png +0 -0
package/dist/assets/clay-rounded-OFL.txt +93 -0
package/dist/assets/clay-rounded.ttf +0 -0
package/dist/assets/neo-noir-corner-dark.png +0 -0
package/dist/assets/neo-noir-corner-light.png +0 -0
package/dist/assets/neo-noir-texture-dark.png +0 -0
package/dist/assets/neo-noir-texture-light.png +0 -0
package/dist/assets/organic-display-OFL.txt +93 -0
package/dist/assets/organic-display.ttf +0 -0
package/dist/assets/organic-icons-LICENSE.txt +21 -0
package/dist/assets/organic-sans-OFL.txt +93 -0
package/dist/assets/organic-sans.ttf +0 -0
package/dist/ui-style-kit.css +47898 -15121
package/dist/ui-style-kit.min.css +2 -2
package/dist/ui-style-kit.visual.css +47771 -15122
package/dist/ui-style-kit.visual.min.css +2 -2
package/dist/ui-style-kit.with-bridge.css +47932 -15145
package/dist/ui-style-kit.with-bridge.min.css +2 -2
package/dist/visual/art-deco.css +3247 -295
package/dist/visual/bauhaus.css +2 -4692
package/dist/visual/bento.css +2 -4708
package/dist/visual/brutalism.css +1229 -231
package/dist/visual/clay.css +2 -4786
package/dist/visual/cyberpunk.css +2663 -282
package/dist/visual/data-terminal.css +2064 -276
package/dist/visual/editorial-luxe.css +2315 -259
package/dist/visual/industrial-utility.css +3142 -270
package/dist/visual/maximalist.css +2185 -454
package/dist/visual/minimal-saas.css +1503 -398
package/dist/visual/neo-noir.css +2 -4787
package/dist/visual/neumorphism.css +1690 -402
package/dist/visual/organic-modern.css +2 -4764
package/dist/visual/paper-editorial.css +2977 -292
package/dist/visual/retro-glass.css +2625 -299
package/dist/visual/retrofuturism.css +1885 -397
package/dist/visual/tactile.css +2716 -498
package/dist/visual/technical-blueprint.css +2599 -267
package/dist/visual/y2k.css +1906 -309
package/docs/ART-DECO.md +80 -0
package/docs/BAUHAUS.md +152 -0
package/docs/BENTO.md +121 -0
package/docs/CLAY.md +127 -0
package/docs/COLOR-THEMES.md +63 -0
package/docs/DEMO-SHOWCASE.md +65 -0
package/docs/ECOSYSTEM.md +4 -4
package/docs/EDITORIAL-LUX.md +75 -0
package/docs/INDUSTRIAL-UTILITY.md +131 -0
package/docs/NATIVE-ELEMENTS.md +23 -17
package/docs/NEO-NOIR.md +94 -0
package/docs/ORGANIC-MODERN.md +91 -0
package/docs/PAPER-EDITORIAL.md +63 -0
package/docs/PUBLISHING.md +31 -10
package/docs/RELEASE-2.4.0.md +88 -0
package/docs/RELEASE-2.4.1.md +35 -0
package/docs/RETRO-GLASS.md +105 -0
package/docs/STYLE-GUIDE.md +41 -26
package/docs/TACTILE.md +38 -0
package/docs/TECHNICAL-BLUEPRINT.md +60 -0
package/docs/TOKENS.md +80 -3
package/docs/superpowers/plans/2026-09-04-library-wide-theme-fallback-and-fidelity.md +331 -0
package/docs/superpowers/specs/2026-09-04-library-wide-theme-fallback-and-fidelity-design.md +113 -0
package/manifest.json +624 -28
package/package.json +20 -11
package/styles/art-deco.css +1402 -17
package/styles/assets/bauhaus-barlow-OFL.txt +93 -0
package/styles/assets/bauhaus-barlow-semibold.ttf +0 -0
package/styles/assets/bauhaus-barlow.ttf +0 -0
package/styles/assets/bauhaus-condensed-OFL.txt +93 -0
package/styles/assets/bauhaus-condensed-bold.ttf +0 -0
package/styles/assets/bauhaus-condensed-extrabold.ttf +0 -0
package/styles/assets/bento-manrope-OFL.txt +93 -0
package/styles/assets/bento-manrope.ttf +0 -0
package/styles/assets/clay-grain.png +0 -0
package/styles/assets/clay-rounded-OFL.txt +93 -0
package/styles/assets/clay-rounded.ttf +0 -0
package/styles/assets/neo-noir-corner-dark.png +0 -0
package/styles/assets/neo-noir-corner-light.png +0 -0
package/styles/assets/neo-noir-texture-dark.png +0 -0
package/styles/assets/neo-noir-texture-light.png +0 -0
package/styles/assets/organic-display-OFL.txt +93 -0
package/styles/assets/organic-display.ttf +0 -0
package/styles/assets/organic-icons-LICENSE.txt +21 -0
package/styles/assets/organic-sans-OFL.txt +93 -0
package/styles/assets/organic-sans.ttf +0 -0
package/styles/bauhaus.css +881 -110
package/styles/bento.css +1182 -113
package/styles/brutalism.css +266 -15
package/styles/clay.css +1307 -72
package/styles/compat-layout.css +1 -2
package/styles/components.css +107 -36
package/styles/content-overflow.css +11 -5
package/styles/cyberpunk.css +1856 -51
package/styles/data-terminal.css +1122 -18
package/styles/editorial-luxe.css +581 -17
package/styles/industrial-utility.css +1775 -16
package/styles/interactive-surface-bridge.css +30 -20
package/styles/interactive-surface-theme.css +21 -11
package/styles/maximalist.css +1215 -133
package/styles/minimal-saas.css +465 -93
package/styles/native-elements.css +347 -171
package/styles/neo-noir.css +661 -19
package/styles/neumorphism.css +1021 -149
package/styles/organic-modern.css +693 -23
package/styles/paper-editorial.css +1053 -17
package/styles/retro-glass.css +639 -50
package/styles/retrofuturism.css +948 -60
package/styles/tactile.css +1813 -111
package/styles/technical-blueprint.css +673 -22
package/styles/theme-colors.css +412 -2
package/styles/y2k.css +954 -46

package/docs/ART-DECO.md ADDED Viewed

@@ -0,0 +1,80 @@
+# Art Deco Element System
+The Art Deco preset implements the retained light and dark **Art Deco UI Element System** boards using the canonical `deco-*` namespace. No public `ad-*` source aliases are introduced. All shared semantic components remain part of the unchanged `.ui-*` API.
+## Loading And Palettes
+```html
+<link rel="stylesheet" href="dist/ui-style-kit.css">
+<body data-ui="art-deco" data-mode="light">
+  <button class="deco-button deco-button-primary">Primary action</button>
+</body>
+```
+Omit `data-theme` for the reference palette. Add a supported theme, for example `data-theme="arctic-indigo"`, to use shared color tokens. `data-mode` supports light, dark, and contrast. The demo's mode-labeled button at the bottom of the Art Deco specimen selects the reference palette; the shared Color Theme picker returns to a named scheme.
+Reference light uses ivory, navy, teal, burgundy, and structural gold. Dark uses near-black green surfaces, navy anchors, pale text, and brighter metal. Separate `--deco-on-primary`, `--deco-on-secondary`, `--deco-on-warning`, and other foreground aliases protect text on filled surfaces. They resolve from the corresponding `--usk-*-text-rgb` tokens. Ordinary component paint resolves through `--deco-*-rgb` to the shared theme tokens, with local reference fallbacks.
+Stepped geometry, serif display type, diamond instruments, and segmented loading rings persist when colors change. Structural metal accepts the host accent token; geometry is not replaced by the color scheme.
+## Public Component Inventory
+All entries compose with the existing universal suffixes and appear in `manifest.classApi.presetExtras["art-deco"]` where preset-specific.
+| Board group | Public classes |
+| --- | --- |
+| 01 Buttons | `deco-button`, `deco-icon-button`, `deco-button-primary`, `deco-button-secondary`, `deco-button-ghost`, `deco-button-danger`, `deco-button-loading` |
+| 02 Navigation | `deco-breadcrumb`, `deco-pagination`, existing nav and badge classes |
+| 03 Fields | `deco-input`, `deco-input-valid`, `deco-select`, `deco-textarea`, `deco-label`, `deco-help-error`, `deco-file-upload`, `deco-file` |
+| 04 Select and choice | `deco-select-panel`, `deco-group-label`, `deco-option`, `deco-multi`, `deco-chip` |
+| 05 Checkboxes | `deco-check`, `deco-check-control` |
+| 06 Radios | `deco-radio`, `deco-radio-control` |
+| 07 Switches | `deco-switch`, `deco-switch-track`, `deco-switch-thumb` |
+| 08 Empty and loading | `deco-empty-state`, `deco-spinner`, `deco-loading-spinner` and spinner size helpers |
+| 09 Range | `deco-slider-wrap`, `deco-slider`, `deco-slider-output` |
+| 10 Threshold meter | `deco-meter` |
+| 11 Progress | `deco-progress`, `deco-progress-bar`, `deco-step-progress` |
+| 12 Tabs and segments | `deco-tabs`, `deco-tab-list`, `deco-tab`, `deco-tab-panel`, `deco-segmented`, `deco-segment` |
+| 13 Quantity | `deco-stepper` |
+| 14 Stages | `deco-stage-list`, `deco-stage`, `deco-stage-number` |
+| 15 Feedback | Existing badge/alert variants plus `deco-badge-info`, `deco-badge-outline`, `deco-alert-info`, `deco-alert-icon`, `deco-alert-close` |
+| 16 Table | `deco-table-wrap`, `deco-table` |
+| 17 Overlays | `deco-tooltip`, `deco-dialog`, `deco-dialog-actions`, existing spinner classes |
+Foundations: `deco-sheet`, `deco-fan`, `deco-frame`, `deco-frame-navy`, `deco-masthead`, `deco-masthead-title`, `deco-monogram`, `deco-stat`, `deco-stat-value`, `deco-stat-label`, `deco-health`, `deco-meta-grid`, `deco-meta`, `deco-status-dot`, `deco-performance`, `deco-section-title`, `deco-number`, `deco-divider`, `deco-palette`, and `deco-swatch`.
+Additional source recipes: `deco-details` and `deco-skeleton`. The previous metric components and all other existing public classes remain supported and showcased in the shared sections.
+## Composition And Fidelity
+The demo begins with a symmetrical serif masthead and two overview bands, followed by five component lanes, a feedback/table/dialog row, and an eight-swatch footer. Four fan motifs, fine construction lines, stepped framing, the curved health gauge, and numbered section rules carry the reference identity.
+The supplied PNGs are visual references, not production-ready markup. Their companion CSS has fixed board dimensions, a seven-column palette, a dotted spinner, a static range fill, and static dialog positioning. This implementation resolves those gaps with responsive composition, eight swatches, segmented rings, bound values, and native modal lifecycle behavior.
+Deliberate functional adaptations: native date/time/number/file controls retain platform behavior; touch targets grow to 44px; layouts reflow below desktop widths instead of scaling text down; extra disclosure/skeleton examples and palette selection sit in a supplemental row. Source paragraph text and status colors are adjusted where needed for readability. These adaptations mean browser captures are not pixel-identical raster copies of the reference board.
+## Interaction Contract
+This package is CSS-only. Applications own state and event handling. `demo/demo-art-deco.js` provides local specimen behavior without introducing runtime JavaScript into the published stylesheet API.
+- Buttons retain stepped focus indicators. Loading state reserves indicator width and uses `aria-busy`; the app must prevent duplicate submissions.
+- Native labels and choice inputs retain keyboard activation. Custom choice paint accompanies the input instead of replacing its semantics.
+- Tabs use `role="tablist"`, `role="tab"`, `aria-selected`, roving tab stops, and a labeled panel. Arrow keys and Home/End update selection.
+- Expanded choices use a listbox/option contract and keyboard selection. The demo keeps the native select synchronized.
+- Chip removal announces the change and moves focus to a remaining control. File names are assigned with `textContent`, not inserted as HTML.
+- Range fill and value bubble share `--deco-value` with the native input value. Quantity controls clamp values to 0-99 and disable at the limits.
+- Threshold and progress examples have accessible numeric values. Stage completion includes readable text and `aria-current="step"` in addition to color.
+- Dialogs use `showModal()`, Escape/cancel, and focus return. The static dialog specimen is a labeled group, not an automatically opened modal.
+- Loaders stop under reduced motion. Alerts include status text and named dismiss controls.
+## Demo Isolation
+The Art Deco specimen is created only when `data-ui="art-deco"` is selected. Existing `data-preset-only` synchronization also hides any other preset-owned regions. Switching styles rebuilds the active specimen instead of leaving hidden controls, stale dialogs, or source-only components visible. Shared semantic examples stay available and change appearance through the normal preset adapter.
+## Verification
+Focused coverage lives in `tests/art-deco-template.test.js` and `tests/e2e/art-deco-template.spec.js`. The browser spec checks the full component inventory, all-preset visibility, both reference palettes, axe results, keyboard interactions, dialog focus return, token overrides, mobile containment, typography, progress rendering, dismiss icons, and touch targets. Its temporary HTTP server exists only for tests so WebKit can inspect stylesheet rules without local-file access errors.
+Full-demo Art Deco accessibility states are included in `tests/e2e/accessibility.spec.js`. Reference screenshots are written to the operating system's temporary `usk-art-deco-template` directory. Repository build, CSS lint, palette contrast, compatibility, ownership, and package checks remain the project's standard commands.
+The semantic authored-hook test currently detects additional `.ui-*` hooks in existing Retrofuturism source, independent of this Art Deco implementation. That source is not changed here. Generated declaration fingerprints and the distinct preset-extras count are updated for the intentional Art Deco expansion; no release, commit, push, or full CI run is implied.

package/docs/BAUHAUS.md ADDED Viewed

@@ -0,0 +1,152 @@
+# Bauhaus Workshop Components
+The Bauhaus preset follows the September 2026 paired component boards from the
+personal `artifact-template-bauhaus` template. Its public `bau-*` classes, generated
+semantic aliases, and native HTML fallbacks retain the library's shared color system.
+## Usage
+```html
+<body data-ui="bauhaus" data-mode="light" data-theme="arctic-indigo">
+  <article class="bau-panel">
+    <h2 class="bau-heading">Workshop settings</h2>
+    <button class="bau-button bau-button-primary">Save changes</button>
+  </article>
+</body>
+```
+Omit `data-theme` for the reference palette. Light mode defaults to an ivory
+`#eee9dd` canvas, `#fffdf7` panels, and cobalt `#064bc4` primary actions. Dark mode
+defaults to `#050505`, `#080808`, and `#0a54e8`. Contrast mode keeps the existing
+high-contrast fallback. Danger and focus fallbacks use contrast-conscious variants
+where small control labels or boundaries need stronger contrast than the board.
+Every `--bau-*-rgb` resolver reads `--usk-*-rgb` first, with the preset color only
+as a fallback. Shared tokens may be defined directly on the host or inherited
+from an ancestor. This preset never assigns a palette to `--usk-*-rgb` variables.
+An active theme therefore controls surfaces, text, selection, status colors,
+and their paired foregrounds without changing the component geometry.
+The sidebar is black with light text only in fallback mode. With a theme it uses
+the inherited strong surface and text roles. The reference's fixed black rail
+must not override the user's selected library theme.
+## Visual Contract
+- Square panels, fields, badges, rectangular switch tracks/thumbs, and ruled tables.
+- Circular radios, range thumbs, and continuously rotating ring loaders.
+- No decorative panel bands, rounded card corners, soft elevation, or clipped buttons.
+- Secondary buttons are outlined; primary, warning, danger, and status fills use
+  their semantic theme roles and matching foregrounds.
+- The dialog retains the board's hard warning-colored offset as a specific exception.
+- Existing `bau-switch` remains the labeled checkbox-based API. `bau-compact-switch`
+  is the source's button-based switch; it requires `role="switch"`, `aria-checked`,
+  an accessible name, and application state handling. These APIs do not share a
+  fixed-width label container.
+- `bau-tooltip` remains an actual tooltip. `bau-tooltip-panel` is the specimen module
+  containing a trigger and tooltip, so the existing API stays compatible.
+## Typography
+The package bundles Barlow Regular/Semibold and Barlow Condensed Bold/ExtraBold
+from [Google Fonts](https://github.com/google/fonts/tree/main/ofl/barlow) and
+[Barlow Condensed](https://github.com/google/fonts/tree/main/ofl/barlowcondensed),
+with their SIL Open Font Licenses in `styles/assets/` and `dist/assets/`.
+No runtime font request is needed. Override `--bau-font-sans` and
+`--bau-font-display` to use application fonts. Display sizes do not scale with
+viewport width, and letter spacing is zero in the new workshop treatments.
+## Reference Mapping
+The full component inventory maps as follows. Existing public classes remain
+available; the added reference-specific composition is scoped inside `bau-sheet`.
+`bh-stage` and export-only pointer suppression are intentionally not public UI.
+Use the normal layout library for application page topology; the sheet is an
+optional responsive component specimen, not a required application wrapper.
+The existing `bau-alert-text` class styles an alert's copy region and is included
+in the preset-specific manifest inventory.
+| Template | Library |
+| --- | --- |
+| `.bauhaus-ui` | `.bau-sheet` |
+| `.bh-panel` | `.bau-panel` |
+| `.bh-sidebar` | `.bau-sidebar` |
+| `.bh-brand` | `.bau-brand` |
+| `.bh-brand-mark` | `.bau-brand-mark` |
+| `.bh-sidebar-spacer` | `.bau-sidebar-spacer` |
+| `.bh-sidebar-note` | `.bau-sidebar-note` |
+| `.bh-theme-toggle` | `.bau-theme-toggle` |
+| `.bh-switch` | `.bau-compact-switch` |
+| `.bh-canvas` | `.bau-canvas` |
+| `.bh-top-grid` | `.bau-top-grid` |
+| `.bh-middle-grid` | `.bau-middle-grid` |
+| `.bh-bottom-grid` | `.bau-bottom-grid` |
+| `.bh-hero` | `.bau-hero` |
+| `.bh-hero-copy` | `.bau-hero-copy` |
+| `.bh-eyebrow` | `.bau-eyebrow` |
+| `.bh-inline-actions` | `.bau-inline-actions` |
+| `.bh-hero-art` | `.bau-hero-art` |
+| `.bh-button` | `.bau-button` |
+| `.bh-actions` | `.bau-actions` |
+| `.bh-system` | `.bau-system` |
+| `.bh-live-dot` | `.bau-live-dot` |
+| `.bh-service-row` | `.bau-service-row` |
+| `.bh-usage` | `.bau-usage` |
+| `.bh-usage-cell` | `.bau-usage-cell` |
+| `.bh-sliders` | `.bau-sliders` |
+| `.bh-metrics-stack` | `.bau-metrics-stack` |
+| `.bh-utility-stack` | `.bau-utility-stack` |
+| `.bh-quota` | `.bau-quota` |
+| `.bh-quota-copy` | `.bau-quota-copy` |
+| `.bh-form-panel` | `.bau-form-panel` |
+| `.bh-form-grid` | `.bau-form-grid` |
+| `.bh-field` | `.bau-field` |
+| `.bh-table-tools` | `.bau-table-tools` |
+| `.bh-input-icon` | `.bau-input-icon` |
+| `.bh-file` | `.bau-file` |
+| `.bh-choices` | `.bau-choices` |
+| `.bh-switch-row` | `.bau-switch-row` |
+| `.bh-stepper` | `.bau-stepper` |
+| `.bh-segment` | `.bau-segment` |
+| `.bh-badges` | `.bau-badges` |
+| `.bh-status` | `.bau-status` |
+| `.bh-alert` | `.bau-alert` |
+| `.bh-toast` | `.bau-toast` |
+| `.bh-tooltip` | `.bau-tooltip-panel` |
+| `.bh-loading` | `.bau-loading` |
+| `.bh-spinner` | `.bau-spinner` |
+| `.bh-spin` | `.bau-spin` |
+| `.bh-skeleton` | `.bau-skeleton` |
+| `.bh-table-panel` | `.bau-table-panel` |
+| `.bh-table-wrap` | `.bau-table-wrap` |
+| `.bh-service-card` | `.bau-service-card` |
+| `.bh-service-icon` | `.bau-service-icon` |
+| `.bh-listbox` | `.bau-listbox` |
+| `.bh-dialog-zone` | `.bau-dialog-zone` |
+| `.bh-dialog-toolbar` | `.bau-dialog-toolbar` |
+| `.bh-tabs` | `.bau-tabs` |
+| `.bh-dialog-surface` | `.bau-dialog-surface` |
+| `.bh-dialog-close` | `.bau-dialog-close` |
+| `.bh-dialog-icon` | `.bau-dialog-icon` |
+| `.bh-live-status` | `.bau-live-status` |
+| `.bh-visually-hidden` | `.bau-visually-hidden` |
+## Demo And Evidence
+`demo/demo-bauhaus.js` provides local examples of switching, password visibility,
+range values, filtering, tab/listbox keyboard navigation, notices, and dialogs.
+No demo action sends data to a server. Its visuals live in `styles/bauhaus.css`.
+The complete unaltered source boards are available under the Reference board
+disclosure; they are never cropped into substitute hero artwork.
+The supplied package did not include separate geometry artwork or runnable
+application source. The live specimen uses the existing licensed icon assets and
+does not claim to reproduce missing decorative artwork. Responsive layouts and
+readable control sizes replace the source's fixed 1536 x 1024 export geometry.
+Focused tests cover the public mapping and fonts, existing component geometry,
+native loaders, all 25 themes in three modes, ancestor-token inheritance,
+reference palettes, responsive widths, reduced motion, keyboard controls, and
+accessibility. These are fresh library tests, not the source package's historical
+QA claims.

package/docs/BENTO.md ADDED Viewed

@@ -0,0 +1,121 @@
+# Bento: Soft Mosaic
+The Bento preset implements the retained September 2026 Bento UI template. Organic and other presets are not changed by this integration.
+## Usage
+```html
+<body data-ui="bento" data-mode="light">
+  <article class="bento-panel">
+    <header><h2>Workspace</h2></header>
+    <button class="bento-button bento-button-primary">Continue</button>
+  </article>
+</body>
+```
+Add `data-theme="arctic-indigo"` (or any registered theme) to use shared theme colors. Omit `data-theme` to use the reference fallback palette. Existing `--usk-*-rgb` roles remain authoritative; no template palette is assigned to shared theme variables. Light defaults use canvas #f8f9fd and primary #3157dc; dark defaults use canvas #07111f and primary #2b5ee2. Contrast mode retains the library's high-contrast fallback.
+The Manrope variable font is bundled with its SIL Open Font License in `styles/assets/` and copied to the distribution. Applications may override `--bento-font-sans`.
+## Class Mapping
+Source `bm-*` classes map one-to-one to the public `bento-*` names below; `.bento-ui` becomes `.bento-sheet`. Existing public classes remain available. Export-only `bm-stage` is not needed in applications. All new geometry lives in `styles/bento.css`, not demo CSS.
+The existing `.bento-stage` wrapper is inventoried for reference/export consumers.
+It is optional; do not apply its `.is-export` state in an interactive application,
+because that state deliberately suppresses pointer input and motion for capture.
+| Template | Library |
+| --- | --- |
+| `.bento-ui` | `.bento-sheet` |
+| `.bm-panel` | `.bento-panel` |
+| `.bm-sidebar` | `.bento-sidebar` |
+| `.bm-brand` | `.bento-brand` |
+| `.bm-brand-mark` | `.bento-brand-mark` |
+| `.bm-sidebar-spacer` | `.bento-sidebar-spacer` |
+| `.bm-sidebar-note` | `.bento-sidebar-note` |
+| `.bm-theme-toggle` | `.bento-theme-toggle` |
+| `.bm-switch` | `.bento-switch` |
+| `.bm-canvas` | `.bento-canvas` |
+| `.bm-top-grid` | `.bento-top-grid` |
+| `.bm-middle-grid` | `.bento-middle-grid` |
+| `.bm-bottom-grid` | `.bento-bottom-grid` |
+| `.bm-hero` | `.bento-hero` |
+| `.bm-hero-copy` | `.bento-hero-copy` |
+| `.bm-eyebrow` | `.bento-eyebrow` |
+| `.bm-inline-actions` | `.bento-inline-actions` |
+| `.bm-hero-art` | `.bento-hero-art` |
+| `.bm-button` | `.bento-button` |
+| `.bm-actions` | `.bento-actions` |
+| `.bm-system` | `.bento-system` |
+| `.bm-live-dot` | `.bento-live-dot` |
+| `.bm-service-row` | `.bento-service-row` |
+| `.bm-usage` | `.bento-usage` |
+| `.bm-usage-cell` | `.bento-usage-cell` |
+| `.bm-sliders` | `.bento-sliders` |
+| `.bm-metrics-stack` | `.bento-metrics-stack` |
+| `.bm-utility-stack` | `.bento-utility-stack` |
+| `.bm-quota` | `.bento-quota` |
+| `.bm-quota-copy` | `.bento-quota-copy` |
+| `.bm-form-panel` | `.bento-form-panel` |
+| `.bm-form-grid` | `.bento-form-grid` |
+| `.bm-field` | `.bento-field` |
+| `.bm-table-tools` | `.bento-table-tools` |
+| `.bm-input-icon` | `.bento-input-icon` |
+| `.bm-file` | `.bento-file` |
+| `.bm-choices` | `.bento-choices` |
+| `.bm-switch-row` | `.bento-switch-row` |
+| `.bm-stepper` | `.bento-stepper` |
+| `.bm-segment` | `.bento-segment` |
+| `.bm-badges` | `.bento-badges` |
+| `.bm-status` | `.bento-status` |
+| `.bm-alert` | `.bento-alert` |
+| `.bm-toast` | `.bento-toast` |
+| `.bm-tooltip` | `.bento-tooltip` |
+| `.bm-loading` | `.bento-loading` |
+| `.bm-spinner` | `.bento-spinner` |
+| `.bm-spin` | `.bento-spin` |
+| `.bm-skeleton` | `.bento-skeleton` |
+| `.bm-table-panel` | `.bento-table-panel` |
+| `.bm-table-wrap` | `.bento-table-wrap` |
+| `.bm-service-card` | `.bento-service-card` |
+| `.bm-service-icon` | `.bento-service-icon` |
+| `.bm-listbox` | `.bento-listbox` |
+| `.bm-dialog-zone` | `.bento-dialog-zone` |
+| `.bm-dialog-toolbar` | `.bento-dialog-toolbar` |
+| `.bm-tabs` | `.bento-tabs` |
+| `.bm-dialog-surface` | `.bento-dialog-surface` |
+| `.bm-dialog-close` | `.bento-dialog-close` |
+| `.bm-dialog-icon` | `.bento-dialog-icon` |
+| `.bm-live-status` | `.bento-live-status` |
+| `.bm-visually-hidden` | `.bento-visually-hidden` |
+## States and Existing Components
+Source button modifiers `is-primary`, `is-secondary`, `is-danger`, and `is-ghost` are supported alongside the established `bento-button-primary`, `bento-button-secondary`, `bento-button-danger`, and `bento-button-ghost` classes. `is-hover` and `is-busy` expose sample states; application loading should also set `aria-busy="true"`. Warning keeps the shared paired warning role. Disabled controls use native `disabled`.
+Native `button[aria-busy="true"]` controls use the same current-color circular ring as authored and semantic busy buttons. The Bento-only override removes the legacy tile background, inset shadow, and clipped corners; reduced-motion preferences remain respected. This is covered by `tests/e2e/bento-native-busy.spec.js` in light, dark, and contrast modes.
+Labeled `bento-switch` / `ui-switch` checkboxes retain a separate text lane beside a fixed 37px by 20px track. Compact button/span switches use the same geometry without applying their thumb rules to label text. Focus and checked states remain native-input driven. Spinner sizes are 16px, 28px, and 40px; intrinsic flex sizing keeps each ring circular. The `ui-spinner`, `loading-spinner`, and `data-loading-spinner` aliases also receive the Bento ring treatment.
+Alert titles and bodies wrap at spaces rather than splitting words. Direct title/body siblings can wrap into separate rows in narrow containers. Service medallion text icons use 32px type while retaining their existing container size.
+Status chips support `is-violet`, `is-success`, `is-warning`, `is-danger`, and `is-info`. Switches use `role="switch"` and `aria-checked`; listboxes use option `aria-selected`; segmented buttons use `aria-pressed`. CSS does not implement application state or persist data.
+Existing cards/panels use 17px corners, buttons 8px, inputs/selects/textareas 6px, badges 5px, feedback 9px, and dialogs 14px. Native form elements inherit the same role tokens. Legacy `ui-*` aliases continue to be generated by the package build.
+## Responsive and Accessibility Adaptations
+The source is a fixed 1536 x 1024 board. Library compositions use intrinsic rows and responsive tracks instead of scaling the board or clipping labels. The sidebar becomes a horizontal strip on smaller screens, then panels stack. Tables retain horizontal scrolling. Typography is at least 12px in the specimen; controls are at least 36px high where the original used tiny 26px targets. Semantic chip text uses the body foreground over tinted backgrounds to preserve contrast rather than reproducing low-contrast source labels.
+Muted light text and hover fills are slightly darker than the source to meet text contrast requirements. The light quota figure uses a darker green fallback; small blue text uses the link role, particularly in dark mode. Selected dialog tabs use the paired surface/text roles. These accessibility adjustments do not override a selected shared theme.
+The Bento-only demo includes local sample interactions for password visibility, upload filenames, switches, range output, segmented choices, dismissible feedback, customer filtering, keyboard listbox/tab navigation, details, and a nonmodal inline confirmation dialog. It makes no service requests and does not store input. Its reference-palette selector is demo state, not a library requirement.
+The native-element demo uses measured grid spans to pack unequal sample heights without reordering the DOM. A demo-only ResizeObserver updates spans when controls, disclosures, fonts, or viewport dimensions change and is disconnected when switching presets. Library consumers do not need this demo layout code. The follow-up annotation checks in `tests/e2e/bento-annotations.spec.js` cover switch activation, spinner geometry and aliases, word-boundary wrapping, icon scale, and desktop/mobile sample gaps.
+## Reference Assets
+The retained template contains light/dark full-board PNGs, extracted from the supplied SVG wrappers, plus the original guide and CSS. It does not contain separate transparent illustration assets or the historical application's source/tests. The demo displays an illustration-only window from each unchanged board; it does not use a screenshot as interactive UI. Those illustration pixels keep their original colors and are not theme tokens. New CSS components contain no dependency on demo images.
+Source provenance: `artifact-template-bento-ui/references/source/bento-ui.css`, `BENTO-UI-DESIGN-GUIDE.md`, and the retained light/dark board assets. Historical supplied QA is not evidence of current library validation.

package/docs/CLAY.md ADDED Viewed

@@ -0,0 +1,127 @@
+# Clay Reference System
+The Clay specimen implements the paired **Sculpted Product Studio** reference
+images from the explicitly requested `artifact-template-clay` template. The saved
+template and original references are unchanged.
+## Entry Points
+Use `ui-style-kit-css/clay.css` for the complete preset, or
+`ui-style-kit-css/visual/clay.css` for its visual-only distribution. Set
+`data-ui="clay"` and `data-mode="light"`, `dark`, or `contrast` on the owning root.
+The full demo is available in both `index.html` and `demo/index.html`.
+## Unified Material
+The approved hand-molded direction supersedes the earlier split between a smooth
+reference sheet and deeply embossed general components. Both now share the same
+type roles, imperfect control contours, matte grain, theme paint, and three depth
+treatments: resting slabs, raised controls, and recessed wells. The sheet retains
+its compact dimensions and responsive arrangement, not a separate component skin.
+Section dividers sit on a continuous slab instead of framing every group as a
+rounded card. Grain is blended into backgrounds rather than overlaid on text.
+Body copy, field values, alerts, and table cells remain crisp; restrained impressed
+lettering is limited to headings and short control labels. Pressed buttons recess,
+and inset keyboard rings remain visible inside the irregular silhouettes.
+Rounded headings use the locally bundled Nunito variable font (exposed as
+`Clay Rounded`), with its SIL Open Font License retained in
+`styles/assets/clay-rounded-OFL.txt`. Source: [Google Fonts Nunito](https://github.com/google/fonts/tree/main/ofl/nunito).
+Body copy and input values retain the compact system font. Circular controls use
+smooth, slightly oval silhouettes rather than faceted polygons. Check marks and
+demo icons are centered independently of font baselines.
+Tables share a formed outer edge and matte raised headers while keeping straight,
+readable rows. Feature strips use one blended slab without internal dividers;
+supporting copy uses the surface's high-contrast foreground. Range, progress,
+threshold, and milestone controls share the same grain and relief as buttons.
+Set `data-theme` to any shared scheme to color the entire preset: canvas, slabs,
+raised and inset surfaces, text, controls, status colors, tooltips, and the reference
+sheet. Prefixed classes, semantic `.ui-*` components, and native elements use the
+same material mappings. Live `--usk-*-rgb` overrides on the owning root also apply.
+The sculpted edges, grain, and relief remain Clay-specific across schemes.
+Omit `data-theme` to retain the original mineral palette. The demo sheet displays
+live semantic-role swatches for a selected theme and mineral swatches in reference
+palette mode. Contrast themes retain their paired semantic foreground/background
+colors while suppressing decorative texture on selected controls.
+## Component Inventory
+`clay-helper` supplies the existing compact supporting-copy treatment for fields
+and component groups. It is included in the manifest alongside the classes below.
+| Reference Area | Public Classes |
+| --- | --- |
+| Continuous slab and rail | `clay-sheet`, `clay-rail`, `clay-rail-link`, `clay-studio-mark` |
+| Masthead, studio plate, palette | `clay-masthead`, `clay-studio`, `clay-palette`, `clay-palette-grid`, `clay-swatch` |
+| Seamed component groups | `clay-reference-section`, `clay-section-title`, `clay-component-matrix`, `clay-choice-stack` |
+| Button state matrix | `clay-button-matrix`, `clay-button`, `clay-button-primary`, `clay-button-secondary`, `clay-button-outline`, `clay-button-danger`, `clay-loading-track` |
+| Text, password, search, numeric, date, time, datetime, textarea | `clay-field-row`, `clay-input-wrap`, `clay-input`, `clay-textarea`, `clay-icon-button` |
+| Upload zone | `clay-file-zone` |
+| Closed and expanded select | `clay-select`, `clay-select-menu`, `clay-option` |
+| Removable multi-select tags | `clay-tags`, `clay-chip` |
+| Checked, unchecked, mixed, selected and disabled controls | `clay-choices`, `clay-check`, `clay-check-control`, `clay-radio`, `clay-radio-control`, `clay-switch`, `clay-switch-track`, `clay-switch-thumb` |
+| Range and value flag | `clay-control-band`, `clay-range`, `clay-range-scale`, `clay-value-flag` |
+| Continuous and segmented progress | `clay-progress`, `clay-progress-bar`, `clay-segments` |
+| Horizontal milestones and vertical progress | `clay-milestones`, `clay-milestone`, `clay-vertical-progress` |
+| Threshold meter | `clay-threshold`, `clay-threshold-scale` |
+| Tabs and panel | `clay-navigation-band`, `clay-tabs`, `clay-tab`, `clay-tab-panel`, `clay-tab-media` |
+| Pagination, view modes, quantity | `clay-pagination`, `clay-segmented`, `clay-quantity` |
+| Success, information, warning and error messages | `clay-feedback-band`, `clay-alert`, `clay-alert-success`, `clay-alert-info`, `clay-alert-warning`, `clay-alert-danger`, `clay-alert-close` |
+| Tooltip and bead loader | `clay-tooltip`, `clay-tooltip-bottom`, `clay-spinner`, `clay-spinner-lg` |
+| Status, category and count badges | `clay-data-band`, `clay-badge` and its semantic color variants |
+| Task table | `clay-table-wrap`, `clay-table` |
+| Team portraits and overflow count | `clay-avatar`, `clay-avatar-group` |
+| Text and engraved studio seal | `clay-inset`, `clay-badge-seal` |
+| Inline confirmation and native modal | `clay-dialog`, `clay-dialog-actions` |
+The 50 added reference-specific classes are registered in `manifest.json`, alongside
+the four existing Clay extras. Layout-only
+legacy `clay-section` is not repurposed as a new visual component.
+## Behavior And Integration
+The CSS library does not install event handlers. `demo/demo-clay.js` demonstrates
+the HTML/ARIA contracts and local interactions: mode switching, anchor navigation,
+password visibility, selectable/filterable options, tag creation/removal, keyboard
+tabs, pagination, segmented selections, bounded quantity changes, range output,
+message dismissal, and native modal confirmation with focus restoration.
+Uploads are inspected locally, never sent to a server. The sample accepts PDF,
+DOCX, XLSX and PNG files up to 10 MB. Tag values are inserted with `textContent`.
+Loading examples and progress indicators are presentation samples, not claims of
+background work. Table actions open the local confirmation demonstration.
+`ClaySpecimen.render()` returns an empty string for every other preset. The shared
+demo visibility pass also hides any `data-preset-only` region that does not match
+the selected style. The browser test checks this across all 20 presets.
+## Assets And Fidelity
+`styles/assets/clay-grain.png` is a generated, neutral clay-grain texture packaged
+with every CSS entrypoint. `demo/assets/clay-avatars.png` contains three generated
+fictional headshots in equal-width cells, used only by the demo. Lucide icons are
+retained locally under their existing license; additional icons use version 0.468.0.
+The reference is a raster, not a source design file with font metrics and separate
+assets. The implemented sheet matches its component inventory and band composition,
+but it is not a pixel-identical rendering: the approved unified material, system font metrics, native date/time
+controls, generated portraits, and reconstructed material grain differ. Responsive
+views deliberately reflow the desktop matrix instead of shrinking its labels.
+## Focused Verification
+- `node --test tests/clay-template.test.js`
+- `npx playwright test tests/e2e/clay-template.spec.js --project=chromium --workers=1`
+- Existing Clay material test in `tests/e2e/clay-reference-fidelity.spec.js`
+- `tests/e2e/clay-theme-colors.spec.js` checks all 25 themes in three modes,
+  live RGB overrides, stable material geometry, and desktop/mobile containment
+- `tests/e2e/clay-unified-material.spec.js` compares rendered public and sheet
+  controls, reading-surface typography, keyboard/pressed states, and responsive views
+- CSS lint, ownership, compatibility, package, and demo asset-version checks
+Run individual browser cases during iteration. Do not replace a focused failure
+with an unrelated full-suite run.

package/docs/COLOR-THEMES.md ADDED Viewed

@@ -0,0 +1,63 @@
+# Color Themes
+UI Style Kit CSS exposes 25 named color themes independently from its 20 visual
+presets. Select a visual system with `data-ui`, a palette with `data-theme`, and
+the display treatment with `data-mode`.
+```html
+<body data-ui="minimal-saas" data-theme="signal-yellow" data-mode="light">
+```
+The five newest themes fill color families that were previously absent or only
+represented by neighboring hues. They use the same complete semantic role set
+as every existing theme and support `light`, `dark`, and `contrast` modes.
+## Gap-filling palettes
+| Theme ID | Color territory | Light foundation | Light primary / secondary / accent | Dark foundation | Dark primary / secondary / accent |
+| --- | --- | --- | --- | --- | --- |
+| `signal-yellow` | True signal yellow with ink-navy support | `#fffbe8` | `#ffcc00` / `#25324e` / `#ffe45c` | `#120f03` | `#ffd83b` / `#8ec6ff` / `#ffe866` |
+| `botanical-green` | Central leaf green with a restrained berry counterpoint | `#eff9f2` | `#0d7e42` / `#793058` / `#40c975` | `#041109` | `#52de8b` / `#ee94c7` / `#6bf0a4` |
+| `cobalt-electric` | Clean saturated cobalt with coral signaling | `#f0f4ff` | `#0052cc` / `#b53948` / `#5279ff` | `#040919` | `#6f95ff` / `#ff8593` / `#8faaff` |
+| `stone-graphite` | Chroma-light stone, graphite, silver, and semantic status color | `#f4f4f2` | `#383c3a` / `#5b615d` / `#b8beba` | `#0c0d0d` | `#d0d4d1` / `#a4aaa6` / `#e6e8e7` |
+| `walnut-clay` | Cocoa walnut, mushroom earth, clay, and muted foliage | `#f8f1e9` | `#704330` / `#58624e` / `#be6f52` | `#120c09` | `#da9e7c` / `#b2c09d` / `#eba988` |
+## Design intent
+- **Signal Yellow** is deliberately yellow-led rather than another gold or
+  amber scheme. Ink navy provides structure without dulling the signal color.
+  In light mode, primary and accent text use the darker link ink on neutral
+  surfaces; primary and accent fills retain their vivid yellow values.
+- **Botanical Green** occupies the clean middle-green range between the
+  library's moss, lime, and teal-emerald themes. Berry is used as a controlled
+  complementary color.
+- **Cobalt Electric** provides a vivid primary blue distinct from steel, cyan,
+  navy, and subdued indigo. Coral carries urgent secondary actions.
+- **Stone Graphite** is the neutral brand palette. Its interface hierarchy
+  comes from value and surface separation; chroma is reserved for semantic
+  success, warning, and danger roles.
+- **Walnut Clay** covers the deep brown and taupe family without behaving like
+  an orange theme. Clay and muted foliage keep the palette warm and grounded.
+## Token contract
+The source values in `styles/theme-colors.css` are space-separated RGB channels,
+not complete CSS colors. For example:
+```css
+:where([data-ui][data-theme="cobalt-electric"][data-mode="light"]) {
+  --usk-primary-rgb: 0 82 204;
+  --usk-primary-text-rgb: 255 255 255;
+}
+```
+Consume those channels through the existing semantic or preset-prefixed tokens.
+Do not put `rgb(...)` or hexadecimal values inside a `--usk-*-rgb` override.
+Each foreground/background role pair is validated to at least WCAG AA text
+contrast by the library's manifest-driven contrast check.
+Bright palettes can also set the optional `--usk-primary-ink` and
+`--usk-accent-ink` tokens to complete CSS colors for text on neutral surfaces.
+These text-only overrides do not change fill colors or text on filled controls.
+They reset at each `data-ui` root, and presets retain their original text colors
+when no ink override is set. Signal Yellow uses this distinction in light mode.

package/docs/DEMO-SHOWCASE.md ADDED Viewed

@@ -0,0 +1,65 @@
+# Demo showcase and reference fixtures
+The default `index.html` and `demo/index.html` present one shared library showcase:
+semantic components, overview, color tokens, prefixed components, native HTML,
+the Interactive Surface bridge, and usage examples.
+## Preview state and palette editing
+Use `?ui=tactile&theme=None&mode=dark` to preview a native palette. The `personality`
+query parameter is a compatibility alias for `ui`; `ui` takes precedence when both
+are present. Only manifest-supported preset, theme, and mode values are accepted.
+**None — style defaults** omits `data-theme`. The color workbench exposes the
+selected preset's computed RGB variables, including material colors such as paper,
+ink, and brass. Native edits export `--<prefix>-*-rgb` and remain scoped to that
+preset and mode. Named themes expose the 23 shared `--usk-*-rgb` roles instead.
+Switching contexts restores that context's edits; reset affects only the active
+palette. Reload clears temporary edits. Recheck accessibility after editing colors.
+The toolbar uses one native dropdown indicator across styles. This does not change
+the preset-specific select specimens or their platform-owned popup behavior.
+## Style-specific components
+The Components section begins with `#style-specific`. This gallery changes with
+the selected UI style without adding a second page header, navigation system,
+palette picker, or repeated form/button catalogue.
+Industrial Utility includes its pilot/status bank, switchgear, key switch, guarded
+stop, pressure readout, meters, process stages, and alarm acknowledgment flow.
+These controls operate on local demonstration state only; no equipment is connected.
+Acknowledging a sample alarm does not remove its critical condition.
+Clay, Neo Noir, Art Deco, Editorial Lux, Retro Glass, and Technical Blueprint also
+reuse distinctive progress and instrumentation fragments from their authored boards.
+Other presets retain their public surface/shape examples in this same section.
+Gallery fragments use the actual library classes and inherit the active palette.
+Selecting **None — style defaults** uses native preset colors; named themes and
+token-editor overrides continue to apply. No gallery sets its own color theme.
+## Original reference boards
+Open `index.html?view=reference` (or `demo/index.html?view=reference`) to display
+the original complete boards for developer comparisons. Select the desired preset
+using the normal controls. The curated gallery is omitted in this view to avoid
+duplicate component IDs and event handlers. The view includes a return link.
+The reference assets, board renderers, and library styles have not been deleted.
+Existing board-specific browser tests use this explicit query. Public-page tests
+continue to use the default URL.
+## Maintaining excerpts
+The authored board marks complete, non-nesting fragments with
+`<!--demo-style-feature-->` / `<!--/demo-style-feature-->` comments. The gallery
+extracts only those explicit boundaries, not arbitrary HTML tags. Associated
+dialog/live-region markup uses `demo-style-support` boundaries and stays outside
+the feature grid. Keep unique IDs and their referenced labels inside retained
+fragments, and bind any interactive controls in the public view as well as the fixture.
+`tests/demo-style-showcase.test.js` verifies rendering and focused controller
+behavior without launching a browser. `tests/e2e/demo-style-showcase.spec.js`
+covers actual layout, keyboard interaction, modal focus, and theme/mode switching.
+The latter requires an available, authorized browser session for rendered QA.

package/docs/ECOSYSTEM.md CHANGED Viewed

@@ -14,11 +14,11 @@ The pinned Interactive Surface and Layout commits are published merge objects. B
 | Library | Current aligned version | Owns |
 |---|---:|---|
-| `ui-style-kit-css@2.3.0` | current release target | visual identity, color themes, UI paint, native HTML styling, content wrapping, and bridge tokens |
-| `interactive-surface-css@1.6.0` | compatible state release | interaction-state primitives, surface behavior, state layers, and input affordances |
+| `ui-style-kit-css@2.4.1` | current release target | visual identity, color themes, UI paint, native HTML styling, content wrapping, and bridge tokens |
+| `interactive-surface-css@1.7.0` | compatible state release | interaction-state primitives, surface behavior, state layers, and input affordances |
 | `layout-style-css@3.1.0` | compatible structural release | structural wrappers, grids, sections, app shells, and layout recipes |
-The current combination is `ui-style-kit-css@2.3.0`, `interactive-surface-css@1.6.0`, and `layout-style-css@3.1.0`. UI Style Kit `2.3.0` is the current release target; the companion versions are published releases. Layout Style `3.1.0` is the compatible structural release. The validated minimum remains `ui-style-kit-css@2.1.0`, `interactive-surface-css@1.5.0`, and `layout-style-css@3.0.0`.
+The current combination is `ui-style-kit-css@2.4.1`, `interactive-surface-css@1.7.0`, and `layout-style-css@3.1.0`. UI Style Kit `2.4.1` is the current release target; the companion versions are published releases. Layout Style `3.1.0` is the compatible structural release. The validated minimum remains `ui-style-kit-css@2.1.0`, `interactive-surface-css@1.5.0`, and `layout-style-css@3.0.0`.
 ## Layout-to-visual pairing matrix
@@ -32,7 +32,7 @@ Pairings are recommendations, never dependencies. `data-ly-layout`, `data-ui`, `
 ## Shared semantic theming
-UI Style Kit's complete, visual, and focused visual entrypoints produce the 12 package-neutral `--ui-*` control tokens under `[data-ui][data-theme][data-mode]`. A third-party theme may produce the same contract under its own scope; consumers do not need UI Style Kit-specific `--usk-*` values. Package-specific values remain first in consumer fallback chains, shared semantic values come second, and legacy values or literals remain last.
+UI Style Kit's complete, visual, and focused visual entrypoints produce the 12 package-neutral `--ui-*` control tokens under `[data-ui][data-mode]`; `data-theme` is optional. A third-party theme may produce the same contract under its own scope; consumers do not need UI Style Kit-specific `--usk-*` values. Package-specific values remain first in consumer fallback chains, shared semantic values come second, and legacy values or literals remain last.
 A third-party producer can theme Interactive Surface's complete standalone entry point without a package-specific adapter: