ui-style-kit-css 1.2.2 → 2.0.1

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 All notable changes to **UI Style Kit CSS** will be documented here.
 
+## [2.0.1] - 2026-06-22
+
+### Added
+
+- Added visible tooltip utilities for every UI preset through `<prefix>-tooltip`, `<prefix>-tooltip-arrow`, `.ui-tooltip`, `[role="tooltip"]`, and `[data-tooltip]`.
+- Added demo coverage for tooltips, switch-style Interactive Surface bridge controls, padded table showcases, combined controls/loading/progress displays, and more useful utility samples.
+- Added the exported `native-elements.css` shared fallback layer for standalone style imports.
+
+### Changed
+
+- Aligned package metadata, generated dist banners, and release documentation to publish from the `v2.0.1` tag after the previous release tag was retired.
+- Moved concrete color scheme values into the shared `styles/theme-colors.css` layer.
+- Updated all UI systems to alias shared `--usk-*` RGB roles back to their public style prefixes.
+- Reduced generated bundle size by removing duplicated per-UI color scheme blocks from `dist`.
+- Kept prefixed functional tokens such as `--saas-primary`, `--neo-card-bg`, and `--rg-on-primary` for component styling.
+- Refactored the Interactive Surface bridge to inherit shared `--usk-*` roles, expose visible hover/active/focus state layers, and support `data-surface-level="1"`, `"2"`, and `"3"` surface depth hooks.
+- Moved the bridge attach switch into the demo bridge section so the opt-in behavior is documented where it is exercised.
+- Refactored native HTML fallback rules into one shared `styles/native-elements.css` layer while each preset now supplies only visual token mappings through `--usk-native-*`.
+- Polished the demo component layout at desktop, tablet, and square viewports with denser controls, richer badge examples, padded native controls, and balanced showcase rows.
+- Moved the demo Usage section to match the primary navigation order and tightened the mobile controls showcase into a readable single-column flow.
+- Updated the Interactive Surface bridge docs to keep the bridge opt-in while `interactive-surface-css` is revised separately.
+
+### Breaking
+
+- Concrete scheme overrides should now target shared `--usk-*-rgb` roles instead of redefining one copy per UI prefix.
+- Standalone style imports rely on `styles/theme-colors.css` and `styles/native-elements.css`; import those shared layers first if your CSS pipeline does not resolve `@import`.
+
 ## [1.2.2] - 2026-06-05
 
 ### Added
@@ -11,7 +38,7 @@ All notable changes to **UI Style Kit CSS** will be documented here.
 
 ### Changed
 
-- Bundled the interactive surface bridge into the generated dist CSS.
+- Added generated `with-bridge` dist CSS for consumers that want the Interactive Surface bridge in the same import.
 - Aligned release metadata, package checks, and documentation for the `1.2.2` release.
 
 ## 0.2.0

package/CONTRIBUTING.md

@@ -11,11 +11,12 @@ The library is CSS-only for consumers. Build and validation scripts run with Nod
 
 ## Adding or changing a style system
 
-1. Keep the public `data-ui`, `data-theme`, and `data-mode` API stable.
-2. Preserve class prefixes.
-3. Include the native HTML coverage and accessibility layer.
-4. Run `npm run check` before publishing.
-5. Update `STYLE-MAP.md`, `docs/TOKENS.md`, and `CHANGELOG.md` for public API changes.
+1. Keep the public `data-ui`, `data-theme`, and `data-mode` API stable unless preparing a documented major version.
+2. Preserve class prefixes and prefixed functional tokens.
+3. Define concrete color scheme values in `styles/theme-colors.css` as shared `--usk-*` roles; UI style files should only alias those roles and define visual treatment.
+4. Include the native HTML coverage and accessibility layer.
+5. Run `npm run check` before publishing.
+6. Update `STYLE-MAP.md`, `docs/TOKENS.md`, `README.md`, wiki pages, and `CHANGELOG.md` for public API changes.
 
 ## Versioning
 

package/README.md

@@ -4,16 +4,25 @@
 
 It is separate from, but complementary to, **Interactive Surface CSS**. Use **UI Style Kit CSS** for visual identity, color themes, UI presets, layout mood, and native HTML styling. Use **Interactive Surface CSS** for interaction-state animation systems and surface behavior.
 
+## Current Release
+
+`v2.0.1` is the current v2 release. It centralizes color schemes in `styles/theme-colors.css`, centralizes native HTML fallback styling in `styles/native-elements.css`, keeps style-specific component APIs prefix-bound, and ships the Interactive Surface bridge as an opt-in import.
+
 ## Features
 
 - 11 UI style systems
 - 10 shared color schemes
 - `light`, `dark`, and `contrast` modes
