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

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

npm install @angel-storybook/design-system

Uso básico

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 (
    <ThemeProvider>
      <Button label="Enviar" primary />
      <Button label="Cancelar" severity="secondary" />
      <Button label="Más info" severity="tertiary" text className="ds-link-action" />
    </ThemeProvider>
  );
}

Peer dependencies: react, react-dom, primereact, styled-components.

Variables CSS principales

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

.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

.
├── .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

npm run build:lib
npm publish

Paquete: @angel-storybook/[email protected]