@grupor5/raya 0.1.0

package/README.md

@@ -0,0 +1,266 @@
+# 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.
+
+## ✅ Current Status
+
+- **Colors**: ✅ Validated and corrected against design palette
+- **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
+└── 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 */
+}
+```
+
+## ✍️ 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 with a **4px base unit** and mathematical progression, featuring an 8-level spacing system for consistent spatial relationships.
+
+### Spacing Scale
+- **XS**: 4px - Minimal spacing, tight layouts
+- **S**: 8px - Small gaps, compact components
+- **M**: 16px - Default spacing, standard gaps
+- **L**: 24px - Comfortable spacing, section gaps
+- **XL**: 32px - Large spacing, major sections
+- **2XL**: 40px - Extra large spacing, page sections
+- **3XL**: 48px - Generous spacing, hero sections
+- **4XL**: 56px - Maximum spacing, major layouts
+
+### Mathematical Progression
+Based on 4px base unit with carefully crafted multipliers:
+- **Base**: 4px (XS) = 4px × 1
+- **Double**: 8px (S) = 4px × 2
+- **Quadruple**: 16px (M) = 4px × 4
+- **6x**: 24px (L) = 4px × 6
+- **8x**: 32px (XL) = 4px × 8
+- **10x**: 40px (2XL) = 4px × 10
+- **12x**: 48px (3XL) = 4px × 12
+- **14x**: 56px (4XL) = 4px × 14
+
+### Implementation
+```css
+/* CSS custom properties */
+: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 el paquete desde npm:
+
+```bash
+npm install @grupor5/raya
+```
+
+### Configuración de Tailwind CSS
+
+Para configurar Tailwind CSS, modifica tu archivo `tailwind.config.js`:
+
+```javascript
+module.exports = {
+  presets: [require('@grupor5/raya/tailwind.config.js')],
+  content: [
+    // Rutas a tus archivos de proyecto...
+  ],
+}
+```
+
+### Archivo CSS Global
+
+Finalmente, importa los estilos base de Raya en tu archivo CSS principal (por ejemplo, `styles/globals.css`):
+
+```css
+@import '@grupor5/raya/styles/globals.css';
+```
+
+Esto asegura que todas las variables CSS y estilos base del sistema de diseño estén disponibles en tu aplicación.
+
+## 🧩 Components (Coming Soon)
+
+React components built on shadcn/ui foundation:
+- Button (variants: primary, secondary, ghost, destructive)
+- Input, Textarea, Select
+- Card, Dialog, Popover
+- Navigation, Breadcrumb, Pagination
+- Alert, Toast, Badge
+
+## 📖 Documentation
+
+The documentation is organized into four main categories:
+
+- **Architectural Decision Records (ADRs)**: Documents key architectural decisions and their rationale.
+- **Design Guidelines**: Provides detailed specifications for the core elements of the design system.
+- **Usage Examples**: Offers practical guidance and inspiration for using components and tokens.
+- **Testing Reports**: Contains validation and testing results for different parts of the system.
+
+### Architectural Decision Records (ADRs)
+
+- [ADR 003: Icons System](./docs/adr/003-icons-system.md)
+- [ADR 004: Buttons System](./docs/adr/004-buttons-system.md)
+
+### Design Guidelines
+
+- [Alerts](./docs/guidelines/alert.md)
+- [Badge](./docs/guidelines/badge.md)
+- [Buttons](./docs/guidelines/buttons.md)
+- [Checkbox](./docs/guidelines/checkbox.md)
+- [Colors](./docs/guidelines/colors.md)
+- [Effects](./docs/guidelines/effects.md)
+- [Grids](./docs/guidelines/grids.md)
+- [Icons](./docs/guidelines/icons.md)
+- [Input](./docs/guidelines/input.md)
+- [Progress Bar](./docs/guidelines/progress-bar.md)
+- [Radio](./docs/guidelines/radio.md)
+- [Spacing](./docs/guidelines/spacing.md)
+- [Stepper](./docs/guidelines/stepper.md)
+- [Stroke](./docs/guidelines/stroke.md)
+- [Switch](./docs/guidelines/switch.md)
+- [Tabs](./docs/guidelines/tabs.md)
+- [Tag](./docs/guidelines/tag.md)
+- [Textarea](./docs/guidelines/textarea.md)
+- [Typography](./docs/guidelines/typography.md)
+
+### Usage Examples
+
+- [Alert Usage](./docs/usage_examples/alert-usage.md)
+- [Buttons Usage](./docs/usage_examples/buttons-usage.md)
+- [Effects Usage](./docs/usage_examples/effects-usage.md)
+- [Grids Usage](./docs/usage_examples/grids-usage.md)
+- [Icons Usage](./docs/usage_examples/icons-usage.md)
+- [Spacing Usage](./docs/usage_examples/spacing-usage.md)
+- [Stepper Usage](./docs/usage_examples/stepper-usage.md)
+- [Stroke Usage](./docs/usage_examples/stroke-usage.md)
+- [Typography Usage](./docs/usage_examples/typography-usage.md)
+
+### Testing Reports
+
+- [Buttons Testing Report](./docs/testing/buttons-testing-report.md)
+- [Colors Validation Report](./docs/testing/colors-validation-report.md)
+- [Icons Testing Report](./docs/testing/icons-testing-report.md)
+
+## 🔧 Development
+
+### Running Storybook
+```