npm package: @nyuchi/theme
Description: Nyuchi Brand System - Design tokens for all brand families (v5 + v6 Five Minerals)
Author: Nyuchi Africa
Latest version: 2.0.0

# @nyuchi/theme

Design tokens for all 5 Nyuchi brand families with WCAG 2.2 compliant colors.

## Source of Truth

This package imports from `assets/guidelines/brand-system-v5.json` and exports TypeScript types. The JSON file is THE single source of truth for all brand colors.

```
assets/guidelines/brand-system-v5.json   ← Master source
        ↓
@nyuchi/theme                            ← This package (TypeScript exports)
        ↓
@nyuchi/ui, consuming apps               ← Import from here
```

## Installation

```bash
npm install @nyuchi/theme
```

## 5 Brand Families

| Brand | Primary | Dark Mode Surface |
|-------|---------|-------------------|
| Nyuchi Platform | `#D4634A` Sunset Deep | `#171717` Off-black |
| Mukoko Platform | `#5E6AD2` Purple | `#1a1625` Dark Purple |
| Travel Brand | `#0D7D5F` Teal Green | `#171717` Off-black |
| Education Brand | `#1E3A8A` Navy Blue | `#0f172a` Slate |
| Community Brand | `#F59E0B` Gold | `#171717` Off-black |

**Light Mode**: Standard off-white `#FAF9F5` for all brands.

## Usage

### Import Design Tokens

```typescript
import {
  brandColors,
  surfaceColors,
  darkSurfaceColors,
  darkAccentColors,
  typography,
  spacing,
  borderRadius,
  shadows,
} from '@nyuchi/theme';

// Brand primary colors (from JSON source)
console.log(brandColors.sunsetDeep); // '#D4634A'
console.log(brandColors.purple);     // '#5E6AD2'

// Surface colors
console.log(surfaceColors.default);      // '#FAF9F5' (light mode)
console.log(darkSurfaceColors.mukoko);   // '#1a1625' (dark purple)
console.log(darkSurfaceColors.education); // '#0f172a' (slate)
```

### Get Brand Configuration

```typescript
import { getBrand, getBrandCSSVariables } from '@nyuchi/theme';

// Get full brand config
const mukoko = getBrand('mukoko');
console.log(mukoko.colors.primary); // '#5E6AD2'

// Generate CSS variables for a brand
const cssVars = getBrandCSSVariables(mukoko);
// Returns: { '--color-primary': '#5E6AD2', ... }
```

### Access Raw JSON

```typescript
import { brandSystemJson } from '@nyuchi/theme';

// Direct access to the source of truth
console.log(brandSystemJson.colorSystem.nyuchiBrand.primary.value);
console.log(brandSystemJson.surfaces.darkMode.education.background);
```

### Quick Access to Primary Colors

```typescript
import { brandPrimaryColors } from '@nyuchi/theme';

console.log(brandPrimaryColors.nyuchi);    // '#D4634A'
console.log(brandPrimaryColors.mukoko);    // '#5E6AD2'
console.log(brandPrimaryColors.travel);    // '#0D7D5F'
console.log(brandPrimaryColors.education); // '#1E3A8A'
console.log(brandPrimaryColors.community); // '#F59E0B'
```

### Typography

```typescript
import { fontFamily, fontSize, fontWeight, typographyPresets } from '@nyuchi/theme';

// Font families
console.log(fontFamily.display); // 'Noto Serif'
console.log(fontFamily.body);    // 'Plus Jakarta Sans'

// Typography presets
const h1Style = typographyPresets.h1;
// { fontFamily: 'Noto Serif', fontSize: '3rem', fontWeight: 700, ... }
```

### Spacing & Layout

```typescript
import { spacing, borderRadius, shadows, breakpoints } from '@nyuchi/theme';

// Border radius
console.log(borderRadius.button); // '0.75rem' (12px)
console.log(borderRadius.card);   // '1rem' (16px)
```

## Exports

### Colors (derived from JSON)
- `brandColors` - Brand primary colors
- `surfaceColors` - Light mode surfaces (off-white for all)
- `darkSurfaceColors` - Per-brand dark mode backgrounds
- `darkAccentColors` - Per-brand dark mode accents
- `flagColors` - Zimbabwe flag colors
- `flagStripColors` - Flag strip colors
- `semanticColors` - Success, warning, error, info
- `neutralColors` - Gray scale
- `textColors` - Text color variants
- `brandSystemJson` - Raw JSON source of truth

### Typography
- `fontFamily` - Font stacks (display, heading, body, mono)
- `fontSize` - Size scale (xs to 5xl)
- `fontWeight` - Weight scale (300-700)
- `lineHeight` - Line height presets
- `typographyPresets` - Complete presets (h1-h6, body, etc.)

### Spacing & Layout
- `spacing` - Spacing scale (rem)
- `spacingPx` - Spacing scale (px)
- `borderRadius` - Radius tokens
- `shadows` - Shadow presets
- `transitions` - Animation timings
- `breakpoints` - Responsive breakpoints

### Brand Configs
- `nyuchiPlatform`, `mukokoPlatform`, `travelBrand`, `educationBrand`, `communityBrand`
- `getBrand(key)` - Get brand by key
- `getBrandCSSVariables(brand)` - Generate CSS variables
- `getBrandMUIColors(brand)` - Get Material UI palette

## License

MIT - Nyuchi Tech