npm package: @horizon-labs/color-palette-generator
Description: Sistema de geração de paletas de cores baseado nas diretrizes Tailwind
Author: Horizon Labs
Latest version: 1.0.1

# @horizon-labs/color-palette-generator

Sistema avançado de geração de paletas de cores baseado nas diretrizes do Tailwind CSS, utilizando algoritmos de mistura percentual e curvas de hue independentes.

## 📋 Visão Geral

Este package implementa um algoritmo sofisticado para gerar paletas de cores completas (20 tons) a partir de uma cor base e sua posição na escala Tailwind. O sistema utiliza:

- **Fórmulas de mistura percentual** com branco/preto baseadas na diferença de luminosidade
- **Curvas de hue independentes** para tons claros e escuros
- **Validações rigorosas** de entrada e formato
- **TypeScript nativo** com tipagem completa

## 🔧 Instalação

```bash
pnpm add @horizon-labs/color-palette-generator
# ou
npm install @horizon-labs/color-palette-generator
```

## 🚀 Uso Básico

```typescript
import { generateColorPalette, logPalette } from '@horizon-labs/color-palette-generator'

// Gerar paleta a partir de uma cor azul na posição 500
const palette = generateColorPalette('#3B82F6', 500)

// Visualizar no console
logPalette(palette, 'blue')

// Acessar cores específicas
console.log(palette[100]) // Tom mais claro
console.log(palette[500]) // Cor base
console.log(palette[900]) // Tom mais escuro
```

## 🎨 Funcionalidades Avançadas

### Curvas de Hue Independentes

```typescript
const palette = generateColorPalette('#3B82F6', 500, {
  hueShiftLight: 10,  // Tons claros ficam 10° mais quentes
  hueShiftDark: -5    // Tons escuros ficam 5° mais frios
})
```

### Validações Automáticas

```typescript
// Cor inválida - lança erro
generateColorPalette('invalid-color', 500)
// Error: Cor inválida: invalid-color. Use formato hex (#RRGGBB)

// Posição inválida - lança erro  
generateColorPalette('#3B82F6', 123)
// Error: Posição inválida: 123. Use uma das posições válidas: 25, 50, 100...
```

## 📐 Algoritmo Detalhado

### 1. Sistema de Mapeamento de Luminosidade

O package usa um mapeamento pré-definido que converte posições Tailwind em valores de luminosidade:

```typescript
const POSITION_LIGHTNESS_MAP = {
  25: 95,    // quase branco
  50: 90,
  100: 80,
  // ... até
  900: 15,
  950: 5     // quase preto
}
```

### 2. Algoritmo de Mistura (Passo 1)

Para cada posição da paleta:

1. **Calcula diferença de luminosidade** entre posição alvo e posição base
2. **Determina direção da mistura:**
   - `luminosityDiff > 0` → mistura com branco
   - `luminosityDiff < 0` → mistura com preto
3. **Calcula percentual de mistura:**
   ```typescript
   // Para tons claros
   const espacoAteOBranco = 100 - baseLuminosity
   const percentualMistura = (Math.abs(luminosityDiff) / espacoAteOBranco) * 100
   
   // Para tons escuros
   const percentualMistura = (Math.abs(luminosityDiff) / baseLuminosity) * 100
   ```

### 3. Aplicação de Hue Shift (Passo 2)

O hue shift é aplicado **após** a mistura, de forma independente:

```typescript
// Intensidade baseada na diferença percentual
const hueIntensity = Math.abs(luminosityDiff) / maxDiff // 0 a 1
const actualHueShift = relevantHueShift * hueIntensity

// Aplicação segura (evita valores negativos/maiores que 360)
const newHue = (currentHue + actualHueShift + 360) % 360
```

### 4. Fórmula de Conversão Shade → Luminosidade

```typescript
function shadeToLuminosity(shade: TailwindPosition): number {
  return Math.max(0, Math.min(100, 100 - shade / 10))
}
```

**Exemplos:**
- 50 → 95% luminosidade
- 500 → 50% luminosidade  
- 900 → 10% luminosidade

## 🔍 Análise Técnica Profunda

### Vantagens do Algoritmo

1. **Precisão Matemática**: Usa diferenças percentuais reais entre luminosidades
2. **Consistência Visual**: Garante progressão uniforme entre tons
3. **Flexibilidade**: Permite ajustes de hue independentes para claros/escuros
4. **Robustez**: Validações impedem entradas inválidas

### Diferenças vs Algoritmos Tradicionais

| Aspecto | Algoritmo Tradicional | Este Package |
|---------|----------------------|--------------|
| Método | Interpolação linear | Mistura percentual |
| Hue Shift | Global ou ausente | Independente claro/escuro |
| Validação | Básica | Rigorosa com TypeScript |
| Luminosidade | Aproximada | Mapeamento preciso |

### Performance

- **Build Size**: ~4KB (CJS) / ~2.7KB (ESM)
- **Dependencies**: Apenas `chroma-js` para manipulação de cores
- **Complexidade**: O(n) onde n = 20 posições (sempre constante)

## 📊 Tipos TypeScript

```typescript
type TailwindPosition = 25 | 50 | 100 | 150 | 200 | 250 | 300 | 350 | 400 | 450 | 500 | 550 | 600 | 650 | 700 | 750 | 800 | 850 | 900 | 950

type ColorPalette = Record<TailwindPosition, string>

interface GenerateOptions {
  hueShiftLight?: number  // -50 a +50 recomendado
  hueShiftDark?: number   // -50 a +50 recomendado
}
```

## 🧪 Testes e Validação

### Casos de Teste Recomendados

```typescript
// Teste básico
const blue = generateColorPalette('#3B82F6', 500)
expect(blue[500]).toBe('#3B82F6')

// Teste com hue shift
const shifted = generateColorPalette('#3B82F6', 500, {
  hueShiftLight: 15,
  hueShiftDark: -10
})

// Validações
expect(() => generateColorPalette('invalid', 500)).toThrow()
expect(() => generateColorPalette('#3B82F6', 999)).toThrow()
```

## 🎯 Casos de Uso

### 1. Design Systems
Gerar paletas consistentes para componentes

### 2. Temas Dinâmicos  
Criar variações de cor em tempo real

### 3. Ferramentas de Design
Integrar em interfaces de seleção de cores

### 4. CSS-in-JS
Gerar variáveis CSS dinamicamente

## 🔄 Comparação com POSITION_LIGHTNESS_MAP

Note que o código possui **duas abordagens** para luminosidade:

1. **`POSITION_LIGHTNESS_MAP`**: Mapeamento fixo (não usado no algoritmo principal)
2. **`shadeToLuminosity()`**: Fórmula dinâmica (usada na geração)

A fórmula `100 - shade/10` é mais simples e garante progressão linear, enquanto o mapeamento fixo permite controle granular por posição.

## 📈 Roadmap

- [ ] Modo de saturação adaptativa
- [ ] Suporte a espaços de cor LAB/LCH
- [ ] Presets para diferentes sistemas de design
- [ ] Ferramenta CLI para geração batch
- [ ] Plugin para Tailwind CSS

## 🤝 Contribuição

Este package foi desenvolvido seguindo as diretrizes do monorepo Horizon Labs. Para contribuir:

1. Mantenha compatibilidade com a API atual
2. Adicione testes para novas funcionalidades  
3. Siga os padrões de código (Prettier + ESLint)
4. Documente mudanças na API

## 📄 Licença

MIT