ui-style-kit-css 2.3.0 → 2.4.0

package/docs/EDITORIAL-LUX.md

@@ -0,0 +1,75 @@
+# Editorial Lux
+
+Editorial Lux implements the retained couture UI element system: a double-rule frame, Didone masthead and stacked headline, collection rail, portrait, restrained forest actions, oxblood destructive states, brass measurement details and ruled component bands.
+
+The display name is **Editorial Lux**. The existing preset ID `editorial-luxe`, stylesheet entrypoints and `luxe-*` prefix are unchanged. The library remains CSS-only; demo JavaScript is an example controller, not a runtime dependency of the package.
+
+## Usage and Tokens
+
+```html
+<link rel="stylesheet" href="ui-style-kit-css/editorial-luxe.css">
+<main data-ui="editorial-luxe" data-mode="light">
+  <button class="luxe-button luxe-button-primary">View look</button>
+</main>
+```
+
+Omit `data-theme` for the fallback reference palette. Add any supported theme, such as `data-theme="arctic-indigo"`, for shared color-theme switching. Both named themes and application overrides flow through `--usk-*` into the `--luxe-*` aliases. Geometry and typography remain preset-owned.
+
+| Role | Light fallback | Dark fallback |
+| --- | --- | --- |
+| Surface | `#f8f5ef` | `#0e1110` |
+| Text | `#111413` | `#e8dfd2` |
+| Primary fill | `#123229` | `#18382e` |
+| Destructive fill | `#7d1113` | `#8d1b1c` |
+| Structural rule | `#706d65` | `#95825c` |
+| Brass material | `#a58246` | `#a58246` |
+
+Primary/destructive backgrounds use separate on-color tokens. Small success/error text has contrast-safe foreground aliases so deep pigments are not used as unreadable dark-canvas copy. Neutral muted copy and rules are strengthened where the original compact sheet is too faint for functional UI. Contrast mode follows the existing high-contrast token system.
+
+## Component Surface
+
+All existing universal `luxe-*` classes remain available. New preset-only suffixes are declared in `manifest.classApi.presetExtras['editorial-luxe']`; there is no public `el-*` alias layer.
+
+| Reference group | Public components |
+| --- | --- |
+| Editorial shell | `luxe-sheet`, `luxe-masthead`, `luxe-masthead-title`, `luxe-collection-rail`, `luxe-portrait`, `luxe-story`, `luxe-story-title`, `luxe-byline`, `luxe-deck`, `luxe-colophon`, `luxe-section-title`, `luxe-section-number` |
+| 01 Buttons | Existing `luxe-button` primary/secondary/ghost/danger variants; `.is-pressed`, native `disabled`, and `aria-busy` |
+| 02 Inputs | Existing input/select/textarea/label; `luxe-input-valid`, `luxe-help-error`, `luxe-file-upload`, `luxe-file-drop`, `luxe-select-panel`, `luxe-option` |
+| 03 Choices | Existing check/radio controls; `luxe-switch-segment` off/on control |
+| 04 Ranges | `luxe-range`, `luxe-range-scale`, labeled native inputs and outputs |
+| 05 Measurement | Existing progress/bar; `luxe-segmented-progress`, `luxe-meter` |
+| 06 Alerts | Existing success/warning/danger alerts; `luxe-alert-mark`, `luxe-alert-close` |
+| 07 Tabs | `luxe-tabs`, `luxe-tab-list`, `luxe-tab`, `luxe-tab-panel` |
+| 08 Data | Existing table/table-wrap; `luxe-details` disclosure |
+| 09 Status/navigation | `luxe-badge-medallion`, `luxe-badge-brass`, existing danger badge; `luxe-pagination`, `luxe-stepper` |
+| 10 Overlay/loading | Existing tooltip/spinner; `luxe-skeleton`, `luxe-dialog`, `luxe-dialog-actions` |
+
+`luxe-badge-medallion luxe-badge-danger` produces the red Hold mark. `luxe-badge-medallion luxe-badge-brass` produces the Saved mark. `--luxe-value` sets the threshold indicator from 0 through 100; provide matching meter semantics and visible meaning. `.is-done` marks completed progress segments.
+
+## Accessible Interaction Contract
+
+Use native buttons and inputs with visible labels. Pair errors with `aria-invalid` and `aria-describedby`; use state text and icons in addition to color. File-drop styling wraps a real file input rather than an inaccessible simulated picker.
+
+The demo implements keyboard tabs and listbox options with roving focus, synchronized native selects, slider outputs, quantity bounds 1-99, page selection, local archive filtering, file-name feedback, alert dismissal and focus recovery. The dialog uses `showModal()`, Escape/cancel/confirm, and returns focus to its opener. Actions affect inert local sample state only; Share and Download do not send or export user data.
+
+Make scrollable table regions focusable and name them. Connect tooltips with `aria-describedby`. Busy actions require an appropriate accessible name and disabled/busy handling in the consuming application's controller. Coarse-pointer targets are at least 44px; reduced motion stops the spinner and skeleton animation.
+
+Standalone loaders use counter-rotating fine rings consistent with the double-rule frame, including semantic and native spinner aliases. Both rings stop under reduced motion. Seal numerals are 28px above 12px captions. Checkbox marks use centered geometric strokes instead of font-dependent glyphs. Warning badges and alert icons use light foregrounds over darkened theme warning pigment; warning labels and outlines retain the original semantic color. Demo toolbar selects use one native indicator in this preset.
+
+## Demo and Fidelity
+
+Open `index.html` or `demo/index.html`, select **Editorial Lux**, then use the specimen's **Use reference palette** button to compare fallback colors. Choose a named Color Theme to resume token-based theme switching.
+
+All ten board groups are visible in the main specimen. Native number/date/time/file/progress/meter examples, validation, loading and token swatches are available in **Native fields & foundations**. The source's additional table disclosure and editorial reading sample are also included. Preset-specific regions are rendered or shown only when their owning style is active, with an all-preset isolation regression test.
+
+The new source module is `demo/demo-editorial-lux.js`; component styling is in `styles/editorial-luxe.css`; demo-only composition is in `demo/demo.css`. The portrait is retained at `demo/assets/editorial-portrait.png`. Icons use the existing licensed Lucide collection, including its paperclip icon.
+
+The reference PNG and supplied interactive HTML are not identical. This implementation follows the PNG's ten-group composition and retains the HTML's additional control surface. Intentional functional adaptations include associated labels, accessible status colors, native browser controls, keyboard focus, 44px touch targets, and responsive reflow instead of shrinking a fixed 1536px canvas. Supplemental controls use disclosure to preserve the main board composition. Font stacks resolve to installed system fonts; no Didot/Bodoni font files are bundled. These differences mean the result is not claimed as a pixel-identical raster reproduction.
+
+## Verification
+
+Focused tests cover the manifest/CSS inventory, all-preset demo isolation, reference light/dark/contrast accessibility, desktop/602px/390px geometry, portrait loading, calibration rules, touch targets, expanded native fields, keyboard interactions and live theme-token overrides. Full-demo representative scans cover all three modes with Arctic Indigo. Interaction tests also run in Firefox and WebKit.
+
+`tests/e2e/editorial-lux-annotations.spec.js` covers the seven annotation refinements in Heritage Brass, including measured warning contrast, centered alert icons, seal typography, native toolbar indicators and reduced-motion spinner aliases.
+
+Rebuild before browser verification because the demo loads `dist/ui-style-kit.css`. Generated default, visual-only, focused visual and bridge bundles are build outputs. No full CI, publication, commit or deployment is implied by these local checks.

