ui-style-kit-css 2.0.3 → 2.1.0

package/docs/ECOSYSTEM.md

@@ -0,0 +1,59 @@
+# Ecosystem Compatibility
+
+UI Style Kit CSS is the visual layer in the three-library CSS ecosystem. It can run alone, but it also has stable integration points for Interactive Surface CSS and Layout Style CSS.
+
+## Aligned Versions
+
+| Library | Current aligned version | Owns |
+|---|---:|---|
+| `ui-style-kit-css@2.1.0` | staged source target | visual identity, color themes, UI paint, native HTML styling, content wrapping, and bridge tokens |
+| `interactive-surface-css@1.5.0` | published release | interaction-state primitives, surface behavior, state layers, and input affordances |
+| `layout-style-css@2.1.0` | staged source target | structural wrappers, grids, sections, app shells, and layout recipes |
+
+UI Style Kit `2.1.0` and Layout Style `2.1.0` remain staged source targets until approved release steps complete. Interactive Surface `1.5.0` is the released companion state engine for this upgrade path.
+
+## Adoption Paths
+
+### Use one
+
+Use UI Style Kit by itself when an app needs visual identity, theme roles, native element styling, and long-text containment without layout primitives or richer interaction-state behavior.
+
+```js
+import "ui-style-kit-css/minimal-saas.css";
+```
+
+### Use two
+
+Pair UI Style Kit with Interactive Surface CSS when controls need the sibling interaction-state primitives. Import UI paint first, its public token bridge second, and the sibling state core third.
+
+```js
+import "ui-style-kit-css/visual/minimal-saas.css";
+import "ui-style-kit-css/interactive-surface-theme.css";
+import "interactive-surface-css/state-core.css";
+```
+
+Pair UI Style Kit with Layout Style CSS when the app already has interaction behavior but needs structural wrappers, grids, and sections.
+
+```js
+import "ui-style-kit-css/visual/minimal-saas.css";
+import "layout-style-css";
+```
+
+### Use all three
+
+Use all three libraries when a project needs structural layout, visual styling, and interaction-state behavior in separate layers.
+
+```js
+import "ui-style-kit-css/visual.css";
+import "ui-style-kit-css/interactive-surface-theme.css";
+import "interactive-surface-css/state-core.css";
+import "layout-style-css";
+```
+
+## Ownership Boundaries
+
+- UI Style Kit CSS owns visual identity, color themes, UI paint, scoped native element styling, content wrapping, and the bridge token mapping.
+- Interactive Surface CSS owns interaction-state semantics, input affordances, state layers, and surface behavior.
+- Layout Style CSS owns structural wrappers, layout recipes, grids, app shells, and section composition.
+
+The canonical theme bridge does not make Interactive Surface a dependency of UI Style Kit. It only maps shared `--usk-*` roles to `--interactive-surface-*` tokens and provides paint; `state-core.css` continues to own interaction mechanics. The older `interactive-surface-bridge` and `with-bridge` exports are deprecated compatibility paths whose stateful behavior remains unchanged.

package/docs/NATIVE-ELEMENTS.md

