ui-style-kit-css 2.4.1 → 2.6.0

package/docs/ART-DECO.md

@@ -1,6 +1,6 @@
 # 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.
+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 `.usk-*` API.
 
 ## Loading And Palettes
 
@@ -77,4 +77,4 @@ Focused coverage lives in `tests/art-deco-template.test.js` and `tests/e2e/art-d
 
 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.
+The semantic authored-hook test currently detects additional `.usk-*` 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/BRIDGE-MIGRATION.md

@@ -18,3 +18,41 @@ import "ui-style-kit-css/with-bridge.css";
 ```
 
 Do not combine a deprecated bridge import with `interactive-surface-theme.css`; select the legacy stateful path during migration or the canonical token-only path for new integration work.
+
+## Replace preset-prefixed runtime hooks
+
+Preset-prefixed classes remain supported advanced entrypoints for applications
+that never switch visual systems. They should not be used as application state
+or queried by runtime logic. Replace markup such as:
+
+```html
+<button class="saas-button saas-button-primary variant-active">Save</button>
+```
+
+with stable semantic markup:
+
+```html
+<button class="ui-button" data-ui-variant="primary" aria-pressed="true">Save</button>
+```
+
+Keep `data-ui` and `data-mode` on the owning scope and use `data-theme` only
+when selecting a shared palette. The semantic class stays unchanged when the
+preset changes.
+
+## Replace preset-private tokens
+
+Application CSS must not depend on tokens such as `--saas-*`, `--bento-*`, or
+another preset's internal material variables. Use the documented `--ui-*`
+semantic handshake for portable control paint and geometry, or the public
+`--usk-*` theme roles when the application intentionally integrates with UI
+Style Kit. Preset-private values may change as a visual system is refined.
+
+## Replace legacy `variant-*` state classes
+
+UI Style Kit does not define a generic `variant-*` class API. Use
+`data-ui-variant` only on the selectors and values declared in
+`manifest.json#semanticComponentApi.variantAttribute`. Use native or ARIA state
+for interaction state, such as `disabled`, `aria-pressed`, `aria-selected`,
+`aria-current`, and `aria-busy`. When Interactive Surface is present, its
+documented `data-surface-variant` and `data-surface-level` attributes own state
+surface behavior; they do not replace `data-ui-variant` paint semantics.

package/docs/ECOSYSTEM.md

@@ -4,21 +4,21 @@ UI Style Kit CSS is the visual layer in the three-library CSS ecosystem. It can
 
 `ecosystem-compatibility.json` is the authoritative source for supported ranges, validated combinations, canonical imports, and deprecated bridge metadata. UI Style Kit owns this file temporarily until a dedicated ecosystem fixture repository is introduced.
 
-Its companion source records pin the exact published merge revisions used by integration and release verification. Update those immutable pins whenever a later companion release changes the validated contract.
+Its companion source records pin the reviewed Interactive Surface 1.7.3 and Layout Style 3.2.3 release commits used by integration and release verification. These immutable revisions must remain remotely reachable; never replace them with mutable branches or dirty working trees.
 
 ## Remote Validation Sequence
 
-The pinned Interactive Surface and Layout commits are published merge objects. Before a UI branch or pull request is expected to validate, verify each pinned SHA remains fetchable from its GitHub repository. The CI and publish workflows perform the same remote-object preflight, so they intentionally fail rather than silently substituting a mutable branch or stale registry artifact when either companion revision is unavailable.
+Before a UI branch or pull request is expected to validate, verify the reviewed Interactive Surface 1.7.3 and Layout 3.2.3 commit objects remain fetchable from their GitHub repositories. The CI and publish workflows intentionally fail rather than silently substituting a mutable branch, dirty checkout, or stale registry artifact.
 
 ## Aligned Versions
 
 | Library | Current aligned version | Owns |
 |---|---:|---|
-| `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 |
+| `ui-style-kit-css@2.6.0` | current release | visual identity, color themes, UI paint, native HTML styling, content wrapping, and bridge tokens |
+| `interactive-surface-css@1.7.3` | compatible state release | interaction-state primitives, surface behavior, state layers, and input affordances |
+| `layout-style-css@3.2.3` | compatible structural release | structural wrappers, grids, sections, app shells, and layout recipes |
 
-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`.
+The current combination is `ui-style-kit-css@2.6.0`, `interactive-surface-css@1.7.3`, and `layout-style-css@3.2.3`. UI Style Kit `2.6.0` is the current release; the companion versions are reviewed releases. Layout Style `3.2.3` 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
 
