ui-style-kit-css 1.2.1 → 1.2.2

package/CHANGELOG.md

@@ -1,138 +1,30 @@
 # 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]
+## [1.2.2] - 2026-06-05
 
-## [1.2.1] - 2026-06-01
+### Added
 
-### Changed - 1.2.1 release metadata
+- 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.
 
-- 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
+- Bundled the interactive surface bridge into the generated dist CSS.
+- Aligned release metadata, package checks, and documentation for the `1.2.2` release.
 
-### Changed - Release stabilization
+## 0.2.0
 
-- 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.
+### Changed
 
-## [1.1.3] - 2026-06-01
+- 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.
 
-### Changed - 1.1.3 release metadata
+## 0.1.0
 
-- Bumped package version metadata to `1.1.3`.
-- Aligned `package-lock.json` root metadata with `package.json` at `1.1.3`.
-
-## [1.1.2] - 2026-06-01
-
-### Fixed - Sync workflow push ambiguity
-
-- Fixed `git push` in `.github/workflows/sync-package-version-with-main.yml` to explicitly target branch refs, preventing potential conflicts with tag refs.
-
-### Changed - Release metadata
-
-- Bumped package version metadata to `1.1.2`.
-- Aligned `package-lock.json` root metadata with `package.json` at `1.1.2`.
-
-## [1.1.1] - 2026-06-01
-
-### 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,24 @@
+# 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.
+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.
+
+## 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,80 +1,22 @@
 # 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.
 
 ## 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
-```
-
-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:
-
-```bash
-npm run verify
-```
-
-## 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`
+- Combined CSS bundle and optional per-style imports
+- Scoped native HTML element coverage
+- Visible `:focus-visible` defaults
+- Skip-link and visually-hidden helpers per style prefix
+- Optional bridge tokens for `interactive-surface-css`
+- Reduced-motion, high-contrast, forced-colors, and print support
+- Cascade-layered CSS for easier consumer overrides
+- No runtime dependencies
 
 ## Install
 
@@ -84,40 +26,33 @@ npm install ui-style-kit-css
 
 ## Import
 
+Full bundle:
+
 ```js
 import "ui-style-kit-css/dist/ui-style-kit.css";
 ```
 
-Or import one style system only:
+Single style system:
 
 ```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`.
-
-If you import the combined build (`dist/ui-style-kit.css`), the bridge is already included.
-
-If you import individual style files, also import the bridge file:
+Shortcut imports are also exported:
 
 ```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/minimal-saas.css";
+import "ui-style-kit-css/retro-glass.css";
 ```
 
-Shortcut export path:
+Optional bridge for Interactive Surface CSS:
 
 ```js
 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.
-
-## Browser / CDN usage
+## CDN usage
 
 After publishing to NPM:
 
@@ -125,10 +60,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@1.2.2/dist/ui-style-kit.min.css" />
 ```
 
 ## Basic usage
@@ -140,53 +75,81 @@ 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>
       </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
+```
 
 ## 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";
+Each style system scopes defaults under `[data-ui="..."]` and covers common native elements, including:
+
+- headings, paragraphs, links, lists, blockquotes, code, pre, mark, abbr
+- images, media, figures, captions
+- 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`
+
+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.
+
+## 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;
+}
 ```
 
 ## File structure
@@ -195,27 +158,9 @@ document.body.dataset.mode = "dark";
 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
@@ -231,28 +176,23 @@ 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
 ```
 
-## Accessibility scope
+## Development checks
 
-UI Style Kit CSS includes CSS-only accessibility presentation helpers:
-
-- 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
+```bash
+npm run check
+npm run pack:dry-run
+```
 
-CSS cannot guarantee accessibility by itself. Use semantic HTML, real labels, keyboard-safe JavaScript, and correct ARIA state management for interactive components.
+`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.
 
 ## License
 

package/SECURITY.md

@@ -0,0 +1,18 @@
+# Security Policy
+
+UI Style Kit CSS is a CSS-only package. It does not execute client-side JavaScript and does not collect or transmit data.
+
+Report potential vulnerabilities privately via GitHub Security Advisories (Security tab → Report a vulnerability), or through the preferred private contact channel once configured.
+
+## Scope
+
+In scope:
+
+- Supply-chain/package integrity concerns
+- Malicious or unexpected files in published package contents
+- Unsafe generated demo code
+
+Out of scope:
+
+- Accessibility bugs that do not create a security issue
+- Visual rendering inconsistencies across browsers

package/STYLE-MAP.md

@@ -0,0 +1,36 @@
+# UI Style Kit CSS Style Map
+
+## UI systems
+
+| UI style | `data-ui` | Prefix | File |
+|---|---:|---:|---|
+| Minimal SaaS | `minimal-saas` | `saas` | `styles/minimal-saas.css` |
+| Bento UI | `bento` | `bento` | `styles/bento.css` |
+| Maximalist / Playful | `maximalist` | `max` | `styles/maximalist.css` |
+| Bauhaus / Swiss Modern | `bauhaus` | `bau` | `styles/bauhaus.css` |
+| Skeuomorphic / Tactile | `tactile` | `tactile` | `styles/tactile.css` |
+| Neumorphism | `neumorphism` | `neo` | `styles/neumorphism.css` |
+| Retrofuturism | `retrofuturism` | `retro` | `styles/retrofuturism.css` |
+| Brutalism | `brutalism` | `brutal` | `styles/brutalism.css` |
+| Cyberpunk | `cyberpunk` | `cyber` | `styles/cyberpunk.css` |
+| Y2K | `y2k` | `y2k` | `styles/y2k.css` |
+| Retro Glass | `retro-glass` | `rg` | `styles/retro-glass.css` |
+
+## Themes
+
+- `midnight-gold`
+- `ocean-steel`
+- `forest-moss`
+- `sunset-ember`
+- `royal-plum`
+- `graphite-cyan`
+- `desert-sage`
+- `rose-quartz`
+- `cyber-lime`
+- `arctic-indigo`
+
+## Modes
+
+- `light`
+- `dark`
+- `contrast`