UI Style Kit CSS

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 separate from, but complementary to, Interactive Surface CSS and Layout Style 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. Use Layout Style CSS for responsive layout wrappers, grid systems, macro-structure positioning, and container scaffolding.

Current release candidate

Version v2.7.0 is the current release candidate. It adds shared card and link presentation controls, repairs component spacing and message feedback, and preserves selected button variants when React combines semantic attributes with preset classes. The demo keeps its controls visible while scrolling and preserves entered values across theme changes. New markup should use .usk-*; generated .ui-* aliases remain available for existing consumers.

The exhaustive browser suite defines 20 presets × 25 themes × 3 modes × 3 engines (4,500 combinations). Run the final release gate on the frozen candidate before treating that full matrix as current verification.

The v2.4.0 baseline introduced complete native-control identities, native light/dark/contrast palettes when data-theme is omitted, a palette-aware color workbench, a unified demo with style-specific components, and exactly pinned parser-based minification. See the 2.7.0 release notes for the current scope and verification boundaries.

Showcase website

How the library fits together

UI Style Kit CSS owns visual identity: themes, semantic .usk-* component paint, native HTML styling, and the advanced prefixed class API. It can be used alone, or paired with the sibling libraries when a project needs structural layout primitives or richer interaction-state behavior.

flowchart LR
  App["Application markup"] --> Attrs["data-ui + data-mode; optional data-theme"]
  Attrs --> USK["ui-style-kit-css"]
  USK --> Themes["Shared --usk-* theme roles"]
  USK --> Components["Prefixed component classes"]
  USK --> Native["Scoped native HTML fallback"]
  Layout["layout-style-css"] --> App
  Surface["interactive-surface-css"] --> Bridge["Optional bridge bundle"]
  Bridge --> USK
  Components --> UI["Branded UI surface"]
  Native --> UI
  Themes --> UI

Loading

flowchart TB
  Theme["styles/theme-colors.css"] --> Rgb["Concrete --usk-*-rgb channels"]
  Rgb --> Modes["Light, dark, and contrast modes"]
  Modes --> Prefixes["Per-style prefixed aliases"]
  Prefixes --> Rules["Component, utility, and native rules"]
  Demo["Demo token workbench"] --> Overrides["Scoped native-palette or shared-theme overrides"]
  Overrides --> Rgb

Loading

The demo shows computed RGB colors for the active native palette or shared theme, supports live edits, and copies a scoped override block. Native mode includes preset-specific material channels such as paper, ink, and brass; shared-theme mode exposes the 23 semantic RGB roles.

The demo showcase guide explains the unified component gallery, Industrial Utility instruments, palette editing, and the opt-in ?view=reference boards. Existing ?personality=maximalist links work; ?ui=tactile&theme=None&mode=dark selects a native-palette preview.

Ecosystem compatibility

These libraries stay standalone, but the current aligned set is:

Library	Aligned version	Owns
ui-style-kit-css@2.7.0	current release candidate	visual identity, color themes, UI paint, native HTML styling, content wrapping, and bridge tokens
interactive-surface-css@1.7.3	compatible state release	interaction-state primitives, surface behavior, state layers, and input affordances
layout-style-css@3.2.3	compatible structural release	structural wrappers, grids, sections, app shells, and layout recipes

UI Style Kit 2.7.0 is the current release candidate; 2.6.1 remains the published npm release. The candidate is aligned with the reviewed Interactive Surface 1.7.3 and Layout Style 3.2.3 releases. The validated minimum remains ui-style-kit-css@2.1.0, interactive-surface-css@1.5.0, and layout-style-css@3.0.0.

Use one, two, or all three depending on the project. UI Style Kit does not require the sibling libraries, and the optional bridge only maps shared --usk-* roles into Interactive Surface tokens when consumers import it.