package/docs/INDUSTRIAL-UTILITY.md

@@ -0,0 +1,131 @@
+# Industrial Utility
+
+Industrial Utility implements the retained Industrial template as the canonical
+`utility-*` preset. The source template's `iu-*` names are not public aliases.
+The shared `.ui-*` contract remains unchanged.
+
+## Loading and Color
+
+Load `dist/ui-style-kit.css`, or the focused `dist/visual/industrial-utility.css`
+bundle with the supporting files required by that entry point. Select
+`data-ui="industrial-utility"` and `data-mode="light"`, `"dark"`, or `"contrast"`.
+Use `data-theme` for a named color scheme. Omit `data-theme` to use the preset's
+reference palette; the demo's **Use reference palette** button does this.
+
+`--utility-material-*` aliases resolve through the host `--usk-*` palette. Action,
+status, text, focus, border, and surface roles therefore follow theme changes
+without replacing the industrial geometry. Foreground/background token pairs
+must be overridden together when customizing a palette.
+
+Dark headers, the console bezel, and black instrument wells are intentional
+materials in both modes. Their optional extension tokens are
+`--usk-industrial-header-rgb`, `--usk-industrial-header-text-rgb`,
+`--usk-industrial-bezel-rgb`, and `--usk-industrial-readout-text-rgb`.
+Metal bevels, rivets, guard stripes, and fixed switch geometry retain the
+template's tactile character. This is not a drafting-grid or glass preset.
+
+## Component Surface
+
+The exact published inventory is `manifest.classApi.presetExtras["industrial-utility"]`
+plus `manifest.classApi.universalVisualSuffixes`. All names below use `utility-`:
+
+| Group | Components |
+| --- | --- |
+| Console | panel, panel-header, panel-body, rivet, nameplate, card, overline |
+| Actions | button, button-primary, button-secondary, button-ghost, button-danger, button-guarded, icon-button |
+| Forms | field, label, input, select, textarea, file, help, check, radio, dropdown, option |
+| Switchgear | control-grid, control-cell, control-name, toggle, three-position, key-switch, emergency-stop, pilot-light |
+| Instruments | readout, readout-label, slider, ticks, meter, progress, progress-bar, stage-track, stage, metric, metric-label, metric-value |
+| Navigation | breadcrumb, tabs, tab, pagination, segmented, details |
+| Data and Feedback | table-wrap, table, badge and status variants, alert and status variants, spinner, skeleton, empty-state, toast-stack, toast |
+| Overlays and Foundations | dialog, tooltip, popover, token-row, token |
+
+The specimen contains eleven reference groups: buttons, inputs, system status,
+selection, switchgear, instruments, navigation, work orders, alerts, overlays,
+and foundations. Additional existing preset examples remain available only
+while Industrial Utility is selected. All demo preset-only regions are checked
+against their owning preset across the full style selector.
+
+## States and Behavior
+
+- Buttons support hover, focus-visible, pressed, disabled, and loading states.
+  Guarded controls retain a striped surround; loading indicators reserve space.
+- Native checkbox/radio inputs can be displayed directly inside `utility-check`
+  and `utility-radio`. Existing adjacent `*-control` markup remains supported.
+- Options, tabs, and segmented controls use selected state plus keyboard focus;
+  the demo implements arrow, Home, and End navigation.
+- Pilot lights and alarms use labels and acknowledgment text as well as color.
+- Range controls use native keyboard behavior. Readouts and progress labels
+  expose their values without depending on their visual fill.
+- A native `dialog.utility-dialog` is hidden until opened. A static
+  `div.utility-dialog` can demonstrate its surface without pretending to be an
+  active modal. Real dialogs retain native focus containment and Escape handling.
+- Reduced motion disables decorative loading animation. Coarse pointers receive
+  larger targets; forced colors retain visible boundaries and checked states.
+
+Demo controls operate on local, inert sample data only. The emergency stop does
+not control equipment. Acknowledgment changes the acknowledgment state, never
+the critical alarm condition. No operator log, server write, or network control
+is implied by the sample interface.
+
+## Reviewed Controls
+
+`.utility-pilot-light.is-warning` adds a warning-role lamp with the same slow
+pulse as warning badges, disabled by reduced-motion preferences. Warning alerts
+use the warning role instead of the primary-action role. `.utility-alert-info`
+keeps the separate blue information treatment. Named theme warning tokens still
+take precedence over fallback paint.
+
+Every preset supports `.{prefix}-button-warning` alongside its base button class,
+and `.ui-button[data-ui-variant="warning"]` is the equivalent semantic API.
+Warning controls inherit preset geometry and use paired warning fill/text roles.
+The shared demo displays this variant for every style; Industrial Danger examples
+opt into `.is-alarm`, while destructive commands remain steady.
+
+Use `.utility-button.is-alarm` (or `.ui-button.is-alarm` in this preset) for an
+active alarm command. Danger badges, danger alerts, and red pilot lights pulse
+at the warning cadence. `.utility-button-danger` alone remains steady for
+destructive commands such as Delete. Reduced-motion preferences stop signaling
+animations without removing the status color or label.
+
+All spinner entry points, including `.is-loading` and `aria-busy`, share the
+eight-step mechanical rotor. Plain `.utility-panel` content has a 16px inset;
+panels with a direct `.utility-panel-body` delegate padding to that body.
+Containers reserve 16px inline padding. Native checked boxes use a centered
+square, and native tables inherit the same header and rule treatment as the
+prefixed table. Icon-only buttons reserve a visible SVG box.
+
+Shared native `audio[controls]` styling now uses each preset's control surface,
+radius, border, and shadow without requiring JavaScript or replacing native
+keyboard/playback behavior. Chromium/WebKit control panels also inherit the
+surface. Internal playback buttons remain browser-owned, particularly in
+Firefox; CSS cannot provide identical internal controls across engines.
+
+## Verification Evidence
+
+Focused checks live in `tests/industrial-utility-template.test.js` and
+`tests/e2e/industrial-utility-template.spec.js`. The browser spec covers the
+generated bundle, all eleven groups, the manifest inventory, preset isolation,
+reference-mode accessibility, keyboard interactions, host token overrides,
+reduced motion, and desktop/mobile containment. Dark and light captures are
+written to the operating system's temporary `usk-industrial-utility-template`
+directory for comparison with the retained boards.
+
+The responsive browser specimen preserves native controls and accessible text
+instead of scaling a fixed bitmap. Native date/file UI and mobile reflow therefore
+differ from the static reference image. Historical QA shipped with the template
+is not evidence that the current library build has passed validation.
+
+### Local Validation, September 5, 2026
+
+The implementation passed its focused component and browser checks, including
+reference dark/light axe audits, a named-theme axe audit with paired custom
+primary tokens, keyboard interactions, and 602/390 px containment. The generated
+build, class/public API checks, contrast matrix, lint, ownership, compatibility,
+package integrity, reviewed fingerprints, and whitespace checks also passed.
+
+The full semantic-component contract file has one remaining unrelated failure:
+its authored-selector assertion expects only `.ui-spinner` and `.ui-tooltip`,
+while the existing Retrofuturism source declares additional semantic aliases.
+Those changes were preserved. This run did not execute full CI, publish a
+package, commit changes, or push a branch.

