# DESIGN.md · Terra (Eclipse UI)

> Instrucciones de diseño para el agente que escribe la interfaz de este
> proyecto. Léelas completas antes de tocar HTML, CSS o componentes y síguelas
> en cada cambio. Si una regla de aquí choca con lo que se te ocurra en el
> momento, gana la regla.
>
> Personalidad **Terra** · Eclipse UI 0.1.0

## La personalidad

Terra es para comunidad, artesanía y lo hecho a mano. Por ejemplo: una escuela de yoga de barrio o una cafetería.
Su modo natural es claro; también funciona en el otro.

| Rasgo | Cómo se ve |
|---|---|
| Voz | Fraunces suave (eje SOFT) para los títulos y Nunito, de terminales redondas, para leer. |
| Forma | Curvas amplias y botones en negrita. |
| Color | Terracota sobre tierra; la marca tiñe todos los grises. |
| Aire | Un poco más de aire y sombras cálidas. |
| Ritmo | Pausado. |

La personalidad vive en los diales de `theme.css` (o en los valores de
`shadcn.css`). No la repitas en cada componente: usa los tokens de abajo y
todo sigue a la marca, también lo que se construya después.

## Cómo está instalada

Una de dos:

- **CSS, en cualquier proyecto.** El motor y luego la personalidad:

  ```html
  <link rel="stylesheet" href="eclipse-ui.css">
  <link rel="stylesheet" href="theme.css">
  ```

  El modo oscuro es `class="dark"` en `<html>`.

- **shadcn/ui con Tailwind v4.** Los bloques `:root` y `.dark` de
  `shadcn.css` en lugar de los de `globals.css`. Ahí viven los colores, el
  radio y las fuentes; la voz, el aire y el ritmo completos están en
  `eclipse-ui.css`: enlázalo también para usar sus clases `eui-*` y sus
  variables de movimiento y densidad.

## Los tokens

Úsalos siempre. Nunca un valor suelto.

| Para | CSS | Tailwind con shadcn.css |
|---|---|---|
| Fondo de la página | `var(--color-background)` | `bg-background` |
| Texto | `var(--color-foreground)` | `text-foreground` |
| Texto secundario | `var(--color-muted-foreground)` | `text-muted-foreground` |
| Tarjeta | `var(--color-card)` | `bg-card` |
| Superficie elevada (barras, paneles) | `var(--color-raised)` | `bg-sidebar` |
| Fondo al pasar el cursor | `var(--color-surface-hover)` | `bg-accent` |
| Borde | `var(--color-border)` | `border-border` |
| Borde tenue (separadores) | `var(--color-border-subtle)` | `border-border/60` |
| Acción principal | `var(--color-primary)` con `var(--color-primary-foreground)` encima | `bg-primary text-primary-foreground` |
| Texto en el color de la marca | `var(--color-primary-text)` | `text-primary`, solo en texto grande |
| Error | `var(--color-destructive)` | `bg-destructive`, `text-destructive` |
| Éxito y aviso | `var(--color-success)`, `var(--color-warning)` | — |
| Radios | `var(--radius-sm)` … `var(--radius-2xl)` | `rounded-sm` … `rounded-2xl` |
| Botones y campos | `var(--radius-button)`, `var(--radius-field)` | `rounded-md`, `rounded-lg` |
| Lo que flota | `var(--shadow-elevated)` | `shadow-lg`, solo en lo que flota |
| Títulos | `var(--font-heading)` y la clase `.eui-display` | `font-[family-name:var(--font-heading)]` |
| Texto y datos | `var(--font-sans)`, `var(--font-mono)` | `font-sans`, `font-mono` |

## Reglas

1. **Solo tokens.** Nada de hex, `rgb()`, `white`, `black` ni la paleta de
   Tailwind (`gray-500`, `blue-600`). Si falta un color, es una decisión de
   diseño, no un valor que inventar.
2. **Profundidad por capas y bordes de 1px.** Fondo, tarjeta, elevada: cada
   capa con su borde. La sombra es solo para lo que flota (menús, popovers,
   modales). Una tarjeta no lleva sombra.
3. **Una acción principal por vista**, en `primary`. Las demás en secundario,
   contorno o fantasma.
4. **Tipografía con intención.** Títulos con la voz de la personalidad
   (`.eui-display`: su fuente, peso, mayúsculas y tracking). Texto con
   `var(--font-sans)`. Cifras que se comparan, con `.eui-numeric`. Etiquetas
   chicas en mono, con `.eui-label`. Botones con `.eui-control-voice`.
5. **Forma.** Radios de la escala. Botones con `var(--radius-button)` y campos
   con `var(--radius-field)`: la personalidad decide si son pastilla o rectos.
6. **Aire.** Alturas de control `var(--eui-control-sm)`,
   `var(--eui-control-md)` o `var(--eui-control-lg)`; rellenos
   `var(--eui-pad-sm)`, `var(--eui-pad-md)` o `var(--eui-pad-lg)`; separación
   `var(--eui-gap)`. La densidad sale del dial, no de cada componente.
7. **Ritmo.** Transiciones de `var(--eui-dur-quick)` (cursor),
   `var(--eui-dur-calm)` (cambios de estado) o `var(--eui-dur-breath)`
   (entradas), con `var(--eui-ease-exhale)` al entrar y
   `var(--eui-ease-inhale)` al salir. El motor las pone en cero con
   `prefers-reduced-motion`: no las fijes a mano. Lo que se toca cede un poco
   con `.eui-press`.
8. **Foco visible** en todo lo que se enfoca: `.eui-focus` (con shadcn,
   `focus-visible:ring-2 ring-ring`).
9. **Contraste.** Texto que hay que leer: `foreground` o `muted-foreground`.
   Sobre la marca: `primary-foreground`. Texto en color de marca:
   `var(--color-primary-text)`, que pasa AA (`primary` no siempre).
10. **El color nunca va solo.** Error, éxito y aviso llevan siempre texto o
    ícono.
11. **Accesible de verdad.** Elementos nativos (`<button>`, `<a>`, `<dialog>`,
    `<label>`), una etiqueta por campo, `aria-live` en lo que cambia sin
    verse y todo usable con teclado.

## Lo que la delata como hecha por IA (y aquí no va)

- Degradados morados o de arcoíris, brillos y vidrio en todas partes.
- Emojis como íconos, o íconos de estilos mezclados.
- Tres tarjetas iguales con ícono, título y dos líneas, una y otra vez.
- Sombras grandes en todo y esquinas distintas en cada pieza.
- Textos genéricos ("Lleva tu negocio al siguiente nivel"). Escribe como habla
  la marca: concreto, corto, en su tono.
- Animaciones que rebotan en todo. El movimiento acompaña una acción; no decora.

## Para ajustarla

En `theme.css`:

- `--eui-brand`: el color de la marca. El texto encima ajusta su contraste solo.
- `--eui-ink` y `--eui-paper`: la tinta y el papel.
- `--eui-roundness`, `--eui-density`, `--eui-depth`, `--eui-motion` y
  `--eui-halo`: forma, aire, sombra, ritmo y brillo (1 es como viene).
- `--eui-font-display` y `--eui-font-text`: las voces.

---

Puedes usar esto en cualquier proyecto, propio o de un cliente, también
comercial. No lo revendas ni lo redistribuyas como plantilla o kit
(LICENCIA.md).