Crusher UI Kit - Personal UI Framework

Get started

Install in any stack.

Three delivery modes, pick what fits. The package is semver-stable at 1.0; pin to ^1.0.0 and trust no breaking changes inside 1.x.

npm

Bundler apps (Vite, Astro, Next.js, etc.). Tokens + components + runtime via package exports.

npm install crusher-ui-kit

CDN / Static HTML

No build step. Drop the standalone bundle + a theme stylesheet onto any page.

<link rel="stylesheet" href="https://unpkg.com/crusher-ui-kit/dist/styles/tokens.css">
<link rel="stylesheet" href="https://unpkg.com/crusher-ui-kit/dist/themes/professional.css">
<script type="module" src="https://unpkg.com/crusher-ui-kit/dist/crusher-ui.standalone.esm.js"></script>

Static tool shell

Pre-baked light/dark/density-aware shell for no-build utility tools.

<link rel="stylesheet" href="https://unpkg.com/crusher-ui-kit/dist/static/tool-shell.css">
<script type="module" src="https://unpkg.com/crusher-ui-kit/dist/static/tool-shell.js"></script>

Design philosophy

Why crusher-ui-kit?

Three principles. Every API choice falls out of them.

Token first

Every design value, color, spacing, radius, shadow, motion, originates from a token in design/tokens/. Components never define raw values. Themes override tokens, not components.

Dialect-driven

Eight visual identities (glass, brutal, neobrutal, neumorph, minimal, futuristic, bento, professional) ship as token overlays. Swap the active dialect via data-theme and every component re-renders. Same API surface; different aesthetic.

Runtime-controlled

Visual state lives on the document, not in components. data-mode (light / dark), data-density (compact / cozy / comfortable), data-theme (dialect). Components react via CSS variables. No React lock-in. Works in plain HTML.

1.4.0 (2026-09-05)

What's in the 1.4 release

The stability promise. From here on, no breaking changes within the 1.x line. The full CHANGELOG documents everything.

Environment Scenes, split in two: a scene is a place and owns the palette; an atmosphere is a composable stack of conditions, each at its own intensity, owning the particles and the colour wash. setAtmosphere(), getAtmosphere(), listAtmospheres().
23 weather conditions + 6 kinds of ambient air on 8 new FX primitives, one global 180-particle budget across the whole stack, and intensity that genuinely reaches 0.
New subpath crusher-ui-kit/runtime/contrast: pure, DOM-free WCAG maths (contrastRatio, composite, fitOverlays, fitInk) so a consumer can prove its own text survives any wash it puts over the page.
Muted ink raised: light #475569, dark #a3b0c2. Both modes now tolerate roughly a 21% overlay instead of 1%, and the atmosphere gate holds muted text to a full 4.5.
Two new CI gates: check:atmosphere sweeps every veil against the kit's own text at 861 points per mode, and check:runtime-types covers the catalogs, unstyled primitives and conditions that would render nothing.
Stability contract unchanged: semver-stable 1.x, no breaking changes within the line. A 2.0 requires alpha + ADR + migration guide + dogfooding first.

Production consumers

What this powers today.

muhammadhassaanjaved.com

Personal site (minimal dialect). Astro static.

portfolio.muhammadhassaanjaved.com

Creative portfolio (neumorph dialect). Astro static.

ui.muhammadhassaanjaved.com

This site, framework demo + release-gate review surface.

tools.muhammadhassaanjaved.com

The hub, via the static tool-shell contract. The 37 tool pages behind it now own their own CSS by design, one committed identity each.

8 dialects

One framework, eight visual identities.

Tap a card to apply its theme across the whole page. Every section below, including the chrome itself, re-renders. The new professional dialect is the trust-signaling B2B neutral, sitting alongside the 7 portfolio dialects.

Environment Scenes

Living, cinematic worlds. Not skins, atmospheres.

Two slots, not one. A scene is a place and owns the palette; an atmosphere is a stack of conditions that compose, each at its own strength, so blossom can still drift through a dust storm. 23 weather conditions, 6 kinds of ambient air, one particle budget across all of them. Opt-in, prefers-reduced-motion safe.