package/docs/NATIVE-ELEMENTS.md

@@ -2,6 +2,14 @@
 
 UI Style Kit uses a hybrid-native policy: it themes safe element boxes and exposed subparts, uses `accent-color` and `color-scheme` as fallbacks, and leaves inaccessible browser popups to the platform.
 
+The scope is `[data-ui][data-mode]`; `data-theme` is optional. Each preset supplies
+native colors and maps `--usk-native-bg` to its functional background, so the shared
+`--ui-color-bg` remains usable by companion libraries without a named theme.
+
+Native inline elements keep their page-text defaults except inside components
+that deliberately own foreground paint, such as trust seals and media scrims.
+Keep labels, status text, and semantic attributes intact when styling these surfaces.
+
 ## Classification
 
 | Classification | Elements and surfaces |
@@ -19,9 +27,9 @@ The native layer styles safely exposed parts where engines allow it:
 
 - placeholder text
 - file selector buttons, including hover, focus, active, and disabled states
-- range tracks and thumbs
+- range tracks, Firefox range progress, and thumbs
 - color swatches
-- progress and meter tracks and values
+- determinate/indeterminate progress and meter tracks and values, including optimum, suboptimum, and critical bands
 - calendar picker indicators
 - search cancellation controls
 - number spinners
@@ -33,20 +41,18 @@ The native layer styles safely exposed parts where engines allow it:
 
 Preset files map existing `--usk-native-*` roles through their active visual system. The shared native layer also defines these sizing and paint tokens:
 