-- Combined CSS bundle and optional per-style imports
-- Scoped native HTML element coverage
+- Combined CSS bundle and per-style production imports
+- Shared `theme-colors.css` scheme layer and `native-elements.css` fallback layer for all UI systems
+- Scoped native HTML element coverage, including semantic containers and inline text elements
 - Visible `:focus-visible` defaults
 - Skip-link and visually-hidden helpers per style prefix
-- Optional bridge tokens for `interactive-surface-css`
+- Compact shared palette → prefixed alias → UI-rule token model
+- Theme-driven card, panel, control, page-background, and spinner defaults
+- Visible tooltip classes and native `[role="tooltip"]` styling inside each UI scope
+- Font-family override variables for body, headings, controls, and mono text
+- Optional bridge tokens, visible state layers, and an opt-in bridge bundle for `interactive-surface-css`
 - Reduced-motion, high-contrast, forced-colors, and print support
 - Cascade-layered CSS for easier consumer overrides
 - No runtime dependencies
@@ -26,32 +35,60 @@ npm install ui-style-kit-css
 
 ## Import
 
-Full bundle:
+Use a single style import for production apps that use one visual system:
 
 ```js
-import "ui-style-kit-css/dist/ui-style-kit.css";
+import "ui-style-kit-css/minimal-saas.css";
 ```
 
-Single style system:
+In `v2.0.1`, standalone style files import the shared color-scheme layer from `styles/theme-colors.css` and the shared native-element fallback layer from `styles/native-elements.css`. Bundlers that understand CSS `@import` will resolve them automatically. If your build pipeline does not resolve CSS imports, import the shared dependencies before the style file:
+
+```js
+import "ui-style-kit-css/theme-colors.css";
+import "ui-style-kit-css/native-elements.css";
+import "ui-style-kit-css/minimal-saas.css";
+```
+
+The longer `styles/*` paths are also exported:
 
 ```js
 import "ui-style-kit-css/styles/minimal-saas.css";
 import "ui-style-kit-css/styles/cyberpunk.css";
 ```
 
-Shortcut imports are also exported:
+Use the full bundle when users need to switch `data-ui` systems at runtime:
 
 ```js
-import "ui-style-kit-css/minimal-saas.css";
-import "ui-style-kit-css/retro-glass.css";
+import "ui-style-kit-css/dist/ui-style-kit.css";
 ```
 
-Optional bridge for Interactive Surface CSS:
+Use the opt-in bridge bundle when you want UI Style Kit CSS and the Interactive Surface bridge in one import:
 
 ```js
+import "ui-style-kit-css/with-bridge.css";
+```
+
+Or import the bridge by itself when you are using a single style file:
+
+```js
+import "ui-style-kit-css/minimal-saas.css";
 import "ui-style-kit-css/interactive-surface-bridge";
 ```
 
+The default full bundle does **not** include the bridge. That keeps `dist/ui-style-kit.css` focused on UI systems and prevents accidental duplicate bridge imports.
+
+When the bridge is attached, add `.interactive-surface` to interactable elements and use `data-surface-variant` plus `data-surface-level="1"`, `"2"`, or `"3"` to opt into the visible rest, hover, active, and focus treatments. The bridge inherits from shared `--usk-*` roles instead of duplicating per-theme or per-preset token maps.
+
+### Bundle size guide
+
+| Import | Raw | Gzip | Best for |
+|---|---:|---:|---|
+| `ui-style-kit-css/dist/ui-style-kit.min.css` | ~269 KB | ~34 KB | Runtime UI-system switchers and demos |
+| `ui-style-kit-css/with-bridge.css` | ~331 KB | ~39 KB | Runtime switchers plus Interactive Surface bridge |
+| `ui-style-kit-css/theme-colors.css` | ~25 KB | ~3 KB | Shared color schemes for standalone style imports |
+| `ui-style-kit-css/native-elements.css` | ~13 KB | ~2 KB | Shared native HTML fallback styling |
+| Single style imports | ~26-28 KB | ~5-6 KB | Production apps with one visual system |
+
 ## CDN usage
 
 After publishing to NPM:
@@ -63,7 +100,7 @@ After publishing to NPM:
 For production, pin a version:
 
 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/ui-style-kit-css@1.2.2/dist/ui-style-kit.min.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/ui-style-kit-css@2.0.1/dist/ui-style-kit.min.css" />
 ```
 
 ## Basic usage
@@ -76,6 +113,7 @@ For production, pin a version:
         <h1 class="saas-title">UI Style Kit CSS</h1>
         <p class="saas-subtitle">Switch UI systems, themes, and modes with attributes.</p>
         <button class="saas-button saas-button-primary">Primary Action</button>
+        <span class="saas-spinner" aria-label="Loading"></span>
       </article>
     </section>
   </main>
@@ -121,6 +159,8 @@ cyber-lime
 arctic-indigo
 ```
 
