crusher-ui-kit

v0.3.1

Published

9 days ago

Token-driven Web Components UI framework with interchangeable design dialects for modern web products.

Downloads

1,283

0High
0Medium
0Low

itxcrusher

design-tokens lit ui-kit web-components themes style-dictionary

🚀 Crusher UI Kit

Design Dialects on Demand — A modern, token-driven UI framework

Modern, themeable Web Components for product-grade apps — infra consoles, AI tools, dashboards, you name it. Tokens-first. Zero lock-in. Accessible. Fast. Framework-free.

Live site: https://ui.muhammadhassaanjaved.com/

🧩 Install

npm i crusher-ui-kit

Use

Bundler apps (Vite/Next/etc):

import 'crusher-ui-kit';
import 'crusher-ui-kit/styles/tokens.css';
import 'crusher-ui-kit/styles/modes.css';
import 'crusher-ui-kit/styles/semantic.css';
import 'crusher-ui-kit/styles/bridge.css';
import 'crusher-ui-kit/styles/code-theme.css';
import 'crusher-ui-kit/styles/theme-scenes.css';
import 'crusher-ui-kit/styles/dialect-overrides.css';
import 'crusher-ui-kit/themes/glass.css';

Theme imports are extension-qualified by contract: import 'crusher-ui-kit/themes/<theme>.css'

Runtime helpers (browser):

import {
  setTheme,
  lockTheme,
  setMode,
  setDensity,
  showToast,
  openPalette,
  createHashPanelController
} from 'crusher-ui-kit/runtime';

setTheme('glass');
lockTheme('minimal'); // optional: pin fixed-dialect sites
setMode('dark');
setDensity('comfortable');
showToast({ title: 'Crusher ready' });
openPalette();

createHashPanelController({
  defaultId: 'home',
  panelSelector: '[data-crusher-panel]',
  linkSelector: '[data-crusher-panel-link]'
});

Static HTML (no bundler, drop-in):

<html data-theme="minimal" data-mode="light">
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/crusher-ui-kit@latest/dist/crusher-ui.min.css" />
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/crusher-ui-kit@latest/dist/themes/minimal.css" />
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/crusher-ui-kit@latest/dist/static/tool-shell.css" />
  <script type="module" src="https://cdn.jsdelivr.net/npm/crusher-ui-kit@latest/dist/crusher-ui.standalone.esm.js"></script>
</html>

For static utilities, start from templates/static-tool-shell.html.

🎨 Theming

Base tokens under :root, dark-mode overrides under html[data-mode="dark"].

Example:

<html data-theme="glass" data-mode="dark">

For fixed-dialect sites, add data-theme-lock. Runtime init keeps data-theme pinned and clears stale saved brand overrides when the lock changes:

<html data-theme="minimal" data-theme-lock="minimal" data-mode="light">

♿ Accessibility

Modal: traps focus, restores on close, locks scroll, supports Esc/overlay dismiss, emits request-close (cancelable).
Tabs: fully ARIA-compliant (role="tablist/tab/tabpanel") with roving focus + live announcements.
Select: announces selections via aria-live, supports async data and keyboard type-ahead.
Contrast: checked automatically via npm run check:contrast (WCAG-compliant).

🧰 Scripts

| Command | Purpose | | --------------------------------- | ------------------------------- | | npm run dev | Vite dev server | | npm run build:tokens | Generate token + theme CSS | | npm run build:site | Build the public framework/demo website artifact from index.html | | npm run build | Build distributable (bundler ESM + standalone ESM + CSS) | | npm run check:package | Verify runtime/package contracts | | npm run check:browser | Verify browser custom-element contracts | | npm run check:demo | Verify every public custom element appears on the demo/review page | | npm run check:types | Verify every public custom element has TypeScript tag-map coverage | | npm run check:contrast | WCAG color contrast validation |

Release flow: Uses Changesets release PRs. Pushes to main validate the package and either update the release PR or publish only after a versioned release PR is merged.

CI publish prerequisite: configure GitHub secret NPM_TOKEN for the owning npm account before expecting automated releases to publish new versions of crusher-ui-kit.

💡 Types

types/index.d.ts declares custom elements for IDE IntelliSense (TS / VSCode).

🧱 Project Structure

crusher-ui-kit/
├── design/           → base tokens + theme overlays (JSON)
├── src/
│   ├── components/   → Web Components (atoms, molecules, organisms)
│   ├── css/          → generated token/theme CSS
│   ├── scss/         → authored SCSS utilities
│   ├── runtime/      → theme + mode switching
│   └── js/           → entrypoint logic
└── dist/             → compiled output

🌈 Overview

Crusher UI Kit is a framework-agnostic design system powered by Web Components and Design Tokens. It allows instant switching between modern aesthetics — Neumorphism, Glassmorphism, Brutalism, Neo-Brutalism, Minimalist, Futuristic, and Bento — all with dark/light support.

This isn’t just CSS — it’s a design engine built for products that evolve.

🧠 Core Philosophy

Token-First Architecture — one JSON source defines all design primitives.
Framework-Agnostic — use in React, Vue, Angular, or plain HTML.
Design Dialects — switch entire aesthetic systems instantly.
Accessible & Performant — built for real-world apps, not demos.
Zero Lock-In — no runtime dependency hell.

🧪 Tech Stack

Vite — ultra-fast dev/build
Style Dictionary — token compilation
Lit — Web Components core
Sass/SCSS — utilities and authoring
ESLint + Prettier — code hygiene
Changesets — release management

🪄 Design Dialects

Each dialect overrides tokens for a distinct personality:

| Dialect | Style Signature | | -------------- | ------------------------- | | Glass | Soft transparency + blur | | Brutal | Bold contrast, hard edges | | NeoBrutal | Modern brutalism | | Neumorph | Subtle lighting, depth | | Minimal | Whitespace and clarity | | Futuristic | Glows, neon, motion | | Bento | Modular grid layouts |

Switch instantly with the root attribute contract:

document.documentElement.setAttribute('data-theme', 'neobrutal');

🌗 Modes

Light and dark modes are tokenized in modes.css. Switch globally:

document.documentElement.setAttribute('data-mode', 'dark');

🧩 Components Overview

| Component | Purpose | | ---------------------------------------- | ------------------------------- | | <crusher-button> | Tokenized button | | <crusher-card> | Glass/brutal cards | | <crusher-input> / <crusher-textarea> | Accessible forms | | <crusher-modal> | Tokenized modal with trap focus | | <crusher-empty-state> | Empty/no-results surface | | <crusher-skill-bar> | Animated progress bars | | <crusher-timeline> | Structured timelines | | <crusher-style-switcher> | Theme/mode toggler |

💬 Credits

Built and maintained by Hassaan (itxcrusher)
🌐 muhammadhassaanjaved.com
Follow updates → future releases, token presets, and dialect packs.