Scene Studio Sunny

Bright, airy, high-noon clarity

Ship it

Details

Place

Weather, composable over any place

Ambient air, composes under the weather

Intensity

Clear scene

Intensity reaches 0: a clear day means no rain at all, not a light drizzle. Weather and ambient chips toggle, so they stack. prefers-reduced-motion drops the motion live, keeping the colour.

The same thing without JavaScript

The studio above drives setScene() and setAtmosphere(). Everything they do is also reachable from markup: <crusher-scene> mirrors its attributes into the runtime, so a static page or a server-rendered template can declare its weather with no script of its own. The element below is real, and these buttons do nothing but set and remove attributes on it. Note the last two: an explicit name="" clears, because that is a stated intent, while an element that declares nothing asserts nothing and leaves the scene alone.

name="forest"

atmosphere="rain:0.8 petals:0.3"

name="" (clears)

no attributes (inert, nothing changes)

<crusher-scene></crusher-scene>

Live playground

Every component, every state, try without leaving the page.

Each card below is both a marketing beat and a live QA fixture, interactive demo on top, state inspector below. The same page powers framework releases, downstream-site reviews, and per-component regression checks across all 8 dialects.

Data & dashboards

Chart it, without shipping a chart library.

A dashboard-grade chart and a KPI tile, token-driven, dark/light aware, no dependencies. For the analytics pages your products and client work actually need. When you outgrow these (tooltips, zoom, multi-series), the sparkline's advice holds: reach for Recharts or ECharts.

Monthly revenue

Active users (90 days)

Theme Studio

Shape it live. Every dial moves every component.

Drag the radius, pick a brand color, switch the dialect and mode. The preview grid and the whole page react instantly. When you land on a look, copy the link, it carries every setting.

Preview

Learn more

New

Roundness 1.0x Brand color

Dialect

Mode

Reset

Project Website + Verification Harness

Review the whole framework from one page.

This site is the canonical coverage surface for Crusher UI Kit. Use it to scan every public element, verify theme behavior, test runtime controls, and catch regressions before packaging or integrating the framework into other products.

Coverage Primitives Atoms Overlays Organisms Runtime

Focused review

Atoms

Low-level controls, feedback, and inline utility surfaces.

Forms

Label, field, hint, and error composition contract.

Molecules

Layout, overlay, selection, and intermediate interaction patterns.

Organisms

Shells, navigation, timelines, tables, and page-level surfaces.

Framework Reach

One system, multiple product shapes

Static HTML via standalone build and theme CSS.
Bundler apps via package root, runtime helpers, and exported themes.
Shared layout primitives for portfolio, SaaS, dashboard, and AI surfaces.

Review Workflow

Use this page as the release gate

Scan the landing section in light and dark mode for overall balance.
Check atoms and overlays for spacing, hover, disabled, and empty states.
Finish with runtime controls, toasts, and table flows before packaging.

What To Watch

Theme regressions show up first in shared surfaces

Menubar, toolbars, filter bars, chips, and badges.
Focus rings, contrast, and dense-mode spacing.
Busy, empty, and validation states that are easy to forget.

Framework Primitives

Start here to validate the framework-level shell, layout primitives, navigation rails, and dashboard surfaces that make Crusher usable as a product foundation instead of just a component dump.

Phase 4

Launch flow

Reusable shell Command surfaces Theme-aware

Shell primitives Navigation Dashboard summaries

Sync shell

+12.4% vs last week

Composed main surface

Use crusher-app-shell to place navigation and supporting rails, then nest crusher-grid and crusher-stack for page-level composition.

Add crusher-nav-list for reusable side navigation and crusher-stat for dashboard summaries before dropping into tables or domain-specific screens.

Context rail

Attach filters, status, or command surfaces without bespoke layout CSS.

Live

Responsive

Reusable

The same shell contract can wrap a portfolio, admin page, AI workspace, or infra console.

Linked card surface

crusher-card-link turns any card composition into a full-surface navigation target without forcing card content structure.

Highlighted card

Brand-accented border, hover-lift opt-in.