-```css
---usk-native-control-min-block-size
---usk-native-control-padding-block
---usk-native-control-padding-inline
---usk-native-subcontrol-padding-block
---usk-native-subcontrol-padding-inline
---usk-native-border-width
---usk-native-field-gap
---usk-native-panel-padding
---usk-native-track
---usk-native-track-fill
---usk-native-thumb
---usk-native-thumb-border
---usk-native-indicator
-```
+| Group | Stable tokens |
+|---|---|
+| Foundation | `--usk-native-control-bg`, `--usk-native-border-width`, `--usk-native-radius-sm`, `--usk-native-radius`, `--usk-native-shadow`, `--usk-native-focus-ring`, `--usk-native-control-min-block-size`, `--usk-native-control-padding-block`, `--usk-native-control-padding-inline`, `--usk-native-subcontrol-padding-block`, `--usk-native-subcontrol-padding-inline` |
+| Choice | `--usk-native-choice-*`, `--usk-native-checkbox-radius`, `--usk-native-radio-radius` |
+| Select | `--usk-native-select-indicator-*`, `--usk-native-select-padding-inline-end` |
+| Range | `--usk-native-range-track-*`, `--usk-native-range-progress-background`, `--usk-native-range-thumb-*` |
+| Progress and meter | `--usk-native-progress-*`, `--usk-native-meter-*-background` |
+| File and color | `--usk-native-file-button-*`, `--usk-native-color-swatch-*` |
+| Indicators and scrollbars | `--usk-native-indicator-*`, `--usk-native-scrollbar-*` |
+
+Single selects consume the preset indicator with logical LTR/RTL positioning. Multiple selects deliberately suppress it. Chromium/WebKit and Firefox pseudo-elements stay in separate safe selector blocks so one unsupported vendor selector cannot invalidate another engine's paint.
+
+Platform-owned select/datalist popups, date/time and color picker dialogs, file pickers, autofill/spellcheck menus, media internals, and operating-system chrome remain native. The library themes only their exposed launch controls and indicators.
 
 Invalid paint activates only through `[aria-invalid="true"]`, `.is-invalid`, or `:user-invalid`. Required empty controls do not get danger paint before user interaction.

package/docs/NEO-NOIR.md

