# Legalty Design System — Documentación completa

Rounded expresivo · Poppins/Inter/Spline Sans Mono · HeroUI v3. Versión 5.0.0. Acento #9268FA.

======================================================================

## Principios de diseño
_Las seis convicciones que guían cada decisión de producto en Legalty._

Legalty opera en un dominio donde la **confianza** lo es todo: constituir empresas, firmar
documentos, gestionar expedientes legales. El diseño debe transmitir rigor y calma, nunca
fricción ni ruido. Estos principios son el filtro de toda decisión visual y de interacción.

## Claridad antes que densidad

Cada pantalla comunica una idea principal. La información legal es compleja; nuestro trabajo
es ordenarla, no reflejarla en desorden. Cuando dudes, quita.

## Jerarquía deliberada

El tamaño, el peso y el color guían la mirada en un orden intencional: qué es lo primero,
qué es acción, qué es contexto. Una sola acción primaria por vista.

## Consistencia sistémica

Un botón, un estado o un espaciado significan lo mismo en toda la plataforma. La coherencia
reduce la carga cognitiva y construye familiaridad —y con ella, confianza.

## Aire con propósito

El espacio en blanco no es vacío: es respiración. En documentos densos, el ritmo vertical y
los radios suaves (rounded expresivo) hacen que lo serio se sienta accesible.

## Accesibilidad no negociable

Contraste AA como mínimo, foco visible, targets táctiles de 44px, navegación por teclado.
Lo legal debe ser usable por todos, sin excepción. Ver el [checklist WCAG](/ux).

## Confianza como estética

Neutros sobrios, un acento violeta usado con intención, tipografía legible. Nada estridente.
El producto debe sentirse como un despacho moderno: profesional, ordenado, humano.

<Callout>
  Estos principios se traducen en tokens y componentes concretos en los capítulos siguientes.
  Si una decisión de UI no puede justificarse con uno de ellos, probablemente sobra.
</Callout>

----------------------------------------------------------------------

## Color
_Neutros sobrios como base, un acento violeta con intención y semánticos de estado claros._

El color en Legalty es mayormente **neutro**. El violeta de marca aparece con moderación,
reservado para acciones y foco. Los colores semánticos comunican estado sin ambigüedad.
Todos los valores se exponen como variables `--lg-*` y funcionan en claro y oscuro.

## Neutros y superficies

La escala neutra construye jerarquía por elevación: fondo, superficie, superficie elevada.

<Grid min={180}>
  <Swatch token="bg" name="Fondo" />
  <Swatch token="surface" name="Superficie" />
  <Swatch token="surface-2" name="Superficie 2" />
  <Swatch token="elevated" name="Elevado" />
  <Swatch token="border" name="Borde" />
  <Swatch token="border-strong" name="Borde fuerte" />
</Grid>

### Texto

<Grid min={180}>
  <Swatch token="text" name="Texto" />
  <Swatch token="text-2" name="Texto 2" />
  <Swatch token="text-3" name="Texto 3" />
</Grid>

## Acento de marca

El violeta `#9268FA` es la identidad. Para texto y rellenos usamos el tono *ink* `#6340C7`,
que cumple contraste **AA** sobre fondos claros. Se usa en la acción primaria, enlaces, foco
y selección — nunca como decoración.

<Grid min={180}>
  <Swatch token="accent" name="Accent" />
  <Swatch token="accent-ink" name="Accent ink · AA" />
  <Swatch token="accent-solid" name="Accent solid" />
  <Swatch token="accent-soft" name="Accent soft" />
  <Swatch token="accent-border" name="Accent border" />
</Grid>

## Semánticos de estado

Cuatro familias: éxito, advertencia, peligro e información. Cada una con su tono sólido, su
fondo suave y su borde.

<Grid min={180}>
  <Swatch token="success" name="Success" />
  <Swatch token="warning" name="Warning" />
  <Swatch token="danger" name="Danger" />
  <Swatch token="info" name="Info" />
</Grid>

