npm package: @kodexalabs/kdx-kit
Description: Kodexalabs Design System - Unified SDK with design tokens, components, and utilities. Consolidates @kodexalabs/asd-tokens and @kdx-kit/ui.
Author: KodexaLabs
Latest version: 1.0.1

# @kodexalabs/kdx-kit

**Unified Design System SDK** for Kodexalabs projects. Consolidates design tokens, UI components, branding assets, and utilities into a single, cohesive package.

[![npm version](https://img.shields.io/npm/v/@kodexalabs/kdx-kit.svg)](https://www.npmjs.com/package/@kodexalabs/kdx-kit)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

## 🎯 What's Included

- **Design Tokens** - Colors, typography, spacing, motion, and more (formerly `@kodexalabs/asd-tokens`)
- **UI Components** - React components built with strict monochrome design principles
- **Branding Assets** - KLogo, KLoadingGrid, and brand utilities
- **Tailwind Plugin** - Seamless integration with Tailwind CSS
- **TypeScript Support** - Full type definitions included

## 📦 Installation

```bash
npm install @kodexalabs/kdx-kit
```

**Peer Dependencies:**
```bash
npm install react react-dom tailwindcss
```

## 🚀 Quick Start

### Using Design Tokens

```typescript
import { colors, typography, spacing } from '@kodexalabs/kdx-kit';

// Access token values
const primaryColor = colors.brand.background.hsl; // hsl(0 0% 0%)
const headingFont = typography.fontFamily.heading; // 'Plus Jakarta Sans'
const baseSpacing = spacing[4]; // 1rem
```

### Using Components

```tsx
import { Button, Card, ThemeProvider } from '@kodexalabs/kdx-kit';

function App() {
  return (
    <ThemeProvider>
      <Card>
        <Button variant="default">Click Me</Button>
      </Card>
    </ThemeProvider>
  );
}
```

### Using Branding Assets

```tsx
import { KLogo, KLoadingGrid } from '@kodexalabs/kdx-kit/branding';

function Header() {
  return <KLogo size={32} variant="dark" />;
}
```

### Tailwind CSS Integration

```javascript
// tailwind.config.js
import kodexaTokens from '@kodexalabs/kdx-kit/tailwind';

export default {
  content: ['./src/**/*.{js,jsx,ts,tsx}'],
  plugins: [kodexaTokens],
};
```

Now use design tokens in your classes:
```tsx
<div className="bg-brand-background text-brand-foreground">
  Styled with KDX tokens
</div>
```

## 📖 API Reference

### Subpath Exports

```typescript
// Main entry (all exports)
import { Button, colors, KLogo } from '@kodexalabs/kdx-kit';

// Tokens only
import { designTokens, colors } from '@kodexalabs/kdx-kit/tokens';

// Components only
import { Button, Card } from '@kodexalabs/kdx-kit/components';

// Branding only
import { KLogo, KLoadingGrid } from '@kodexalabs/kdx-kit/branding';

// Tailwind plugin
import kodexaTokens from '@kodexalabs/kdx-kit/tailwind';
```

### Available Components

- `Button` - Versatile button component with variants
- `Card` - Card container with header, content, footer
- `ThemeProvider` - Theme context provider
- `AssistantUI` - Assistant interface component

### Design Token Categories

- `colors` - Brand colors, semantic colors, UI colors, grayscale
- `typography` - Font families, sizes, weights, line heights
- `spacing` - Consistent spacing scale (0-96)
- `radius` - Border radius values
- `shadow` - Box shadow definitions
- `motion` - Animation timing and easing
- `layout` - Breakpoints and container widths
- `borderWidth` - Border width scale
- `zIndex` - Z-index layering system

## 🎨 Design Philosophy

**Strict Monochrome** - KDX-Kit follows a pure black-and-white design system:
- Background: `#000000` (pure black)
- Foreground: `#ffffff` (pure white)
- Surface: `hsl(0 0% 7%)`
- Border: `hsl(0 0% 23%)`

**No accent colors** - All UI states use contrast, borders, and opacity instead of color.

## 🔄 Migration Guide

Migrating from split packages (`@kodexalabs/asd-tokens` + `@kdx-kit/ui`)?

**Before:**
```typescript
import { colors } from '@kodexalabs/asd-tokens';
import { Button } from '@kdx-kit/ui';
```

**After:**
```typescript
import { colors, Button } from '@kodexalabs/kdx-kit';
```

See full migration guide: [migrate-to-kdx-kit.md](https://github.com/kodexalabs/kdx-kit/blob/main/docs/migrate-to-kdx-kit.md)

## 📚 Documentation

- [Target Architecture](https://github.com/kodexalabs/kdx-kit/blob/main/docs/kdx-kit-target-architecture.md)
- [Publishing Roadmap](https://github.com/kodexalabs/kdx-kit/blob/main/docs/kdx-kit-publishing-roadmap.md)
- [Architecture Rules](https://github.com/kodexalabs/kdx-kit/blob/main/docs/kdx-kit-architecture-rules.md)

## 🛠️ Requirements

- **Node.js**: >=18.0.0
- **React**: ^18.0.0
- **TypeScript**: ^5.0.0 (recommended)

## 📄 License

MIT © [KodexaLabs](https://github.com/kodexalabs)

## 🤝 Contributing

This package consolidates the Kodexalabs design system. For issues or contributions, please visit the [GitHub repository](https://github.com/kodexalabs/kdx-kit).

## 📦 Package Info

- **Version**: 1.0.0
- **Bundle Size**: ~24 KB (gzipped)
- **TypeScript**: Full type definitions included
- **Tree-shakeable**: ESM and CJS builds
- **React**: Server Components compatible (`"use client"` directives included)