npm package: @grupor5/raya
Description: A comprehensive, extensible design system built with **shadcn/ui** and **Tailwind CSS**, designed for React applications with future Flutter support.
Latest version: 0.2.50

# Raya Design System

A comprehensive, extensible design system built with **shadcn/ui** and **Tailwind CSS**, designed for React applications with future Flutter support.

## 🎯 Overview

The Raya Design System provides a unified approach to building consistent, accessible, and beautiful user interfaces across all Raya products. Built on top of industry-standard tools, it ensures rapid development while maintaining design consistency.

## ⚡ Bundle Size Optimization

**v0.2.2** introduces major bundle size optimizations:

- **Icons Package**: Reduced from ~856KB to ~5.3KB gzipped (98% reduction)
- **Main Package**: Individual imports reduce bundle size by up to 94%
- **Tree-shaking**: Optimal support for importing only what you need

### Bundle Size Comparison

| Import Method | Bundle Size | Best For |
|--------------|-------------|----------|
| Barrel Import (`@grupor5/raya`) | ~97KB gzipped | Prototypes, small apps |
| Individual Imports | ~3-50KB gzipped | Production apps |
| Single Component | ~3-11KB gzipped | Micro-frontends |

**Example**: `Button + Input + Card`
- **Before**: ~321KB (barrel import)
- **After**: ~18KB (individual imports)
- **Reduction**: 94% smaller!

## 🎨 Complete Color System Export

**🆕 NEW in v0.2.24**: All color combinations are now fully exported and available for external use!

### ✅ Available Color Classes

**194 out of 204 color classes (95.1% coverage)** including:

- **Primary Colors**: All shades (100-1200) in `text-`, `bg-`, and `border-` variants
- **Secondary Colors**: Complete range with all variants
- **Neutral Colors**: Full neutral palette support
- **Status Colors**: Destructive (red), success (green), warning (yellow)
- **Theme Colors**: Foreground, background, accent, card, muted, etc.

```tsx
// ✅ All these classes are now available in external projects:

// Primary colors
<div className="text-primary-600 bg-primary-100 border-primary-300">
  Primary styling
</div>

// Secondary colors  
<div className="text-secondary-600 bg-secondary-100 border-secondary-300">
  Secondary styling
</div>

// Status colors
<div className="text-red-600 bg-green-100 border-yellow-300">
  Status styling
</div>

// Theme colors
<div className="text-foreground bg-background border-border">
  Theme styling
</div>
```

### 📊 Color Validation

Run `npm run validate-colors` to verify all color classes are properly exported. The validation also generates an interactive HTML test file to visually verify colors.

```bash
# Validate color export
npm run validate-colors

# Full validation (grid + colors)
npm run validate
```

## ✅ Current Status

- **Colors**: ✅ Validated and corrected against design palette (**95.1% exported**)
- **Typography**: ✅ Complete with Rubik font family and 4-scale system
- **Spacing**: ✅ Complete with 4px base unit and 8-level system
- **Components**: 🚧 React components based on shadcn/ui
- **Documentation**: ✅ Complete color, typography, and spacing documentation
- **Tokens**: ✅ Synchronized hex, HSL, typography, and spacing implementations

## 🏗️ Architecture

### Technology Stack
- **React Components**: Built on shadcn/ui foundation
- **Styling**: Tailwind CSS with custom design tokens
- **Design Tokens**: JSON-based, platform-agnostic
- **Typography**: Rubik font family with comprehensive scales
- **Documentation**: Markdown with usage examples and Storybook
- **Future**: Planned Flutter implementation

### Project Structure
```
design_system/
├── src/
│   ├── tokens/               # Design tokens (colors, typography, spacing)
│   ├── styles/              # Global CSS and theme variables
│   └── components/          # React components (planned)
├── docs/                    # Documentation
│   ├── guidelines/         # Design system guidelines
│   │   ├── colors.md       # Color system documentation
│   │   └── typography.md   # Typography system documentation
│   └── usage_examples/     # Usage guides and examples
│       └── typography-usage.md # Typography usage guide
├── scripts/                # Validation and build scripts
│   ├── validate-grid.js    # Grid system validation
│   └── validate-colors.js  # Color export validation
└── stories/                # Storybook examples
```

## 🎨 Color System

Our color system has been **validated and corrected** to ensure perfect alignment with the design palette.

### Color Families
- **Primary**: 240° hue, 12 shades (100-1200) - Main brand color
- **Secondary**: 271° hue, 12 shades (100-1200) - Accent color  
- **Neutral**: Grayscale, 8 shades - Text, backgrounds, borders
- **Feedback**: Red, Yellow, Green - Semantic states