<DoDont
  do="Usar el acento solo para la acción primaria, enlaces y foco. Un punto de color por vista."
  dont="Colorear varios elementos con el acento a la vez: diluye la jerarquía y la intención."
/>

----------------------------------------------------------------------

## Tipografía
_Poppins para marca y titulares, Inter para cuerpo y datos densos, Spline Sans Mono para metadatos._

Tres familias con roles bien separados. La partición no es estética: equilibra **identidad de
marca** con **legibilidad** en interfaces legales densas.

## Poppins — display y marca

**Poppins** es la fuente del logotipo de Legalty. Geométrica, amable y rotunda, aporta
carácter y calidez a titulares, portadas y momentos de marca. Su forma redondeada dialoga con
el estilo *rounded expresivo* del sistema.

Se reserva a **Display, H1–H4 y overlines destacados**. No se usa en cuerpo largo ni en tablas:
a tamaños pequeños su geometría resta legibilidad y densidad.

## Inter — cuerpo y UI

**Inter** es la voz de trabajo: párrafos, formularios, tablas, etiquetas y componentes de alta
densidad. Neutra, altamente legible y profesional, sostiene la seriedad del producto donde más
importa: la lectura de información legal.

## Spline Sans Mono — datos y metadatos

Para importes, códigos de color, identificadores y overlines técnicos usamos **Spline Sans
Mono**. Sus terminales ligeramente redondeadas armonizan con Poppins y le dan un carácter
propio —lejos del monoespaciado genérico— sin perder precisión tabular.

## Escala tipográfica

Base de `15px / 24px`. Poppins en los niveles display; Inter del cuerpo hacia abajo; Spline
Sans Mono en el overline.

<TypeScale />

<DoDont
  do="Poppins para titular y marca; Inter para cuerpo, tablas y formularios; Spline Sans Mono para datos."
  dont="Poppins en párrafos largos o en celdas de tabla: pierde legibilidad y densidad."
/>

----------------------------------------------------------------------

## Medida y ritmo
_Base de 4px, radios generosos (rounded expresivo) y sombras suaves que sugieren profundidad sin dramatismo._

Todo se compone sobre una rejilla de **4px**. Los radios son generosos —la evolución más
visible de esta versión— y las sombras, difusas y discretas.

## Radio de esquina — rounded expresivo

Siguiendo la tendencia de iOS y Material 3 Expressive, la escala de radios se amplió respecto a
versiones anteriores: esquinas más suaves y protagonistas que hacen el producto más moderno y
amable, sin perder seriedad. En HeroUI esto se controla con una única variable `--radius`
(botones y campos) de la que se derivan los demás.

<RadiusScale />

## Espaciado — base 4px

Una única escala de espaciado gobierna márgenes, padding y gaps. La consistencia del ritmo es
lo que hace que la interfaz se sienta ordenada.

<SpacingScale />

## Elevación

Sombras neutras y difusas. En modo oscuro, la elevación se apoya además en el cambio de
superficie, no solo en la sombra.

<ShadowScale />

<Callout>
  Los <strong>botones son full rounded</strong> (pill) — la firma más visible del estilo rounded
  expresivo. Los campos usan <code className="tok">md</code> (14px) y las cards <code className="tok">xl</code> (24px).
  En HeroUI: <code className="tok">medium</code> ≈ md, <code className="tok">large</code> ≈ xl.
</Callout>

----------------------------------------------------------------------

## Componentes
_Los bloques reutilizables de Legalty, renderizados con componentes HeroUI reales e interactivos._

Todos los componentes de esta página son **HeroUI reales y ejecutables** —puedes interactuar
con ellos— vestidos con los tokens de Legalty (acento violeta, radios rounded, tipografía).
Son la fuente de verdad: lo que ves aquí es lo que se construye en producto.

## Botones

Una sola acción primaria por vista. El resto, secundario, terciario o ghost. El destructivo
solo confirma acciones irreversibles.

> [demo interactiva: Button]

## Campos de formulario

