ui-style-kit-css 1.2.2 → 2.0.2

package/docs/PUBLISHING.md

@@ -7,7 +7,7 @@ npm run check
 npm run pack:dry-run
 ```
 
-`npm run check` rebuilds dist CSS, runs stylelint, executes unit package checks, verifies contrast pairs, and confirms package metadata. `npm run pack:dry-run` shows the exact files that would publish.
+`npm run check` rebuilds dist CSS, runs stylelint, executes package, class API, shared theme-color, and vendor-prefix unit checks, validates core text/link contrast pairs and filled component `on-*` contrast pairs, and confirms package metadata. `npm run pack:dry-run` shows the exact files that would publish.
 
 ## Publish
 
@@ -15,7 +15,7 @@ npm run pack:dry-run
 npm publish
 ```
 
-For GitHub releases, create or dispatch a release for the matching package tag, such as `v1.2.2`. The release workflows verify that `package.json`, `package-lock.json`, and `CHANGELOG.md` are aligned before publishing.
+For GitHub releases, create or dispatch a release for the matching package tag, such as `v2.0.2`. The release workflows verify that `package.json`, `package-lock.json`, `CHANGELOG.md`, and generated dist banners are aligned before publishing.
 
 ## Versioning
 
@@ -25,4 +25,4 @@ npm run release:minor
 npm run release:major
 ```
 
-Use patch for fixes, minor for new themes/styles, and major for breaking public API changes.
+Use patch for fixes, minor for new themes/styles, and major for breaking public API changes. The 2.x release line is major because color-scheme authoring moved from per-UI `--<prefix>-*-rgb` blocks to shared `--usk-*-rgb` roles in `styles/theme-colors.css`.

package/docs/STYLE-GUIDE.md

@@ -13,8 +13,10 @@
 | Cyberpunk | Security, gaming, encryption, developer demos, nightlife/tech branding |
 | Y2K | Nostalgic, playful, music/fashion/event sites |
 | Retro Glass | Futuristic premium apps, glass dashboards, hero sections |
-Use `data-mode="contrast"` for high-contrast variants and pair it with semantic HTML for best accessibility outcomes.
 
+All styles share the same 10 color schemes through `styles/theme-colors.css`, so changing `data-theme` affects the active color scheme independently from the selected UI treatment.
+
+Use `data-mode="contrast"` for high-contrast variants and pair it with semantic HTML for best accessibility outcomes.
 
 ## Visual regression baseline
 

package/docs/TOKENS.md

@@ -1,6 +1,12 @@
 # Token Contract
 
-Each UI style uses its own prefix, but the token shape is intentionally consistent.
+Each UI style uses its own prefix, but concrete color schemes are shared. The 2.0 token model is deliberately compact:
+
+```txt
+shared scheme channels -> prefixed aliases -> UI rules
+```
+
+`styles/theme-colors.css` defines the active scheme and mode once as `--usk-*` RGB channels. Each UI style maps those shared channels to its public prefix, then component rules consume prefixed functional variables. `styles/native-elements.css` owns native HTML fallback selectors and consumes `--usk-native-*` tokens that each preset maps back to its own public variables.
 
 ## Prefixes
 
@@ -18,41 +24,132 @@ Each UI style uses its own prefix, but the token shape is intentionally consiste
 | Y2K | `y2k` |
 | Retro Glass | `rg` |
 
-## Stable token families
+## Stable functional tokens
 
 Replace `<prefix>` with the style prefix:
 
 ```css
 --<prefix>-bg
+--<prefix>-fg
 --<prefix>-surface
+--<prefix>-surface-fg
 --<prefix>-surface-strong
 --<prefix>-surface-soft
 --<prefix>-text
 --<prefix>-text-muted
+--<prefix>-muted
 --<prefix>-border
+--<prefix>-control-bg
+--<prefix>-control-fg
 --<prefix>-primary
 --<prefix>-primary-hover
---<prefix>-primary-text
 --<prefix>-secondary
 --<prefix>-secondary-hover
---<prefix>-secondary-text
 --<prefix>-accent
 --<prefix>-success
 --<prefix>-warning
 --<prefix>-danger
 --<prefix>-link
 --<prefix>-focus