Every UI Style Kit visual or preset entrypoint also publishes a small, fully typed --ui-* semantic handshake. These tokens let companion libraries and third-party themes share paint, control geometry, focus, and default motion without depending on preset-specific names. They are optional fallbacks for consumers: package-specific tokens still take precedence, and standalone packages keep their existing legacy and literal defaults when the handshake is absent. See the token contract for the exact 12-token inventory.

A third-party producer can load its semantic token stylesheet before interactive-surface-css/standalone-preset.css. UI Style Kit's visual entrypoints support the same portable composition; keep the canonical theme bridge with state-core.css when specialized variant, level, and icon-role mappings are required.

For import order, ownership boundaries, and adoption paths, see the Ecosystem guide.

Features

• 20 UI style systems
• 25 shared color schemes
• light, dark, and contrast modes
• Native preset colors when no shared theme is selected
• Combined CSS bundle and canonical self-contained per-style imports
• Visual-only full and focused entrypoints for consumer-owned layouts
• Machine-readable manifest.json preset, theme, mode, class, and native-part capabilities
• Shared theme-colors.css, native-elements.css, and content-overflow.css layers 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
• Canonical token-and-paint-only theme bridge for interactive-surface-css/state-core.css
• Deprecated stateful bridge exports retained for backward compatibility
• Reduced-motion, high-contrast, forced-colors, and print support
• Cascade-layered CSS for easier consumer overrides
• No runtime dependencies

Install

npm install ui-style-kit-css

v2 distribution defaults

The default bundle remains unchanged for all v2 releases. The root package and canonical . export resolve to the readable dist/ui-style-kit.css; the canonical ./min.css export resolves to the minified dist/ui-style-kit.min.css. The focused visual/<preset>.css entrypoints remain available for applications fixed to one visual system.

ui-style-kit-css/visual.css is the recommended entrypoint when consumers own layout. Making visual.css the package default remains only a v3 proposal; no v2 export is redirected as part of that proposal.

The ./css, ./css.css, and ./min exports are redundant deprecated compatibility aliases. They remain available throughout v2 with their existing targets: ./css and ./css.css match ., while ./min matches ./min.css. New integrations should use the canonical exports.

Import

Use the generated default bundle for semantic components that can switch across every preset at runtime:

import "ui-style-kit-css";

Use ui-style-kit-css/visual.css for the same 75-selector semantic runtime API without the deprecated prefixed layout selectors. The generated default, visual, and with-bridge bundles all support all 20 data-ui values.

Applications fixed to one preset can use its canonical self-contained entrypoint. It includes the shared foundations, preset paint, and semantic aliases scoped to that preset, with no unresolved CSS @import statements:

import "ui-style-kit-css/presets/minimal-saas.css";

The existing ui-style-kit-css/visual/<preset>.css paths remain supported aliases to the same generated files.

For applications that let a user switch styles at runtime, import the all-style bundle once and update data-ui. Theme and mode remain independent attributes:

import "ui-style-kit-css";

document.documentElement.dataset.ui = "cyberpunk";
document.documentElement.dataset.theme = "arctic-indigo";
document.documentElement.dataset.mode = "dark";

The exact preset, theme, mode, class, and native-part capability matrix is available from ui-style-kit-css/manifest.json.

Advanced prefixed and raw imports

