ui-style-kit-css 1.2.1 → 2.0.1

package/CHANGELOG.md

@@ -1,138 +1,57 @@
 # Changelog
 
-All notable changes to this project will be documented in this file.
-Entries are aligned to commits merged into `main` between tagged release points.
+All notable changes to **UI Style Kit CSS** will be documented here.
 
-## [Unreleased]
+## [2.0.1] - 2026-06-22
 
-## [1.2.1] - 2026-06-01
+### Added
 
-### Changed - 1.2.1 release metadata
+- 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.
 
-- Bumped package version metadata to `1.2.1`.
-- Aligned `package-lock.json` root metadata with `package.json` at `1.2.1`.
+### Changed
 
-## [1.2.0] - 2026-06-01
+- 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.
 
-### Changed - Release stabilization
+### Breaking
 
-- Bumped package version metadata to `1.2.0`.
-- Aligned `package-lock.json` root metadata with `package.json` at `1.2.0`.
-- Updated release workflow guidance to avoid release branch version rewrites during pull request automation.
+- 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.1.3] - 2026-06-01
+## [1.2.2] - 2026-06-05
 
-### Changed - 1.1.3 release metadata
+### Added
 
-- Bumped package version metadata to `1.1.3`.
-- Aligned `package-lock.json` root metadata with `package.json` at `1.1.3`.
+- Added package exports for the optional `interactive-surface-bridge` stylesheet.
+- Added unit, lint, e2e, and dry-run pack scripts expected by CI and release workflows.
 
-## [1.1.2] - 2026-06-01
+### Changed
 
-### Fixed - Sync workflow push ambiguity
+- 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.
 
-- Fixed `git push` in `.github/workflows/sync-package-version-with-main.yml` to explicitly target branch refs, preventing potential conflicts with tag refs.
+## 0.2.0
 
-### Changed - Release metadata
+### Changed
 
-- Bumped package version metadata to `1.1.2`.
-- Aligned `package-lock.json` root metadata with `package.json` at `1.1.2`.
+- Added cascade layer wrapping to all UI style systems so consumer CSS can override the library more predictably.
+- Fixed light-mode primary button contrast for `midnight-gold` and `cyber-lime` across all UI systems.
+- Added native HTML and CSS accessibility coverage to `brutalism`, `cyberpunk`, `y2k`, and `retro-glass` for parity with the newer UI systems.
+- Added build, package, and contrast-check scripts.
+- Expanded package exports to include both extensionless and `.css` import paths.
+- Removed runtime dependencies; this is a CSS-only consumer package.
 
-## [1.1.1] - 2026-06-01
+## 0.1.0
 