@@ -0,0 +1,52 @@
+# Native Element Coverage
+
+UI Style Kit uses a hybrid-native policy: it themes safe element boxes and exposed subparts, uses `accent-color` and `color-scheme` as fallbacks, and leaves inaccessible browser popups to the platform.
+
+## Classification
+
+| Classification | Elements and surfaces |
+|---|---|
+| Fully themed | `html`, `body`, `main`, `section`, `header`, `footer`, `nav`, `article`, `aside`, `address`, `form`, `fieldset`, `legend`, `label`, `input`, `textarea`, `select`, `button`, `table`, `caption`, `thead`, `tbody`, `tfoot`, `tr`, `th`, `td`, `details`, `summary`, `dialog`, `progress`, `meter`, `menu`, `search`, headings `h1`-`h6`, `hgroup`, paragraphs, lists, definition lists, blockquotes, `code`, `kbd`, `samp`, `pre`, `mark`, `abbr`, `strong`, `b`, `em`, `i`, `cite`, `var`, `q`, `ins`, `del`, `s`, `u`, `sub`, `sup`, `output`, `time`, `data`, `dfn`, `ruby`, `rt`, `rp`, `bdi`, and `bdo` |
+| Progressively enhanced | `img`, `picture`, `video`, `audio`, `canvas`, `svg`, `math`, `iframe`, `object`, `embed`, `map`, `area`, `col`, `colgroup`, `optgroup`, `option`, `slot`, `selectedcontent`, `br`, and `wbr` |
+| Platform-owned | `select` popup, `datalist popup`, color picker dialog, date/time picker dialogs, native media controls, autofill menus, spellcheck menus, and operating-system file pickers |
+| Non-rendered | `base`, `datalist`, `head`, `link`, `meta`, `noscript`, `script`, `source`, `style`, `template`, `title`, and `track` |
+
+`selectedcontent` is classified as progressive enhancement because support is still emerging. `datalist` remains non-rendered; the input box is themed, but the datalist popup is platform-owned.
+
+## Exposed Subparts
+
+The native layer styles safely exposed parts where engines allow it:
+
+- placeholder text
+- file selector buttons, including hover, focus, active, and disabled states
+- range tracks and thumbs
+- color swatches
+- progress and meter tracks and values
+- calendar picker indicators
+- search cancellation controls
+- number spinners
+- select picker indicators where supported
+- summary and list markers
+- supported scrollbars
+
+## Native Tokens
+
+Preset files map existing `--usk-native-*` roles through their active visual system. The shared native layer also defines these sizing and paint tokens:
+
+```css
+--usk-native-control-min-block-size
+--usk-native-control-padding-block
+--usk-native-control-padding-inline
+--usk-native-subcontrol-padding-block
+--usk-native-subcontrol-padding-inline
+--usk-native-border-width
+--usk-native-field-gap
+--usk-native-panel-padding
+--usk-native-track
+--usk-native-track-fill
+--usk-native-thumb
+--usk-native-thumb-border
+--usk-native-indicator
+```
+
+Invalid paint activates only through `[aria-invalid="true"]`, `.is-invalid`, or `:user-invalid`. Required empty controls do not get danger paint before user interaction.

package/docs/PUBLISHING.md

@@ -3,21 +3,36 @@
 ## Dry run
 
 ```bash
-npm run check
-npm run pack:dry-run
+npm run release:verify
 ```
 
-`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.
+`npm run release:verify` is the non-publishing release gate. It runs `npm run check`, `npm run test:e2e`, `npm run test:axe`, `npm run test:visual`, `npm run test:matrix`, `npm run check:ecosystem:packs`, `npm audit --audit-level=moderate`, and `npm run pack:dry-run`.
+
+`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. Browser gates cover regular demo flows, representative Axe scans, curated visual smoke checks, and the sharded 990-combination matrix. `npm run check:ecosystem:packs` verifies standalone, pairwise, and all-three packed package compatibility for the canonical visual/theme/state/layout imports and the deprecated bridge imports. `npm run pack:dry-run` shows the exact files that would publish.
+
+By default, `npm run check:ecosystem:packs` packs this repository, packs the sibling `../Layout-Style-CSS` checkout, and packs the published `interactive-surface-css@1.5.0` artifact. Use `-- --layout-repo <path>` or `-- --interactive-spec <specifier>` when validating a different local Layout Style checkout or a different Interactive Surface package source.
+
+`npm run build` uses exactly pinned CSS Tree parsing and Lightning CSS formatting/minification. Generated minified bundles retain the release banner while preserving grammar-sensitive selector and `calc()` whitespace.
 
 The npm artifact is library-focused: `dist/`, `styles/`, docs, and metadata. Demo pages, favicon source assets, and social preview images remain checked in for GitHub Pages but are excluded from the tarball to keep package installs small.
 
 ## Publish
 
