# Fundamentos visuales

## Principios

1. Sobriedad: superficies claras, jerarquía tipográfica fuerte y sombras discretas.
2. Semántica antes que paleta: los componentes consumen intención (`primary`, `danger`, `surface`) y no tonos de producto directos.
3. Accesibilidad visible: foco, errores y estados no dependen únicamente del color.
4. Composición: `DsStack`, `DsInline`, `DsPanel` y encabezados resuelven layouts repetidos sin acoplarse a páginas.
5. Movimiento funcional: transiciones breves, anuladas con `prefers-reduced-motion`.

## Tokens

Los valores predeterminados viven en `src/tokens/`.

| Familia       | Variables principales                                                                                                             |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| Fondos        | `--ds-color-background`, `--ds-color-surface`, `--ds-color-surface-muted`, `--ds-color-surface-inverse`                           |
| Texto         | `--ds-color-text`, `--ds-color-text-muted`, `--ds-color-text-inverse`, `--ds-color-text-danger`                                   |
| Bordes y foco | `--ds-color-border`, `--ds-color-border-hover`, `--ds-color-border-danger`, `--ds-color-focus-ring`                               |
| Acciones      | `--ds-color-primary`, `--ds-color-primary-hover`, `--ds-color-primary-active`, `--ds-color-primary-disabled`, `--ds-color-danger` |
| Estado        | variables `info-*`, `success-*`, `warning-*` y `error-*`                                                                          |
| Espacio       | `--ds-space-1` a `--ds-space-12`                                                                                                  |
| Forma         | `--ds-radius-sm` a `--ds-radius-xl`, `--ds-shadow-sm`, `--ds-shadow-md`                                                           |
| Controles     | `--ds-control-height-sm`, `--ds-control-height-md`, `--ds-control-height-lg`                                                      |
| Movimiento    | `--ds-duration-fast`, `--ds-duration-normal`                                                                                      |

## Tema predeterminado

- `slate-50` como fondo.
- Blanco para superficies.
- `slate-900` para texto y superficies inversas.
- `sky-600` para acciones principales y `sky-400` para foco.
- Radios de 10–18 px y sombras de baja opacidad.

El sistema no usa gradientes, transparencias de tipo glass, sombras decorativas ni movimiento ornamental.

## Personalización

Sobrescribe variables después de importar la hoja del paquete:

```css
:root {
  --ds-color-primary: #2563eb;
  --ds-color-primary-hover: #1d4ed8;
  --ds-radius-md: 0.5rem;
  --ds-page-width: 80rem;
}
```

No sobrescribas selectores internos salvo que estés corrigiendo una limitación documentada. La API estable de theming son las variables `--ds-*`.