Dense data card

Tighter padding for dashboard tiles.

Muted comfortable card

Lower-emphasis background, generous padding.

Atoms

Atoms should hold up across every theme, size, and state. This section is where we validate low-level controls before trusting them inside bigger product compositions.

Hover + focus Disabled Filled + empty Feedback tones

Buttons

Variants

⚡Primary

Secondary

Outline

Ghost

Subtle

Destructive

Sizes

Small

Medium

Large

States

Loading…

Disabled

Disabled secondary

Full width

Inputs & Toggles

Text entry

Binary controls

Unchecked

Checked

Disabled

Off

Disabled

Feedback Surfaces

Chips

Chip

Secondary chip

Warning

Danger

Neutral

Badges & tooltip

Badge

Brand

Success

Warning

Error

Tooltip

Icon links

Code Block

Syntax colors, chrome, and surface contrast should hold across all dialects.

{`const hello = (name) => console.log('Hello', name);
hello('Crusher');`}

Form Primitives

The field contract needs to support neutral, hint, and error states without bespoke page CSS.

Validate

Submit

Selects & Dropdowns

Static, async, and nested selection surfaces should stay legible in every theme.

Select states

Development

Staging

Production

Nested actions

New File

New Folder

AI Tools

Generate Summary

Generate README

Overlays & Navigation

These components handle transient interaction: dialogs, tabs, menus, quick actions, and runtime-driven command surfaces. They are often where theme regressions show up first.

Transient surfaces Keyboard flows Nested actions Global runtime triggers

Modal

Review focus trap, header/footer spacing, and destructive-action clarity.

Escape to close Footer actions Backdrop lock

Tabs

Selected state, panel visibility, and border treatments need to remain stable across dialects.

Settings overview

Validate active tab chrome, default spacing, and readable secondary text.

Runtime config Theme hooks

Command Palette

Press ⌘/Ctrl+K or use the button.

Open Palette

Show Toast

Keyboard shortcut Async command provider Global runtime API

Open Settings
Scale cluster to 5 nodes
Tail app logs

Empty State

Use this for no-results, no-data, or not-yet-configured surfaces.

Reset filters

Alerts

Inline contextual alerts for status feedback. Variant tokens map directly to --crusher-color-status-*. Dismissible alerts persist their closed state to crusher_prefs.alertsDismissed.

5 variants Dismissible + persistent Slotted title, body, actions, icon

Heads up crusher-alert shipped in M3 (0.2.0) and is part of the 1.0 stability surface. Five variants below; each maps to a --crusher-color-status-* token.

Dismissible alert This alert remembers when you close it via crusher_prefs.alertsDismissed[id].

Form Field

crusher-field is a form-field wrapper that auto-wires aria-labelledby, aria-describedby, and aria-invalid on the slotted control, no consumer markup needed. Supports vertical (default) and horizontal orientations.

Auto a11y wiring Vertical & horizontal Error > helper precedence

1. Vertical + helper text

2. Vertical + error state (aria-invalid)

3. Horizontal orientation

4. Disabled state (label color only; slotted control self-disables)

Disclosure

crusher-disclosure is a thin Lit wrapper over native <details>. Open state reflects bidirectionally, set the open attribute programmatically or let the user toggle. Also available as a CSS-only .crusher-disclosure utility for no-build consumers.

Bidirectional open-state reflection Height animation (Chrome 129+) CSS-only utility

1. Lit wrapper, summary attr (starts closed)

Unlimited projects
Priority support
Custom domain

2. Lit wrapper, starts open

Shipped in 0.3.0 (M4): crusher-field, crusher-disclosure, and button enhancements. All folded into 1.0's stability surface.

3. CSS-only utility (no Lit import needed)

Plain HTML disclosure

Works without the Lit component. Add class="crusher-disclosure" to any <details>. Tokens resolve from the same design system.

Stack: orientation & wrap

crusher-stack now accepts orientation (vertical | horizontal) and wrap. The default is vertical, so existing usage is unchanged. Horizontal clusters with wrap replace bespoke chip-row and action-bar CSS across consumers.

