ui-style-kit-css 2.0.4 → 2.2.0

package/CHANGELOG.md

@@ -2,6 +2,45 @@
 
 All notable changes to **UI Style Kit CSS** will be documented here.
 
+## [Unreleased]
+
+## [2.2.0] - 2026-08-09
+
+### Added
+
+- Added the public 12-token shared semantic producer contract and its machine-readable manifest inventory for companion and third-party consumers.
+- Implemented the manifest-backed semantic component API with 29 exact `.ui-*` selectors, context-constrained `data-ui-variant` values, and unchanged-markup runtime switching across all 11 presets.
+- Added a persistent semantic component demo whose DOM nodes and classes remain stable through every preset switch.
+- Documented native `<dialog>` as the neutral modal/dialog fallback without inventing `.ui-modal` or `.ui-dialog` selectors.
+
+### Changed
+
+- Clarified that generated default, visual, with-bridge, and focused entrypoints provide semantic aliases, while raw preset sources, partial extras, and deprecated structural aliases remain prefixed compatibility or advanced APIs.
+- Preserved `.ui-spinner` and `.ui-tooltip` as retained hooks while generating the other 27 selectors from existing preset declarations.
+
+## [2.1.0] - 2026-07-20
+
+### Added
+
+- Added visual-only full, minified, and focused preset entrypoints for applications that own their structural layout.
+- Added `manifest.json` with preset entrypoints, themes, modes, composed class capabilities, deprecated structural suffixes, and native-part ownership classifications.
+- Added a canonical `interactive-surface-theme.css` bridge that supplies public tokens and paint while leaving interaction mechanics to `interactive-surface-css/state-core.css`.
+- Added CSS Tree AST contract coverage for generated class retention, export targets, cascade layers, and bridge ownership boundaries.
+- Added exact `@axe-core/playwright` representative scans and a sharded 990-combination UI matrix across presets, themes, modes, and browser engines.
+- Added manifest-backed demo control data and real `showModal()` dialog coverage for themed native backdrop behavior.
+
+### Changed
+
+- Rebuilt combined output around the ordered `theme_colors`, `native_elements`, `components`, `presets`, and `compat_layout` layers.
+- Moved shared component foundations into `components` and isolated retained prefixed structural helpers in `compat_layout`.
+- Formatted generated CSS through Lightning CSS and pinned `css-tree` exactly for deterministic AST partitioning.
+- Increased native and custom checkbox/radio targets to the WCAG 2.2 24px minimum and tightened demo accessibility semantics.
+
+### Deprecated
+
+- Deprecated the `page`, `container`, `section`, `grid`, `stack`, `cluster`, and `split` prefixed structural suffixes for removal in v3.
+- Deprecated the stateful `interactive-surface-bridge` and `with-bridge` integration paths while preserving their existing behavior.
+
 ## [2.0.4] - 2026-07-20
 
 ### Added

package/README.md

@@ -9,13 +9,13 @@ It is separate from, but complementary to, **Interactive Surface CSS**. Use **UI
 
 ## Current Release
 
