Este repositorio contiene un diseño de sistema de componentes basado en la metodología Atomic Design, integrado con React, Solid.js, Storybook y Style Dictionary, listo para usarse como paquete npm reutilizable en múltiples proyectos.

✨ Características principales

• 🎨 Sistema de tokens de diseño: Tokens centralizados con Style Dictionary para colores, tipografía, espaciado y más
• 📝 Tokens de tipografía: Escalas (xs → 5xl), familias (Lato, Inter, Roboto) y pesos de fuente como variables CSS
• 🌓 Soporte de temas: Tema claro y oscuro con variables CSS semánticas
• 🧩 Atomic Design: Componentes organizados en átomos, moléculas y organismos
• 📚 Storybook personalizado: Interfaz temática y sección Foundation/Typography para ver escalas y fuentes
• 🎯 Variables CSS: Todas las propiedades de estilo usan variables CSS del design system
• 📦 Paquete npm: Listo para ser importado y usado en cualquier proyecto React/Solid.js
• 🔧 TypeScript: Tipado completo y export de typographyTokens / TypographyTokens

🚅 Inicio rápido

1. Clonar el repositorio

git clone https://github.com/hermes-EY/design-system-storybook.git

2. Instalar dependencias

cd design-system-storybook
npm install

3. Ejecutar Storybook (para desarrollo y revisión de componentes)

npm run storybook

4. Ver tus historias

Abre http://localhost:6006 para ver las historias de tus componentes

📦 Instalación en tu proyecto

Para usar este design system en tu proyecto:

npm install @angel-storybook/design-system

Uso básico

// Importar estilos (incluye theme, foundation, typography, semantic y componentes)
import '@angel-storybook/design-system/styles';

// Importar componentes
import { Button } from '@angel-storybook/design-system';

// Opcional: tokens de tipografía en TypeScript
import { typographyTokens, foundationTokens, semanticTokens } from '@angel-storybook/design-system';

// Usar el componente
<Button label="Click me" primary />

Variables CSS disponibles

El design system expone variables CSS que puedes usar en tus proyectos:

/* Colores foundation */
--ds-color-neutral-50 a --ds-color-neutral-900
--ds-color-primary-50 a --ds-color-primary-900
--ds-color-success-50 a --ds-color-success-900
--ds-color-warning-50 a --ds-color-warning-900
--ds-color-error-50 a --ds-color-error-900

/* Tipografía: escalas (xs, sm, base, lg, xl, 2xl, 3xl, 4xl, 5xl) × variantes (primary, secondary, tertiary) */
--ds-typography-{scale}-{variant}-family   /* ej. --ds-typography-base-primary-family */
--ds-typography-{scale}-{variant}-size
--ds-typography-{scale}-{variant}-weight
--ds-typography-{scale}-{variant}-line-height
--ds-typography-{scale}-{variant}-letter-spacing
--ds-typography-{scale}-{variant}-size-mobile
--ds-typography-{scale}-{variant}-size-desktop

/* Familias y pesos de fuente */
--ds-font-families-primary   /* Lato */
--ds-font-families-secondary /* Inter */
--ds-font-families-tertiary  /* Roboto */
--ds-font-weights-thin, light, normal, medium, semibold, bold, extrabold, black

/* Variables semánticas (tema claro) */
--ds-semantic-light-text-primary
--ds-semantic-light-text-secondary
--ds-semantic-light-surface-background
--ds-semantic-light-surface-card
--ds-semantic-light-button-primary-background

/* Variables semánticas (tema oscuro) */
--ds-semantic-dark-text-primary
--ds-semantic-dark-text-secondary
--ds-semantic-dark-surface-background
--ds-semantic-dark-surface-card
--ds-semantic-dark-button-primary-background

/* Variables de tema (abstracción semántica) */
--ds-theme-text-primary
--ds-theme-text-secondary
--ds-theme-surface-background
--ds-theme-surface-card
--ds-theme-button-primary-background
--ds-theme-button-primary-text
--ds-theme-font-family
--ds-theme-button-border-radius

