Design System — Atomic Design + Storybook — EnviaYa
Repositorio del design system de **EnviaYa**: tokens de diseño (Style Dictionary), sección **Foundation** en Storybook, componentes **Atomic Design** y paquete npm **`@angel-storybook/design-system`** (v3.0.0) para React.
## ✨ Características principales
- 🎨 **Tokens centralizados**: Colores MD3, roles semánticos, tipografía, layout, radius, shape, elevation, motion e interaction
- 📐 **Foundation en Storybook**: Stories visuales por categoría de token (paletas, grid, motion, etc.)
- 📝 **Tipografía**: Escalas xs → 5xl, variantes primary/secondary/tertiary (Lato, Inter, Roboto)
- 🌓 **Temas claro/oscuro**: Variables `--ds-semantic-light-*` / `--ds-semantic-dark-*` y abstracción `--ds-theme-*`
- 🧩 **Atomic Design**: Atoms (Button, ThemeToggle), molecules y organisms en expansión
- 📦 **Paquete npm**: Componentes, estilos y exports TypeScript de todos los tokens
- 🔧 **TypeScript**: Tipado completo de componentes y tokens
## 🚅 Inicio rápido
```bash
git clone https://github.com/hermes-EY/design-system-storybook.git
cd design-system-storybook
npm install
npm run storybook
```
Abre `http://localhost:6006`. La página de bienvenida está en **StoryBook EnviaYa** (`Configure.mdx`).
## 📦 Instalación en tu proyecto
```bash
npm install @angel-storybook/design-system
```
### Uso básico
```typescript
import "@angel-storybook/design-system/styles";
import {
Button,
ThemeProvider,
typographyTokens,
colorPaletteTokens,
colorRoleTokens,
layoutTokens,
radiusTokens,
elevationTokens,
motionTokens,
interactionTokens,
foundationTokens,
semanticTokens,
} from "@angel-storybook/design-system";
function App() {
return (
);
}
```
> **Peer dependencies**: `react`, `react-dom`, `primereact`, `styled-components`.
### Variables CSS principales
```css
/* Paletas MD3 (color-palettes.json) */
--ds-primary-40;
--ds-neutral-90;
--ds-secondary-80;
--ds-tertiary-40;
--ds-error-80;
--ds-warning-80;
--ds-success-80;
/* Roles semánticos (color-roles.json) */
--ds-roles-primary;
--ds-roles-on-primary;
--ds-color-bg-canvas;
--ds-color-bg-surface;
--ds-color-text-primary;
--ds-outline-outline-variant;
/* Tipografía (typography.json) */
--ds-typography-base-primary-family;
--ds-typography-base-primary-size;
--ds-font-families-primary; /* Lato */
--ds-font-families-secondary; /* Inter */
--ds-font-weights-medium;
/* Layout / grid (grid.json) */
--ds-layout-grid-columns-desktop; /* 12 */
--ds-layout-grid-gutter-tablet;
--ds-layout-grid-margin-mobile;
--ds-layout-container-max-width-desktop;
/* Forma y elevación */
--ds-radius-md;
--ds-elevation-level2-shadow;
/* Motion e interaction */
--ds-motion-duration-normal;
--ds-motion-easing-standard;
--ds-interaction-hover-opacity;
--ds-interaction-focus-opacity;
/* Tema runtime (semantic + theme.css) */
--ds-theme-text-primary;
--ds-theme-button-primary-background;
--ds-semantic-dark-surface-background;
/* Foundation legacy (Foundations.json) */
--ds-color-neutral-800;
--ds-color-primary-500;
```
### Ejemplo CSS
```css
.card {
background: var(--ds-color-bg-surface);
color: var(--ds-color-text-primary);
border-radius: var(--ds-radius-md);
box-shadow: var(--ds-elevation-level1-shadow);
padding: var(--ds-layout-container-padding-mobile);
}
.titulo {
font-family: var(--ds-typography-2xl-primary-family);
font-size: var(--ds-typography-2xl-primary-size);
line-height: var(--ds-typography-2xl-primary-line-height);
}
.animado {
transition: transform var(--ds-motion-duration-fast) var(--ds-motion-easing-standard);
}
```
## 🔎 Estructura del proyecto
```plaintext
.
├── .storybook/
│ ├── main.ts
│ ├── preview.tsx # ThemeProvider + index.css (tokens)
│ ├── preview-head.html # Tema oscuro UI + fixes Foundation swatches
│ └── manager.ts
├── design-tokens/
│ ├── Foundations.json # Colores legacy (neutral, primary, …)
│ ├── color-palettes.json # Paletas MD3 (0–100)
│ ├── color-roles.json # Roles semánticos (bg, text, roles)
│ ├── typography.json
│ ├── grid.json # → layout.css
│ ├── radius.json
│ ├── shape.json
│ ├── elevation.json
│ ├── motion.json
│ ├── interaction.json
│ └── semantic.json # light / dark
├── scripts/
│ └── generate-theme-variables.mjs
├── src/
│ ├── components/
│ │ └── atoms/ # Button, ThemeToggle
│ ├── context/ # ThemeContext
│ ├── styles/
│ │ ├── design-tokens/ # CSS + TS generados
│ │ │ ├── foundation.css
│ │ │ ├── color-palettes.css
│ │ │ ├── color-roles.css
│ │ │ ├── typography.css
│ │ │ ├── layout.css
│ │ │ ├── radius.css
│ │ │ ├── shape.css
│ │ │ ├── elevation.css
│ │ │ ├── motion.css
│ │ │ ├── interaction.css
│ │ │ ├── semantic.css
│ │ │ └── theme.css
│ │ └── index.css
│ ├── stories/
│ │ ├── Configure.mdx # Página de bienvenida
│ │ ├── foundation/ # Stories visuales de tokens
│ │ └── atoms/ # Button, ThemeToggle
│ └── index.ts # Exports públicos
├── style-dictionary.config.mjs
└── package.json
```
## 🎨 Sistema de tokens
**Style Dictionary** transforma JSON en CSS (`src/styles/design-tokens/*.css`) y TypeScript (`*.ts`).
| Token JSON | Salida CSS | Prefijo variables |
|------------|------------|-------------------|
| `Foundations.json` | `foundation.css` | `--ds-color-*` (legacy) |
| `color-palettes.json` | `color-palettes.css` | `--ds-primary-*`, `--ds-neutral-*`, … |
| `color-roles.json` | `color-roles.css` | `--ds-roles-*`, `--ds-color-bg-*`, … |
| `typography.json` | `typography.css` | `--ds-typography-*`, `--ds-font-*` |
| `grid.json` | `layout.css` | `--ds-layout-*` |
| `radius.json` | `radius.css` | `--ds-radius-*` |
| `shape.json` | `shape.css` | `--ds-shape-*` |
| `elevation.json` | `elevation.css` | `--ds-elevation-*` |
| `motion.json` | `motion.css` | `--ds-motion-*` |
| `interaction.json` | `interaction.css` | `--ds-interaction-*` |
| `semantic.json` | `semantic.css` | `--ds-semantic-light-*`, `--ds-semantic-dark-*` |
| (script) | `theme.css` | `--ds-theme-*` |
### Exports TypeScript (`src/index.ts`)
`foundationTokens`, `colorPaletteTokens`, `colorRoleTokens`, `semanticTokens`, `typographyTokens`, `layoutTokens`, `radiusTokens`, `shapeTokens`, `elevationTokens`, `motionTokens`, `interactionTokens` — cada uno con su tipo `*Tokens`.
## 📚 Storybook
### Foundation (tokens visuales)
| Story | Contenido |
|-------|-----------|
| **Color Palettes** | Swatches MD3 por paleta y tono |
| **Color Roles** | Superficie, texto, outline, roles de marca |
| **Typography** | Escalas, familias y pesos |
| **Layout** | Grid 4/8/12, gutters, composición de página |
| **Radius** | Tokens de border-radius |
| **Shape** | Formas y contenedores |
| **Elevation** | Sombras por nivel |
| **Motion** | Duración y easing (demos clicables) |
| **Interaction** | Opacidades hover/focus/pressed + botones DS |
### Atoms
- **Button**: primary, secondary, tertiary, tamaños, outlined, text, raised, rounded, iconos
- **ThemeToggle**: cambio de tema claro/oscuro
La UI de Storybook usa tema oscuro personalizado (`preview-head.html`) alineado con los colores del design system.
## 🌓 Temas
- **Semánticos**: `--ds-semantic-light-*` y `--ds-semantic-dark-*` en `semantic.css`
- **Runtime**: `--ds-theme-*` generadas por `generate-theme-variables.mjs` según el tema activo en `ThemeProvider`
- Los componentes Button usan variables `--ds-theme-button-*`
## 🛠️ Comandos
| Comando | Descripción |
|---------|-------------|
| `npm run storybook` | Servidor de desarrollo (puerto 6006) |
| `npm run build-storybook` | Build estático de Storybook |
| `npm run build:tokens` | Genera CSS/TS desde `design-tokens/` |
| `npm run build:theme-variables` | Genera `theme.css` |
| `npm run build:lib` | Build completo para publicar npm |
| `npm run types` | Declaraciones TypeScript en `dist/` |
| `npm run test` | Tests Jest |
| `npm run clean` | Limpia `dist/` |
## 📖 Documentación en Storybook
1. Abre **StoryBook EnviaYa** (página inicial).
2. Navega **Foundation** para tokens.
3. Navega **Atoms** para componentes.
Para detalles de cada prop y variante, usa la pestaña **Docs** y **Controls** en cada story.
## Publicación npm
```bash
npm run build:lib
npm publish
```
Paquete: `@angel-storybook/design-system@3.0.0`