@@ -0,0 +1,94 @@
+# Neo Noir / Midnight Cut
+
+The existing **Neo-Noir** preset ID (neo-noir), stylesheet entrypoints and **noir-** prefix remain stable. The updated preset implements the retained Midnight Cut reference: blue-black or soft-white paper, fine grain, a diagonal corner, narrow display type, square fields, complete parallelogram action borders, diamond stages, calibrated exposure controls and semantic production states.
+
+The package remains CSS-only. The demo controller is not a runtime dependency.
+
+## Usage
+
+~~~html
+<link rel="stylesheet" href="ui-style-kit-css/visual/neo-noir.css">
+<main data-ui="neo-noir" data-mode="dark">
+  <button class="noir-button noir-button-primary">Approve</button>
+</main>
+~~~
+
+Omit data-theme for reference colors. Named schemes such as arctic-indigo override palette roles through the existing --usk-* to --noir-* aliases. Geometry remains preset-owned. In the demo, select Neo-Noir and use the specimen's **Use reference palette** button.
+
+## Component Inventory
+
+All names below use the **noir-** prefix. Existing universal classes remain supported. Preset-only additions are declared in manifest.classApi.presetExtras["neo-noir"]; no source nn-* alias layer is exported.
+
+| Group | Public component families |
+| --- | --- |
+| Identity | sheet, identity, brand-line, title, edition, subtitle, section-title, section-number |
+| 01 Navigation | breadcrumbs, tabs, tab, tab-panel, pagination, segmented, stepper-track, step, step-marker |
+| 02 Buttons | Existing button/primary/secondary/danger/ghost/icon-button; button-outline; default, hover, pressed, focus, disabled and busy |
+| 03 Forms | Existing input/select/textarea/label; field-row, file-zone, file-state; text/password/search/number/date/time/datetime-local/textarea states |
+| 04 Select | Native select; listbox, option with single selection |
+| 05 Multi-select | chips, chip; add and remove tokens |
+| 06 Controls | Existing check/check-control, radio/radio-control, switch/track/thumb; checked, selected, on/off and disabled |
+| 07 Exposure | range, slider-value, range-scale, range-legend |
+| 08 Progress | Existing progress/bar; segments, workflow, threshold, threshold-labels |
+| 09 Feedback | Existing badges and alerts; badge-review, alert-close, processing, tooltip, details |
+| 10 Table | Existing table/table-wrap; progress-cell; six production records |
+| 11 Confirmation | dialog, dialog-meta, dialog-actions; nonmodal anatomy and real native modal |
+| 12 Palette | swatches, swatch; neutral, action and semantic roles |
+| 13 Type | display-sample, alpha, mono-sample |
+| 14 Geometry | geometry-row, shape, line-samples, texture-sample |
+| 15 Accessibility | ratio, focus-sample, color-safe, existing sr-only |
+| Retained utilities | metric, metric-label, metric-value, empty-state |
+
+## State and Controller Contract
+
+- aria-selected and roving tabindex control tabs/options. Each tab points to an associated panel. Arrow keys, Home and End work alongside pointer activation. The native select and expanded listbox remain synchronized.
+- aria-current="page" marks pagination; aria-current="step" marks the diamond workflow stage. Segmented controls and workflow buttons use aria-pressed.
+- Native disabled, aria-invalid="true" and aria-busy="true" communicate control states. Pair application errors with descriptions. The specimen uses visible Default/Focus/Success/Error/Disabled labels rather than color alone.
+- data-noir-state="hover|pressed|focus|success" freezes reference states for inspection. Real hover, active and focus selectors work independently.
+- File rows use data-status="success|error|locked". File zones wrap real inputs and accept drops. The demo reads only file name and size and does not upload content.
+- Set --noir-value to a percentage for the range flag and meter indicator. Keep the native range and output synchronized. Exposure runs from -5 to +5 in 0.1 increments.
+- .is-done marks completed segments. Provide progressbar/meter semantics and explicit safe/caution/critical meaning. Omitting aria-valuenow selects indeterminate progress.
+- Modal actions use showModal(), native Escape/cancel and focus return. Approval changes only sample state. Icon actions report their selected command without editing or sending real production data.
+- Name scrollable table regions and make them keyboard focusable. Connect tooltips with aria-describedby.
+- Narrow/coarse-pointer targets expand to 44px. Reduced motion stops processing/progress animations. Contrast mode removes textures. Contrast-ratio labels are targets, not certification of arbitrary consuming content.
+
+## Tokens and Assets
+
+| Role | Light reference | Dark reference |
+| --- | --- | --- |
+| Paper | #f2f1ed | #070d11 |
+| Surface | #f8f7f3 | #080f14 |
+| Text | #101417 | #ddd6c7 |
+| Primary action | #f1c35e | #f2bd4b |
+| Focus signal | #159eb4 | #36b8c8 |
+| Review foreground | #68438f | #ae7adb |
+
+Small semantic foregrounds and muted copy are strengthened from the original pigments for readable contrast. Named themes still control semantic colors.
+
+Four supplied raster files are retained unchanged in styles/assets/neo-noir-{texture,corner}-{light,dark}.png. The build copies them into dist/assets; focused stylesheets rebase URLs to ../assets. Keep these asset directories when self-hosting CSS. Grain is composited at low opacity instead of displaying its raw black-and-white pixels as a surface.
+
+Source provenance: the explicitly requested artifact-template-neo-noir skill's references/source assets, design guide and specimen, with its paired 3072x2048 references. Icons are retained Lucide SVGs under demo/assets/lucide with its license.
+
+## Demo and Fidelity
+
+All 15 groups are present at once for Neo-Noir; retained utility examples follow the board. The renderer returns no Neo Noir specimen for other styles. Existing data-preset-only regions remain governed by the shared all-preset visibility controller.
+
+The PNG's component arrangement is the target, not the simplified browser capture. Intentional adaptations include native localized date/time controls, stronger semantic text, installed system font fallbacks, extra source field states, real keyboard/modal behavior and responsive reflow instead of scaling or clipping the entire sheet. Desktop spacing is compact; narrow layouts retain controls and scroll only the dense table. These changes are not a claim of pixel-identical raster reproduction.
+
+Implementation is split between styles/neo-noir.css (public components), demo/demo.css (composition), and demo/demo-neo-noir.js (example controller). No unrelated preset material was redesigned.
+
+## Local Verification
+
+The annotation refinements retain the existing component API: loaders use a fixed registration ring with rotating aperture segments (and a dashed-ring fallback), directional tooltip modifiers expose external pointers, the service star is 28px inside its unchanged 60px medallion, and the callout uses a centered Lucide arrow. The 80px seal uses a 28px number and 13px label. Reduced motion stops the aperture blades and busy-control indicators. These refinements are scoped to Neo Noir.
+
+The focused `tests/e2e/neo-noir-annotations.spec.js` checks geometry, tooltip directions, animated versus reduced-motion loaders, and light/dark/mobile captures. Annotation images are written to the system temporary directory as `noir-annotations-*.png`.
+
+The follow-up refinements use octagonal medallions and seals at the same dimensions, remove rectangular paint behind skewed button states, and give explicit rounding utilities 8/12/16px corners. The demo selectors retain one native indicator. Native checkboxes use a centered angular check, with hidden custom-choice inputs excluded. The exposure handle is 24px wide with a center index; keep `--noir-position` (0 to 1) synchronized with `--noir-value` (percentage) so its value flag follows native thumb travel. The ruler retains eleven evenly spaced labels. `tests/e2e/neo-noir-refinements.spec.js` covers these changes, keyboard behavior, and responsive screenshots.
+
+Focused unit tests cover the independent API inventory and portable asset URLs. Focused browser tests cover 15-group coverage, all 20 presets' isolation, light/dark/contrast accessibility, 1920/1115/602/390px geometry, aligned controls, keyboard navigation, live range values, safe tag text, upload feedback, modal lifecycle, palette switching and reduced motion.
+
+Browser captures are written to the local temporary directory usk-neo-noir. Rebuild before browser checks because the demo loads generated distribution CSS. Local checks do not imply a full CI run, commit, publication or deployment.
+
+The build now content-versions local CSS and JavaScript URLs in both demo entrypoints, including the default/bridge switch URLs. Reload the HTML page after a rebuild to pick up these URLs; already-open pages do not hot-reload. Native Neo Noir dialogs have 20px inner padding. The dark-mode annotation regression checks the full button matrix, single dropdown indicators, octagonal badges and dialog insets.
+
+The focused Neo Noir checks pass locally, including interaction runs in Chromium, Firefox and WebKit. The broader public-API manifest test currently fails on unrelated Tactile workspace classes absent from that preset's manifest entry; that work was left untouched. Intermittent Windows write errors occurred during builds, followed by successful completed retries.