Ejemplo de uso de variables CSS

.mi-componente {
	background-color: var(--ds-theme-surface-card);
	color: var(--ds-theme-text-primary);
	border: 1px solid var(--ds-color-neutral-700);
	border-radius: var(--ds-theme-button-border-radius);
	font-family: var(--ds-theme-font-family);
}

/* Tipografía con tokens (Lato/Inter/Roboto por variante) */
.titulo {
	font-family: var(--ds-typography-2xl-primary-family);
	font-size: var(--ds-typography-2xl-primary-size);
	font-weight: var(--ds-typography-2xl-primary-weight);
	line-height: var(--ds-typography-2xl-primary-line-height);
	letter-spacing: var(--ds-typography-2xl-primary-letter-spacing);
}

🔎 Estructura del proyecto

La estructura del proyecto sigue las mejores prácticas de desarrollo y está organizada para facilitar la navegación y el mantenimiento:

.
├── .storybook              # Configuración de Storybook
│   ├── manager.ts          # Configuración del tema de Storybook
│   ├── preview.tsx         # Configuración del preview
│   └── preview-head.html   # Estilos personalizados de Storybook
├── design-tokens           # Tokens de diseño (JSON)
│   ├── Foundations.json    # Colores base (neutral, primary, success, etc.)
│   ├── semantic.json       # Tokens semánticos (light/dark)
│   └── typography.json     # Escalas tipográficas y familias (Lato, Inter, Roboto)
├── scripts                 # Scripts de build
│   └── generate-theme-variables.mjs  # Genera variables de tema
├── src
│   ├── components          # Componentes organizados por Atomic Design
│   │   ├── atoms           # Componentes básicos (Button, Input, etc.)
│   │   ├── molecules       # Combinaciones de átomos
│   │   └── organisms       # Componentes complejos
│   ├── styles              # Estilos del design system
│   │   ├── design-tokens   # Tokens generados por Style Dictionary
│   │   │   ├── foundation.css    # Variables de colores
│   │   │   ├── semantic.css      # Variables semánticas
│   │   │   ├── theme.css         # Variables de tema (abstracción)
│   │   │   └── typography.css    # Variables de tipografía (escalas y familias)
│   │   └── index.css       # Punto de entrada de estilos
│   ├── stories             # Historias de Storybook
│   │   ├── foundation      # Foundation/Typography (escalas y fuentes)
│   │   └── atoms           # Atoms (Button, ThemeToggle, etc.)
│   └── index.ts            # Exportaciones principales (Button, tokens, etc.)
├── dist                    # Build de producción
├── package.json
└── style-dictionary.config.mjs  # Configuración de Style Dictionary

Descripción de los archivos y directorios

• .storybook: Configuración de Storybook, tema personalizado y carga de estilos del design system (incl. typography)
• design-tokens: Tokens en JSON (Foundations, semantic, typography) que Style Dictionary transforma a CSS/TS
• scripts: Scripts de automatización (p. ej. generate-theme-variables.mjs) para variables de tema
• src/components: Componentes según Atomic Design (atoms, molecules, organisms)
• src/styles: Estilos y tokens generados (foundation, semantic, theme, typography)
• src/stories: Historias de Storybook (atoms, foundation/Typography)
• dist: Build de producción para publicación npm
• style-dictionary.config.mjs: Configuración de Style Dictionary para generar CSS y TypeScript desde los tokens

🎨 Sistema de tokens de diseño

El design system utiliza Style Dictionary para gestionar los tokens de diseño de forma centralizada.

Tipos de tokens

1. Foundation Tokens: Valores base (colores)

   • Ubicación: design-tokens/Foundations.json
   • Genera: src/styles/design-tokens/foundation.css

2. Typography Tokens: Escalas tipográficas y familias de fuente

   • Ubicación: design-tokens/typography.json
   • Genera: src/styles/design-tokens/typography.css y typography.ts
   • Escalas: xs, sm, base, lg, xl, 2xl, 3xl, 4xl, 5xl
   • Variantes: primary (Lato), secondary (Inter), tertiary (Roboto)
   • Incluye: fontFamilies, fontWeights, size, lineHeight, letterSpacing (y sizeMobile/sizeDesktop)

