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.

// ✅ 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.

# 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

/* 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

// 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

/* 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

// 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

: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

// 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:

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)

// 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

// 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

// ✅ 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

// 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:

// 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

# 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:

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)

# 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)

# 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:

# 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

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