+--<prefix>-theme-bg
+--<prefix>-theme-bg-size
+--<prefix>-card-bg
+--<prefix>-spinner-track
+--<prefix>-spinner-stroke
+--<prefix>-spinner-accent
+```
+
+## Filled-surface text aliases
+
+Filled UI uses compact `on-*` aliases instead of a large foreground-token matrix:
+
+```css
+--<prefix>-on-primary
+--<prefix>-on-secondary
+--<prefix>-on-accent
+--<prefix>-on-success
+--<prefix>-on-warning
+--<prefix>-on-danger
+```
+
+Backward-compatible aliases `--<prefix>-primary-text` and `--<prefix>-secondary-text` remain available and point to the same filled-surface text colors.
+
+## Shared RGB palette channels
+
+Concrete theme/mode blocks now live in `styles/theme-colors.css` and expose shared RGB channels:
+
+```css
+--usk-bg-rgb
+--usk-surface-rgb
+--usk-surface-strong-rgb
+--usk-surface-soft-rgb
+--usk-text-rgb
+--usk-text-muted-rgb
+--usk-border-rgb
+--usk-primary-rgb
+--usk-primary-hover-rgb
+--usk-primary-text-rgb
+--usk-secondary-rgb
+--usk-secondary-hover-rgb
+--usk-secondary-text-rgb
+--usk-accent-rgb
+--usk-accent-text-rgb
+--usk-success-rgb
+--usk-success-text-rgb
+--usk-warning-rgb
+--usk-warning-text-rgb
+--usk-danger-rgb
+--usk-danger-text-rgb
+--usk-link-rgb
+--usk-focus-rgb
 ```
 
-Most systems also expose RGB source tokens such as:
+Each standalone style file imports the shared color and native layers, then aliases those roles back to the style prefix:
 
 ```css