-`v2.0.4` is the current v2 correctness patch. It adds parser-based minification, restores valid native file-button and modal-backdrop styling, routes status foregrounds through semantic `on-*` tokens, and retains the shared content-overflow and responsive coverage work without changing the CSS API.
+`v2.2.0` adds the shared 12-token semantic producer contract and a manifest-backed 29-selector `.ui-*` component API across all 11 presets. Existing default and focused entrypoints remain compatible, including their deprecated structural helpers, and parser-based minification remains exactly pinned.
 
 [Showcase website](https://foscat.github.io/ui-style-kit-css/)
 
 ## How the library fits together
 
-UI Style Kit CSS owns visual identity: themes, component paint, native HTML styling, and the prefixed class API. It can be used alone, or paired with the sibling libraries when a project needs structural layout primitives or richer interaction-state behavior.
+UI Style Kit CSS owns visual identity: themes, semantic `.ui-*` component paint, native HTML styling, and the advanced prefixed class API. It can be used alone, or paired with the sibling libraries when a project needs structural layout primitives or richer interaction-state behavior.
 
 ```mermaid
 flowchart LR
@@ -50,12 +50,18 @@ These libraries stay standalone, but the current aligned set is:
 
 | Library | Aligned version | Owns |
 |---|---:|---|
-| `ui-style-kit-css@2.0.4` | source release target | visual identity, color themes, UI paint, native HTML styling, content wrapping, and bridge tokens |
-| `interactive-surface-css@1.3.0` | latest published sibling | interaction-state primitives, surface behavior, state layers, and input affordances |
-| `layout-style-css@1.1.2` | latest published sibling | structural wrappers, grids, sections, app shells, and layout recipes |
+| `ui-style-kit-css@2.2.0` | current package version | visual identity, color themes, UI paint, native HTML styling, content wrapping, and bridge tokens |
+| `interactive-surface-css@1.6.0` | published release | interaction-state primitives, surface behavior, state layers, and input affordances |
+| `layout-style-css@3.0.1` | published release | structural wrappers, grids, sections, app shells, and layout recipes |
+
+The current combination is `ui-style-kit-css@2.2.0`, `interactive-surface-css@1.6.0`, and `layout-style-css@3.0.1`. UI Style Kit `2.2.0` is the current package version, and the release pipeline treats it as the active candidate only while that exact npm version is absent. Interactive Surface `1.6.0` and Layout Style `3.0.1` are published releases. The validated minimum remains `ui-style-kit-css@2.1.0`, `interactive-surface-css@1.5.0`, and `layout-style-css@3.0.0`.
 
 Use one, two, or all three depending on the project. UI Style Kit does not require the sibling libraries, and the optional bridge only maps shared `--usk-*` roles into Interactive Surface tokens when consumers import it.
 
+Every UI Style Kit visual or preset entrypoint also publishes a small, fully typed `--ui-*` semantic handshake. These tokens let companion libraries and third-party themes share paint, control geometry, focus, and default motion without depending on preset-specific names. They are optional fallbacks for consumers: package-specific tokens still take precedence, and standalone packages keep their existing legacy and literal defaults when the handshake is absent. See the [token contract](docs/TOKENS.md#shared-semantic-token-handshake) for the exact 12-token inventory.
+
+A third-party producer can load its semantic token stylesheet before `interactive-surface-css/standalone-preset.css`. UI Style Kit's visual entrypoints support the same portable composition; keep the canonical theme bridge with `state-core.css` when specialized variant, level, and icon-role mappings are required.
+
 For import order, ownership boundaries, and adoption paths, see the [Ecosystem guide](docs/ECOSYSTEM.md).
 
 ## Features
@@ -64,6 +70,8 @@ For import order, ownership boundaries, and adoption paths, see the [Ecosystem g
 - 10 shared color schemes
 - `light`, `dark`, and `contrast` modes
 - Combined CSS bundle and per-style production imports
+- Visual-only full and focused entrypoints for consumer-owned layouts
+- Machine-readable `manifest.json` preset, theme, mode, class, and native-part capabilities
 - Shared `theme-colors.css`, `native-elements.css`, and `content-overflow.css` layers for all UI systems
 - Scoped native HTML element coverage, including semantic containers and inline text elements
 - Visible `:focus-visible` defaults
@@ -72,7 +80,8 @@ For import order, ownership boundaries, and adoption paths, see the [Ecosystem g
 - Theme-driven card, panel, control, page-background, and spinner defaults
 - Visible tooltip classes and native `[role="tooltip"]` styling inside each UI scope
 - Font-family override variables for body, headings, controls, and mono text
-- Optional bridge tokens, visible state layers, and an opt-in bridge bundle for `interactive-surface-css`
+- Canonical token-and-paint-only theme bridge for `interactive-surface-css/state-core.css`
+- Deprecated stateful bridge exports retained for backward compatibility
 - Reduced-motion, high-contrast, forced-colors, and print support
 - Cascade-layered CSS for easier consumer overrides
 - No runtime dependencies
@@ -83,50 +92,69 @@ For import order, ownership boundaries, and adoption paths, see the [Ecosystem g
 npm install ui-style-kit-css
 ```
 
+### v2 distribution defaults
+
+The default bundle remains unchanged for all v2 releases. The root package and canonical `.` export resolve to the readable `dist/ui-style-kit.css`; the canonical `./min.css` export resolves to the minified `dist/ui-style-kit.min.css`. The focused `visual/<preset>.css` entrypoints remain available for applications fixed to one visual system.
+
+`ui-style-kit-css/visual.css` is the recommended entrypoint when consumers own layout. Making `visual.css` the package default remains only a v3 proposal; no v2 export is redirected as part of that proposal.
+
+The `./css`, `./css.css`, and `./min` exports are redundant deprecated compatibility aliases. They remain available throughout v2 with their existing targets: `./css` and `./css.css` match `.`, while `./min` matches `./min.css`. New integrations should use the canonical exports.
+
 ## Import
 
-Use a single style import for production apps that use one visual system:
+Use the generated default bundle for semantic components that can switch across every preset at runtime:
 
 ```js
-import "ui-style-kit-css/minimal-saas.css";
+import "ui-style-kit-css";
 ```
 
-In `v2.0.4`, standalone style files import the shared color-scheme layer from `styles/theme-colors.css`, the shared native-element fallback layer from `styles/native-elements.css`, and the shared content-overflow layer from `styles/content-overflow.css`. Bundlers that understand CSS `@import` will resolve them automatically. If your build pipeline does not resolve CSS imports, import the shared dependencies before the style file:
+Use `ui-style-kit-css/visual.css` for the same 29-selector semantic runtime API without the deprecated prefixed layout selectors. The generated default, visual, and with-bridge bundles all support all 11 `data-ui` values.
+
+Applications fixed to one preset can use a generated focused visual entrypoint. It includes semantic aliases scoped to that preset only:
 
 ```js
-import "ui-style-kit-css/theme-colors.css";
-import "ui-style-kit-css/native-elements.css";
-import "ui-style-kit-css/content-overflow.css";
-import "ui-style-kit-css/minimal-saas.css";
+import "ui-style-kit-css/visual/minimal-saas.css";
 ```
 
-The longer `styles/*` paths are also exported:
+The exact preset, theme, mode, class, and native-part capability matrix is available from `ui-style-kit-css/manifest.json`.
+
+### Advanced prefixed and raw imports
+
+The standalone preset exports and longer `styles/*` paths remain advanced compatibility entrypoints. They preserve the prefixed API and do not promise multi-preset semantic switching:
 
 ```js
+import "ui-style-kit-css/minimal-saas.css";
+// Equivalent raw source export:
 import "ui-style-kit-css/styles/minimal-saas.css";
-import "ui-style-kit-css/styles/cyberpunk.css";
 ```
 
-Use the full bundle when users need to switch `data-ui` systems at runtime:
+In `v2.1.0`, legacy standalone style files continue to import the shared color-scheme, native-element fallback, and content-overflow layers. Bundlers that understand CSS `@import` resolve them automatically. If your build pipeline does not resolve CSS imports, import the shared dependencies before the style file:
 
 ```js
-import "ui-style-kit-css/dist/ui-style-kit.css";
+import "ui-style-kit-css/theme-colors.css";
+import "ui-style-kit-css/native-elements.css";
+import "ui-style-kit-css/content-overflow.css";
+import "ui-style-kit-css/minimal-saas.css";
 ```
 
-Use the opt-in bridge bundle when you want UI Style Kit CSS and the Interactive Surface bridge in one import:
+The explicit distribution path is also available for runtime switching:
 
 ```js
-import "ui-style-kit-css/with-bridge.css";
+import "ui-style-kit-css/dist/ui-style-kit.css";
 ```
 
-Or import the bridge by itself when you are using a single style file:
+For the canonical all-three integration, import visual paint, the token-only theme bridge, Interactive Surface state mechanics, and Layout structure in this order:
 
 ```js
-import "ui-style-kit-css/minimal-saas.css";
-import "ui-style-kit-css/interactive-surface-bridge";
+import "ui-style-kit-css/visual.css";
+import "ui-style-kit-css/interactive-surface-theme.css";
+import "interactive-surface-css/state-core.css";
+import "layout-style-css";
 ```
 
-The default full bundle does **not** include the bridge. That keeps `dist/ui-style-kit.css` focused on UI systems and prevents accidental duplicate bridge imports.
+The older stateful bridge and combined bundle remain public, deprecated compatibility paths. See the [bridge migration guide](docs/BRIDGE-MIGRATION.md) when upgrading an existing v2 integration.
+
+The default and visual-only bundles do **not** include either bridge. That keeps UI paint independent and prevents accidental duplicate bridge imports.
 
 When the bridge is attached, add `.interactive-surface` to interactable elements and use `data-surface-variant` plus `data-surface-level="1"`, `"2"`, or `"3"` to opt into the visible rest, hover, active, and focus treatments. The bridge inherits from shared `--usk-*` roles instead of duplicating per-theme or per-preset token maps.
 
@@ -134,11 +162,13 @@ When the bridge is attached, add `.interactive-surface` to interactable elements
 
 | Import | Raw | Gzip | Best for |
 |---|---:|---:|---|
-| `ui-style-kit-css/dist/ui-style-kit.min.css` | ~271 KB | ~35 KB | Runtime UI-system switchers and demos |
-| `ui-style-kit-css/with-bridge.css` | ~339 KB | ~40 KB | Runtime switchers plus Interactive Surface bridge |
+| `ui-style-kit-css/dist/ui-style-kit.min.css` | ~357 KB | ~44 KB | Compatible runtime UI-system switchers and demos |
+| `ui-style-kit-css/visual.min.css` | ~348 KB | ~43 KB | Runtime visual switching with consumer-owned layout |
+| `ui-style-kit-css/with-bridge.css` | ~431 KB | ~52 KB | Deprecated runtime switcher plus stateful bridge |
 | `ui-style-kit-css/theme-colors.css` | ~25 KB | ~3 KB | Shared color schemes for standalone style imports |
-| `ui-style-kit-css/native-elements.css` | ~13 KB | ~2 KB | Shared native HTML fallback styling |
+| `ui-style-kit-css/native-elements.css` | ~22 KB | ~4 KB | Shared native HTML fallback styling |
 | `ui-style-kit-css/content-overflow.css` | ~7 KB | ~1 KB | Shared long-text containment for standalone style imports |
+| `ui-style-kit-css/interactive-surface-theme.css` | ~8 KB | ~1 KB | Canonical token-and-paint bridge for Interactive Surface state core |
 | Single style imports | ~26-28 KB | ~5-6 KB | Production apps with one visual system |
 
 ## CDN usage
@@ -149,25 +179,23 @@ Use the latest published NPM package:
 <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/ui-style-kit-css@latest/dist/ui-style-kit.min.css" />
 ```
 
-For production today, pin the latest published patch. Update this pin to `2.0.4` after that release is published:
+For production, pin the exact approved release rather than relying on `latest`:
 
 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/ui-style-kit-css@2.0.3/dist/ui-style-kit.min.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/ui-style-kit-css@2.2.0/dist/ui-style-kit.min.css" />
 ```
 
 ## Basic usage
 
 ```html
 <body data-ui="minimal-saas" data-theme="arctic-indigo" data-mode="light">
-  <main class="saas-page">
-    <section class="saas-container saas-stack">
-      <article class="saas-card">
-        <h1 class="saas-title">UI Style Kit CSS</h1>
-        <p class="saas-subtitle">Switch UI systems, themes, and modes with attributes.</p>
-        <button class="saas-button saas-button-primary">Primary Action</button>
-        <span class="saas-spinner" aria-label="Loading"></span>
-      </article>
-    </section>
+  <main>
+    <article class="ui-card">
+      <h1>UI Style Kit CSS</h1>
+      <p>Switch UI systems, themes, and modes without changing component classes.</p>
+      <button class="ui-button" data-ui-variant="primary">Primary Action</button>
+      <span class="ui-spinner" role="status" aria-label="Loading"></span>
+    </article>
   </main>
 </body>
 ```
@@ -180,6 +208,47 @@ document.body.dataset.theme = "midnight-gold";
 document.body.dataset.mode = "dark";
 ```
 
+This changes the semantic components' visual preset without replacing their DOM nodes or rewriting their `.ui-*` classes.
+
+## Semantic component API
+
+`manifest.json#semanticComponentApi` is the authoritative specification for the implemented generic component API. Its 29 selectors keep the same class names while `data-ui` changes across all 11 presets. `implementationStatus` records the two retained `.ui-spinner` and `.ui-tooltip` hooks, the 27 generated semantic aliases, and an empty pending set.
+
+| Role | Generic selectors | Switching coverage |
+|---|---|---|
+| Buttons | `.ui-button`, `.ui-icon-button` | all 11 presets |
+| Card | `.ui-card` | all 11 presets |
+| Forms | `.ui-field`, `.ui-label`, `.ui-help-text`, `.ui-input`, `.ui-select`, `.ui-textarea` | all 11 presets |
+| Choice controls | `.ui-check`, `.ui-check-control`, `.ui-radio`, `.ui-radio-control`, `.ui-switch`, `.ui-switch-track`, `.ui-switch-thumb` | all 11 presets |
+| Badge | `.ui-badge` | all 11 presets |
+| Alert | `.ui-alert`, `.ui-alert-title`, `.ui-alert-body` | all 11 presets |
+| Navigation | `.ui-nav`, `.ui-nav-link` | all 11 presets |
+| Table | `.ui-table`, `.ui-table-wrap` | all 11 presets |
+| Progress | `.ui-progress`, `.ui-progress-bar` | all 11 presets |
+| Toolbar | `.ui-toolbar` | all 11 presets |
+| Existing generic hooks | `.ui-spinner`, `.ui-tooltip` | all 11 presets |
+
+The only new attribute is context-constrained `data-ui-variant`. Omit it for the neutral treatment.
+
+| Selector | `data-ui-variant` values |
+|---|---|
+| `.ui-button` | `primary`, `secondary`, `danger`, `ghost` |
+| `.ui-badge` | `primary`, `secondary`, `success`, `warning`, `danger` |
+| `.ui-alert` | `success`, `warning`, `danger` |
+
+```html
+<body data-ui="minimal-saas" data-theme="arctic-indigo" data-mode="light">
+  <button class="ui-button" data-ui-variant="primary">Save</button>
+  <article class="ui-card">...</article>
+</body>
+```
+
+Modal and dialog roles deliberately use a neutral native `<dialog>` fallback. There is no `.ui-modal` or `.ui-dialog` selector. The semantic API also does not define `data-ui-state`, `data-ui-size`, or `data-ui-placement`; continue to use native and ARIA state hooks, `.is-active`, and `[data-ui-tooltip-anchor]` where supported.
+
+Preset-prefixed classes remain supported compatibility and advanced APIs. Partial preset extras, typography and paint utilities, surface/size/placement helpers, shape and accessibility utilities, and the deprecated `page`, `container`, `section`, `grid`, `stack`, `cluster`, and `split` structural aliases remain prefix-bound rather than entering the generic contract.
+
+For example, a fixed Minimal SaaS integration may continue to use `<button class="saas-button saas-button-primary">`. Prefer `.ui-button` plus `data-ui-variant="primary"` when markup must survive runtime preset changes.
+
 ## UI systems
 
 | UI style | `data-ui` | Class prefix | Best for |
@@ -244,6 +313,8 @@ CSS improves accessibility presentation, but it cannot guarantee accessibility b
 
 Semantic text utilities such as `saas-text-primary`, `saas-text-warning`, and `saas-text-danger` use the active theme palette directly. Filled UI such as buttons, badges, and busy states use compact `on-*` aliases like `--saas-on-primary` and `--saas-on-danger`.
 
+For the full native-element and subpart support contract, including platform-owned picker and popup limitations, see [Native Element Coverage](docs/NATIVE-ELEMENTS.md).
+
 ## Loading states
 
 Every style includes theme-driven spinner utilities:
@@ -290,6 +361,8 @@ Override `--<prefix>-font-sans` and `--<prefix>-font-display` for the broadest c
 
 The library styles are wrapped in `@layer ui-style-kit.*`. Unlayered consumer CSS can override the library without specificity fights:
 
+The declared order is `theme_colors`, `native_elements`, `components`, `presets`, then `compat_layout`. Visual-only entrypoints leave the final compatibility layer empty of deprecated structural selectors.
+
 ```css
 [data-ui="minimal-saas"][data-theme="arctic-indigo"] {
   --saas-radius-md: 1rem;
@@ -314,6 +387,7 @@ The color model is intentionally small: shared `--usk-*` RGB variables feed pref
 ```txt
 ui-style-kit-css/
   package.json
+  manifest.json
   README.md
   LICENSE
   CHANGELOG.md
@@ -321,11 +395,18 @@ ui-style-kit-css/
   dist/
     ui-style-kit.css
     ui-style-kit.min.css
+    ui-style-kit.visual.css
+    ui-style-kit.visual.min.css
     ui-style-kit.with-bridge.css
     ui-style-kit.with-bridge.min.css
+    visual/
+      minimal-saas.css
+      ...
   styles/
     theme-colors.css
     native-elements.css
+    components.css
+    compat-layout.css
     content-overflow.css
     minimal-saas.css
     bento.css
@@ -338,6 +419,7 @@ ui-style-kit-css/
     cyberpunk.css
     y2k.css
     retro-glass.css
+    interactive-surface-theme.css
     interactive-surface-bridge.css
   docs/
     TOKENS.md
@@ -351,10 +433,21 @@ The checked-in demo, favicon pack, and social preview image stay in the reposito
 
 ```bash
 npm run check
+npm run test:e2e
+npm run test:axe
+npm run test:visual
+npm run test:matrix
 npm run pack:dry-run
 ```
 
-`npm run check` rebuilds the bundles, runs stylelint, verifies package metadata, checks the documented class API, and validates contrast for base text/link pairs and filled component `on-*` pairs. Optional Playwright visual smoke tests are available through `npm run test:visual` after installing dev dependencies.
+`npm run check` rebuilds the bundles, runs stylelint, verifies package metadata, checks the documented class API, and validates contrast for base text/link pairs and filled component `on-*` pairs. Browser release gates add all-engine Playwright coverage, representative Axe scans, curated visual smoke checks, and the sharded `11 presets x 10 themes x 3 modes x 3 engines` matrix.
+
+## v2.1.0 Architecture Notes
+
+- Prefer `visual.css` or `visual/<preset>.css` when Layout Style CSS or application CSS owns structure.
+- Existing root, minified, focused preset, `interactive-surface-bridge`, and `with-bridge` entrypoints preserve their v2 behavior.
+- Treat `page`, `container`, `section`, `grid`, `stack`, `cluster`, and `split` suffixes as deprecated compatibility helpers; their removal is reserved for v3.
+- Prefer `interactive-surface-theme.css` with `interactive-surface-css/state-core.css`. The old stateful bridge exports remain deprecated compatibility paths.
 
 ## v2.0.1 Migration Notes
 
@@ -363,7 +456,7 @@ The `v2.0.1` release line removes duplicated per-UI color-scheme blocks. Color s
 - Use `--usk-*-rgb` when defining or overriding a color scheme.
 - Continue using prefixed functional tokens such as `--saas-primary`, `--neo-card-bg`, and `--rg-on-primary` inside components.
 - Import `ui-style-kit-css/theme-colors.css`, `ui-style-kit-css/native-elements.css`, and `ui-style-kit-css/content-overflow.css` before standalone style files if your bundler does not follow CSS `@import`.
-- Keep using `ui-style-kit-css/interactive-surface-bridge` or `ui-style-kit-css/with-bridge.css` for the opt-in bridge. The bridge now inherits shared `--usk-*` roles and exposes three `data-surface-level` visual states while the default bundle remains bridge-free.
+- Existing v2.0.1 integrations can keep using `ui-style-kit-css/interactive-surface-bridge` or `ui-style-kit-css/with-bridge.css`; those stateful compatibility paths are deprecated in v2.1.0. New integrations should compose the visual, theme-bridge, and state-core entrypoints documented above.
 
 ## License
 

package/STYLE-MAP.md

@@ -1,5 +1,18 @@
 # UI Style Kit CSS Style Map
 
+## Recommended runtime API
+
+Lead with stable semantic classes when an interface can switch visual presets:
+
+```html
+<article class="ui-card">
+  <button class="ui-button" data-ui-variant="primary">Continue</button>
+  <span class="ui-badge" data-ui-variant="success">Ready</span>
+</article>
+```
+
+Changing only the ancestor `data-ui` value restyles that markup across all 11 presets in the generated default, visual, and with-bridge bundles. A generated `visual/<preset>.css` focused entrypoint supplies the same semantic aliases for its selected preset only. Raw `styles/*` and standalone preset exports remain advanced prefixed APIs and do not promise multi-preset semantic switching.
+
 ## UI systems
 
 Color schemes are defined once in `styles/theme-colors.css`. Native HTML fallback selectors are defined once in `styles/native-elements.css`. Long-text containment rules are defined once in `styles/content-overflow.css`. Each UI system file imports all shared layers, aliases `--usk-*` RGB roles back to its prefix, and maps `--usk-native-*` tokens into the preset's visual identity.
@@ -66,3 +79,26 @@ The bridge inherits from shared `--usk-*` color roles, then applies `.interactiv
 - `light`
 - `dark`
 - `contrast`
+
+## Semantic component contract
+
+The machine-readable source of truth is `manifest.json#semanticComponentApi`. Its 29 implemented generic selectors map only to source suffixes with 11-of-11 composed preset coverage. The `implementationStatus` section records `.ui-spinner` and `.ui-tooltip` as retained hooks, the other 27 selectors as generated aliases, and no pending selectors.
+
+| Role | Generic selector -> current source suffix |
+|---|---|
+| Button | `.ui-button` -> `button`; `.ui-icon-button` -> `icon-button` |
+| Card | `.ui-card` -> `card` |
+| Form | `.ui-field` -> `field`; `.ui-label` -> `label`; `.ui-help-text` -> `help-text`; `.ui-input` -> `input`; `.ui-select` -> `select`; `.ui-textarea` -> `textarea` |
+| Choice control | `.ui-check` -> `check`; `.ui-check-control` -> `check-control`; `.ui-radio` -> `radio`; `.ui-radio-control` -> `radio-control`; `.ui-switch` -> `switch`; `.ui-switch-track` -> `switch-track`; `.ui-switch-thumb` -> `switch-thumb` |
+| Badge | `.ui-badge` -> `badge` |
+| Alert | `.ui-alert` -> `alert`; `.ui-alert-title` -> `alert-title`; `.ui-alert-body` -> `alert-body` |
+| Navigation | `.ui-nav` -> `nav`; `.ui-nav-link` -> `nav-link` |
+| Table | `.ui-table` -> `table`; `.ui-table-wrap` -> `table-wrap` |
+| Progress | `.ui-progress` -> `progress`; `.ui-progress-bar` -> `progress-bar` |
+| Toolbar | `.ui-toolbar` -> `toolbar` |
+| Loading | `.ui-spinner` -> `spinner` |
+| Tooltip | `.ui-tooltip` -> `tooltip` |
+
+`data-ui-variant` is the only new attribute. Omission means neutral. `.ui-button` accepts `primary`, `secondary`, `danger`, and `ghost`; `.ui-badge` accepts `primary`, `secondary`, `success`, `warning`, and `danger`; `.ui-alert` accepts `success`, `warning`, and `danger`.
+
+Modal and dialog roles retain native `<dialog>` as their one neutral fallback; `.ui-modal` and `.ui-dialog` are not defined. Preset-prefixed classes remain supported for compatibility and advanced use. Partial preset extras and the seven deprecated structural suffixes stay out of the semantic contract.