# Design System Master File

> **LOGIC:** When building a specific page, first check `design-system/pulso/pages/[page-name].md`.
> If that file exists, its rules **override** this Master file.

- **Proyecto:** Pulso · Dashboard Ticksy para hosteleros (prototipo HTML, móvil 390 px)
- **Estilo:** Bento Box Grid (`bento-box-grid`, ui-ux-pro-max 2.13.0) sobre el Ticksy Design System 2.0
- **Origen:** escrito a mano el 22-09-2026 siguiendo la plantilla del plugin. El generador `--design-system` propone landing pages, paleta y tipografía ajenas, así que no se usa. Spec: `docs/superpowers/specs/2026-09-22-pulso-bento-design.md`.

## Global Rules

### Color Palette
Ninguna paleta nueva. Todo el color son tokens del TDS (`css/tokens.css`) o la capa `--app-*` de `css/app.css`. Prohibido el hex en pantallas.

| Rol | Token |
|---|---|
| Fondo de pantalla | `--bg-canvas` |
| Tile | `--bg-surface` |
| Tile hero | `--bg-surface-raised` |
| Tooltip, seleccionado | `--bg-surface-highlight` (oscuro) · `--bg-surface` (claro) vía `--app-tip-bg` |
| Texto principal | `--text-primary` |
| Rótulos e iconos de tile | `--text-accent` |
| Texto de apoyo | `--app-text-support` |
| Estado en texto | `--app-status-ok-text`, `--app-status-warn-text`, `--app-status-bad-text` |
| Acción principal | `--action-primary` + `--text-on-accent` |
| Bordes | `--border-default` (tile), `--border-subtle` (divisores), `--border-strong` (hover) |
| Gráficos | `--app-chart-accent`, `--app-chart-ink`, `--text-secondary` (esperado), `--channel-*` |

### Typography
Rubik 300 y 400 desde Google Fonts. Escala móvil: 44/52 hero, 33/40 cifra grande, 28/36 cifra de tile, 24/30 título de aviso, 20/24 título de pantalla, 16/22 cuerpo, 15/20 unidad y filas clave-valor, 14/16 rótulo (letter-spacing 1.4 px, versalitas), 14/20 texto, 13/18 nota, 12/16 rótulo pequeño y fecha de tooltip, 11/14 etiqueta de canal, fuente de cita, eje de columnas y tabbar.

### Spacing Variables
Tokens `--space-*`. Rejilla: gap `--space-16`; tile: padding `--space-16`, gap interno `--space-8`; radio de tile `--radius-xl`; radio de tooltip, citas y botones `--radius-sm`.

### Shadow Depths
Ninguna sombra en TPV. Profundidad por capas de fondo (`bg-canvas → bg-surface → bg-surface-raised → bg-surface-highlight`) y borde de 1 px.

## Component Specs

### Cards (tiles)
Rejilla `.bento` de 6 columnas, `grid-auto-flow: dense`, gap 16. Spans: `.tile` mitad (3), `.tile--third` (2), `.tile--wide` (6), `.tile--tall` (2 filas), `.tile--hero` (6 + fondo raised), `.tile--row` (ancha, en fila: punto de estado + texto + chevron, para listas de avisos). Anatomía: `tile__head` (icono 20 + `tile__label` + `tile__chevron` si navega) → `tile__figure` (+ `tile__unit`) → `tile__note` con estado → visualización opcional (`.chart`, `tile__bar`, filas `tile__kv`, columnas `tile__cols`, tablas `tile__table-row`, listas `tile__list-row`). Hover: borde `--border-strong`. Pulsación: `scale(0.98)` 150 ms. Foco: outline 2 px `--action-primary`.

Regla de tamaño: el dinero es hero; la sección con avisos activos crece en alto y muestra el aviso principal; la que lleva gráfico de barras ocupa el ancho; el resto cuadrado. En una sección: primera tarjeta hero, trío de KPI en tercios, cuatro KPI en dos filas de mitades, lo demás ancho.