### Implementation
```css
/* HSL format for optimal theming */
:root {
  --primary: 240 18% 51%;        /* #6b6b98 */
  --secondary: 271 75% 54%;      /* #8d32e2 */
  --background: 0 0% 100%;       /* white */
  --foreground: 240 14% 21%;     /* #2e2e3d */
}
```

### External Usage
```tsx
// Import the CSS to get all color classes
import "@grupor5/raya/dist/tailwind.css";

// Use any color combination
<Title level={1} className="text-secondary-600">
  Estamos por cambiar lo que sabes sobre <span className="text-secondary-600">Seguros</span>.
</Title>
```

## ✍️ Typography System

Built with **Rubik** font family, featuring a comprehensive 4-scale system optimized for readability and hierarchy.

### Typography Scales
- **Display**: 5 sizes (72px - 30px) - Hero sections and prominent headers
- **Heading**: 6 sizes (24px - 12px) - Semantic headings (H1-H6)
- **Body**: 5 sizes (20px - 12px) - Paragraphs and general content
- **Caption**: 4 sizes (14px - 10px) - Labels, metadata, supporting info

### Font Weights
- **Light (300)**: Decorative text, large displays
- **Regular (400)**: Body text, paragraphs
- **Medium (500)**: Labels, captions, emphasis
- **Semi Bold (600)**: Headings, subheadings
- **Bold (700)**: Display text, strong emphasis

### Implementation
```css
/* Typography CSS variables */
:root {
  --font-primary: 'Rubik', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
  --text-display-lg: 3rem;       /* 48px */
  --text-heading-xl: 1.5rem;     /* 24px */
  --text-body-md: 1rem;          /* 16px */
  --text-caption-lg: 0.875rem;   /* 14px */
}
```

### Usage Examples
```tsx
// Display typography
<h1 className="text-display-l">Hero Title</h1>

// Headings with semantic structure
<h2 className="text-heading-xl">Section Title</h2>

// Body text
<p className="text-body-md">Paragraph content</p>

// Form labels and captions
<label className="text-caption-c1">FORM LABEL</label>
```

## 📐 Spacing System

Built on a **4px base unit** for consistent rhythm and visual hierarchy.

### Spacing Scale
```css
:root {
  --spacing-xs: 0.25rem;   /* 4px */
  --spacing-s: 0.5rem;     /* 8px */
  --spacing-m: 1rem;       /* 16px */
  --spacing-l: 1.5rem;     /* 24px */
  --spacing-xl: 2rem;      /* 32px */
  --spacing-2xl: 2.5rem;   /* 40px */
  --spacing-3xl: 3rem;     /* 48px */
  --spacing-4xl: 3.5rem;   /* 56px */
}
```

### Usage Examples
```tsx
// Button spacing
<button className="px-m py-s">Medium Button</button>

// Card spacing
<div className="p-l">Comfortable Card</div>

// Layout spacing
<section className="mb-2xl">Major Section</section>

// Form spacing
<div className="space-y-m">
  <input className="px-m py-s" />
  <input className="px-m py-s" />
</div>
```

## 📋 Quick Start

### Instalación

Para integrar Raya en tu proyecto, instala los paquetes desde npm:

```bash
npm install @grupor5/raya @grupor5/raya-icons
```

**Nota importante**: A partir de la versión 0.2.0, los iconos se han separado en un paquete independiente (`@grupor5/raya-icons`) para optimizar el bundle size y mejorar el tree-shaking.

### Configuración de CSS

**Opción 1: Importación directa (Recomendado)**
```tsx
// Importa el CSS compilado con todos los colores
import "@grupor5/raya/dist/tailwind.css";

// Opcional: CSS normalizer para consistencia cross-browser
import "@grupor5/raya/dist/normalize.css";
```

**Opción 2: Configuración avanzada de Tailwind**
```javascript
// tailwind.config.js
module.exports = {
  presets: [require('@grupor5/raya/tailwind.config.js')],
  content: [
    "./src/**/*.{js,ts,jsx,tsx}",
    "./node_modules/@grupor5/raya/dist/**/*.{js,mjs}"
  ],
}
```

### Uso de Componentes

```tsx
// ✅ Importación individual (recomendado para bundle size óptimo)
import { Button } from '@grupor5/raya/atoms/button';
import { Typography, Title } from '@grupor5/raya/atoms/typography';

// ✅ Uso correcto con colores
<Title level={1} className="text-secondary-600 mb-l">
  Estamos por cambiar lo que sabes sobre <span className="text-secondary-600">Seguros</span>.
</Title>

// ✅ O usando Typography directamente
<Typography variant="display-l" className="text-secondary-600 mb-l font-bold">
  Título con colores personalizados
</Typography>
```

### Uso de Iconos