+No package, tag, or registry release occurs without explicit approval.
+
+For this ecosystem upgrade, use the approval-gated rollout order below:
+
+1. Release `ui-style-kit-css@2.0.4` as the correctness hotfix from the merged hotfix content on `origin/main`. The 2.0.4 hotfix release line must pass `npm run release:verify` before any tag or publish step.
+2. Confirm the already published `interactive-surface-css@1.5.0` companion state engine remains available from npm.
+3. Release `ui-style-kit-css@2.1.0` after the hotfix is live.
+4. Release `layout-style-css@2.1.0` after UI Style Kit 2.1 is live and Layout replaces its temporary GitHub UI fixture with the registry package.
+5. Run the final all-three packed compatibility suite against the published packages.
+
 ```bash
 npm publish
 ```
 
-For GitHub releases, create or dispatch a release for the matching package tag, such as `v2.0.3`. The release workflows verify that `package.json`, `package-lock.json`, `CHANGELOG.md`, and generated dist banners are aligned before publishing.
+`prepublishOnly` runs `npm run release:verify`, so a direct `npm publish` still has the full release gate. For GitHub releases, create or dispatch a release for the matching package tag, such as `v2.1.0`. The release workflows verify that `package.json`, `package-lock.json`, `CHANGELOG.md`, and generated dist banners are aligned before publishing.
 
 ## Versioning
 

package/docs/TOKENS.md

@@ -142,6 +142,19 @@ Native HTML coverage is shared in `styles/native-elements.css` to avoid repeatin
 --usk-native-radius-sm
 --usk-native-radius
 --usk-native-radius-lg
+--usk-native-border-width
+--usk-native-field-gap
+--usk-native-panel-padding
+--usk-native-control-min-block-size
+--usk-native-control-padding-block
+--usk-native-control-padding-inline
+--usk-native-subcontrol-padding-block
+--usk-native-subcontrol-padding-inline
+--usk-native-track
+--usk-native-track-fill
+--usk-native-thumb
+--usk-native-thumb-border
+--usk-native-indicator
 --usk-native-shadow
 --usk-native-shadow-md
 --usk-native-focus-ring

package/manifest.json