Etiqueta siempre visible, texto de ayuda debajo y estado de error explícito. El campo hereda el
radio del sistema.

> [demo interactiva: Field]

## Controles de selección

Checkbox, switch y radios para decisiones binarias y de opción única.

> [demo interactiva: Selection]

## Estados y badges

Chips para etiquetar estado de expedientes, documentos y firmas.

> [demo interactiva: Badge]

## Alertas

Mensajes contextuales con color semántico. Título breve y descripción accionable.

> [demo interactiva: Alert]

## Cards

Contenedor de información agrupada. Cabecera, cuerpo y pie con la acción de la tarjeta.

> [demo interactiva: Card]

## Tabs

Navegación entre vistas relacionadas dentro de un mismo contexto.

> [demo interactiva: Tabs]

## Tooltips

Información contextual breve, activada por hover o foco.

> [demo interactiva: Tooltip]

## Modales / Diálogos

Interrupciones deliberadas para confirmar o completar una tarea sin perder el contexto.

> [demo interactiva: Modal]

## Dropdowns

Menús de acciones secundarias sobre un elemento.

> [demo interactiva: Dropdown]

## Select

Selección de una opción entre muchas, con búsqueda y teclado.

> [demo interactiva: Select]

## Tabla de datos

El caballo de batalla de los expedientes: densa, legible y ordenable.

> [demo interactiva: Table]

## Carga

Indicadores de progreso para operaciones asíncronas.

> [demo interactiva: Spinner]

----------------------------------------------------------------------

## Dashboard y navegación
_Patrones de layout para la aplicación: sidebar en escritorio, bottom navigation en móvil._

El producto Legalty se organiza alrededor de expedientes. La navegación debe ser estable,
predecible y dejar el máximo espacio al contenido.

## Escritorio — Sidebar con submenús

Una barra lateral fija a la izquierda agrupa las áreas principales (Expedientes, Documentos,
Facturación, Ajustes). Los submenús se expanden en su sección, nunca en overlays. El acento
violeta marca el elemento activo, como en la navegación de esta guía.

- Ancho estable (~240px), colapsable a iconos en pantallas medianas.
- Un único nivel de submenú; más profundidad indica que la IA de la información falla.
- El estado activo usa `--lg-accent-soft` de fondo y texto en `--lg-text`.

## Móvil — Bottom navigation

En móvil, 3–5 destinos principales viven en una barra inferior con targets de 44px. Las
acciones secundarias se mueven a un menú "Más". El contenido ocupa todo el ancho.

## Composición de una vista de expediente

Una vista típica combina cabecera con título y acción primaria, una fila de estado con chips,
tabs para las secciones y una tabla de documentos:

> [demo interactiva: Card]

<Callout>
  Regla de oro: el usuario siempre sabe <strong>dónde está</strong> (sección activa),
  <strong>qué puede hacer</strong> (una acción primaria clara) y <strong>cómo volver</strong>.
</Callout>

----------------------------------------------------------------------

## Diseño responsivo
_Breakpoints del sistema y reglas de adaptación por componente._

Diseñamos *mobile-first* y escalamos hacia arriba. El contenido manda: los breakpoints existen
para servir a la lectura, no al revés.

## Breakpoints del sistema

| Token | Ancho | Uso |
|---|---|---|
| `sm` | 640px | Móvil grande / apilado a 1 columna |
| `md` | 768px | Tablet · 2 columnas |
| `lg` | 1024px | Escritorio · aparece el sidebar |
| `xl` | 1280px | Escritorio amplio · ancho máximo de lectura |

## Reglas de responsividad

- **Un contenido, un ancho de lectura.** El texto largo nunca supera ~68 caracteres por línea.
- **Apilar antes que encoger.** En móvil, las columnas se apilan; no se comprimen hasta ser ilegibles.
- **Targets táctiles de 44px** en cualquier viewport con entrada táctil.
- **La tabla se desplaza** horizontalmente dentro de su contenedor; el layout de página nunca lo hace.

## Comportamiento por componente