```tsx
// Importación individual de iconos
import { AddIcon, EditIcon } from '@grupor5/raya-icons/icons/AddIcon';

// Uso en componentes
<Button iconLeft={<AddIcon />}>Agregar</Button>
```

## 🎨 Colores Disponibles

Con la versión actualizada, tienes acceso a **194 clases de colores**:

```tsx
// Colores primarios (42 clases)
text-primary-100, text-primary-200, ..., text-primary-1200, text-primary, text-primary-foreground
bg-primary-100, bg-primary-200, ..., bg-primary-1200, bg-primary, bg-primary-foreground  
border-primary-100, border-primary-200, ..., border-primary-1200, border-primary, border-primary-foreground

// Colores secundarios (42 clases)
text-secondary-100, text-secondary-200, ..., text-secondary-1200, text-secondary, text-secondary-foreground
bg-secondary-100, bg-secondary-200, ..., bg-secondary-1200, bg-secondary, bg-secondary-foreground
border-secondary-100, border-secondary-200, ..., border-secondary-1200, border-secondary, border-secondary-foreground

// Colores neutrales (30 clases)
text-neutral-10, text-neutral-20, text-neutral-30, ..., text-neutral-500, text-muted, text-muted-foreground
bg-neutral-10, bg-neutral-20, ..., bg-neutral-500, bg-muted, bg-muted-foreground
border-neutral-10, border-neutral-20, ..., border-neutral-500, border-muted, border-muted-foreground

// Colores de estado (48 clases) 
text-red-100, text-red-200, ..., text-red-600, text-destructive, text-destructive-foreground
text-green-10, text-green-100, ..., text-green-600
text-yellow-10, text-yellow-100, text-yellow-200, text-yellow-300
// + variantes bg- y border-

// Colores de tema (33 clases)
text-foreground, text-background, text-card, text-accent, text-border, etc.
// + variantes bg- y border-
```

## 🔧 Desarrollo

### Scripts Disponibles

```bash
# Desarrollo
npm run dev              # Modo watch para desarrollo
npm run build           # Build de producción
npm run storybook       # Servidor de Storybook

# Validación
npm run validate-grid   # Valida sistema de grid
npm run validate-colors # Valida exportación de colores
npm run validate        # Validación completa

# Testing
npm run test           # Ejecuta tests
npm run chromatic      # Visual testing
```

### Validación de Colores

Para verificar que todos los colores se exportan correctamente:

```bash
npm run validate-colors
```

Esto generará:
- ✅ Reporte de validación en consola
- 📊 Estadísticas de cobertura por categoría
- 🎨 Archivo HTML interactivo para pruebas visuales

## 🚀 Deployment

### Publishing Packages

Este proyecto consta de dos paquetes npm que deben ser publicados por separado:

1. **@grupor5/raya-icons**: Biblioteca de iconos independiente
2. **@grupor5/raya**: Sistema de diseño principal (depende de raya-icons)

#### 1. Publicar Iconos (@grupor5/raya-icons)

```bash
# Navegar al directorio de iconos
cd raya-icons

# Verificar que todos los iconos estén compilados
npm run build

# Aumentar versión (patch, minor, o major)
npm version patch

# Publicar a npm
npm publish
```

#### 2. Publicar Sistema de Diseño (@grupor5/raya)

```bash
# Navegar al directorio del sistema de diseño
cd design_system

# Actualizar la versión de dependencia de raya-icons en package.json si es necesario
# "dependencies": {
#   "@grupor5/raya-icons": "^X.X.X"
# }

# Compilar el paquete
npm run build

# Aumentar versión
npm version patch

# Publicar a npm
npm publish
```

#### Script de Despliegue Automatizado

Para facilitar el proceso, puedes usar el script `deploy.sh` desde la raíz del proyecto:

```bash
# Desde la raíz del proyecto
./deploy.sh
```

Este script:
1. Publica automáticamente `@grupor5/raya-icons` con versión patch
2. Actualiza la dependencia en el sistema de diseño
3. Publica `@grupor5/raya` con versión patch
4. Confirma las publicaciones

#### Versiones y Compatibilidad

- **Versiones patch** (X.X.+1): Correcciones de bugs, nuevos iconos
- **Versiones minor** (X.+1.0): Nuevas funcionalidades, componentes adicionales
- **Versiones major** (+1.0.0): Cambios breaking, nueva arquitectura

**Importante**: Siempre publicar primero `@grupor5/raya-icons` antes que `@grupor5/raya` para mantener la compatibilidad de dependencias.

## 🔧 Development

### Prerequisites

```bash
# Instalar dependencias en ambos proyectos
cd raya-icons && npm install
cd ../design_system && npm install
```