---<prefix>-primary-rgb
---<prefix>-border-rgb
---<prefix>-focus-rgb
+[data-ui="minimal-saas"][data-theme][data-mode] {
+  --saas-bg-rgb: var(--usk-bg-rgb);
+  --saas-primary-rgb: var(--usk-primary-rgb);
+  --saas-primary-text-rgb: var(--usk-primary-text-rgb);
+}
 ```
 
-These are useful for custom alpha effects:
+## Native fallback tokens
+
+Native HTML coverage is shared in `styles/native-elements.css` to avoid repeating the same semantic selector blocks in every preset. Preset files provide visual mappings for these stable native-layer tokens:
+
+```css
+--usk-native-surface
+--usk-native-surface-strong
+--usk-native-surface-soft
+--usk-native-card-bg
+--usk-native-control-bg
+--usk-native-text
+--usk-native-text-muted
+--usk-native-border
+--usk-native-primary
+--usk-native-primary-hover
+--usk-native-on-primary
+--usk-native-focus
+--usk-native-success
+--usk-native-warning
+--usk-native-danger
+--usk-native-link
+--usk-native-font-body
+--usk-native-font-heading
+--usk-native-font-control
+--usk-native-font-mono
+--usk-native-radius-sm
+--usk-native-radius
+--usk-native-radius-lg
+--usk-native-shadow
+--usk-native-shadow-md
+--usk-native-focus-ring
+```
+
+Consumers usually override the prefixed public tokens, not these internal bridge tokens. Use `--usk-native-*` only when intentionally customizing native fallback styling across every UI preset.
+
+Use prefixed RGB aliases for component-local alpha effects:
 
 ```css
 .my-component {
@@ -60,12 +157,120 @@ These are useful for custom alpha effects:
 }
 ```
 
+Use shared `--usk-*` roles when defining or overriding a scheme:
+
+```css
+:where([data-ui][data-theme="arctic-indigo"][data-mode="light"]) {
+  --usk-primary-rgb: 72 91 255;
+  --usk-primary-hover-rgb: 55 75 230;
+  --usk-primary-text-rgb: 255 255 255;
+}
+```
+
+## Theme-composition tokens
+
+The library derives larger visual defaults from the active theme:
+
+```css
+--<prefix>-theme-bg       /* page-level background layers */
+--<prefix>-theme-bg-size  /* matching background-size list */
+--<prefix>-card-bg        /* default card/panel background */
+--<prefix>-control-bg     /* default neutral button/toolbar/table-wrap background */
+```
+
+These tokens make color themes visually distinct by changing page atmosphere, card tinting, and neutral control surfaces when `data-theme` or `data-mode` changes.
+
+## Spinner tokens
+
+Loading indicators use theme variables by default:
+
+```css
+--<prefix>-spinner-track
+--<prefix>-spinner-stroke
+--<prefix>-spinner-accent
+```
+
+The class utilities are `<prefix>-spinner`, `<prefix>-loading-spinner`, `<prefix>-spinner-sm`, and `<prefix>-spinner-lg`. Native buttons and prefixed buttons also render an inline spinner when `aria-busy="true"` is present.
+
+## Interactive Surface bridge tokens
+
+The opt-in bridge maps shared `--usk-*` roles directly to `--interactive-surface-*` tokens. It avoids per-UI token maps so the bridge follows the same shared scheme -> mode role -> component rule flow as the main bundle.
+
+Use `.interactive-surface` with `data-surface-variant` for semantic intent and `data-surface-level` for visual depth:
+
+```html
+<button class="interactive-surface" data-surface-variant="primary" data-surface-level="2">
+  Save changes
+</button>
+```
+
+Stable bridge attributes:
+
+```txt
+data-surface-variant="primary|secondary|accent|subtle|warning|danger"
+data-surface-level="1|2|3"
+```
+
+The bridge defines visible state layer tokens for hover, active, and focus plus level tokens such as `--interactive-surface-level-1-bg`, `--interactive-surface-level-2-bg`, and `--interactive-surface-level-3-bg`.
+
+## Typography tokens
+
+Each style exposes broad and granular font variables:
+
+```css
+--<prefix>-font-sans
+--<prefix>-font-display
+--<prefix>-font-body
+--<prefix>-font-heading
+--<prefix>-font-control
+--<prefix>-font-mono
+```
+
+`--<prefix>-font-body`, `--<prefix>-font-heading`, and `--<prefix>-font-control` default back to `font-sans` or `font-display`, so existing overrides continue to work.
+
+## Palette utilities vs filled UI
+
+Semantic text utility classes use direct palette colors:
+
+```css
+.saas-text-primary { color: var(--saas-primary); }
+.saas-text-warning { color: var(--saas-warning); }
+```
+
+Filled UI uses the matching `on-*` alias:
+
+```css
+.saas-button-primary {
+  background: var(--saas-primary);
+  color: var(--saas-on-primary);
+}
+
+.saas-badge-warning {
+  background: var(--saas-warning);
+  color: var(--saas-on-warning);
+}
+```
+
 ## Override example
 
 ```css
 /* Consumer CSS is unlayered, so it overrides the library's layered rules cleanly. */
 [data-ui="minimal-saas"][data-theme="arctic-indigo"] {
   --saas-radius-md: 1rem;
-  --saas-primary-rgb: 72 91 255;
+  --saas-font-sans: Inter, system-ui, sans-serif;
+  --saas-font-display: Inter, system-ui, sans-serif;
+}
+
+:where([data-ui][data-theme="arctic-indigo"][data-mode="light"]) {
+  --usk-primary-rgb: 72 91 255;
+  --usk-primary-hover-rgb: 55 75 230;
+  --usk-primary-text-rgb: 255 255 255;
 }
 ```
+
+## 2.x compatibility notes
+
+- Component-facing prefixed tokens remain available.
+- Concrete color authoring moved to `--usk-*` shared roles.
+- Bundled CSS inlines `theme-colors.css`; standalone style files import it.
+- If a consumer build system ignores CSS `@import`, import `ui-style-kit-css/theme-colors.css` before the standalone style file.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ui-style-kit-css",
-  "version": "1.2.2",
+  "version": "2.0.2",
   "description": "CSS theme and UI style preset library for accessible websites, dashboards, admin interfaces, and client-facing pages.",
   "style": "dist/ui-style-kit.css",
   "main": "dist/ui-style-kit.css",
@@ -61,6 +61,14 @@
     "./dist/ui-style-kit.css": "./dist/ui-style-kit.css",
     "./dist/ui-style-kit.min.css": "./dist/ui-style-kit.min.css",
     "./package.json": "./package.json",
+    "./styles/theme-colors": "./styles/theme-colors.css",
+    "./styles/theme-colors.css": "./styles/theme-colors.css",
+    "./theme-colors": "./styles/theme-colors.css",
+    "./theme-colors.css": "./styles/theme-colors.css",
+    "./styles/native-elements": "./styles/native-elements.css",
+    "./styles/native-elements.css": "./styles/native-elements.css",
+    "./native-elements": "./styles/native-elements.css",
+    "./native-elements.css": "./styles/native-elements.css",
     "./styles/minimal-saas": "./styles/minimal-saas.css",
     "./styles/minimal-saas.css": "./styles/minimal-saas.css",
     "./minimal-saas": "./styles/minimal-saas.css",
@@ -108,7 +116,11 @@
     "./styles/interactive-surface-bridge": "./styles/interactive-surface-bridge.css",
     "./styles/interactive-surface-bridge.css": "./styles/interactive-surface-bridge.css",
     "./interactive-surface-bridge": "./styles/interactive-surface-bridge.css",
-    "./interactive-surface-bridge.css": "./styles/interactive-surface-bridge.css"
+    "./interactive-surface-bridge.css": "./styles/interactive-surface-bridge.css",
+    "./with-bridge": "./dist/ui-style-kit.with-bridge.css",
+    "./with-bridge.css": "./dist/ui-style-kit.with-bridge.css",
+    "./dist/ui-style-kit.with-bridge.css": "./dist/ui-style-kit.with-bridge.css",
+    "./dist/ui-style-kit.with-bridge.min.css": "./dist/ui-style-kit.with-bridge.min.css"
   },
   "repository": {
     "type": "git",
@@ -123,8 +135,8 @@
   },
   "type": "module",
   "devDependencies": {
-    "@playwright/test": "^1.60.0",
-    "stylelint": "^17.12.0"
+    "@playwright/test": "~1.61.1",
+    "stylelint": "~17.14.0"
   },
   "scripts": {
     "build": "node scripts/build.mjs",
@@ -132,7 +144,7 @@
     "check:contrast": "node scripts/check-contrast.mjs",
     "check:package": "node scripts/check-package.mjs",
     "test": "npm run test:unit",
-    "test:unit": "node --test tests/package-integrity.test.js",
+    "test:unit": "node --test tests/*.test.js",
     "test:e2e": "playwright test --config playwright.config.js",
     "test:e2e:install:ci": "playwright install --with-deps chromium",
     "check": "npm run build && npm run lint && npm run test:unit && npm run check:contrast && npm run check:package",