- **Sidebar** → se colapsa a iconos en `md`, se oculta tras un botón en `sm` (reemplazado por bottom nav).
- **Cards** → de rejilla multi-columna a una sola columna en `sm`.
- **Modales** → centrados en escritorio, hoja inferior (bottom sheet) en móvil.
- **Tabs** → scroll horizontal cuando no caben, sin truncar etiquetas.

<Callout>
  El propio sitio es la demo: reduce el ancho de la ventana para ver cómo se reorganiza el layout.
</Callout>

----------------------------------------------------------------------

## Formularios
_Principios para capturar datos legales con el mínimo de fricción y el máximo de confianza._

Los formularios son el corazón de Legalty: constituir, firmar, declarar. Cada campo pide un
esfuerzo al usuario; nuestro trabajo es que ese esfuerzo se sienta seguro y breve.

## Principios

- **Una etiqueta clara y visible** por campo. Nunca dependas solo del placeholder.
- **Agrupa por significado**, no por tipo de dato. El orden sigue el modelo mental del usuario.
- **Valida en el momento correcto**: al salir del campo, no en cada tecla. El error explica cómo corregir.
- **Pide lo mínimo.** Cada campo opcional que quitas mejora la conversión.

## Anatomía de un campo

> [demo interactiva: Field]

## Reglas: hacer vs. evitar

<DoDont
  do="Etiqueta arriba, ayuda debajo, error explícito que dice cómo corregir."
  dont="Placeholder como etiqueta: desaparece al escribir y deja al usuario sin contexto."
/>

<DoDont
  do="Agrupar campos relacionados con un título de sección y espacio entre grupos."
  dont="Un muro de campos sin jerarquía ni respiración visual."
/>

<Callout>
  En trámites largos, divide en pasos con progreso visible. El usuario debe saber cuánto falta.
</Callout>

----------------------------------------------------------------------

## UX y accesibilidad
_Reglas de interacción y checklist WCAG 2.1 AA que todo producto de Legalty debe cumplir._

La accesibilidad no es una capa final: es una restricción de diseño desde el primer trazo.
Estas reglas son obligatorias, no recomendaciones.

## Reglas de interacción

<DoDont
  do="Foco visible en todos los elementos interactivos, con anillo de acento."
  dont="Eliminar el outline de foco sin ofrecer una alternativa visible."
/>

<DoDont
  do="Estados claros: hover, activo, foco, deshabilitado y cargando, todos distinguibles."
  dont="Botones que no comunican que están procesando: el usuario hace doble clic."
/>

## Checklist de accesibilidad · WCAG 2.1 AA

- **Contraste** de texto ≥ 4.5:1 (≥ 3:1 para texto grande y elementos de UI).
- **Navegación por teclado** completa: todo lo que se hace con ratón se hace con teclado.
- **Foco visible** y orden de tabulación lógico.
- **Targets táctiles** de al menos 44×44px.
- **Etiquetas** asociadas a cada control de formulario (`label` / `aria-label`).
- **Errores** anunciados a lectores de pantalla y descritos en texto.
- **Movimiento** respeta `prefers-reduced-motion`.
- **No solo color**: el estado se comunica también con icono o texto.

<Callout>
  HeroUI se apoya en React Aria, que aporta gran parte de este comportamiento accesible de base.
  Nuestra responsabilidad es no romperlo con overrides y verificar el contraste de la marca.
</Callout>

----------------------------------------------------------------------

## Tokens y distribución
_La fuente única de verdad y cómo consumirla en cualquier proyecto de Legalty._

Todo el lenguaje visual vive en un solo archivo: `theme/tokens.ts`. De ahí se generan los
artefactos que consumen la app, otros proyectos y los LLMs. Nunca se editan a mano los archivos
generados.

## Artefactos generados

