ui-style-kit-css 2.4.0 → 2.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (65) hide show
  1. package/CHANGELOG.md +63 -0
  2. package/README.md +47 -19
  3. package/STYLE-MAP.md +5 -0
  4. package/dist/ui-style-kit.css +1102 -616
  5. package/dist/ui-style-kit.min.css +2 -2
  6. package/dist/ui-style-kit.visual.css +1102 -616
  7. package/dist/ui-style-kit.visual.min.css +2 -2
  8. package/dist/ui-style-kit.with-bridge.css +1102 -616
  9. package/dist/ui-style-kit.with-bridge.min.css +2 -2
  10. package/dist/visual/art-deco.css +539 -65
  11. package/dist/visual/bauhaus.css +2 -2
  12. package/dist/visual/bento.css +2 -2
  13. package/dist/visual/brutalism.css +499 -10
  14. package/dist/visual/clay.css +2 -2
  15. package/dist/visual/cyberpunk.css +535 -46
  16. package/dist/visual/data-terminal.css +516 -27
  17. package/dist/visual/editorial-luxe.css +526 -37
  18. package/dist/visual/industrial-utility.css +531 -42
  19. package/dist/visual/maximalist.css +496 -7
  20. package/dist/visual/minimal-saas.css +511 -21
  21. package/dist/visual/neo-noir.css +2 -2
  22. package/dist/visual/neumorphism.css +500 -11
  23. package/dist/visual/organic-modern.css +2 -2
  24. package/dist/visual/paper-editorial.css +537 -48
  25. package/dist/visual/retro-glass.css +534 -45
  26. package/dist/visual/retrofuturism.css +500 -11
  27. package/dist/visual/tactile.css +499 -10
  28. package/dist/visual/technical-blueprint.css +552 -63
  29. package/dist/visual/y2k.css +514 -13
  30. package/docs/BAUHAUS.md +1 -1
  31. package/docs/BRIDGE-MIGRATION.md +38 -0
  32. package/docs/CLAY.md +1 -1
  33. package/docs/COLOR-THEMES.md +63 -0
  34. package/docs/ECOSYSTEM.md +7 -7
  35. package/docs/ORGANIC-MODERN.md +1 -1
  36. package/docs/PUBLISHING.md +13 -13
  37. package/docs/RELEASE-2.4.1.md +35 -0
  38. package/docs/RELEASE-2.4.2.md +37 -0
  39. package/docs/RELEASE-2.5.0.md +34 -0
  40. package/docs/STYLE-GUIDE.md +1 -1
  41. package/manifest.json +358 -160
  42. package/package.json +6 -5
  43. package/styles/art-deco.css +10 -27
  44. package/styles/bauhaus.css +12 -12
  45. package/styles/bento.css +37 -31
  46. package/styles/brutalism.css +5 -5
  47. package/styles/clay.css +5 -5
  48. package/styles/components.css +81 -2
  49. package/styles/cyberpunk.css +14 -14
  50. package/styles/data-terminal.css +12 -12
  51. package/styles/editorial-luxe.css +6 -6
  52. package/styles/industrial-utility.css +5 -5
  53. package/styles/maximalist.css +2 -2
  54. package/styles/minimal-saas.css +13 -12
  55. package/styles/native-elements.css +1 -1
  56. package/styles/neo-noir.css +8 -8
  57. package/styles/neumorphism.css +6 -6
  58. package/styles/organic-modern.css +8 -9
  59. package/styles/paper-editorial.css +6 -6
  60. package/styles/retro-glass.css +5 -5
  61. package/styles/retrofuturism.css +6 -6
  62. package/styles/tactile.css +7 -7
  63. package/styles/technical-blueprint.css +18 -18
  64. package/styles/theme-colors.css +410 -0
  65. package/styles/y2k.css +22 -8
package/docs/BAUHAUS.md CHANGED
@@ -146,7 +146,7 @@ does not claim to reproduce missing decorative artwork. Responsive layouts and
146
146
  readable control sizes replace the source's fixed 1536 x 1024 export geometry.
147
147
 
148
148
  Focused tests cover the public mapping and fonts, existing component geometry,