Non-breaking Cluster + wrap No new element

1. Vertical (default, unchanged)

First

Second

Third

2. Horizontal cluster (chip row)

React

TypeScript

Lit

Web Components

3. Horizontal + wrap (tag list / action bar)

Design system

Web components

Open source

Token-driven

Multi-theme

Light + dark

A11y first

Organisms

Organisms prove that Crusher can compose into real product surfaces: timelines, data tables, navigation-aware layouts, and dashboard content instead of isolated snippets.

Composed surfaces Busy + empty states Selection + filtering

Timeline

Day 1

Foundation

Tokens, reset, typography.

Day 5

Components

Buttons, inputs, overlays, data.

Skill Bars

Table States

Busy and empty surfaces should still feel like part of the same framework, not fallback browser UI.

Busy

Empty

Refresh

Export

Resizable columns Sticky pins Selectable rows

24 visible 0 selected

Live dataset wiring through framework workflow primitives

Focus running

All status

Running

Starting

Stopped

All regions

us-east-1

eu-west-1

ap-south-1

Clear

SaaS connection status

Inline indicator for any external connection (OAuth, DB, webhook, service). Five states covering the realistic lifecycle: connected, disconnected, re-authorize required, error, connecting.

Manage

Reconnect

Connect

Retry

Wire the cta slot's button to your own click handler, the component is a passive status surface, no events fire.

Avatar profile menu

Avatar-anchored dropdown for SaaS app shells. Click the avatar to open the panel, user info at the top, consumer-slotted menu items in the body, pinned footer slot for the sign-out action.

Profile Billing Team settings

Documentation Contact support

Initials fallback when no avatar-url is set. Set avatar-url="https://…" to render an image instead.

SaaS pricing tiers