-### Changed - Release readiness
-
-- Bumped package version metadata to `1.1.1` for the next publish target.
-- Aligned `package-lock.json` root metadata with `package.json` at `1.1.1`.
-- Hardened npm publish automation to validate release tag/version alignment before attempting `npm publish`.
-- Updated changelog history alignment notes to reflect tagged release progression.
-
-## [1.1.0] - 2026-06-01
-
-### Added - UI Style Kit bridge
-
-- Added `styles/interactive-surface-bridge.css` to map UI Style Kit tokens to `interactive-surface-css` token hooks.
-- Added new package export aliases:
-  - `ui-style-kit-css/interactive-surface-bridge`
-  - `ui-style-kit-css/styles/interactive-surface-bridge`
-
-### Changed - UI Style Kit bridge
-
-- Included `interactive-surface-bridge.css` in the combined `dist/ui-style-kit.css` and `dist/ui-style-kit.min.css` build pipeline.
-- Updated README and wiki setup docs with first-class cross-library integration guidance.
-- Added package integrity coverage for interactive surface bridge export and bundling.
-- Included release metadata correction commit (`chore(release): bump version to 1.0.4`) in the `1.0.4..v1.1.0` commit range.
-
-## [1.0.4] - 2026-05-26
-
-### Changed - 1.0.4
-
-- Added deployment/build prep updates across CI, publish, and release workflows (`[chore] Build deployment pieces`).
-- Synced `package.json` version from `main` (`chore: sync package.json version with main`).
-
-## [1.0.3] - 2026-05-26
-
-### Added - 1.0.3
-
-- Added `.github/workflows/npm-publish.yml` (`Add publish workflow`).
-
-### Changed - 1.0.3
-
-- Updated `package.json` version metadata and changelog formatting for the `1.0.3` line.
-- Applied pull request follow-up changelog fix (`Potential fix for pull request finding`).
-- Included `package.json` sync commits from automation (`chore: sync package.json version with main`).
-
-## [1.0.2] - 2026-05-25
-
-### Added - 1.0.2
-
-- `.github/workflows/sync-package-version-with-main.yml` to keep pull request branch versions aligned with `main`.
-- `.github/workflows/release-version-alignment.yml` to enforce matching GitHub tag, `package.json`, changelog entry, and npm publish target version.
-
-### Changed - 1.0.2
-
-- Bumped package version to `1.0.2`.
-- Upgraded `stylelint` from `16.26.1` to `17.12.0`.
-- Updated GitHub Actions in CI:
-  - `actions/checkout` from `v4` to `v6`
-  - `actions/setup-node` from `v4` to `v6`
-- Updated release alignment notes and changelog formatting during review feedback.
-
-## [1.0.1] - 2026-05-25
-
-### Fixed - 1.0.1
-
-- Patched release metadata and demo HTML (`package.json`, `index.html`) for package stability.
-
-## [1.0.0] - 2026-05-24
-
-### Added - 1.0.0
-
-- Full project wiki under `wiki/`
-- `CODE_OF_CONDUCT.md`
-- SEO support files for GitHub Pages demo:
-  - `robots.txt`
-  - `sitemap.xml`
-  - `site.webmanifest`
-  - `browserconfig.xml`
-  - `.nojekyll`
-  - `logo.png`
-  - `assets/seo/social-card.png`
-- `llms.txt`
-- Professional repository scaffolding:
-  - `CONTRIBUTING.md`
-  - `SECURITY.md`
-  - `.editorconfig`
-  - `.gitattributes`
-  - `.github/workflows/ci.yml`
-  - GitHub issue and pull request templates
-  - Dependabot config
-- Stylelint configuration:
-  - `.stylelintrc.json`
-  - `.stylelintignore`
-  - package scripts and dev dependencies
-
-### Changed - 1.0.0
-
-- Expanded `index.html` with comprehensive SEO, social metadata, and JSON-LD structured data.
-- Updated README with quality, community, and SEO sections.
+- Initial library package with 11 UI style systems, 10 shared color themes, and light/dark/contrast modes.

package/CONTRIBUTING.md

@@ -0,0 +1,25 @@
+# Contributing
+
+## Local workflow
+
+```bash
+npm install
+npm run check
+```
+
+The library is CSS-only for consumers. Build and validation scripts run with Node and do not create runtime dependencies for package users.
+
+## Adding or changing a style system
+
+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
+
+- Patch: CSS fixes, docs fixes, small accessibility corrections.
+- Minor: new UI style, new theme, new public utility classes.
+- Major: breaking token names, class names, mode names, or import paths.

package/README.md

@@ -1,123 +1,95 @@
 # UI Style Kit CSS
 
-**UI Style Kit CSS** is a CSS-only theme and visual style preset library for standardizing websites, dashboards, admin tools, and customer-facing pages.
+**UI Style Kit CSS** is a CSS-only theme and UI style preset library for accessible websites, dashboards, admin interfaces, and customer-facing pages.
 