149
- native loaders, all 20 themes in three modes, ancestor-token inheritance,
149
+ native loaders, all 25 themes in three modes, ancestor-token inheritance,
150
150
  reference palettes, responsive widths, reduced motion, keyboard controls, and
151
151
  accessibility. These are fresh library tests, not the source package's historical
152
152
  QA claims.
package/docs/BRIDGE-MIGRATION.md CHANGED
@@ -18,3 +18,41 @@ import "ui-style-kit-css/with-bridge.css";
18
18
  ```
19
19
 
20
20
  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.
21
+
22
+ ## Replace preset-prefixed runtime hooks
23
+
24
+ Preset-prefixed classes remain supported advanced entrypoints for applications
25
+ that never switch visual systems. They should not be used as application state
26
+ or queried by runtime logic. Replace markup such as:
27
+
28
+ ```html
29
+ <button class="saas-button saas-button-primary variant-active">Save</button>
30
+ ```
31
+
32
+ with stable semantic markup:
33
+
34
+ ```html
35
+ <button class="ui-button" data-ui-variant="primary" aria-pressed="true">Save</button>
36
+ ```
37
+
38
+ Keep `data-ui` and `data-mode` on the owning scope and use `data-theme` only
39
+ when selecting a shared palette. The semantic class stays unchanged when the
40
+ preset changes.
41
+
42
+ ## Replace preset-private tokens
43
+
44
+ Application CSS must not depend on tokens such as `--saas-*`, `--bento-*`, or
45
+ another preset's internal material variables. Use the documented `--ui-*`
46
+ semantic handshake for portable control paint and geometry, or the public
47
+ `--usk-*` theme roles when the application intentionally integrates with UI
48
+ Style Kit. Preset-private values may change as a visual system is refined.
49
+
50
+ ## Replace legacy `variant-*` state classes
51
+
52
+ UI Style Kit does not define a generic `variant-*` class API. Use
53
+ `data-ui-variant` only on the selectors and values declared in
54
+ `manifest.json#semanticComponentApi.variantAttribute`. Use native or ARIA state
55
+ for interaction state, such as `disabled`, `aria-pressed`, `aria-selected`,
56
+ `aria-current`, and `aria-busy`. When Interactive Surface is present, its
57
+ documented `data-surface-variant` and `data-surface-level` attributes own state
58
+ surface behavior; they do not replace `data-ui-variant` paint semantics.
package/docs/CLAY.md CHANGED
@@ -117,7 +117,7 @@ views deliberately reflow the desktop matrix instead of shrinking its labels.
117
117
  - `node --test tests/clay-template.test.js`
118
118
  - `npx playwright test tests/e2e/clay-template.spec.js --project=chromium --workers=1`
119
119
  - Existing Clay material test in `tests/e2e/clay-reference-fidelity.spec.js`
120
- - `tests/e2e/clay-theme-colors.spec.js` checks all 20 themes in three modes,
120
+ - `tests/e2e/clay-theme-colors.spec.js` checks all 25 themes in three modes,
121
121
  live RGB overrides, stable material geometry, and desktop/mobile containment
122
122
  - `tests/e2e/clay-unified-material.spec.js` compares rendered public and sheet
123
123
  controls, reading-surface typography, keyboard/pressed states, and responsive views