The standalone preset exports and longer styles/* paths remain advanced compatibility entrypoints. They preserve the prefixed API and do not promise multi-preset semantic switching:

import "ui-style-kit-css/minimal-saas.css";
// Equivalent raw source export:
import "ui-style-kit-css/styles/minimal-saas.css";

Compatible standalone style files continue to import the shared color-scheme, native-element fallback, content-overflow, and clean-default layers. Bundlers that understand CSS @import resolve them automatically. If your build pipeline does not resolve CSS imports, import the shared dependencies before the style file:

import "ui-style-kit-css/theme-colors.css";
import "ui-style-kit-css/native-elements.css";
import "ui-style-kit-css/content-overflow.css";
import "ui-style-kit-css/component-composition.css";
import "ui-style-kit-css/clean-defaults.css";
import "ui-style-kit-css/minimal-saas.css";

The explicit distribution path is also available for runtime switching:

import "ui-style-kit-css/dist/ui-style-kit.css";

For the canonical all-three integration, import visual paint, the token-only theme bridge, Interactive Surface state mechanics, and Layout structure in this order:

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";

The older stateful bridge and combined bundle remain public, deprecated compatibility paths. See the bridge migration guide when upgrading an existing v2 integration.

The default and visual-only bundles do not include either bridge. That keeps UI paint independent 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 resolved --usk-native-* paint pairs and radius geometry first, so both shared themes and a preset's reference palette retain matched foregrounds, backgrounds, and corner identity.

Clean defaults

Every element inside a themed UI root receives a 2px margin and padding fallback before preset-specific declarations are applied. Preset spacing still wins when it is roomier. Technical Blueprint is exempt because its drafting grammar intentionally joins controls and measured structures. Add .usk-flush (recommended) or its concise .flush alias to an element that intentionally needs zero margin and padding in every other style. Buttons and badges receive a 2px block and 4px inline padding floor when a preset does not provide roomier values.

Decorative underlines are disabled by default across UI roots. Add .usk-underline to opt an element back into an underline. Native u, ins, del, and s elements keep their semantic text decoration.

Semantic .usk-check, .usk-radio, and .usk-switch wrappers keep their native input focusable but visually hide it, leaving the authored control or switch track as the only painted affordance. Their visible controls are vertically centered and inset from the wrapper edge.

SVG icons marked with data-ui-icon receive stable 1em square geometry, block alignment, and visible overflow from the CSS library. Component libraries can provide semantic SVG markup without adding framework-specific icon classes or styles. Avatar initials receive optical centering, removable chips constrain their nested action to a subordinate 24px square, and pagination can distinguish compact page numbers from larger bookends with data-pagination-kind="page|direction".

Bundle size guide

Import	Raw	Gzip	Best for
ui-style-kit-css/dist/ui-style-kit.min.css	~2513 KB	~425 KB	Compatible runtime UI-system switchers and demos
ui-style-kit-css/visual.min.css	~2496 KB	~423 KB	Runtime visual switching with consumer-owned layout
ui-style-kit-css/with-bridge.css	~2888 KB	~451 KB	Deprecated runtime switcher plus stateful bridge
ui-style-kit-css/theme-colors.css	~64 KB	~8 KB	Shared color schemes for standalone style imports
ui-style-kit-css/native-elements.css	~33 KB	~5 KB	Shared native HTML fallback styling
ui-style-kit-css/content-overflow.css	~20 KB	~3 KB	Shared long-text containment for standalone style imports
ui-style-kit-css/clean-defaults.css	<10 KB	<2 KB	Shared spacing floors and opt-in flush/underline utilities
ui-style-kit-css/interactive-surface-theme.css	~9 KB	~1 KB	Canonical token-and-paint bridge for Interactive Surface state core
ui-style-kit-css/visual/minimal-saas.css	~355 KB	~51 KB	Focused Minimal SaaS, including semantic aliases and shared foundations
ui-style-kit-css/visual/industrial-utility.css	~444 KB	~61 KB	Focused Industrial Utility, including its instrumentation styles

CDN usage

Use the latest published NPM package:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/ui-style-kit-css@latest/dist/ui-style-kit.min.css" />

For production, pin the exact approved release rather than relying on latest:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/ui-style-kit-css@2.4.1/dist/ui-style-kit.min.css" />

Basic usage

<body data-ui="minimal-saas" data-theme="arctic-indigo" data-mode="light">
  <main>
    <article class="usk-card">
      <h1>UI Style Kit CSS</h1>
      <p>Switch UI systems, themes, and modes without changing component classes.</p>
      <button class="usk-button" data-ui-variant="primary">Primary Action</button>
      <span class="usk-spinner" role="status" aria-label="Loading"></span>
    </article>
  </main>
</body>

Dynamic switching

document.body.dataset.ui = "cyberpunk";
document.body.dataset.theme = "midnight-gold";
document.body.dataset.mode = "dark";

This changes the semantic components' visual preset without replacing their DOM nodes or rewriting their .usk-* classes.

Native palettes and None

Keep data-ui and data-mode, and omit data-theme to display the selected style's native palette:

<body data-ui="tactile" data-mode="light">

document.body.removeAttribute("data-theme");

The demo labels this choice None — style defaults. Do not assign the literal strings "None" or "null" to the HTML attribute. Native editor exports use --<prefix>-*-rgb variables scoped to the active preset/mode without a theme; named-theme exports use --usk-*-rgb and remain reusable across presets. Check contrast again after changing colors.

Semantic component API

manifest.json#semanticComponentApi is the authoritative specification for the implemented generic component API. Its 75 canonical .usk-* selectors keep the same class names while data-ui changes across all 20 presets. classNamespaces.compatibility records the generated .ui-* migration alias. implementationStatus records the two retained .usk-spinner and .usk-tooltip hooks, the 73 generated semantic aliases, and an empty pending set.

Role	Generic selectors	Switching coverage
Buttons	.usk-button, .usk-icon-button	all 20 presets
Card	.usk-card	all 20 presets
Forms	.usk-field, .usk-label, .usk-help-text, .usk-input, .usk-select, .usk-textarea	all 20 presets
Choice controls	.usk-check, .usk-check-control, .usk-radio, .usk-radio-control, .usk-switch, .usk-switch-track, .usk-switch-thumb	all 20 presets
Badge	.usk-badge	all 20 presets
Alert	.usk-alert, .usk-alert-title, .usk-alert-body	all 20 presets
Navigation	.usk-nav, .usk-nav-link	all 20 presets
Table	.usk-table, .usk-table-wrap	all 20 presets
Progress	.usk-progress, .usk-progress-bar	all 20 presets
Toolbar	.usk-toolbar	all 20 presets
Tabs	.usk-tabs, .usk-tab-list, .usk-tab, .usk-tab-panel	all 20 presets
Pagination	.usk-pagination, .usk-pagination-item, .usk-pagination-link	all 20 presets
Breadcrumb	.usk-breadcrumb, .usk-breadcrumb-list, .usk-breadcrumb-item, .usk-breadcrumb-link, .usk-breadcrumb-separator	all 20 presets
Skeleton	.usk-skeleton	all 20 presets
Empty state	.usk-empty-state, .usk-empty-state-icon, .usk-empty-state-title, .usk-empty-state-body, .usk-empty-state-actions	all 20 presets
Metric	.usk-metric, .usk-metric-label, .usk-metric-value, .usk-metric-detail	all 20 presets
Chip	.usk-chip, .usk-chip-group	all 20 presets
Avatar	.usk-avatar, .usk-avatar-group	all 20 presets
Stepper	.usk-stepper, .usk-step, .usk-step-marker, .usk-step-label	all 20 presets
Toast	.usk-toast-stack, .usk-toast, .usk-toast-title, .usk-toast-body, .usk-toast-actions	all 20 presets
Popover	.usk-popover	all 20 presets
Menu	.usk-menu, .usk-menu-item, .usk-menu-group, .usk-menu-separator	all 20 presets
Segmented control	.usk-segmented-control, .usk-segment	all 20 presets
File upload	.usk-file-upload, .usk-dropzone	all 20 presets
Listbox	.usk-listbox, .usk-listbox-option	all 20 presets
Existing generic hooks	.usk-spinner, .usk-tooltip	all 20 presets

Semantic paint variants use context-constrained data-ui-variant. Omit it for the neutral treatment.

Selector	data-ui-variant values
.usk-button	primary, secondary, warning, danger, ghost
.usk-badge	primary, secondary, success, warning, danger
.usk-alert	success, warning, danger
.usk-chip	primary, secondary, success, warning, danger
.usk-toast	info, success, warning, danger
.usk-tooltip	primary, secondary, accent

Skeleton shape uses data-shape="text|circle|block". Step workflow presentation uses data-state="complete|current|upcoming|error"; React and application code remain responsible for behavior and ARIA state.

<body data-ui="minimal-saas" data-theme="arctic-indigo" data-mode="light">
  <button class="usk-button" data-ui-variant="primary">Save</button>
  <article class="usk-card">...</article>
</body>

Modal and dialog roles deliberately stay outside the 75-selector preset-paint alias contract and use native <dialog> semantics. The optional component-composition.css entrypoint supplies framework-neutral .usk-modal geometry; there is no generic .usk-dialog paint alias. The semantic API also does not define data-ui-state, data-ui-size, or data-ui-placement; continue to use native and ARIA state hooks, .is-active, and [data-ui-tooltip-anchor] where supported.

Preset-prefixed classes remain supported compatibility and advanced APIs. Partial preset extras, typography and paint utilities, surface/size/placement helpers, shape and accessibility utilities, and the deprecated page, container, section, grid, stack, cluster, and split structural aliases remain prefix-bound rather than entering the generic contract.

For example, a fixed Minimal SaaS integration may continue to use <button class="saas-button saas-button-primary">. Prefer .usk-button plus data-ui-variant="primary" when markup must survive runtime preset changes.

UI systems

UI style	data-ui	Prefix	Defining visual contract	Best for
Minimal SaaS	minimal-saas	saas	compact flat modules, cool 1px rules, tight radii, restrained type, negligible elevation	dense dashboards, admin tools, focused SaaS workflows
Bento UI	bento	bento	Soft Mosaic tiles, Manrope, fine borders, compact rounded controls, restrained elevation	friendly product surfaces, feature mosaics, showcase dashboards
Maximalist / Playful	maximalist	max	loud poster collage, sticker offsets, hard ink strokes, expressive condensed typography	creators, entertainment, bold client sites
Bauhaus / Swiss Modern	bauhaus	bau	strict grids, heavy rules, primary geometry, flat construction, condensed uppercase type	agencies, editorial layouts, design-forward brands
Skeuomorphic / Tactile	tactile	tactile	paper plates, serif headings, keylines, chamfered keycaps, dark troughs, mechanical controls	physical workspace configuration and instrument-like product UI
Neumorphism	neumorphism	neo	borderless same-surface shells, opposing extrusion shadows, concave fields and pressed states	sculpted dashboards and quiet configuration workflows
Retrofuturism	retrofuturism	retro	atomic enamel shells, metallic rims, inset instrument bays, oval actions, dial controls	atomic-age dashboards and configuration workspaces
Brutalism	brutalism	brutal	square full-bleed grids, heavy rules, numbered modules, blunt controls, segmented meters	direct operational and bold creative interfaces
Cyberpunk	cyberpunk	cyber	chamfered HUD panels, clipped controls, technical condensed type, signal-colored edges	security, gaming, routing, and high-tech command tools
Y2K	y2k	y2k	dense portal panels, 1px bevels, title bars, system typography, segmented indicators	nostalgic fashion, music, event, and community portals
Retro Glass	retro-glass	rg	brushed application chrome, glossy navigation, beveled controls, glass panes, dark dock treatment	dense desktop-style media and productivity applications
Editorial Luxe	editorial-luxe	luxe	Didone hierarchy, double rules, rigid editorial geometry, restrained couture material	luxury brands, architecture, hospitality, premium editorial sites
Organic Modern	organic-modern	organic	matte limestone/forest surfaces, Cormorant Garamond + DM Sans, pointed actions, material photography, fine ledger rules	architecture, sustainable materials, natural product workspaces
Industrial Utility	industrial-utility	utility	metal-framed panels, recessed instruments, mechanical actions, safety gauges, technical type	operations, manufacturing, logistics, fleet, and equipment systems
Technical Blueprint	technical-blueprint	blueprint	drafting grids, technical linework, square measured controls, annotations, calibrated geometry	engineering, architecture, technical documentation, scientific tools
Art Deco	art-deco	deco	stepped symmetry, metallic double keylines, fanbursts, elegant display type, jewel controls	luxury, hospitality, heritage brands, and distinctive showcases
Clay	clay	clay	hand-molded imperfect edges, mineral grain, raised lower shadows, carved fields, debossed type, and clay-bead loaders	collaborative tools, education, and approachable product sites
Data Terminal	data-terminal	terminal	dense 1px command grid, mono typography, bracketed actions, strict semantic signal colors	operator consoles, telemetry, infrastructure, monitoring, developer tools
Paper Editorial	paper-editorial	paper	physical field-manual sheet, binder and index details, print rules, condensed and monospaced type	news, journals, cultural sites, and story-led publishing
Neo-Noir	neo-noir	noir	cinematic slants, trapezoid controls, diagonal cuts, subtle grain, semantic amber/teal/red signaling	cinematic portfolios, production tools, and dramatic product sites

Each description is backed by concrete CSS declaration checks and preset-scoped visual cases. This lets a failing preset or pair be rerun directly without repeating unrelated green coverage.

The demo uses one shared layout with a Style-specific components gallery. Industrial Utility's switchgear, instruments, and alarm workflow are showcased alongside each preset's distinctive components. Original template boards remain available for visual QA at index.html?view=reference (also supported by demo/index.html). See the demo showcase guide for the gallery, native/shared palettes, and reference-fixture workflow.

See the Retro Glass component guide for the full reference-board API, native palette selection, token customization, and accessible interaction contracts. Preset-specific demo components appear only while their owning style is selected.

The Art Deco component guide covers the 17-group Metropolitan Moderne specimen, its complete public component inventory, paired reference palettes, theme-token integration, and keyboard interactions. Select Art Deco in the reference view to reveal its complete board.

The Editorial Lux component guide covers the couture reference specimen, its ten component groups, token-based palettes, accessible interactions, and responsive layout. Its existing editorial-luxe preset ID and luxe-* public API remain compatible.

The Neo Noir component guide covers all 15 Midnight Cut reference groups, portable textures, canonical noir-* components, light/dark palettes and keyboard interactions. The complete specimen appears in the reference view when Neo-Noir is selected.

The Organic Modern component guide maps the architecture workspace and Control Lab to public organic-* classes. Both reference palettes are fallbacks only; shared themes paint the complete UI. Its complete specimen appears in the reference view when Organic Modern is selected.

The Bento component guide maps the retained Soft Mosaic template one-to-one to public bento-* classes, including service status, quota, listbox, loading, and dialog components. Reference colors are fallbacks behind shared theme roles. Its complete interactive specimen appears in the reference view when Bento UI is selected.

The Tactile workspace guide documents its optional navigation, settings, and instrument-panel composition, native material colors, and theme-safe foregrounds. These advanced classes are included in the public manifest.

Color themes

midnight-gold
ocean-steel
forest-moss
sunset-ember
royal-plum
graphite-cyan
desert-sage
rose-quartz
cyber-lime
arctic-indigo
chrome-navy
recycled-emerald
industrial-orange
performance-red
heritage-brass
service-blue-red
newsprint-crimson
foundry-amber
soft-orchid
electric-noir
signal-yellow
botanical-green
cobalt-electric
stone-graphite
walnut-clay

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.

See the color-theme reference for the five gap-filling palettes, their intended roles, and representative light/dark values.

Commercial component modifiers

The cross-style API also includes reusable marketing and service-site patterns. These suffixes are available for all 20 UI systems and inherit the active data-theme / data-mode palette:

card-media
card-service
card-feature
card-accent-edge
icon-medallion
button-cut
button-outline-heavy
badge-seal
feature-strip
feature-item
callout-bar
eyebrow
media-scrim

Combine them with the preset prefix and existing base components:

<article class="saas-card saas-card-service">
  <img class="saas-card-media" src="service.jpg" alt="">
  <span class="saas-icon-medallion" aria-hidden="true">★</span>
  <p class="saas-eyebrow">Professional Service</p>
  <h3 class="saas-heading">A reusable service card</h3>
  <p class="saas-copy">The visual treatment changes with the selected UI system.</p>
  <a class="saas-button saas-button-primary saas-button-cut" href="#">Learn More</a>
</article>

The components intentionally contain no domain-specific content. Icons, media, labels, and copy remain consumer-owned.

Component composition

• Service cards combine the base card with card-service; add card-media for responsive media, icon-medallion for an overlapping symbol, and button-primary button-cut for the filled service action.
• Feature cards use card-feature or card-accent-edge when information needs a stronger preset-specific edge treatment without changing the semantic element.
• Media treatments place an image and its caption inside media-scrim. The scrim supplies readable theme-token paint; the image and alternative text remain application content.
• Feature strips contain one or more feature-item children. They use balanced columns when space permits and collapse without requiring a new class.
• Callout bars use callout-bar as the visual lane and button-outline-heavy for the framed supporting action. There is no separate button-cta API.

button-cut and button-outline-heavy are independent modifiers: the first supplies the preset's filled-action silhouette and the second supplies its framed-action geometry and material. Do not combine them unless a deliberate hybrid is required. The same preset identity continues through service cards, media scrims, feature strips, callout bars, native action controls, and dialogs; color still comes only from the active theme and mode tokens.

All modifiers consume the active theme and mode tokens. Keep controls as real links or buttons, provide useful accessible names, mark decorative medallions with aria-hidden="true", and avoid placing essential text in CSS artwork. The shared containment layer allows cards, strips, scrims, callouts, controls, and preset-specific specimens to shrink inside consumer-owned grids; application layout remains responsible for choosing the outer column count.

Modes

light
dark
contrast

Native HTML coverage

styles/native-elements.css owns the shared native selectors under [data-ui][data-mode]; data-theme is optional. Each style system maps the complete --usk-native-* identity contract, so choices, selects, ranges, progress, meters, file/color/date launch controls, indicators, and scrollbars inherit preset-specific geometry, material, borders, depth, typography, and either the active theme or the preset's accessible fallback palette. Browser/OS popup internals remain platform-owned.

styles/content-overflow.css owns the shared text containment contract under [data-ui][data-mode], with or without data-theme. Text and compact controls use overflow-wrap: break-word with normal word boundaries so long hashes, URLs, and copyable tokens wrap only when necessary. Structural wrappers receive shrink constraints without inheriting a forced wrapping policy.

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, .usk-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.

For the full native-element and subpart support contract, including platform-owned picker and popup limitations, see Native Element Coverage.

Loading states

Every style includes theme-driven spinner utilities:

<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 native palette or active data-theme and data-mode, while geometry, motion cadence, depth, and busy-button indicators follow the active UI preset. The generic .usk-spinner, .loading-spinner, and [data-loading-spinner] hooks receive the same preset identity inside any [data-ui="..."] scope.

Tooltip surfaces

Every style includes visible tooltip utilities with the same API and preset-specific visual treatment:

<span class="saas-tooltip" role="tooltip">
  Helpful context
  <span class="saas-tooltip-arrow" aria-hidden="true"></span>
</span>

Inside a [data-ui="..."] scope, generic .usk-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:

[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:

The declared order is theme_colors, native_elements, components, presets, then compat_layout. Visual-only entrypoints leave the final compatibility layer empty of deprecated structural selectors.

[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

ui-style-kit-css/
  package.json
  manifest.json
  README.md
  LICENSE
  CHANGELOG.md
  STYLE-MAP.md
  dist/
    ui-style-kit.css
    ui-style-kit.min.css
    ui-style-kit.visual.css
    ui-style-kit.visual.min.css
    ui-style-kit.with-bridge.css
    ui-style-kit.with-bridge.min.css
    visual/
      minimal-saas.css
      ...
  styles/
    theme-colors.css
    native-elements.css
    components.css
    compat-layout.css
    content-overflow.css
    minimal-saas.css
    bento.css
    maximalist.css
    bauhaus.css
    tactile.css
    neumorphism.css
    retrofuturism.css
    brutalism.css
    cyberpunk.css
    y2k.css
    retro-glass.css
    interactive-surface-theme.css
    interactive-surface-bridge.css
  docs/
    TOKENS.md
    STYLE-GUIDE.md
    PUBLISHING.md

The checked-in demo, favicon pack, and social preview image stay in the repository for GitHub Pages, but they are intentionally excluded from the npm tarball so installs only receive the CSS library, docs, and metadata.

Development checks

npm run check
npm run check:compat
npm run test:e2e
npm run test:e2e:full
npm run test:axe
npm run test:axe:full
npm run test:visual:full
npm run test:matrix
npm run test:matrix:block -- --block 33
npm run test:matrix:case -- --case 3245
npm run test:matrix:range -- --from 3201 --to 3244
npm run release:verify
npm run release:verify:full
npm run pack:dry-run

npm run check rebuilds the bundles, runs stylelint, verifies package metadata and the documented class API, validates 4.5:1 text/link/filled-component contrast plus 3:1 light-mode component-edge contrast, and invokes check:compat for every generated entrypoint. npm run test:e2e is the bounded release smoke path: a curated Chromium-only Playwright suite that covers representative accessibility scans, demo switching, semantic runtime contracts, and the regression-prone preset checks. npm run test:e2e:full keeps the exhaustive Chromium/Firefox/WebKit suite available for explicit manual review. npm run test:visual:full preserves the historical visual-baseline suite for deliberate manual demo review; it is not part of the default PR, tag, or npm publish gate.

The full UI matrix is intentionally opt-in. Local matrix checks are divided into 36 stable blocks of 100 cases. npm run test:matrix runs the blocks in order and stops after the first failing block; use -- --from-block N to start at any untested block without repeating earlier green blocks. Each test title includes a stable global case number. Rerun only each failing case with npm run test:matrix:case -- --case N; because the other cases in that block have already completed, continue at the next block after the targeted fixes pass. Use test:matrix:range only when a bounded follow-up range is useful. test:matrix:raw is reserved for the manual sharded automation workflow.

The package browser policy is the last two major Chrome, Edge, and Firefox releases plus Safari and iOS 16 or newer, excluding dead browsers. The build resolves that single package.json policy into Lightning CSS targets, while check:compat verifies required prefix pairs, stable fallbacks, guarded color-mix(), text-wrap, and forced-color-adjust enhancements, and the absence of obsolete intrinsic CTA sizing declarations.

v2.1.0 Architecture Notes

• Prefer visual.css or visual/<preset>.css when Layout Style CSS or application CSS owns structure.
• Existing root, minified, focused preset, interactive-surface-bridge, and with-bridge entrypoints preserve their v2 behavior.
• Treat page, container, section, grid, stack, cluster, and split suffixes as deprecated compatibility helpers; their removal is reserved for v3.
• Prefer interactive-surface-theme.css with interactive-surface-css/state-core.css. The old stateful bridge exports remain deprecated compatibility paths.

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, ui-style-kit-css/native-elements.css, and ui-style-kit-css/content-overflow.css before standalone style files if your bundler does not follow CSS @import.
• Existing v2.0.1 integrations can keep using ui-style-kit-css/interactive-surface-bridge or ui-style-kit-css/with-bridge.css; those stateful compatibility paths are deprecated in v2.1.0. New integrations should compose the visual, theme-bridge, and state-core entrypoints documented above.

License

MIT