| Archivo | Para qué | Consumidor |
|---|---|---|
| [`/tokens.json`](/tokens.json) | Tokens en crudo (color, radios, tipografía, sombras) | Herramientas, LLMs, scripts |
| [`/tokens.css`](/tokens.css) | Variables CSS `--lg-*` (claro y oscuro) | Cualquier proyecto web |
| `theme/generated-tokens.css` | Variables + override del tema HeroUI | Esta guía en runtime |
| [`/llms.txt`](/llms.txt) · [`/llms-full.txt`](/llms-full.txt) | Documentación legible por máquinas | Agentes / LLMs |

## Cómo usarlo hoy (Fase 1)

En cualquier proyecto de Legalty, importa las variables y úsalas directamente:

```css
@import "https://<host>/tokens.css";

.boton-primario {
  background: var(--lg-accent-solid);
  border-radius: var(--lg-radius-md);
  font-family: var(--lg-font-sans);
}
```

## Hacia dónde va (Fase 2)

Los tokens y el tema HeroUI se extraerán a paquetes versionados —`@legalty/tokens` y
`@legalty/theme`— que las apps instalarán vía npm. La estructura actual (todo derivado de
`theme/tokens.ts`) hace esa extracción mecánica, sin reescribir nada.

## Grupos de tokens

- **Color** — neutros, acento de marca y semánticos, en claro y oscuro.
- **Radios** — escala rounded expresivo (`--lg-radius-xs` … `--lg-radius-pill`).
- **Espaciado** — base 4px (`--lg-sp-1` … `--lg-sp-16`).
- **Tipografía** — familias display / sans / mono y escala.
- **Sombras** — `--lg-shadow-sm|md|lg`.

<Callout>
  ¿Necesitas cambiar el acento de marca o los radios en todo el sistema? Edita
  <code className="tok">theme/tokens.ts</code> y ejecuta <code className="tok">pnpm gen</code>.
  Todo lo demás se regenera solo.
</Callout>

----------------------------------------------------------------------

## Guía para LLMs y agentes
_Cómo esta guía se vuelve fuente de verdad no solo para humanos, sino para modelos y agentes._

Este design system está pensado para que un **LLM lo entienda con solo recibir la URL**, igual
de bien que un humano leyendo esta página. Ese es un requisito de primera clase, no un extra.

## El patrón llms.txt

Al construir el sitio, un script recorre el contenido de los capítulos y genera dos archivos en
la raíz:

- **[`/llms.txt`](/llms.txt)** — índice conciso: qué es el sistema, sus fundamentos y enlaces a
  cada capítulo. Es lo primero que se le pasa a un modelo.
- **[`/llms-full.txt`](/llms-full.txt)** — todo el contenido editorial en texto plano, listo
  para pegar en el contexto de un LLM.

Como se generan desde los mismos `.mdx` que lees aquí, **humano y máquina nunca divergen**.

## AGENTS.md

En la raíz del repositorio, `AGENTS.md` da instrucciones directas a agentes de código (Claude
Code, Cursor, Windsurf): qué fuente usar, cómo elegir un componente, qué tokens aplicar y qué
evitar. Cualquier proyecto de Legalty puede copiarlo para alinear a sus asistentes.

## Cómo pedirle a un LLM que use el sistema

> "Usa el design system de Legalty descrito en `https://<host>/llms-full.txt`. Respeta los
> tokens `--lg-*`, los radios rounded y la partición tipográfica Poppins/Inter/Spline Sans Mono.
> Construye los componentes con HeroUI."

## Estructura recomendada de un DESIGN.md por proyecto

Cada app puede tener un `DESIGN.md` breve que enlace a esta guía y documente solo sus
particularidades:

1. **Fuente de verdad** — enlace a esta guía y a `/tokens.json`.
2. **Decisiones locales** — lo que difiere o extiende, con su porqué.
3. **Componentes propios** — los que no están en HeroUI y son específicos del producto.

<Callout>
  Regla de oro: una sola fuente (<code className="tok">theme/tokens.ts</code> + los
  <code className="tok">.mdx</code>) y todo lo demás —CSS, JSON, llms.txt— se genera. Editar el
  origen, nunca el derivado.
</Callout>

----------------------------------------------------------------------