package/docs/COLOR-THEMES.md ADDED
@@ -0,0 +1,63 @@
1
+ # Color Themes
2
+
3
+ UI Style Kit CSS exposes 25 named color themes independently from its 20 visual
4
+ presets. Select a visual system with `data-ui`, a palette with `data-theme`, and
5
+ the display treatment with `data-mode`.
6
+
7
+ ```html
8
+ <body data-ui="minimal-saas" data-theme="signal-yellow" data-mode="light">
9
+ ```
10
+
11
+ The five newest themes fill color families that were previously absent or only
12
+ represented by neighboring hues. They use the same complete semantic role set
13
+ as every existing theme and support `light`, `dark`, and `contrast` modes.
14
+
15
+ ## Gap-filling palettes
16
+
17
+ | Theme ID | Color territory | Light foundation | Light primary / secondary / accent | Dark foundation | Dark primary / secondary / accent |
18
+ | --- | --- | --- | --- | --- | --- |
19
+ | `signal-yellow` | True signal yellow with ink-navy support | `#fffbe8` | `#ffcc00` / `#25324e` / `#ffe45c` | `#120f03` | `#ffd83b` / `#8ec6ff` / `#ffe866` |
20
+ | `botanical-green` | Central leaf green with a restrained berry counterpoint | `#eff9f2` | `#0d7e42` / `#793058` / `#40c975` | `#041109` | `#52de8b` / `#ee94c7` / `#6bf0a4` |
21
+ | `cobalt-electric` | Clean saturated cobalt with coral signaling | `#f0f4ff` | `#0052cc` / `#b53948` / `#5279ff` | `#040919` | `#6f95ff` / `#ff8593` / `#8faaff` |
22
+ | `stone-graphite` | Chroma-light stone, graphite, silver, and semantic status color | `#f4f4f2` | `#383c3a` / `#5b615d` / `#b8beba` | `#0c0d0d` | `#d0d4d1` / `#a4aaa6` / `#e6e8e7` |
23
+ | `walnut-clay` | Cocoa walnut, mushroom earth, clay, and muted foliage | `#f8f1e9` | `#704330` / `#58624e` / `#be6f52` | `#120c09` | `#da9e7c` / `#b2c09d` / `#eba988` |
24
+
25
+ ## Design intent
26
+
27
+ - **Signal Yellow** is deliberately yellow-led rather than another gold or
28
+ amber scheme. Ink navy provides structure without dulling the signal color.
29
+ In light mode, primary and accent text use the darker link ink on neutral
30
+ surfaces; primary and accent fills retain their vivid yellow values.
31
+ - **Botanical Green** occupies the clean middle-green range between the
32
+ library's moss, lime, and teal-emerald themes. Berry is used as a controlled
33
+ complementary color.
34
+ - **Cobalt Electric** provides a vivid primary blue distinct from steel, cyan,
35
+ navy, and subdued indigo. Coral carries urgent secondary actions.
36
+ - **Stone Graphite** is the neutral brand palette. Its interface hierarchy
37
+ comes from value and surface separation; chroma is reserved for semantic
38
+ success, warning, and danger roles.
39
+ - **Walnut Clay** covers the deep brown and taupe family without behaving like
40
+ an orange theme. Clay and muted foliage keep the palette warm and grounded.
41
+
42
+ ## Token contract
43
+
44
+ The source values in `styles/theme-colors.css` are space-separated RGB channels,
45
+ not complete CSS colors. For example:
46
+
47
+ ```css
48
+ :where([data-ui][data-theme="cobalt-electric"][data-mode="light"]) {
49
+ --usk-primary-rgb: 0 82 204;
50
+ --usk-primary-text-rgb: 255 255 255;
51
+ }
52
+ ```
53
+
54
+ Consume those channels through the existing semantic or preset-prefixed tokens.
55
+ Do not put `rgb(...)` or hexadecimal values inside a `--usk-*-rgb` override.
56
+ Each foreground/background role pair is validated to at least WCAG AA text
57
+ contrast by the library's manifest-driven contrast check.
58
+
59
+ Bright palettes can also set the optional `--usk-primary-ink` and
60
+ `--usk-accent-ink` tokens to complete CSS colors for text on neutral surfaces.
61
+ These text-only overrides do not change fill colors or text on filled controls.
62
+ They reset at each `data-ui` root, and presets retain their original text colors
63
+ when no ink override is set. Signal Yellow uses this distinction in light mode.
package/docs/ECOSYSTEM.md CHANGED
@@ -4,21 +4,21 @@ UI Style Kit CSS is the visual layer in the three-library CSS ecosystem. It can
4
4
 