@@ -50,7 +50,7 @@ UI Style Kit can use the same portable path by loading `ui-style-kit-css/visual.
 Use UI Style Kit by itself when an app needs visual identity, theme roles, native element styling, and long-text containment without layout primitives or richer interaction-state behavior.
 
 ```js
-import "ui-style-kit-css/minimal-saas.css";
+import "ui-style-kit-css/presets/minimal-saas.css";
 ```
 
 ### Use two
@@ -58,7 +58,7 @@ import "ui-style-kit-css/minimal-saas.css";
 Pair UI Style Kit with Interactive Surface CSS when controls need the sibling interaction-state primitives. Import UI paint first, its public token bridge second, and the sibling state core third.
 
 ```js
-import "ui-style-kit-css/visual/minimal-saas.css";
+import "ui-style-kit-css/presets/minimal-saas.css";
 import "ui-style-kit-css/interactive-surface-theme.css";
 import "interactive-surface-css/state-core.css";
 ```
@@ -66,7 +66,7 @@ import "interactive-surface-css/state-core.css";
 Pair UI Style Kit with Layout Style CSS when the app already has interaction behavior but needs structural wrappers, grids, and sections.
 
 ```js
-import "ui-style-kit-css/visual/minimal-saas.css";
+import "ui-style-kit-css/presets/minimal-saas.css";
 import "layout-style-css";
 ```
 
@@ -87,8 +87,8 @@ import "layout-style-css";
 - Interactive Surface CSS owns interaction-state semantics, input affordances, state layers, and surface behavior.
 - Layout Style CSS owns structural wrappers, layout recipes, grids, app shells, and section composition.
 
-The canonical theme bridge does not make Interactive Surface a dependency of UI Style Kit. It only maps shared `--usk-*` roles to `--interactive-surface-*` tokens and provides paint; `state-core.css` continues to own interaction mechanics. The older `interactive-surface-bridge` and `with-bridge` exports are deprecated compatibility paths whose stateful behavior remains unchanged.
+The canonical theme bridge does not make Interactive Surface a dependency of UI Style Kit. It maps resolved `--usk-native-*` paint pairs and radius geometry to `--interactive-surface-*` tokens, falling back to shared `--usk-*` roles only when needed; this keeps reference palettes readable and preserves preset-specific clipped or squared controls when `data-theme` is omitted. `state-core.css` continues to own interaction mechanics. The older `interactive-surface-bridge` and `with-bridge` exports are deprecated compatibility paths whose stateful behavior remains unchanged.
 
 ## Canonical ownership order
 
-Load UI visual CSS first, UI interaction-theme paint second, Interactive Surface state core third, Layout CSS fourth, and application overrides last. Layout `3.1.0` no longer exports `integrations/ui-style-kit.css` or `legacy.css`; use its root or supported `foundation.css`, wrapper, primitive, recipe, utility, and personality entrypoints.
+Load UI visual CSS first, UI interaction-theme paint second, Interactive Surface state core third, Layout CSS fourth, and application overrides last. Layout `3.2.3` does not export `integrations/ui-style-kit.css` or `legacy.css`; use its root or supported `foundation.css`, wrapper, primitive, recipe, utility, and personality entrypoints.

package/docs/PUBLISHING.md

@@ -1,10 +1,10 @@
 # Publishing Guide
 
-## 2.4.1 release workflow
+## 2.6.0 release workflow
 
-The current checkout is a release candidate. [Release preparation notes](RELEASE-2.4.1.md)
+The current checkout is a release candidate. [Release preparation notes](RELEASE-2.6.0.md)
 record the current local scope and gates; existing visual-QA documents are historical
-evidence, not proof that subsequent edits passed browser validation. The 2.4.1
+evidence, not proof that subsequent edits passed browser validation. The 2.6.0
 changelog entry must carry the approved publication date before tagging.
 
 Update the tracked `wiki/` sources with the README and docs. Publishing those pages
@@ -13,9 +13,9 @@ documentation generator is configured in this package; reusable JavaScript helpe
 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.1` 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`.
+Prepare `ui-style-kit-css@2.6.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 releases are `layout-style-css@3.2.3` and `interactive-surface-css@1.7.3`.
 