Plan-card primitive for billing / upgrade pages. Three tier variants demonstrated below: standard, featured (the recommended tier, visually elevated), and current (the user's active plan). Both flags can coexist.

1 connected QBO company
5 vendor changes / month
Email verification
Community support

Select Starter

Invoice list

Past invoices in a table with predefined columns (date / number / amount / status badge / download link). Composes crusher-table; layers invoice-specific formatting (locale-aware dates, currency-aware amounts, provider-agnostic status badges covering Polar / Stripe / Paddle conventions).

Property: .invoices = [{ id, number?, date, amount, currency?, status, download_url?, hosted_url? }]. amount-in-cents if you're passing minor units. Listens for invoice-download event for tracking.

Payment method

Display-only card: brand + last 4 + expiry, plus optional email and Default / Expired badges. CTA slot for the "Manage" link to the provider's hosted portal, card collection happens at the billing provider, not in your UI.

Manage

Update

Add a payment method

File upload

Drag-drop zone + native file picker + per-file validation (size, accept-types, max-files). Manages selected-files state + UX; the consumer wires the actual upload (fetch / XHR / FormData submit). Designed for CSV imports + bulk uploads.

Listens for files-change event with { files, errors } detail; call .clear() after a successful upload to reset.

Currency input

Locale-formatted on blur (1234.5 → 1,234.50), raw numeric while focused. inputmode="decimal" shows the right mobile keypad. Compatible with native form submission + crusher-field labels/errors.

Sparkline

Opinionated minimal trend, single line / area / dots, no axes or legend. For inline "trend at a glance" cards. NOT a chart library; use a real one (Recharts, Chart.js) for axes / tooltips / multi-series.

brand · area · first/last

success · all dots

danger · line only

Runtime & Verification

This section is the runtime sanity surface. Use it to confirm URL state sync, theme switching, palette behavior, and toast rendering without leaving the project website.

Theme sync URL state Palette API Toast variants

Runtime Control Center

Use this view to verify state sync, jump between focused review sections, and confirm the current route is shareable before you leave the local proving ground.

Focused review links

Current view

view: / review: full matrix: 14 views density: 3 modes

Theme Quick Picks

Jump between dialects without scrolling back to the top controls.

Light mode

Dark mode

Toggle density

Current Runtime State

These values should always mirror the URL and top control panel.

theme: glass mode: light density: comfortable brand: default

Copy state URL

Open command palette

Toast Center

Validate success, info, warning, and destructive feedback without changing sections.

Success toast

Info toast

Warning toast

Danger toast

Audio Player

Opt-in ambient audio control for creative sites, games, demos, and branded experiences. preload="none" by default, audio is fetched only when the user clicks play.

Verification Checklist

Use this as the final pass before carrying Crusher into another repo.

Check hero, menus, chips, and cards in light and dark mode.
Cycle density and confirm rows, fields, and toolbars still breathe correctly.
Trigger validation, toasts, modal, dropdown, and command palette.
Review normal, busy, empty, and filtered table surfaces.

Style Switcher Showroom

One component, eight live configurations. Every tile below is a real <crusher-style-switcher inline> writing to the same global <html> state, toggle dark mode in any tile and they all sync. The inline attribute (new in 0.3.1) flips the default floating slide-out into an in-flow block for documentation pages, settings panels, and embedded admin UIs.

Full panel Default, mode + brand colors + theme primary + 8 dialects. Use when the consumer needs every lever.

<crusher-style-switcher inline></crusher-style-switcher>

Mode only Just the light/dark toggle. Best when the rest of the brand is fixed.

<crusher-style-switcher inline hide-themes hide-colors hide-theme-color>

Colors only, defaults Four built-in brand accents. Mode + dialects hidden.

<crusher-style-switcher inline hide-mode hide-themes hide-theme-color>

Custom 3 colors Consumer picks the count and the hex values via the swatches attribute.

swatches="sky:#0ea5e9, emerald:#10b981, violet:#8b5cf6"

Custom 6 colors Same attribute, different palette. No fixed slot count, consumer decides.

swatches="rose:#f43f5e, amber:#f59e0b, lime:#84cc16, teal:#14b8a6, indigo:#6366f1, fuchsia:#d946ef"

Site-locked (no dialects) Mode + brand color, but the visual dialect is owned by the site. The typical product-site config.

<crusher-style-switcher inline hide-themes hide-theme-color>

Music only Everything hidden, audio player in the extra slot. Useful for creative sites that just want ambient sound control.

<crusher-style-switcher inline hide-mode hide-themes hide-colors hide-theme-color>
  <crusher-audio-player slot="extra" src="..." loop>
</crusher-style-switcher>

Full panel + music Everything together. The portfolio-grade config: mode, brand, dialects, plus ambient audio in the extra slot.

<crusher-style-switcher inline>
  <crusher-audio-player slot="extra" src="..." loop>
</crusher-style-switcher>

Theme Matrix

10 representative components × all 8 dialects in one grid. The fastest way to spot a theme regression: scan one row, find the dialect that looks wrong. Each cell is a per-cell data-theme scope, so the framework's CSS applies without disturbing the page-level theme.

Light + dark inherits from page mode Curated subset, edit src/scripts/theme-matrix.js

Install in any stack.

npm

CDN / Static HTML

Static tool shell

Why crusher-ui-kit?

Token first

Dialect-driven

Runtime-controlled

What's in the 1.4 release

What this powers today.

One framework, eight visual identities.

Living, cinematic worlds. Not skins, atmospheres.

Every component, every state, try without leaving the page.

Chart it, without shipping a chart library.

Shape it live. Every dial moves every component.

Review the whole framework from one page.

Atoms

Forms

Molecules

Organisms

One system, multiple product shapes

Use this page as the release gate

Theme regressions show up first in shared surfaces

Composed main surface

Highlighted card

Dense data card

Muted comfortable card

Buttons

Inputs & Toggles

Feedback Surfaces

Code Block

Form Primitives

Selects & Dropdowns

Modal

Confirm Action

Tabs

Command Palette

Empty State

Timeline

Foundation

Components

Skill Bars

Table States

SaaS connection status

Avatar profile menu

SaaS pricing tiers

Invoice list

Payment method

File upload

Currency input

Sparkline

Runtime Control Center

Theme Quick Picks

Current Runtime State

Toast Center

Audio Player

Verification Checklist

Style Switcher Showroom