5
5
  `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.
6
6
 
7
- 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.
7
+ 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.
8
8
 
9
9
  ## Remote Validation Sequence
10
10
 
11
- 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.
11
+ 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.
12
12
 
13
13
  ## Aligned Versions
14
14
 
15
15
  | Library | Current aligned version | Owns |
16
16
  |---|---:|---|
17
- | `ui-style-kit-css@2.4.0` | current release target | visual identity, color themes, UI paint, native HTML styling, content wrapping, and bridge tokens |
18
- | `interactive-surface-css@1.7.0` | compatible state release | interaction-state primitives, surface behavior, state layers, and input affordances |
19
- | `layout-style-css@3.1.0` | compatible structural release | structural wrappers, grids, sections, app shells, and layout recipes |
17
+ | `ui-style-kit-css@2.5.0` | current release | visual identity, color themes, UI paint, native HTML styling, content wrapping, and bridge tokens |
18
+ | `interactive-surface-css@1.7.3` | compatible state release | interaction-state primitives, surface behavior, state layers, and input affordances |
19
+ | `layout-style-css@3.2.3` | compatible structural release | structural wrappers, grids, sections, app shells, and layout recipes |
20
20
 
21
- The current combination is `ui-style-kit-css@2.4.0`, `interactive-surface-css@1.7.0`, and `layout-style-css@3.1.0`. UI Style Kit `2.4.0` is the current release target; the companion versions are published releases. Layout Style `3.1.0` is the compatible structural release. The validated minimum remains `ui-style-kit-css@2.1.0`, `interactive-surface-css@1.5.0`, and `layout-style-css@3.0.0`.
21
+ 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`.
22
22
 
23
23
  ## Layout-to-visual pairing matrix
24
24
 
@@ -91,4 +91,4 @@ The canonical theme bridge does not make Interactive Surface a dependency of UI
91
91
 
92
92
  ## Canonical ownership order
93
93
 
94
- 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.
94
+ 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/ORGANIC-MODERN.md CHANGED
@@ -85,7 +85,7 @@ and a left-aligned caption. Demo toolbar selects show one custom chevron.
85
85
  ## Verification Evidence
86
86
 
87
87
  Focused tests cover public class coverage and isolation, both fallback palettes,
88
- 20 themes across light/dark/contrast, live RGB overrides, keyboard/native control
88
+ 25 themes across light/dark/contrast, live RGB overrides, keyboard/native control
89
89
  behavior, responsive screenshots, local asset loading, and scoped accessibility.
90
90
  Supplied template QA is historical evidence only; see the repository QA log for
91
91
  fresh implementation results.
package/docs/PUBLISHING.md CHANGED
@@ -1,11 +1,11 @@
1
1
  # Publishing Guide
2
2
 
3
- ## 2.4.0 release workflow
3
+ ## 2.5.0 release workflow
4
4
 
5
- The current checkout is a release candidate. [Release preparation notes](RELEASE-2.4.0.md)
5
+ The current checkout is a release candidate. [Release preparation notes](RELEASE-2.5.0.md)
6
6
  record the current local scope and gates; existing visual-QA documents are historical
7
- evidence, not proof that subsequent edits passed browser validation. Replace the
8
- 2.4.0 changelog's `Unreleased` marker with the actual release date at approved publication.
7
+ evidence, not proof that subsequent edits passed browser validation. The 2.5.0
8
+ changelog entry must carry the approved publication date before tagging.
9
9
 
10
10
  Update the tracked `wiki/` sources with the README and docs. Publishing those pages
11
11
  to GitHub Wiki is a separate handoff, not a side effect of the CSS build. No jsdoc2md
@@ -13,9 +13,9 @@ documentation generator is configured in this package; reusable JavaScript helpe
13
13
  use JSDoc-compatible comments, and the checked-in build owns generated CSS, manifests,
14
14
  icons, README size measurements, and demo asset hashes.
15
15
 
16
- 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`.
16
+ 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`.
17
17
 
18
- 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.
18
+ 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.
19
19
 
20
20
  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.
21
21
 
@@ -33,7 +33,7 @@ Manual release review should open the checked-in demo, exercise the changed pres
33
33
 
34
34
  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.
35
35
 
36
- `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.
36
+ `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.
37
37
 
38
38
  `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`.
39
39
 
@@ -41,18 +41,18 @@ The local UI matrix stops after the first failing 100-case block. Every case has
41
41
 