package/docs/ORGANIC-MODERN.md

@@ -0,0 +1,91 @@
+# Organic Modern
+
+The September 2026 Organic template is implemented with public `organic-*`
+classes. Cormorant Garamond display type and DM Sans interface type are bundled
+locally under their SIL Open Font Licenses. Shape, typography, and material
+treatment remain unchanged when a color scheme is selected.
+
+## Palette Contract
+
+```html
+<!-- Original limestone palette; omit data-theme entirely. -->
+<body data-ui="organic-modern" data-mode="light">
+
+<!-- Original forest-dark palette. -->
+<body data-ui="organic-modern" data-mode="dark">
+
+<!-- Shared theme paints canvas, panels, controls, text, borders, and feedback. -->
+<body data-ui="organic-modern" data-theme="arctic-indigo" data-mode="dark">
+```
+
+Preset roles resolve `--usk-*-rgb` first, then `--organic-fallback-*-rgb`.
+Live shared RGB overrides work without changing component selectors. Use a valid
+manifest theme ID or omit the attribute; an empty string is not a theme ID.
+The existing high-contrast mode remains supported. The secondary button uses the
+raised-surface/text pair, matching the reference rather than a saturated fill.
+Original dark destructive text is white instead of warm ivory to meet 4.5:1.
+
+## Component Map
+
+| Source Design Family | Public Classes |
+| --- | --- |
+| Masthead and identity | `organic-masthead`, `organic-brand`, `organic-icon`, `organic-search`, `organic-avatar` |
+| Project selection | `organic-project-list`, `organic-project-item` |
+| Status and people | `organic-status-card`, `organic-score`, `organic-avatar-row` |
+| Editorial imagery | `organic-photo`, `organic-hero-card`, `organic-hero-overlay`, `organic-quote-card` |
+| Materials and metrics | `organic-materials`, `organic-material`, `organic-material-image`, `organic-impact`, `organic-performance` |
+| Schedule and notices | `organic-table`, `organic-table-wrap`, `organic-notices`, `organic-notice` |
+| Add-material form | `organic-add-material`, `organic-field`, `organic-input-grid`, `organic-dialog-actions` |
+| Control laboratory | `organic-control-lab`, `organic-section-heading`, `organic-button-grid` |
+| Actions | `organic-button` with `-primary`, `-secondary`, `-outline`, `-danger`; `organic-icon-button` |
+| Fields | `organic-input`, `organic-textarea`, `organic-select`, `organic-input-action`, `organic-file-drop` |
+| Multi-select and menu | `organic-token-input`, `organic-token`, `organic-expanded-select`, `organic-option` |
+| Choices | Native checkbox/radio/switch; existing `organic-check`, `organic-radio`, `organic-switch` APIs retained |
+| Progress | `organic-range`, `organic-value`, `organic-progress`, `organic-progress-bar`, `organic-progress-steps`, native meter |
+| Navigation | `organic-tabs`, `organic-tab`, `organic-pagination`, `organic-segmented` |
+| Quantity and feedback | `organic-stepper`, `organic-badge`, `organic-alert`, `organic-spinner`, `organic-tooltip` |
+| Dialog | `organic-dialog`, `organic-dialog-actions` |
+
+All additions are registered in `manifest.json`. Existing semantic aliases such
+as `.ui-card` and `.ui-button` receive the updated visual treatment automatically.
+The JavaScript in `demo/demo-organic.js` is specimen behavior, not a runtime
+dependency of the CSS library. Consumers own application state and persistence.
+
+## Source Adaptation
+
+The source is a fixed 1536 x 1024 export board, not a responsive application.
+The implementation keeps its component geometry and visual roles while using
+readable 12-14px controls and intrinsic height. The three-zone layout reflows into
+two columns, then one, instead of scaling all text into a fixed-size screenshot.
+
+Only photographic regions of the supplied board are shown through clipped image
+windows in the demo. No screenshot pixels stand in for controls or interface text.
+The hero uses the unobstructed photographic region, so its framing differs from
+the complete reference image. The original individual photographs were not
+provided. All example project names and metrics are fictional demonstration data.
+
+The specimen uses bundled Phosphor regular SVG icons under their MIT license.
+`scripts/build.mjs` embeds these into `demo/demo-organic-icons.js` so local-file
+and HTTP demos behave alike. The retained board is `demo/assets/organic-reference-light.png`.
+Fonts and their licenses ship in `styles/assets` and `dist/assets`; focused
+distribution paths are rebased by the existing build pipeline.
+
+## Annotation Refinements
+
+Standalone and busy-button loaders share a veined Phosphor leaf with a gentle
+sway. Reduced-motion preferences disable the animation. The embedded SVG mask
+works without a network request; its MIT license ships as
+`assets/organic-icons-LICENSE.txt` alongside the library assets.
+
+Marketing medallions use centered SVG icons, with a larger service star and
+30px/14px seal labels. Outline-heavy actions have uniform themed borders.
+Prefixed and semantic tables share a tinted sans-serif header, horizontal rules,
+and a left-aligned caption. Demo toolbar selects show one custom chevron.
+
+## Verification Evidence
+
+Focused tests cover public class coverage and isolation, both fallback palettes,
+20 themes across light/dark/contrast, live RGB overrides, keyboard/native control
+behavior, responsive screenshots, local asset loading, and scoped accessibility.
+Supplied template QA is historical evidence only; see the repository QA log for
+fresh implementation results.