-It is designed to be separate from, but complementary to, **Interactive Surface CSS**. Use this library for visual identity, color themes, UI style presets, and native HTML coverage. Use Interactive Surface CSS for interaction-state animation systems and surface behavior.
+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
-- one combined CSS entry file
-- optional per-style CSS files
-- CSS-only native HTML element coverage
-- visible focus states
-- reduced-motion support
-- high-contrast and forced-colors support
-- print styles
-- NPM/CDN-friendly package structure
-
-## Wiki
-
-Extended documentation lives in [`wiki/`](wiki/):
-
-- [`wiki/Home.md`](wiki/Home.md)
-- [`wiki/Installation-and-Setup.md`](wiki/Installation-and-Setup.md)
-- [`wiki/Theming-Model.md`](wiki/Theming-Model.md)
-- [`wiki/Class-API.md`](wiki/Class-API.md)
-- [`wiki/UI-Systems.md`](wiki/UI-Systems.md)
-- [`wiki/Accessibility.md`](wiki/Accessibility.md)
-
-## Community
-
-- [Code of Conduct](CODE_OF_CONDUCT.md)
-- [Contributing Guide](CONTRIBUTING.md)
-- [Security Policy](SECURITY.md)
-
-## Quality
-
-```bash
-npm install
-npm run build
-npm run lint:css
-npm test
-```
+- 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
+- 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
 
-Run Playwright tests:
-
-```bash
-npm run test:e2e:install
-npm run test:e2e
-```
-
-Auto-fix style issues:
-
-```bash
-npm run lint:css:fix
-```
-
-Full release gate:
+## Install
 
 ```bash
-npm run verify
+npm install ui-style-kit-css
 ```
 
-## Demo SEO Files
-
-The demo page includes production SEO/social metadata plus supporting files for GitHub Pages:
-
-- `index.html` comprehensive metadata + JSON-LD
-- `robots.txt`
-- `sitemap.xml`
-- `site.webmanifest`
-- `browserconfig.xml`
-- `.nojekyll`
-- `logo.png`
-- `assets/seo/social-card.png`
+## Import
 
-## Install
+Use a single style import for production apps that use one visual system:
 
-```bash
-npm install ui-style-kit-css
+```js
+import "ui-style-kit-css/minimal-saas.css";
 ```
 
-## Import
+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/dist/ui-style-kit.css";
+import "ui-style-kit-css/theme-colors.css";
+import "ui-style-kit-css/native-elements.css";
+import "ui-style-kit-css/minimal-saas.css";
 ```
 
-Or import one style system only:
+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";
 ```
 
-## Integration with Interactive Surface CSS
-
-This package now ships with an integration bridge for `interactive-surface-css`.
+Use the full bundle when users need to switch `data-ui` systems at runtime:
 
-If you import the combined build (`dist/ui-style-kit.css`), the bridge is already included.
+```js
+import "ui-style-kit-css/dist/ui-style-kit.css";
+```
 
-If you import individual style files, also import the bridge file:
+Use the opt-in bridge bundle when you want UI Style Kit CSS and the Interactive Surface bridge in one import:
 
 ```js
-import "interactive-surface-css/interactive-surface.css";
-import "ui-style-kit-css/styles/minimal-saas.css";
-import "ui-style-kit-css/styles/interactive-surface-bridge.css";
+import "ui-style-kit-css/with-bridge.css";
 ```
 
-Shortcut export path:
+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 bridge maps active `data-ui`, `data-theme`, and `data-mode` tokens to `.interactive-surface` tokens, including variant tokens (`variant-primary`, `variant-secondary`, etc.) and focus/icon color hooks.
+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 |
 
-## Browser / CDN usage
+## CDN usage
 
 After publishing to NPM:
 
@@ -125,10 +97,10 @@ After publishing to NPM:
 <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/ui-style-kit-css@latest/dist/ui-style-kit.min.css" />
 ```
 
-Local usage:
+For production, pin a version:
 
 ```html
-<link rel="stylesheet" href="dist/ui-style-kit.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
@@ -140,86 +112,166 @@ Local usage:
       <article class="saas-card">
         <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>
 </body>
 ```
 
+## Dynamic switching
+
+```js
+document.body.dataset.ui = "cyberpunk";
+document.body.dataset.theme = "midnight-gold";
+document.body.dataset.mode = "dark";
+```
+
 ## UI systems
 