+Color schemes are defined once in `styles/theme-colors.css` as shared `--usk-*` RGB roles. Each UI style maps those shared roles back to its public prefix, so existing component rules still consume variables such as `--saas-primary`, `--bau-surface`, and `--rg-on-primary`.
+
 ## Modes
 
 ```txt
@@ -131,27 +171,90 @@ contrast
 
 ## Native HTML coverage
 
-Each style system scopes defaults under `[data-ui="..."]` and covers common native elements, including:
+`styles/native-elements.css` owns the shared native selectors under `[data-ui][data-theme][data-mode]`. Each style system maps those selectors to its visual identity through `--usk-native-*` tokens, so native controls keep the same coverage while inheriting each preset's radius, shadows, borders, typography, and color surfaces.
 
-- headings, paragraphs, links, lists, blockquotes, code, pre, mark, abbr
-- images, media, figures, captions
+The shared native layer covers common native elements, including:
+
+- semantic containers: `main`, `section`, `header`, `footer`, `nav`, `article`, `aside`, `address`
+- headings, paragraphs, links, lists, definition lists, blockquotes, code, pre, mark, abbr
+- inline semantics: `strong`, `b`, `em`, `i`, `cite`, `var`, `q`, `ins`, `del`, `s`, `sub`, `sup`, `output`, `time`, `data`, `dfn`, `ruby`, `rt`, `rp`
+- images, media, figures, captions, `audio`, `picture`, `object`, `embed`, and `math`
 - forms, fieldsets, labels, inputs, textareas, selects, checkboxes, radios, range, color, file inputs
 - buttons and submit/reset controls
 - tables and captions
-- `details`, `summary`, `dialog`, `progress`, and `meter`
+- `details`, `summary`, `dialog`, `progress`, `meter`, `menu`, `search`, `optgroup`, and `option`
+- loading indicators through `<prefix>-spinner`, `<prefix>-loading-spinner`, and busy native buttons with `aria-busy="true"`
+- tooltip surfaces through `<prefix>-tooltip`, `<prefix>-tooltip-arrow`, `.ui-tooltip`, `[role="tooltip"]`, and `[data-tooltip]`
 
 CSS improves accessibility presentation, but it cannot guarantee accessibility by itself. Use semantic HTML, real labels, keyboard-safe JavaScript, meaningful link/button text, and correct ARIA state management.
 
+Semantic text utilities such as `saas-text-primary`, `saas-text-warning`, and `saas-text-danger` use the active theme palette directly. Filled UI such as buttons, badges, and busy states use compact `on-*` aliases like `--saas-on-primary` and `--saas-on-danger`.
+
+## Loading states
+
+Every style includes theme-driven spinner utilities:
+
+```html
+<span class="saas-spinner" aria-label="Loading"></span>
+<span class="saas-loading-spinner saas-spinner-sm" aria-hidden="true"></span>
+<button class="saas-button saas-button-primary" aria-busy="true">Saving</button>
+```
+
+Spinner track, stroke, and accent colors come from the active `data-theme` and `data-mode`. The generic `.ui-spinner`, `.loading-spinner`, and `[data-loading-spinner]` hooks are also themed inside any `[data-ui="..."]` scope.
+
+## Tooltip surfaces
+
+Every style includes visible tooltip utilities with the same API and preset-specific visual treatment:
+
+```html
+<span class="saas-tooltip" role="tooltip">
+  Helpful context
+  <span class="saas-tooltip-arrow" aria-hidden="true"></span>
+</span>
+```
+
+Inside a `[data-ui="..."]` scope, generic `.ui-tooltip`, `[role="tooltip"]`, and `[data-tooltip]` hooks inherit the active UI system.
+
+## Font overrides
+
+Each style exposes backward-compatible base font variables plus more granular aliases:
+
+```css
+[data-ui="minimal-saas"] {
+  --saas-font-sans: Inter, system-ui, sans-serif;
+  --saas-font-display: Inter, system-ui, sans-serif;
+  --saas-font-body: var(--saas-font-sans);
+  --saas-font-heading: var(--saas-font-display);
+  --saas-font-control: var(--saas-font-display);
+  --saas-font-mono: "JetBrains Mono", ui-monospace, monospace;
+}
+```
+
+Override `--<prefix>-font-sans` and `--<prefix>-font-display` for the broadest changes, or override `--<prefix>-font-body`, `--<prefix>-font-heading`, `--<prefix>-font-control`, and `--<prefix>-font-mono` for targeted typography control.
+
 ## Cascade layers
 
 The library styles are wrapped in `@layer ui-style-kit.*`. Unlayered consumer CSS can override the library without specificity fights:
 
 ```css
 [data-ui="minimal-saas"][data-theme="arctic-indigo"] {
-  --saas-primary-rgb: 72 91 255;
+  --saas-radius-md: 1rem;
+  --saas-font-sans: Inter, system-ui, sans-serif;
+  --saas-font-display: Inter, system-ui, sans-serif;
+  --saas-font-body: var(--saas-font-sans);
+  --saas-font-heading: var(--saas-font-display);
+  --saas-font-control: var(--saas-font-display);
+}
+
+: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;
 }
 ```
 
+The color model is intentionally small: shared `--usk-*` RGB variables feed prefixed aliases such as `--<prefix>-bg`, `--<prefix>-text`, `--<prefix>-surface`, and `--<prefix>-border`. Filled components use `--<prefix>-on-primary`, `--<prefix>-on-secondary`, `--<prefix>-on-success`, `--<prefix>-on-warning`, and `--<prefix>-on-danger` for readable text over filled surfaces.
+
 ## File structure
 
 ```txt
