Sistema de Diseño Stack-and-Flow

🎯 ¿Qué es este proyecto?

Un Design System moderno, escalable y accesible construido desde cero con React, TypeScript, Tailwind CSS v4 y Storybook. Este proyecto sigue patrones profesionales de arquitectura como Atomic Design y Container/Presentational para mantener un código limpio, predecible y fácil de mantener.

✨ Características principales

• 🧱 Arquitectura Atomic Design: Componentes organizados en átomos, moléculas y organismos
• 🎨 Diseño tokenizado: Sistema consistente de colores, tipografías y espaciados
• ♿ Accesibilidad primero: ARIA attributes, navegación por teclado y cumplimiento WCAG
• 📚 Documentación en vivo: Todos los componentes documentados en Storybook
• 🔒 Type-safe: TypeScript estricto sin any permitidos
• 🎭 Dark mode: Soporte nativo para temas claro y oscuro
• 🚀 Developer Experience: Git hooks, linting automático y herramientas CLI personalizadas

🛠️ Stack Tecnológico

🚀 Inicio Rápido

Prerrequisitos

• Node.js (versión especificada en .nvmrc)
• pnpm - Guía de instalación
• nvm (opcional pero recomendado) - UNIX | Windows

Instalación

# 1. Clonar el repositorio
git clone https://github.com/Stack-and-Flow/design-system.git
cd design-system

# 2. Usar la versión correcta de Node
nvm use

# 3. Instalar dependencias
pnpm install

# 4. Ejecutar Storybook con hot reload
npx storybook-watch

¡Listo! Storybook se abrirá en http://localhost:6006 🎉

📖 Demo en Vivo

Explora todos los componentes y su documentación interactiva:

🔗 sf-design-system.netlify.app

🏗️ Arquitectura de Componentes

Cada componente sigue una estructura estricta de 5 archivos que separa responsabilidades:

src/components/atoms/button/
├── Button.tsx           # Capa Presentacional (solo JSX)
├── useButton.ts         # Capa Container (lógica + CVA)
├── types.ts             # Tipos + Variantes CVA
├── index.ts             # Exportaciones públicas
└── Button.stories.tsx   # Documentación Storybook

¿Por qué esta arquitectura?

• ✅ Separación clara de lógica y presentación
• ✅ Reutilización de hooks entre componentes
• ✅ Testing simplificado (prueba lógica independiente de UI)
• ✅ Escalabilidad predecible y mantenible

🤝 ¿Cómo Contribuir?

Este es un proyecto educativo y abierto a colaboración. Nos encantaría que participes, sin importar tu nivel de experiencia.

Flujo de Trabajo

1. Investiga componentes similares y patrones
2. Define la funcionalidad, props, variantes y casos de uso
3. Implementa siguiendo la arquitectura de 5 archivos
4. Documenta en Storybook con controles y ejemplos
5. Abre un PR siguiendo Conventional Commits

🚀 ¿Primera vez? Sigue la Quick Start Guide y haz tu primera contribución en menos de 10 minutos.

📚 Documentación completa: Lee CONTRIBUTING.md y GUIDELINES.md antes de empezar.

Reglas de Oro

• ✅ Solo usamos Radix UI como librería base (primitivos sin estilos)
• ✅ Usa tokens del sistema (colores, espaciados, fuentes) en src/styles/theme.css
• ✅ TypeScript estricto: tipos explícitos, nada de any
• ✅ Accesibilidad obligatoria: atributos ARIA, navegación por teclado
• ✅ Inglés en código: variables, comentarios y documentación

💡 ¿Tienes ideas?

• 🆕 Propón componentes en el Kanban Board
• 🐛 Reporta bugs usando las plantillas de issues
• 💬 Contacta al Project Lead para discutir features antes de implementar

🧰 Herramientas del Proyecto

Compilot CLI

Herramienta interactiva para scaffolding de componentes y mantenimiento.

npx compilot-cli

📖 Más información

Storybook Watch

Hot reload inteligente para Storybook durante desarrollo.

npx storybook-watch

📖 Más información

Playwright MCP (AI Visual Audit)

Herramienta para que el agente AI pueda abrir el navegador, navegar Storybook y tomar capturas de pantalla durante auditorías visuales. Es infraestructura del agente — no forma parte del proyecto ni se instala con pnpm install.

Nota: Solo es necesario si usas un agente AI (como opencode) para hacer auditorías visuales de componentes.

Prerrequisitos

• opencode u otro cliente AI compatible con MCP
• Node.js disponible globalmente

Configuración

Añade el siguiente bloque a tu archivo de configuración del agente (p. ej. ~/.config/opencode/opencode.json):

"playwright": {
  "type": "local",
  "command": [
    "npx",
    "@playwright/mcp@latest",
    "--output-dir",
    ".playwright-mcp"
  ]
}

Reemplaza /ruta/absoluta/a/tu/proyecto/screenshots con la ruta real en tu máquina.

Carpeta de capturas

Las capturas se guardan en screenshots/ en la raíz del proyecto. Esta carpeta está incluida en .gitignore — no se sube al repositorio.

# La carpeta ya existe en el repo (vacía, ignorada por git)
screenshots/

---

📚 Recursos de Aprendizaje

• HeroUI: UI library reference
• 📖 Wiki Deepwiki: deepwiki.com/Stack-and-Flow/design-system
• 🎨 Referencias UI: UI Libraries repo
• 📋 Kanban Board: GitHub Projects

🎓 Proyecto Educativo

Este repositorio tiene fines educativos y está completamente abierto a colaboración. Si estás interesado en:

• Aprender cómo se construye un Design System profesional
• Mejorar tus habilidades en React, TypeScript o Arquitectura de Software
• Contribuir a un proyecto open-source real
• Trabajar con patrones avanzados (Atomic Design, Container/Presentational)

📩 ¡Contáctame directamente o abre un issue! Eres más que bienvenido.

📫 Contacto

---

⭐ Si este proyecto te resulta útil, considera darle una estrella en GitHub ⭐