npm package: @nyuchi/ui
Description: Nyuchi Brand System - Tailwind 4 design tokens and utilities for the Five African Minerals palette
Author: Nyuchi Africa
Latest version: 1.1.0

# @nyuchi/ui

Tailwind 4 design tokens and utilities for the Nyuchi Brand System using the Five African Minerals palette.

## Source of Truth

This package imports from `assets/v6/guidelines/brand-system-v6.json`. All colors flow from the single JSON source using the Five African Minerals palette.

## Installation

```bash
npm install @nyuchi/ui tailwindcss@^4.0.0
```

## Usage

### CSS Import (Tailwind 4)

```css
@import "tailwindcss";
@import "@nyuchi/ui/css";

/* Your custom styles */
```

### TypeScript/JavaScript

```typescript
import { minerals, brands, getBrand, getBrandCSSVariables } from '@nyuchi/ui';

// Get mineral colors
const cobalt = minerals.cobalt;
// { light: '#0047AB', dark: '#00B0FF', containerLight: '#E3F2FD', ... }

// Get brand configuration
const mukoko = getBrand('mukoko');
// { name: 'Mukoko Platform', primary: { light: '#4B0082', dark: '#B388FF' }, ... }

// Get CSS variables for a brand
const vars = getBrandCSSVariables('nyuchi', 'dark');
// { '--primary': '#FFD740', '--secondary': '#64FFDA', '--bg': '#0A0A0A', ... }
```

### Tailwind Theme Values

```typescript
import { tailwindTheme } from '@nyuchi/ui/preset';

// Use in your tailwind config if needed
export default {
  theme: {
    extend: tailwindTheme
  }
};
```

## Available Exports

### Design Tokens

- `minerals` - Five African Minerals with light/dark values
- `backgrounds` - Surface colors for light/dark modes
- `textColors` - Text colors for light/dark modes
- `semanticColors` - Success, error, warning, info colors
- `flagColors` - Zimbabwe flag colors
- `spacing` - Spacing scale
- `borderRadius` - Border radius values
- `shadows` - Shadow definitions
- `fontFamily` - Font family definitions
- `fontSize` - Font size scale

### Brand Configuration

- `brands` - All 7 brand configurations
- `getBrand(key)` - Get a specific brand
- `getBrandCSSVariables(key, mode)` - Get CSS variables for a brand

### CSS Classes

The CSS import includes:

**Buttons:**
- `.btn`, `.btn-primary`, `.btn-secondary`, `.btn-outline`

**Cards:**
- `.card`, `.card-interactive`

**Minerals Strip:**
- `.minerals-strip` - Vertical gradient strip (4px left edge)

**Inputs:**
- `.input`

**Badges:**
- `.badge`, `.badge-cobalt`, `.badge-tanzanite`, `.badge-malachite`, `.badge-gold`, `.badge-terracotta`

**Typography:**
- `.font-display`, `.font-heading`, `.font-body`, `.font-mono`
- `.text-display`, `.text-h1`, `.text-h2`, `.text-h3`, `.text-h4`
- `.text-body-lg`, `.text-body`, `.text-body-sm`, `.text-caption`

## Five African Minerals

| Mineral | Light | Dark | Use Case |
|---------|-------|------|----------|
| Cobalt | `#0047AB` | `#00B0FF` | Education, CTAs |
| Tanzanite | `#4B0082` | `#B388FF` | Mukoko, Premium |
| Malachite | `#004D40` | `#64FFDA` | Travel, Success |
| Gold | `#5D4037` | `#FFD740` | Nyuchi, Rewards |
| Terracotta | `#8B4513` | `#D4A574` | Community, Ubuntu |

All colors achieve **WCAG AAA (7:1+)** contrast in both light and dark modes.

## Design Tokens

### Typography
- **Display/H1**: Noto Serif (400, 700)
- **H2-H6**: Plus Jakarta Sans (600, 700, 800)
- **Body**: Plus Jakarta Sans (300, 400, 500, 600)
- **Code**: JetBrains Mono (400, 500)

### Border Radius
- **Button**: 12px (warm, modern feel)
- **Card**: 16px (generous)
- **Input**: 8px
- **Badge**: 9999px (pill-shaped)

### Surface Colors

**Light Mode** (all brands):
- Base: `#FAF9F5` (Warm Cream)
- Surface: `#FFFFFF`

**Dark Mode**:
- Base: `#0A0A0A` (Charcoal)
- Surface: `#141414`
- Education variant: `#0F172A` (Slate 900)

## Critical Rules

1. **Button Radius = 12px**: Always (not 8px)
2. **Card Radius = 16px**: Generous, modern
3. **Minerals Strip**: 4px VERTICAL stripe on LEFT edge
4. **Travel Brand**: NO purple/tanzanite (nature-forward)
5. **Education Brand**: Use slate dark theme variant
6. **Wordmarks**: Always lowercase

## Related

- `@nyuchi/ubuntu` - Ubuntu philosophy utilities
- [assets.nyuchi.com](https://assets.nyuchi.com) - CDN API
- [brand.nyuchi.com](https://brand.nyuchi.com) - Brand documentation

## License

MIT - Nyuchi Tech