ui-style-kit-css 2.5.0 → 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/ECOSYSTEM.md

@@ -14,11 +14,11 @@ Before a UI branch or pull request is expected to validate, verify the reviewed
 
 | Library | Current aligned version | Owns |
 |---|---:|---|
-| `ui-style-kit-css@2.5.0` | current release | visual identity, color themes, UI paint, native HTML styling, content wrapping, and bridge tokens |
+| `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.5.0`, `interactive-surface-css@1.7.3`, and `layout-style-css@3.2.3`. UI Style Kit `2.5.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`.
+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,7 +87,7 @@ 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
 

package/docs/PUBLISHING.md

@@ -1,10 +1,10 @@
 # Publishing Guide
 
-## 2.5.0 release workflow
+## 2.6.0 release workflow
 
-The current checkout is a release candidate. [Release preparation notes](RELEASE-2.5.0.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.5.0
+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.5.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`.
+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.5.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.
+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.
 
@@ -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.5.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.
+`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.5.0` is the current compatible candidate for the expanded semantic component API; 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.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.