@@ -0,0 +1,436 @@
+{
+  "schemaVersion": 1,
+  "name": "ui-style-kit-css",
+  "version": "2.1.0",
+  "cascadeLayers": [
+    "ui-style-kit.theme_colors",
+    "ui-style-kit.native_elements",
+    "ui-style-kit.components",
+    "ui-style-kit.presets",
+    "ui-style-kit.compat_layout"
+  ],
+  "presets": [
+    {
+      "id": "minimal-saas",
+      "label": "Minimal SaaS",
+      "prefix": "saas",
+      "entrypoints": {
+        "default": "./minimal-saas.css",
+        "visual": "./visual/minimal-saas.css"
+      }
+    },
+    {
+      "id": "bento",
+      "label": "Bento UI",
+      "prefix": "bento",
+      "entrypoints": {
+        "default": "./bento.css",
+        "visual": "./visual/bento.css"
+      }
+    },
+    {
+      "id": "maximalist",
+      "label": "Maximalist / Playful",
+      "prefix": "max",
+      "entrypoints": {
+        "default": "./maximalist.css",
+        "visual": "./visual/maximalist.css"
+      }
+    },
+    {
+      "id": "bauhaus",
+      "label": "Bauhaus / Swiss Modern",
+      "prefix": "bau",
+      "entrypoints": {
+        "default": "./bauhaus.css",
+        "visual": "./visual/bauhaus.css"
+      }
+    },
+    {
+      "id": "tactile",
+      "label": "Skeuomorphic / Tactile",
+      "prefix": "tactile",
+      "entrypoints": {
+        "default": "./tactile.css",
+        "visual": "./visual/tactile.css"
+      }
+    },
+    {
+      "id": "neumorphism",
+      "label": "Neumorphism",
+      "prefix": "neo",
+      "entrypoints": {
+        "default": "./neumorphism.css",
+        "visual": "./visual/neumorphism.css"
+      }
+    },
+    {
+      "id": "retrofuturism",
+      "label": "Retrofuturism",
+      "prefix": "retro",
+      "entrypoints": {
+        "default": "./retrofuturism.css",
+        "visual": "./visual/retrofuturism.css"
+      }
+    },
+    {
+      "id": "brutalism",
+      "label": "Brutalism",
+      "prefix": "brutal",
+      "entrypoints": {
+        "default": "./brutalism.css",
+        "visual": "./visual/brutalism.css"
+      }
+    },
+    {
+      "id": "cyberpunk",
+      "label": "Cyberpunk",
+      "prefix": "cyber",
+      "entrypoints": {
+        "default": "./cyberpunk.css",
+        "visual": "./visual/cyberpunk.css"
+      }
+    },
+    {
+      "id": "y2k",
+      "label": "Y2K",
+      "prefix": "y2k",
+      "entrypoints": {
+        "default": "./y2k.css",
+        "visual": "./visual/y2k.css"
+      }
+    },
+    {
+      "id": "retro-glass",
+      "label": "Retro Glass",
+      "prefix": "rg",
+      "entrypoints": {
+        "default": "./retro-glass.css",
+        "visual": "./visual/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"
+  ],
+  "nativeElements": {
+    "fullyThemed": [
+      "a",
+      "abbr",
+      "address",
+      "article",
+      "aside",
+      "b",
+      "bdi",
+      "bdo",
+      "blockquote",
+      "body",
+      "button",
+      "caption",
+      "cite",
+      "code",
+      "data",
+      "dd",
+      "del",
+      "details",
+      "dfn",
+      "dialog",
+      "div",
+      "dl",
+      "dt",
+      "em",
+      "fieldset",
+      "figcaption",
+      "figure",
+      "footer",
+      "form",
+      "h1",
+      "h2",
+      "h3",
+      "h4",
+      "h5",
+      "h6",
+      "header",
+      "hgroup",
+      "hr",
+      "html",
+      "i",
+      "input",
+      "ins",
+      "kbd",
+      "label",
+      "legend",
+      "li",
+      "main",
+      "mark",
+      "menu",
+      "meter",
+      "nav",
+      "ol",
+      "output",
+      "p",
+      "pre",
+      "progress",
+      "q",
+      "rp",
+      "rt",
+      "ruby",
+      "s",
+      "samp",
+      "search",
+      "section",
+      "select",
+      "small",
+      "span",
+      "strong",
+      "sub",
+      "summary",
+      "sup",
+      "table",
+      "tbody",
+      "td",
+      "textarea",
+      "tfoot",
+      "th",
+      "thead",
+      "time",
+      "tr",
+      "u",
+      "ul",
+      "var"
+    ],
+    "progressivelyEnhanced": [
+      "area",
+      "audio",
+      "br",
+      "canvas",
+      "col",
+      "colgroup",
+      "embed",
+      "iframe",
+      "img",
+      "map",
+      "math",
+      "object",
+      "optgroup",
+      "option",
+      "picture",
+      "selectedcontent",
+      "slot",
+      "svg",
+      "video",
+      "wbr"
+    ],
+    "platformOwned": [
+      "audio-controls",
+      "color-picker-dialog",
+      "datalist-popup",
+      "date-time-picker-dialog",
+      "select-popup",
+      "video-controls"
+    ],
+    "nonRendered": [
+      "base",
+      "datalist",
+      "head",
+      "link",
+      "meta",
+      "noscript",
+      "script",
+      "source",
+      "style",
+      "template",
+      "title",
+      "track"
+    ]
+  },
+  "classApi": {
+    "universalVisualSuffixes": [
+      "alert",
+      "alert-body",
+      "alert-danger",
+      "alert-success",
+      "alert-title",
+      "alert-warning",
+      "badge",
+      "badge-danger",
+      "badge-primary",
+      "badge-secondary",
+      "badge-success",
+      "badge-warning",
+      "bg-primary",
+      "bg-secondary",
+      "border",
+      "button",
+      "button-danger",
+      "button-ghost",
+      "button-pill",
+      "button-primary",
+      "button-secondary",
+      "card",
+      "check",
+      "check-control",
+      "copy",
+      "disabled",
+      "divider",
+      "field",
+      "heading",
+      "help-text",
+      "hover-lift",
+      "icon-button",
+      "input",
+      "inset",
+      "kicker",
+      "label",
+      "loading-spinner",
+      "nav",
+      "nav-link",
+      "panel",
+      "pill",
+      "progress",
+      "progress-bar",
+      "radio",
+      "radio-control",
+      "rounded",
+      "rounded-lg",
+      "rounded-xl",
+      "select",
+      "skip-link",
+      "spinner",
+      "spinner-lg",
+      "spinner-sm",
+      "sr-only",
+      "subtitle",
+      "surface",
+      "surface-lg",
+      "surface-sm",
+      "switch",
+      "switch-thumb",
+      "switch-track",
+      "table",
+      "table-wrap",
+      "text-accent",
+      "text-danger",
+      "text-muted",
+      "text-primary",
+      "text-secondary",
+      "text-success",
+      "text-warning",
+      "textarea",
+      "title",
+      "toolbar",
+      "tooltip",
+      "tooltip-arrow",
+      "tooltip-bottom",
+      "tooltip-left",
+      "tooltip-right",
+      "tooltip-top",
+      "visually-hidden",
+      "well"
+    ],
+    "presetExtras": {
+      "minimal-saas": [
+        "empty-state",
+        "metric",
+        "metric-label",
+        "metric-value"
+      ],
+      "bento": [
+        "grid-feature",
+        "stat",
+        "stat-label",
+        "stat-value",
+        "tile",
+        "tile-lg",
+        "tile-md",
+        "tile-sm"
+      ],
+      "maximalist": [
+        "callout",
+        "sticker",
+        "wiggle"
+      ],
+      "bauhaus": [
+        "block",
+        "composition",
+        "rail"
+      ],
+      "tactile": [
+        "bevel",
+        "knob",
+        "pressed"
+      ],
+      "neumorphism": [],
+      "retrofuturism": [],
+      "brutalism": [
+        "pressed"
+      ],
+      "cyberpunk": [
+        "console"
+      ],
+      "y2k": [
+        "bubble"
+      ],
+      "retro-glass": [
+        "console"
+      ]
+    },
+    "deprecatedStructuralSuffixes": [
+      "page",
+      "container",
+      "section",
+      "grid",
+      "stack",
+      "cluster",
+      "split"
+    ]
+  },
+  "nativeParts": {
+    "standard": [
+      "accent-color",
+      "color-scheme",
+      "dialog-backdrop",
+      "file-selector-button",
+      "list-marker",
+      "placeholder",
+      "selection",
+      "summary-marker"
+    ],
+    "vendorSpecific": [
+      "calendar-picker-indicator",
+      "color-swatch",
+      "number-spinner",
+      "progress-track",
+      "progress-value",
+      "range-thumb",
+      "range-track",
+      "scrollbar",
+      "search-cancel-button",
+      "select-indicator"
+    ],
+    "platformOwned": [
+      "color-picker-dialog",
+      "datalist-popup",
+      "date-time-picker-dialog",
+      "select-option-rendering",
+      "select-popup"
+    ],
+    "nonRendered": [
+      "datalist"
+    ]
+  }
+}