npm package: @nyuchi/ubuntu
Description: Ubuntu philosophy utilities for Nyuchi Platform - The ethical operating system for community technology
Latest version: 1.0.0

# @nyuchi/ubuntu

Ubuntu philosophy utilities for the Nyuchi Platform.

> "I am because we are" - Ubuntu

## Installation

```bash
npm install @nyuchi/ubuntu
```

## Overview

This package provides utilities for implementing the Ubuntu philosophy that drives the Nyuchi Africa platform. Ubuntu emphasizes community, interconnectedness, and collective growth.

**Important**: Ubuntu is the *philosophy*, not the brand name. The brand is always "Nyuchi" or "Nyuchi Africa".

**Note**: For design tokens, use `@nyuchi/theme`. For UI components, use `@nyuchi/ui`. Both derive from `assets/guidelines/brand-system-v5.json`.

## Usage

### Ubuntu Messages

```typescript
import {
  getUbuntuMessage,
  getRandomUbuntuMessage,
  formatUbuntuMessage,
  UBUNTU_PRINCIPLE,
} from '@nyuchi/ubuntu';

// Core principle
console.log(UBUNTU_PRINCIPLE); // "I am because we are"

// Get message for specific context
const welcomeMsg = getUbuntuMessage('welcome');
// { type: 'welcome', message: 'Welcome to the Nyuchi community', ... }

// Get random motivational message
const randomMsg = getRandomUbuntuMessage();

// Format for display
const formatted = formatUbuntuMessage(welcomeMsg);
```

### Contribution Scoring

```typescript
import {
  calculateUbuntuLevel,
  awardPoints,
  getLevelDescription,
  getLevelColor,
  UBUNTU_POINTS,
  UBUNTU_LEVELS,
} from '@nyuchi/ubuntu';

// Award points for a contribution
const points = awardPoints('content_published'); // 100

// Calculate level from points
const level = calculateUbuntuLevel(1500); // 'Contributor'

// Get level description and color (Zimbabwe flag colors)
const desc = getLevelDescription(level);
const color = getLevelColor(level);
```

## Contribution Levels

| Level | Points | Color | Description |
|-------|--------|-------|-------------|
| Newcomer | 0 - 999 | Yellow | Welcome to the community |
| Contributor | 1,000 - 4,999 | Green | Making a difference |
| Community Leader | 5,000 - 9,999 | Red | Inspiring others |
| Ubuntu Champion | 10,000+ | Black | True community pillar |

## Point Values

| Contribution Type | Points |
|-------------------|--------|
| `collaboration` | 150 |
| `content_published` | 100 |
| `listing_verified` | 75 |
| `knowledge_sharing` | 75 |
| `listing_created` | 50 |
| `review_completed` | 50 |
| `community_help` | 25 |

## Message Contexts

Available contexts for `getUbuntuMessage()`:
- `welcome`, `welcomeBack` - Welcome messages
- `contentPublished`, `listingCreated`, `communityHelp` - Contributions
- `achievementUnlocked`, `levelUp` - Success
- `collaboration`, `teamwork` - Collaboration
- `loading`, `processing` - Loading states
- `error`, `notFound` - Error states

## Philosophy

The Nyuchi brand is rooted in the Shona word "nyuchi" (bee), symbolizing:

- **Collective Effort** - Bees work together for the hive
- **Pollination** - Spreading knowledge across the ecosystem
- **Community Building** - Strengthening through connection

## Related Packages

- `@nyuchi/theme` - Design tokens (colors, typography, spacing)
- `@nyuchi/ui` - Material UI components and themes

## License

MIT - Nyuchi Tech