First commit

docs/foundations.md

@@ -0,0 +1,50 @@
+# 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-*`.