42
42
  `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.
43
43
 
44
- 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`.
44
+ 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`.
45
45
 
46
46
  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.
47
47
 
48
48
  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.
49
49
 
50
- 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`.
50
+ 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.
51
51
 
52
52
  Use this exact bootstrap and merge sequence:
53
53
 
54
- 1. Verify the published Interactive Surface CSS and Layout Style CSS merge commits remain remotely reachable.
55
- 2. Update and review the final UI companion pins against those immutable merge commits.
54
+ 1. Create and review stable Interactive Surface CSS and Layout Style CSS candidate commits.
55
+ 2. Update and review the final UI companion pins against those immutable candidate commits, then verify both objects are remotely reachable.
56
56
  3. Push the final UI branch, rerun its explicit UI-candidate ecosystem preflight, and merge UI with a merge commit.
57
57
  4. Do not squash or rebase away reviewed release commits that remain part of the pinned verification history.
58
58
 
@@ -76,7 +76,7 @@ npm run check:ecosystem:packs -- --layout-repo ../Layout-Style-CSS --interactive
76
76
  npm publish
77
77
  ```
78
78
 
79
- `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.
79
+ `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.
80
80
 
81
81
  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.
82
82
 
@@ -88,4 +88,4 @@ npm run release:minor
88
88
  npm run release:major
89
89
  ```
90
90
 