-| UI style | `data-ui` | Class prefix |
-| --- | ---: | ---: |
-| Minimal SaaS | `minimal-saas` | `saas` |
-| Bento UI | `bento` | `bento` |
-| Maximalist / Playful | `maximalist` | `max` |
-| Bauhaus / Swiss Modern | `bauhaus` | `bau` |
-| Skeuomorphic / Tactile | `tactile` | `tactile` |
-| Neumorphism | `neumorphism` | `neo` |
-| Retrofuturism | `retrofuturism` | `retro` |
-| Brutalism | `brutalism` | `brutal` |
-| Cyberpunk | `cyberpunk` | `cyber` |
-| Y2K | `y2k` | `y2k` |
-| Retro Glass | `retro-glass` | `rg` |
+| UI style | `data-ui` | Class prefix | Best for |
+|---|---:|---:|---|
+| Minimal SaaS | `minimal-saas` | `saas` | dashboards, admin tools, SaaS apps |
+| Bento UI | `bento` | `bento` | landing pages, feature sections, showcases |
+| Maximalist / Playful | `maximalist` | `max` | creators, entertainment, bold client sites |
+| Bauhaus / Swiss Modern | `bauhaus` | `bau` | agencies, editorial layouts, design-forward brands |
+| Skeuomorphic / Tactile | `tactile` | `tactile` | premium tactile interfaces, control panels |
+| Neumorphism | `neumorphism` | `neo` | soft dashboards, experimental UI |
+| Retrofuturism | `retrofuturism` | `retro` | futuristic portfolios and product pages |
+| Brutalism | `brutalism` | `brutal` | bold creative websites |
+| Cyberpunk | `cyberpunk` | `cyber` | security, gaming, encryption, tech demos |
+| Y2K | `y2k` | `y2k` | nostalgic, playful, fashion/music/event sites |
+| Retro Glass | `retro-glass` | `rg` | futuristic glass dashboards and hero sections |
 
 ## Color themes
 
-- `midnight-gold`
-- `ocean-steel`
-- `forest-moss`
-- `sunset-ember`
-- `royal-plum`
-- `graphite-cyan`
-- `desert-sage`
-- `rose-quartz`
-- `cyber-lime`
-- `arctic-indigo`
+```txt
+midnight-gold
+ocean-steel
+forest-moss
+sunset-ember
+royal-plum
+graphite-cyan
+desert-sage
+rose-quartz
+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
 
-- `light`
-- `dark`
-- `contrast`
+```txt
+light
+dark
+contrast
+```
 
-## Dynamic switching
+## Native HTML coverage
 
-```js
-document.body.dataset.ui = "cyberpunk";
-document.body.dataset.theme = "midnight-gold";
-document.body.dataset.mode = "dark";
+`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.
+
+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`, `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-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
 ui-style-kit-css/
   package.json
   README.md
-  CONTRIBUTING.md
-  SECURITY.md
-  CODE_OF_CONDUCT.md
   LICENSE
-  index.html
-  logo.png
-  llms.txt
-  robots.txt
-  sitemap.xml
-  site.webmanifest
-  browserconfig.xml
-  assets/
-    seo/
-      social-card.png
-  .stylelintrc.json
-  .stylelintignore
-  .editorconfig
-  .gitattributes
-  .github/
-    workflows/
-      ci.yml
+  CHANGELOG.md
+  STYLE-MAP.md
   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
@@ -231,28 +283,32 @@ ui-style-kit-css/
     cyberpunk.css
     y2k.css
     retro-glass.css
-  wiki/
-    Home.md
-    Installation-and-Setup.md
-    Theming-Model.md
-    Class-API.md
-    UI-Systems.md
-    Accessibility.md
+    interactive-surface-bridge.css
+  docs/
+    TOKENS.md
+    STYLE-GUIDE.md
+    PUBLISHING.md
+  demo/
+    index.html
+```
+
+## Development checks
+
+```bash
+npm run check
+npm run pack:dry-run
 ```
 
-## Accessibility scope
+`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.
 
-UI Style Kit CSS includes CSS-only accessibility presentation helpers:
+## v2.0.1 Migration Notes
 
-- scoped native HTML defaults
-- visible `:focus-visible` styles
-- `prefers-reduced-motion` support
-- `prefers-contrast: more` support
-- `forced-colors: active` support
-- print styles
-- skip-link and visually-hidden utilities per style prefix
+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.
 
-CSS cannot guarantee accessibility by itself. Use semantic HTML, real labels, keyboard-safe JavaScript, and correct ARIA state management for interactive components.
+- 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