@thundrex/web-components

A clean, accessible design system and web component library built with Lit. Themeable, framework-agnostic, and ships with a Tailwind CSS preset.

Documentation · GitHub

Features

• 11 components — Button, Input, Toggle, Checkbox, Slider, Card, Badge, Avatar, Progress, Tag, Divider
• Accessible — WCAG AA contrast, ARIA roles, keyboard navigation, focus management
• Themeable — CSS custom properties power the entire system; three built-in themes (light, dark, ocean) plus custom themes via setTheme()
• Tailwind CSS preset — Maps all design tokens to utility classes, theme-aware via CSS variables
• Framework-agnostic — Works in React, Vue, Angular, Svelte, or plain HTML
• Red Hat Text / Mono — Clean typography with eight size tokens

Installation

npm install @thundrex/web-components

Quick Start

import '@thundrex/web-components';

<tx-button variant="primary">Click me</tx-button>
<tx-input label="Name" placeholder="Enter your name"></tx-input>
<tx-card>
  <h3 slot="header">Hello</h3>
  <p>This is a thundrex card.</p>
</tx-card>

Theming

import { setTheme, resetTheme } from '@thundrex/web-components';

setTheme('dark');
setTheme('ocean');
setTheme({ accent: '#E040FB', primary: '#00BCD4' });
resetTheme();

Or override tokens directly in CSS:

:root {
  --tx-primary: #e040fb;
  --tx-accent: #00bcd4;
}

Tailwind CSS

// tailwind.config.js
import thundrex from '@thundrex/web-components/tailwind-preset';

export default {
  presets: [thundrex],
  content: ['./src/**/*.{html,js,ts}'],
};

<div class="bg-tx-surface rounded-tx-lg shadow-tx-sm p-tx-6 font-tx">
  <h2 class="text-tx-text text-tx-xl font-bold">Title</h2>
  <p class="text-tx-text-secondary text-tx-sm mt-tx-2">Body</p>
</div>

Components

| Component | Description | | --------------- | ---------------------------------------- | | <tx-button> | Button with four variants and sizes | | <tx-input> | Text field with label and search variant | | <tx-toggle> | Switch toggle with ARIA support | | <tx-checkbox> | Checkbox with animated checkmark | | <tx-slider> | Range input with live value readout | | <tx-card> | Content card with accent bar and slots | | <tx-badge> | Status label with color variants | | <tx-avatar> | User avatar with initials and status | | <tx-progress> | Animated progress bar | | <tx-tag> | Chip with optional remove button | | <tx-divider> | Separator with optional label |

Each component has its own README in src/components/<name>/README.md with full API docs.

Development

Prerequisites

• Node.js 18+
• npm 9+

Setup

git clone https://github.com/thundrex/web-components.git
cd web-components
npm install

Dev Server (component playground)

npm run dev

Documentation Site

npm run docs:dev       # Start dev server
npm run docs:build     # Build for production
npm run docs:preview   # Preview production build

Build Library

npm run build:lib

Adding New Components

Always use the generator. Both humans and AI assistants must use this command to create new components. Do not manually create component files.

npm run generate <component-name>

The generator automatically:

1. Creates src/components/<name>/<name>.ts with base Lit component and design tokens
2. Creates src/components/<name>/README.md with API documentation template
3. Creates docs/components/<name>.md with a VitePress docs page
4. Updates src/index.ts with the barrel export
5. Updates the VitePress sidebar

Example:

npm run generate tx-tooltip

Then edit src/components/tx-tooltip/tx-tooltip.ts to build your component.

Publishing to npm

First-time Setup

npm login

Releasing

Use the version scripts to bump, build, and prepare for publish:

npm run release:patch   # 1.0.0 → 1.0.1 (bug fixes)
npm run release:minor   # 1.0.0 → 1.1.0 (new features)
npm run release:major   # 1.0.0 → 2.0.0 (breaking changes)

Then publish:

npm publish --access public

What Gets Published

Only these files ship to npm (configured in package.json files field):

• dist-lib/ — compiled components
• tailwind-preset.js — Tailwind CSS preset
• README.md
• LICENSE

Design Tokens

| Category | Tokens | | ---------- | ------------------------------------------------ | | Colors | --tx-bg, --tx-surface, --tx-primary, --tx-accent, --tx-success, --tx-danger | | Text | --tx-text, --tx-text-secondary, --tx-text-muted | | Shadows | --tx-shadow-xs through --tx-shadow-xl | | Spacing | --tx-space-1 (4px) through --tx-space-16 (64px) | | Radius | --tx-radius-sm (6px) through --tx-radius-pill | | Typography | --tx-text-xs through --tx-text-4xl | | Fonts | --tx-font (Red Hat Text), --tx-font-mono (Red Hat Mono) |

Project Structure

web-components/
├── src/
│   ├── components/
│   │   ├── tx-button/
│   │   │   ├── tx-button.ts    # Component source
│   │   │   └── README.md       # Component API docs
│   │   ├── tx-input/
│   │   └── ...
│   ├── styles/
│   │   └── tx-tokens.ts        # Design tokens
│   ├── theme.ts                # Theme engine
│   └── index.ts                # Barrel exports
├── docs/                       # VitePress documentation
│   ├── .vitepress/
│   │   ├── config.ts           # Site config & sidebar
│   │   └── theme/              # Custom theme
│   ├── guide/                  # Foundation docs
│   └── components/             # Component docs (auto-includes README)
├── scripts/
│   └── generate-component.mjs  # Component generator
├── tailwind-preset.js          # Tailwind CSS preset
└── package.json

License

MIT