npm package: @kashdao/ui
Description: Kash Design System — tokens, utilities, and React components
Latest version: 0.2.4

# @kash/ui

Design system for the Kash ecosystem — tokens, utilities, and React components.

## Install

```bash
npm install @kash/ui
```

**Peer dependencies**: `react >= 18`, `react-dom >= 18`

## Quick start

### 1. Import the stylesheet

Add one of these to your app's CSS entry point (e.g. `globals.css`):

```css
/* Full design system: tokens + utility classes + animations */
@import '@kash/ui/dist/styles.css';

/* Or tokens only (CSS custom properties, no utility classes) */
@import '@kash/ui/dist/tokens.css';
```

> **Note**: Use the `dist/` path for CSS `@import` — PostCSS doesn't resolve Node exports maps. JS imports (`import '@kash/ui/styles'`) also work in bundlers that support exports maps.

### 2. Use components

```tsx
import { Button, Tabs, Alert, cn } from '@kash/ui';

function MyPage() {
  return (
    <div className={cn('bg-kash-background p-4', 'flex flex-col gap-4')}>
      <Alert variant="info">Welcome to the app</Alert>
      <Button variant="white" onClick={() => {}}>
        Get started
      </Button>
    </div>
  );
}
```

## What's included

### CSS tokens (`@kash/ui/tokens`)

All design decisions as CSS custom properties — use in any framework:

| Category       | Examples                                                                  |
| -------------- | ------------------------------------------------------------------------- |
| **Colors**     | `--color-kash-yellow-100`, `--color-kash-red-8`, `--kash-foreground`      |
| **Surfaces**   | `--kash-surface`, `--kash-surface-hover`, `--kash-surface-elevated`       |
| **Borders**    | `--kash-border-default`, `--kash-border-hover`, `--kash-border-focus`     |
| **Shadows**    | `--kash-shadow-sm` through `--kash-shadow-xl`                             |
| **Spacing**    | `--spacing-xs` (4px) through `--spacing-6xl` (64px)                       |
| **Radius**     | `--radius-sm` (8px) through `--radius-2xl` (24px)                         |
| **Typography** | `--font-size-xs` through `--font-size-4xl`, `--line-height-*`             |
| **Transitions**| `--transition-fast` (120ms), `--transition-normal` (200ms), `--transition-entrance` (280ms) |
| **Components** | Button, input, card, modal, dropdown, tab, badge, toast, progress, skeleton |

Dark mode is the default. Light mode activates with `data-theme="light"` on any ancestor element.

### CSS utilities (`@kash/ui/styles`)

Includes all tokens plus ready-made utility classes:

```css
/* Backgrounds */
.bg-kash-surface          .bg-kash-surface-hover      .bg-kash-yellow-8

/* Text */
.text-kash-foreground     .text-kash-foreground-muted  .text-kash-red-100

/* Borders */
.border-kash-default      .border-kash-hover

/* Radius */
.rounded-kash-sm          .rounded-kash-lg             .rounded-kash-2xl

/* Spacing */
.p-kash-sm                .gap-kash-md                 .px-kash-lg

/* Shadows */
.shadow-kash-md           .shadow-kash-xl

/* Transitions */
.transition-kash-fast     .transition-kash-colors      .transition-kash-interactive

/* Component classes */
.btn-primary              .btn-ghost                   .input-field
.card                     .card-glass                  .nav-item
.skeleton                 .focus-ring                  .dropdown-item

/* Animations */
.animate-kash-fade-in-up  .animate-kash-scale-in       .animate-kash-shimmer
.animate-kash-slide-up    .animate-kash-pop-in         .animate-kash-spin
```

### React components

| Component            | Description                                  |
| -------------------- | -------------------------------------------- |
| `Button`             | Primary button with variants, loading states |
| `IconButton`         | Square icon-only button                      |
| `Spinner`            | Conic-gradient loading spinner               |
| `Input`              | Text input with error state                  |
| `Textarea`           | Multi-line text input                        |
| `FormField`          | Label + input + error wrapper                |
| `Label`              | Standalone label                             |
| `Tabs`               | Sliding-pill tab bar with color themes       |
| `EmptyState`         | Empty content placeholder                    |
| `ErrorState`         | Error with retry action                      |
| `ErrorBanner`        | Inline error message                         |
| `Alert`              | Status alert (error/success/info/warning)    |
| `ToggleSwitch`       | On/off toggle                                |
| `Slider`             | Range slider with labels                     |
| `GlassCard`          | Glass-morphism card                          |
| `Stepper`            | Step progress indicator                      |
| `MenuItem`           | Navigation menu item                         |
| `MenuItemIcon`       | Icon slot for MenuItem                       |
| `MenuItemText`       | Text slot for MenuItem                       |
| `Skeleton`           | Shimmer loading placeholder                  |
| `SkeletonText`       | Multi-line text skeleton                     |
| `SkeletonAvatar`     | Circular avatar skeleton                     |
| `SkeletonCard`       | Card-shaped skeleton                         |
| `SplitProgressBar`   | Yes/No split bar                             |
| `AnimatedProgressBar`| Animated fill bar                            |

Every component accepts a `className` prop for overrides via the `cn()` utility.

## `cn()` utility

```tsx
import { cn } from '@kash/ui';

cn('text-sm font-medium', isActive && 'text-white', className);
// Deduplicates Tailwind classes via tailwind-merge
```

## Design system rules

### Transition tiers

| Tier       | Duration | Use for                                      |
| ---------- | -------- | -------------------------------------------- |
| **Fast**   | 120ms    | Hover colors, opacity, focus rings, toggles  |
| **Normal** | 200ms    | Card hover scale, content reveal, transforms |
| **Entrance** | 280ms | Modal entrance, slide-up, dropdown-in        |

### Interactive states

| State      | Token                     | Opacity |
| ---------- | ------------------------- | ------- |
| Resting    | `--kash-surface`          | 2%      |
| Hover      | `--kash-surface-hover`    | 4%      |
| Active     | `--kash-surface-active`   | 2% + `opacity: 0.64` |
| Focus      | `--kash-surface-focus`    | 12%     |
| Selected   | `--kash-surface-selected` | 16%     |

### Press scale effect

- Cards: `hover:scale-[1.01] active:scale-100`
- Buttons: `hover:scale-[1.02] active:scale-100`
- Rows: `hover:scale-[1.005] active:scale-100`
- Exceptions (no scale): dropdowns, inputs, tabs, toggles

### Border radius

| Size   | Token / Value     | Use for                |
| ------ | ----------------- | ---------------------- |
| Small  | `--radius-sm` 8px | Badges, tab buttons    |
| Medium | `--radius-md` 12px| Dropdown items, pills  |
| Large  | `--radius-lg` 16px| Buttons, inputs        |
| XL     | `--radius-xl` 20px| —                      |
| 2XL    | `--radius-2xl` 24px| Cards, modals         |

## Compatibility

- React 18+ / React 19
- Next.js 13+ (App Router with RSC — `"use client"` directive included)
- Vite / CRA / any React bundler
- Tailwind CSS v3 or v4 (utility classes are plain CSS, not Tailwind-dependent)
- Works without Tailwind — tokens and utility classes are self-contained CSS

## Development

```bash
npm run dev       # Watch mode
npm run build     # Production build
npm run lint      # Type-check
```

## License

MIT