Inline permitido dentro de una tile: `--i` (orden de animación), anchos y colores de segmento de barra, colores de punto de leyenda, `grid-template-columns` de una tabla, posición del tooltip y geometría de SVG. Tipografía, color, padding y flex van siempre en clase.

### Buttons
Los del bundle del TDS (`data-ds="Button"`). Los enlaces que navegan con aspecto de botón usan `.btn .btn--primary|--secondary` (64 px de alto, radio `--radius-sm`, 20/24 versalitas); `.btn--step` para los de 56 × 56 de los formularios. Mínimo táctil en el prototipo 44 × 44 px con 8 px o más de separación.

### Inputs
Compositor del Copiloto: campo de 44 px, radio 22, fondo `--bg-canvas`, borde `--border-default`, foco con outline `--action-primary`. Los controles de Tus datos (stepper, banda, Toggle del bundle) se conservan como en el prototipo.

### Modals
Los del TDS (claros, cabecera cian). No hay modales en el prototipo.

## Style Guidelines
- Rejilla de 6 columnas con spans variados; nunca una fila de tiles todas iguales si hay jerarquía que mostrar.
- Radios consistentes: todas las tiles `--radius-xl`.
- Sin sombra; jerarquía por fondo y borde.
- El contenido cabe en la tile: nada se recorta; los textos envuelven.
- Una sola cifra grande por tile, siempre con unidad o línea de estado.
- El color de estado acompaña siempre a una palabra; nunca viaja solo.
- Iconos del set del TDS por nombre; sin emoji.

## Page Pattern
Dashboard: Ventas hero (gráfico de 30 días con tooltip de hoy) · Salud alta · Márgenes · Control · Canales ancha (barra y leyenda) · Previsión · Carta · Clientes · Ritmo. Orden DOM igual al orden de lectura; el flujo `dense` sube Control junto a Salud.

Gráfico de Ventas (`.chart`): curva de la venta real suavizada con media móvil de 3 días (los tres últimos puntos se funden hacia el valor real de hoy), área degradada `--app-chart-accent` 32 % → 0, línea fina de lo esperado en `--text-secondary`, rejilla punteada en los lunes con fecha, punto de hoy con halo y tooltip "Hoy · fecha · importe". Escala Y ajustada a la serie con 6 % de aire. Se genera con `docs/superpowers/specs/assets/2026-09-22-pulso-bento-gen-chart.py`.

## Motion
Dial 3 (sutil). Aparición escalonada de tiles al cargar: `tile-in` 250 ms ease-out, 30 ms entre tiles vía `--i`, `animation-fill-mode: backwards`. Pulsación 150 ms. Todo dentro de `@media (prefers-reduced-motion: no-preference)`; con movimiento reducido, estado final inmediato.

## Anti-Patterns (Do NOT Use)
- Emoji como icono. Hex en pantallas. Sombras en TPV.
- Texto de apoyo por debajo de 13 px salvo rótulos pequeños con etiqueta contextual (12 y 11 px).
- Cifras sin unidad ni línea de estado. Estado solo por color.
- Inline para tipografía, color o layout de tile: se añade una clase.
- Rubik Medium o Bold. Fuentes distintas de Rubik.

## Pre-Delivery Checklist
- [ ] Captura a 390 px en `tpv-dark` y `light` de cada pantalla
- [ ] Sin errores de consola ni avisos de `ds-mount`
- [ ] `grep -c 'class="card' *.html` = 0 · `grep -oE '#[0-9a-fA-F]{6}\b' *.html` vacío
- [ ] Chips de 44 px; tiles con gap 16; foco visible; `prefers-reduced-motion` respetado
- [ ] Gráfico: punto de hoy sobre la línea, tooltip "Hoy · 27 may · 2.957 €", fechas sin solapar
- [ ] Contraste 4,5:1 del texto de apoyo en claro