package/docs/PAPER-EDITORIAL.md

@@ -0,0 +1,63 @@
+# Paper Editorial
+
+The Paper Editorial preset translates the retained **Pressroom Field Manual** template into the canonical `paper-*` API. It preserves the current eleven-folio reference composition, not the older twelve-panel distressed alternative.
+
+## Reference Contract
+
+- Source: the retained `artifact-template-paper-editorial` design guide, stylesheet, specimen HTML, and dark/light reference boards.
+- Square controls, thin printed rules, oxblood editorial identity, blue revision/focus states, serif content, sans-serif labels, and monospaced metadata.
+- Binder rail, manual metadata, oversized masthead, property stamp, circular revision stamp, and a numbered section index.
+- Original dark/light paper-fiber PNG tiles are embedded in CSS. This keeps source, focused, and combined bundles portable without path rebasing. A consumer CSP must permit `data:` images to show the optional texture.
+
+## Component Coverage
+
+| Folio | Public components and examples |
+| --- | --- |
+| 1 | Navigation, breadcrumb, tabs, pagination |
+| 2 | Primary/secondary/destructive action states, icon actions, loading and text buttons |
+| 3 | Inputs, search and input icon, textarea, upload, date/time, validation and disabled states |
+| 4 | Grouped native select, removable chips, checkboxes and radio buttons |
+| 5 | Switches and keyboard-focus states |
+| 6 | Ruler, range slider, measurement output and secondary ranges |
+| 7 | Progress, threshold meter, workflow stages and loading indicator |
+| 8 | Semantic badges, dismissible alerts, skeletons and tooltip |
+| 9 | Revision form, modal dialog, empty state, token swatches, metric, disclosure and popover |
+| 10 | Dense records table and CSV export |
+| 11 | Article deck, byline, drop cap, pull quote, marginalia, footnote and segmented control |
+
+The manifest is the authoritative class inventory. Template `pe-*` selectors are translated, not exposed as aliases. The ruled module uses `paper-folio-section` because `paper-section` remains a deprecated structural-layout selector. Existing common components continue to appear in the shared demonstration below the specimen.
+
+## Tokens And Modes
+
+Use `data-ui="paper-editorial"` with `data-mode="light"`, `dark`, or `contrast`. Omit `data-theme` for the preset reference palette; set it to a supported named theme to recolor the preset through `--usk-*` tokens.
+
+`--paper-sheet-*` material aliases resolve through the existing `--paper-*` semantic aliases. Primary/background and foreground pairs remain coupled. Contrast-safe status inks replace low-contrast reference text without discarding the reference color roles. The demo's **Use reference palette** control removes the named-theme override; it does not change the mode.
+
+For a Chromium range fill, set `--paper-slider-value` to the current percentage on `.paper-slider` and update it with the input value. Firefox uses its native range-progress pseudo-element. The demo updates all slider fills locally.
+
+## Interaction And Accessibility
+
+The demo provides roving keyboard focus for tabs and segmented controls, range-key input, local tag addition/removal, alert dismissal, table filtering/export, file selection, native modal Escape/focus return, and local revision confirmation. No newsroom backend is contacted and selected files are not uploaded.
+
+Controls have labels; icon actions have accessible names and tooltips. Status copy supplements color. Reduced motion suppresses loaders and skeleton animation; coarse-pointer controls receive 44px targets. The reference board reflows on narrow screens, with bounded scrolling for dense tables and the button-state matrix.
+
+The specimen is rendered only for Paper Editorial. The shared preset-visibility contract hides every non-owning `data-preset-only` region across all presets.
+
+## Verification
+
+Focused tests live in `tests/paper-editorial-template.test.js` and `tests/e2e/paper-editorial-template.spec.js`. They cover the component inventory, reference materials, dark/light accessibility, native/legacy loader consistency, token switching, keyboard behavior, modal behavior, mobile containment, and all-preset visibility.
+
+Browser screenshots are captured from the rebuilt distribution, not the retained source package. The supplied source QA report is historical evidence only. Native date, time, select, file, and meter rendering may differ by browser; responsive reflow and contrast corrections are intentional departures from a static bitmap.
+
+### Local Verification, 2026-09-05
+
+- Component inventory unit test and all four focused Chromium cases passed, run individually.
+- Dark/light specimen axe checks and named-theme axe passed. Keyboard, Escape/focus return, tag removal, slider updates, and 602px/390px containment passed.
+- Every manifest preset was selected to verify non-owning preset-specific regions remain hidden.
+- Class API passed. Public API passed after resolving the deprecated `paper-section` collision; only that failed subsection was rerun.
+- Updated declaration fingerprints and partial-extra inventory checks passed. The existing authored semantic-hook assertion still fails on unrelated Retrofuturism `.ui-*` aliases; it was not relaxed or repaired here.
+- Lint, contrast (1,200 named-theme states and 60 fallbacks), compatibility (26 entrypoints), ownership, package integrity, and `git diff --check` passed.
+- Final distribution generation completed using the existing build module. Windows repeatedly blocked rewriting `styles/content-overflow.css`; an invocation-local guard skipped that one write only after proving its existing bytes exactly matched the generator output. No generator or build source was changed for this workaround. A plain `npm.cmd run build` remains subject to that local file-lock condition.
+- Screenshots: `%TEMP%/usk-paper-editorial-template/dark.png`, `light.png`, and `mobile.png`.
+
+No full test suite, CI, commit, push, publication, or deployment was run as part of this Paper Editorial change.