91
- 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.
91
+ 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.
package/docs/RELEASE-2.4.1.md ADDED
@@ -0,0 +1,35 @@
1
+ # v2.4.1 release preparation
2
+
3
+ ## Scope
4
+
5
+ UI Style Kit CSS 2.4.1 packages the five shared color themes already merged into
6
+ `main`: Signal Yellow, Botanical Green, Cobalt Electric, Stone Graphite, and Walnut
7
+ Clay. Each theme provides light, dark, and contrast palettes through the existing
8
+ `data-theme` and `data-mode` contract.
9
+
10
+ The release preserves the v2 selectors and package entrypoints. It does not add or
11
+ remove preset identifiers, exports, cascade layers, or companion-library ownership
12
+ boundaries.
13
+
14
+ ## Release surfaces
15
+
16
+ - Package, lockfile, public manifest, web manifests, structured metadata, generated
17
+ CSS banners, compatibility metadata, README, wiki sources, and maintained release
18
+ documentation identify `2.4.1`.
19
+ - The changelog records the theme additions, expanded 4,500-case browser matrix,
20
+ demo metadata refresh, and Signal Yellow foreground correction under the dated
21
+ `2.4.1` entry.
22
+ - The aligned companion versions remain `interactive-surface-css@1.7.0` and
23
+ `layout-style-css@3.1.0`.
24
+
25
+ ## Verification boundary
26
+
27
+ Run focused version and compatibility tests after updating source metadata, then run
28
+ the repository's final `npm run release:verify` gate. That gate rebuilds generated
29
+ assets, lints authored CSS, executes unit and release-smoke browser checks, validates
30
+ contrast, compatibility, ownership, package contents, ecosystem preflight, audit,
31
+ and the dry-run tarball.
32
+
33
+ A local green gate does not publish anything. Merge the reviewed release branch into
34
+ `main` before creating `v2.4.1`; the tag-alignment workflow creates the GitHub Release,
35
+ and the protected npm workflow publishes the immutable tagged package.
package/docs/RELEASE-2.4.2.md ADDED
@@ -0,0 +1,37 @@
1
+ # v2.4.2 release preparation
2
+
3
+ UI Style Kit CSS 2.4.2 is a backward-compatible release candidate focused on
4
+ consumer composition. It does not add a preset, theme, selector, component
5
+ variant, or package export.
6
+
7
+ ## Candidate scope
8
+
9
+ - Preserve consumer-owned width, sticky-position, and internal-scroll rules
10
+ when the visual bundle loads after application CSS.
11
+ - Verify semantic cards at 320px and 390px with selects, ranges, progress,
12
+ wide tables, icon-only controls, and long content.
13
+ - Verify a short-height card keeps its toolbar sticky and its content region
14
+ internally scrollable.
15
+ - Verify representative icon-only actions retain neutral or subtle preset paint
16
+ and do not inherit the primary action treatment.
17
+ - Expand migration guidance for preset-prefixed hooks, preset-private tokens,
18
+ and legacy `variant-*` state classes.
19
+
20
+ ## Ecosystem alignment
21
+
22
+ The coordinated local candidate train is `ui-style-kit-css@2.4.2`,
23
+ `interactive-surface-css@1.7.1`, and `layout-style-css@3.2.1`. The checked-in
24
+ companion revisions remain the last reviewed immutable release baselines until
25
+ the candidate packages have stable commits. They must be refreshed to those
26
+ commits before remote release workflows can treat the candidate train as
27
+ publishable.
28
+
29
+ The supported minimum remains `ui-style-kit-css@2.1.0`,
30
+ `interactive-surface-css@1.5.0`, and `layout-style-css@3.0.0`.
31
+
32
+ ## Verification boundary
33
+
34
+ Local build, lint, unit, focused browser, package, and candidate-tarball checks
35
+ are evidence for preparation only. They do not prove a commit, pull request,
36
+ tag, registry publication, or deployed site. Those external mutations require
37
+ separate approval and immutable companion revisions.
package/docs/RELEASE-2.5.0.md ADDED
@@ -0,0 +1,34 @@
1
+ # v2.5.0 release notes
2
+
3
+ UI Style Kit CSS 2.5.0 is a backward-compatible minor release that
4
+ expands the stable semantic component API from 29 to 75 selectors.
5
+
6
+ ## Scope
7
+
8
+ - Tier A promotes tabs, pagination, breadcrumb, skeleton, empty state, metric,
9
+ chip, avatar, stepper, and toast patterns.
10
+ - Tier B promotes popover, menu, segmented-control, file-upload, dropzone, and
11
+ listbox patterns.
12
+ - Semantic chip and toast variants continue to use `data-ui-variant`.
13
+ - Skeleton shape and step workflow state use explicit, documented data hooks.
14
+ - Preset-prefixed classes remain supported for compatibility and advanced use.
15
+
16
+ Every stable `.ui-*` selector maps to a universal preset-prefixed source suffix.
17
+ The build emits specificity-safe aliases beneath the active `data-ui` root, and
18
+ the shared foundation resolves visual paint through that preset's native tokens.
19
+ React or application code continues to own selection, focus, dismissal, file
20
+ handling, and other behavior.
21
+
22
+ The reviewed companion release set is `interactive-surface-css@1.7.3` and
23
+ `layout-style-css@3.2.3`. The compatibility manifest pins their immutable
24
+ release commits so CI and publication cannot silently substitute branch heads,
25
+ dirty working trees, or stale registry artifacts.
26
+
27
+ ## Verification boundary
28
+
29
+ Focused semantic source, generated alias, runtime-markup, artifact-integrity,
30
+ and pairwise identity checks are required before the full release gate. The
31
+ identity metric uses a one-percent perceptual threshold and viewport-specific
32
+ component floors so restrained preset palettes remain measurable without
33
+ pair-specific exceptions. Browser matrix, package preflight, registry
34
+ publication, tag creation, and deployment remain separate proofs.
package/docs/STYLE-GUIDE.md CHANGED
@@ -23,7 +23,7 @@
23
23
  | Paper Editorial | News, magazines, journals, cultural sites and story-led publishing |
24
24
  | Neo-Noir | Cinematic portfolios, nightlife, premium creative studios and dramatic product sites |
25
25
 
26
- All styles share the same 20 color schemes through `styles/theme-colors.css`, so changing `data-theme` affects the active color scheme independently from the selected UI treatment.
26
+ All styles share the same 25 color schemes through `styles/theme-colors.css`, so changing `data-theme` affects the active color scheme independently from the selected UI treatment.
27
27
 
28
28
  Omit `data-theme` to use the chosen preset's native light, dark, or contrast colors.
29
29
  The [demo guide](DEMO-SHOWCASE.md) explains the unified style-specific gallery and