-Do not push `v2.4.1` 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.
+Do not push `v2.6.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.
 
@@ -33,7 +33,7 @@ Manual release review should open the checked-in demo, exercise the changed pres
 
 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.1` 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 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. The release verification scripts pass `--candidate-package ui-style-kit-css --companion-candidate-root ../Layout-Style-CSS --companion-candidate-root ../Interactive-Surface-CSS`. Those explicit roots exempt only local packages whose name and version exactly match the exact versions in the current compatibility matrix; minimum versions remain registry-backed. Omitting the companion flags preserves the registry-only default, and a mismatched or duplicate local candidate fails closed. 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`.
 
@@ -41,18 +41,18 @@ The local UI matrix stops after the first failing 100-case block. Every case has
 
 `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.4.1` 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`.
+The current matrix checks the candidate UI tarball with `interactive-surface-css@1.7.3` and `layout-style-css@3.2.3`. 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 `b48b8b9080e4b1d4e344b6749ab1969a2863b3d1` 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. The current values identify the reviewed Interactive 1.7.3 and Layout 3.2.3 release commits. Do not replace them with dirty working-tree SHAs or mutable branches.
 
 Use this exact bootstrap and merge sequence:
 
-1. Verify the published Interactive Surface CSS and Layout Style CSS merge commits remain remotely reachable.
-2. Update and review the final UI companion pins against those immutable merge commits.
+1. Create and review stable Interactive Surface CSS and Layout Style CSS candidate commits.
+2. Update and review the final UI companion pins against those immutable candidate commits, then verify both objects are remotely reachable.
 3. Push the final UI branch, rerun its explicit UI-candidate ecosystem preflight, and merge UI with a merge commit.
 4. Do not squash or rebase away reviewed release commits that remain part of the pinned verification history.
 