@@ -164,7 +267,11 @@ ui-style-kit-css/
   dist/
     ui-style-kit.css
     ui-style-kit.min.css
+    ui-style-kit.with-bridge.css
+    ui-style-kit.with-bridge.min.css
   styles/
+    theme-colors.css
+    native-elements.css
     minimal-saas.css
     bento.css
     maximalist.css
@@ -192,7 +299,16 @@ npm run check
 npm run pack:dry-run
 ```
 
-`npm run check` rebuilds the bundle, runs stylelint, verifies package metadata, and checks core contrast pairs. Optional Playwright visual smoke tests are available through `npm run test:visual` after installing dev dependencies.
+`npm run check` rebuilds the bundles, runs stylelint, verifies package metadata, checks the documented class API, and validates contrast for base text/link pairs and filled component `on-*` pairs. Optional Playwright visual smoke tests are available through `npm run test:visual` after installing dev dependencies.
+
+## v2.0.1 Migration Notes
+
+The `v2.0.1` release line removes duplicated per-UI color-scheme blocks. Color schemes now live in `theme-colors.css` as shared `--usk-*` roles, native HTML fallback styling lives in `native-elements.css`, and each UI style aliases those shared roles back to its prefix.
+
+- Use `--usk-*-rgb` when defining or overriding a color scheme.
+- Continue using prefixed functional tokens such as `--saas-primary`, `--neo-card-bg`, and `--rg-on-primary` inside components.
+- Import `ui-style-kit-css/theme-colors.css` and `ui-style-kit-css/native-elements.css` before standalone style files if your bundler does not follow CSS `@import`.
+- Keep using `ui-style-kit-css/interactive-surface-bridge` or `ui-style-kit-css/with-bridge.css` for the opt-in bridge. The bridge now inherits shared `--usk-*` roles and exposes three `data-surface-level` visual states while the default bundle remains bridge-free.
 
 ## License
 

package/STYLE-MAP.md

@@ -2,6 +2,8 @@
 
 ## UI systems
 
+Color schemes are defined once in `styles/theme-colors.css`. Native HTML fallback selectors are defined once in `styles/native-elements.css`. Each UI system file imports both shared layers, aliases `--usk-*` RGB roles back to its prefix, and maps `--usk-native-*` tokens into the preset's visual identity.
+
 | UI style | `data-ui` | Prefix | File |
 |---|---:|---:|---|
 | Minimal SaaS | `minimal-saas` | `saas` | `styles/minimal-saas.css` |
@@ -16,6 +18,28 @@
 | Y2K | `y2k` | `y2k` | `styles/y2k.css` |
 | Retro Glass | `retro-glass` | `rg` | `styles/retro-glass.css` |
 
+## Shared color file
+
+| Purpose | Import |
+|---|---|
+| Shared color schemes and mode palettes | `styles/theme-colors.css` |
+
+## Shared native layer
+
+| Purpose | Import |
+|---|---|
+| Shared native HTML element fallback selectors | `styles/native-elements.css` |
+
+Native selectors stay generic under `[data-ui][data-theme][data-mode]`. Presets only provide token mappings such as `--usk-native-surface`, `--usk-native-radius`, and `--usk-native-shadow`, which avoids repeating the same fieldset, table, dialog, details, form, and semantic-element rules in every UI file.
+
+## Bridge bundle
+
+| Purpose | Import |
+|---|---|
+| Interactive Surface bridge tokens and state levels | `styles/interactive-surface-bridge.css` |
+
+The bridge inherits from shared `--usk-*` color roles, then applies `.interactive-surface`, `data-surface-variant`, and `data-surface-level` hooks without duplicating theme or UI preset maps.
+
 ## Themes
 
 - `midnight-gold`