package/docs/PUBLISHING.md

@@ -1,10 +1,23 @@
 # Publishing Guide
 
-## 2.3.0 release workflow
+## 2.4.0 release workflow
 
-Prepare `ui-style-kit-css@2.3.0` on its release branch, open a pull request against `main`, and merge only after the complete gate is green. The aligned companion set is `layout-style-css@3.1.0` and `interactive-surface-css@1.6.0`.
+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.
 
-Do not push `v2.3.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.
+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
 
@@ -12,23 +25,29 @@ Do not push `v2.3.0` before the reviewed release commit is on `main`. A pushed v
 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: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 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.3.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.
+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.
 
-`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. Browser gates cover regular demo flows, representative Axe scans, curated visual checks, and the sharded 3,600-combination matrix. `npm run check:ecosystem:packs` verifies standalone, pairwise, and all-three packed package compatibility 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.
+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.3.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.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`.
+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 `afcb1fdf70d4635e35739e621ee1598400fed103`.
+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:
 
@@ -57,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, push or dispatch the matching package tag, such as `v2.3.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.
+`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
 
@@ -67,4 +88,4 @@ npm run release:minor
 npm run release:major
 ```
 
-Use patch for compatible fixes, minor for new themes, presets, component capabilities, or browser-support contracts, and major for incompatible public API changes. The nine additional presets, ten additional schemes, universal component vocabulary, and compatibility contract make `2.3.0` a minor release.
+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.