3. Semantic Tokens: Tokens con significado semántico (light/dark)

   • Ubicación: design-tokens/semantic.json
   • Genera: src/styles/design-tokens/semantic.css

4. Theme Tokens: Abstracción semántica para facilitar el cambio de tema

   • Genera: src/styles/design-tokens/theme.css
   • Mapea tokens semánticos a variables reutilizables (y métricas de botón/tipografía de tema)

Comandos de build

# Generar tokens foundation y semantic
npm run build:tokens

# Generar variables de tema
npm run build:theme-variables

# Build completo (tokens + tema + compilación)
npm run build:lib

🌓 Temas (Light/Dark)

El design system soporta temas claro y oscuro mediante variables CSS semánticas:

• Tema claro: Variables con prefijo --ds-semantic-light-*
• Tema oscuro: Variables con prefijo --ds-semantic-dark-*
• Variables de tema: Abstracción --ds-theme-* que mapea al tema activo

Cambiar de tema

Las variables de tema (--ds-theme-*) se mapean automáticamente según el tema activo. Para cambiar de tema, simplemente cambia qué variables semánticas se asignan a las variables de tema.

📚 Storybook personalizado

Storybook está completamente personalizado con los colores y estilos del design system:

• Tema oscuro: Interfaz de Storybook con tema oscuro personalizado
• Foundation/Typography: Sección con historias de escalas (xs → 5xl), familias (Lato, Inter, Roboto) y pesos de fuente, usando las variables --ds-typography-*
• Controles temáticos: Todos los controles (inputs, selects, switches) usan los colores del design system
• Tablas de props: Estilizadas con los colores del tema
• Bloques de código: Con el mismo estilo que las tablas de props
• Variables CSS: Todo usa variables del design system; en el canvas se prioriza la tipografía del design system (Lato por defecto)

Estructura de carpetas y archivos

La estructura de carpetas y archivos sigue la metodología Atomic Design, que organiza los componentes en niveles jerárquicos:

• Átomos/Atoms: Componentes más pequeños e indivisibles, como botones e inputs.
• Moléculas/Molecules: Combinaciones de átomos que forman componentes más complejos, como campos de formulario.
• Organismos/Organisms: Combinaciones de moléculas que forman secciones completas de la interfaz, como formularios de inicio de sesión.
• Plantillas/Templates: Estructuras de página que combinan organismos y definen el diseño general.
• Páginas/Pages: Combinaciones de plantillas y datos específicos que representan vistas completas de la aplicación.

Uso de Storybook

Storybook es una herramienta de desarrollo que permite crear y documentar componentes de UI de forma aislada. En este proyecto, Storybook se utiliza para:

• Desarrollar y probar componentes de forma aislada.
• Documentar los componentes con historias que muestran diferentes estados y variaciones.
• Facilitar la colaboración entre diseñadores y desarrolladores al proporcionar una interfaz visual para los componentes.
• Visualizar componentes con el tema personalizado del design system.

🛠️ Comandos disponibles

• npm run storybook: Inicia el servidor de desarrollo de Storybook para ver y probar los componentes.
• npm run build:lib: Compila los componentes en un paquete npm listo para ser publicado.
• npm run build:tokens: Genera los tokens CSS desde los archivos JSON usando Style Dictionary.
• npm run build:theme-variables: Genera las variables de tema que mapean tokens semánticos.
• npm run types: Genera los tipos TypeScript para el paquete.
• npm run clean: Limpia el directorio dist.

📖 Documentación adicional

Para más información sobre cómo usar los componentes, consulta la documentación en Storybook ejecutando npm run storybook y navegando por las historias de cada componente.

🤝 Contribuir

Las contribuciones son bienvenidas. Por favor, asegúrate de seguir las convenciones del proyecto y de actualizar los tokens de diseño si es necesario.

📄 Licencia

El proyecto está licenciado bajo la licencia MIT.