@@ -76,7 +76,7 @@ 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 default fast release gate. For GitHub releases, push or dispatch the matching package tag, such as `v2.4.1`, 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.
+`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.6.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.
 
@@ -88,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. Version `2.4.1` is the explicitly approved patch release for the already-merged, backward-compatible five-theme expansion; future feature versioning continues to follow this policy.
+Use patch for compatible fixes, minor for new themes, presets, component capabilities, or browser-support contracts, and major for incompatible public API changes. Version `2.6.0` is the current compatible candidate for self-contained preset delivery and the hardened semantic component API; future feature versioning continues to follow this policy.

package/docs/RELEASE-2.4.2.md

@@ -0,0 +1,37 @@
+# v2.4.2 release preparation
+
+UI Style Kit CSS 2.4.2 is a backward-compatible release candidate focused on
+consumer composition. It does not add a preset, theme, selector, component
+variant, or package export.
+
+## Candidate scope
+
+- Preserve consumer-owned width, sticky-position, and internal-scroll rules
+  when the visual bundle loads after application CSS.
+- Verify semantic cards at 320px and 390px with selects, ranges, progress,
+  wide tables, icon-only controls, and long content.
+- Verify a short-height card keeps its toolbar sticky and its content region
+  internally scrollable.
+- Verify representative icon-only actions retain neutral or subtle preset paint
+  and do not inherit the primary action treatment.
+- Expand migration guidance for preset-prefixed hooks, preset-private tokens,
+  and legacy `variant-*` state classes.
+
+## Ecosystem alignment
+
+The coordinated local candidate train is `ui-style-kit-css@2.4.2`,
+`interactive-surface-css@1.7.1`, and `layout-style-css@3.2.1`. The checked-in
+companion revisions remain the last reviewed immutable release baselines until
+the candidate packages have stable commits. They must be refreshed to those
+commits before remote release workflows can treat the candidate train as
+publishable.
+
+The supported minimum remains `ui-style-kit-css@2.1.0`,
+`interactive-surface-css@1.5.0`, and `layout-style-css@3.0.0`.
+
+## Verification boundary
+
+Local build, lint, unit, focused browser, package, and candidate-tarball checks
+are evidence for preparation only. They do not prove a commit, pull request,
+tag, registry publication, or deployed site. Those external mutations require
+separate approval and immutable companion revisions.

package/docs/RELEASE-2.5.0.md

@@ -0,0 +1,34 @@
+# v2.5.0 release notes
+
+UI Style Kit CSS 2.5.0 is a backward-compatible minor release that
+expands the stable semantic component API from 29 to 75 selectors.
+
+## Scope
+
+- Tier A promotes tabs, pagination, breadcrumb, skeleton, empty state, metric,
+  chip, avatar, stepper, and toast patterns.
+- Tier B promotes popover, menu, segmented-control, file-upload, dropzone, and
+  listbox patterns.
+- Semantic chip and toast variants continue to use `data-ui-variant`.
+- Skeleton shape and step workflow state use explicit, documented data hooks.
+- Preset-prefixed classes remain supported for compatibility and advanced use.
+
+Every stable `.ui-*` selector maps to a universal preset-prefixed source suffix.
+The build emits specificity-safe aliases beneath the active `data-ui` root, and
+the shared foundation resolves visual paint through that preset's native tokens.
+React or application code continues to own selection, focus, dismissal, file
+handling, and other behavior.
+
+The reviewed companion release set is `interactive-surface-css@1.7.3` and
+`layout-style-css@3.2.3`. The compatibility manifest pins their immutable
+release commits so CI and publication cannot silently substitute branch heads,
+dirty working trees, or stale registry artifacts.
+
+## Verification boundary
+
+Focused semantic source, generated alias, runtime-markup, artifact-integrity,
+and pairwise identity checks are required before the full release gate. The
+identity metric uses a one-percent perceptual threshold and viewport-specific
+component floors so restrained preset palettes remain measurable without
+pair-specific exceptions. Browser matrix, package preflight, registry
+publication, tag creation, and deployment remain separate proofs.

package/docs/RELEASE-2.6.0.md

@@ -0,0 +1,36 @@
+# v2.6.0 release notes
+
+UI Style Kit CSS 2.6.0 is a backward-compatible minor release that improves
+component quality and makes every UI style available through a canonical,
+self-contained preset import.
+
+## Delivery contract
+
+- Import `ui-style-kit-css` or `ui-style-kit-css/visual.css` when an application
+  needs all 20 styles and runtime `data-ui` switching.
+- Import `ui-style-kit-css/presets/<name>.css` when an application needs one
+  style. Each generated preset file includes its shared foundations and contains
+  no unresolved CSS imports.
+- Existing `visual/<name>.css`, raw preset, bridge, and v2 compatibility exports
+  remain available.
+- Runtime selection continues to use `data-ui`; `data-theme` and `data-mode`
+  remain independent.
+
+## Component and visual fixes
+
+- Added clean spacing defaults plus explicit `.usk-flush` and `.usk-underline`; Technical Blueprint remains exempt so its measured, adjoining geometry is preserved
+  overrides.
+- Kept decorative underlines opt-in while preserving semantic edit notation.
+- Corrected reference-palette foreground and background pairs, including late
+  Bento and Clay contrast cases.
+- Repaired semantic checkbox, radio, switch, avatar, chip, icon, and pagination
+  geometry without framework-specific CSS.
+- Preserved preset-owned radius and clipped-corner identities through the
+  Interactive Surface bridge.
+
+## Verification boundary
+
+The release candidate requires focused public-export, manifest, package,
+contrast, ownership, semantic-component, and browser checks before the final
+release gate. Pull-request checks, the merge commit, GitHub Release, npm
+publication, and registry availability are verified as separate stages.

package/docs/STYLE-GUIDE.md

@@ -32,6 +32,16 @@ without assigning a shared theme or changing geometry.
 
 Use `data-mode="contrast"` for high-contrast variants and pair it with semantic HTML for best accessibility outcomes.
 
+## Clean spacing and decoration defaults
+
+Every element inside a themed UI root starts with a 2px margin and padding fallback unless a preset supplies a roomier value. Technical Blueprint is exempt because its measured drafting structures intentionally adjoin. Use `.usk-flush` (recommended) or `.flush` only for an intentionally edge-to-edge element in the remaining styles. Buttons and badges retain at least 2px of block padding and 4px of inline padding.
+
+Links and component text are not underlined by default. Apply `.usk-underline` when an underline is deliberately part of the design. Semantic edit notation remains available through native `u`, `ins`, `del`, and `s` elements.
+
+Semantic choice wrappers expose one visual affordance. Their native checkbox or radio remains focusable and form-associated, while `.usk-check-control`, `.usk-radio-control`, or `.usk-switch-track` owns the visible, vertically centered geometry. The wrapper supplies its own inset so the affordance never touches the painted edge. Do not reveal both surfaces with a local override.
+
+Mark reusable SVG artwork with `data-ui-icon`. The library supplies `1em` square geometry, block alignment, and visible overflow so React, Vue, and plain-HTML consumers do not need framework-specific icon CSS. Nested chip remove controls remain 24px square with a 12px glyph. Use `data-pagination-kind="page"` for compact number controls and `data-pagination-kind="direction"` for the larger Previous and Next bookends.
+
 ## Preset identity and component roles
 
 UI presets own geometry, material, spacing, depth, and typographic character. Color schemes own semantic color roles. A preset should therefore remain recognizable when its `data-theme` changes, while every component continues to consume the active theme tokens instead of fixed artwork colors.