---
name: design-system
description: >-
  Use when writing, editing, or reviewing any UI code in this project —
  components, screens, styles, native chrome in app.json — or whenever a
  message changes a visual/design decision (a color, a spacing rule, a new
  role like "racha" or "info"). Enforces that every color comes from the
  ProofIt design system instead of a hardcoded literal, and that
  docs/design.md is updated to match, not just src/constants/colors.ts.
---

# Sistema de diseño de ProofIt

Dos archivos son la fuente de verdad, y **tienen que decir lo mismo
siempre**:

- **`docs/design.md`** — la referencia legible: qué token existe, qué
  valor tiene, para qué se usa, qué huecos/decisiones quedaron pendientes.
- **`src/constants/colors.ts`** — el código que corre. Exporta `Palette`
  (valores en bruto), `Colors` (tokens semánticos) y `Gradients` (paradas
  de degradado).

## Regla 1 — nunca un color hardcodeado

Ningún componente escribe un hex o un `rgba(...)` literal en
`backgroundColor`, `color`, `borderColor`, `shadowColor`, etc. Siempre a
través de:

- `useTheme()` (o los props `type`/`themeColor` de
  `ThemedView`/`ThemedText`) para tokens semánticos: `theme.text`,
  `theme.surface`, `theme.primary`...
- `Palette` importado de `@/constants/theme` solo para paradas de
  degradado o casos que de verdad no tienen token semántico (p. ej. un
  brillo puntual como `Palette.powerFlash`).
- `Gradients` para cualquier relleno con degradado.
- Config nativa que no puede importar TypeScript (`app.json`) copia el hex
  a mano — y ese valor tiene que coincidir con el `Palette` del que salió;
  decláralo en un comentario de `design.md`, no solo en el JSON.

Antes de escribir un valor de color, lee `docs/design.md`. Si el rol que
necesitas no está documentado ahí (ni como token activo ni como hueco
pendiente), **no te lo inventes**: para y pregunta al usuario el valor
exacto. Inventar un color "razonable" es exactamente lo que este sistema
existe para evitar.

## Regla 2 — `docs/design.md` se actualiza SIEMPRE que cambie una decisión de diseño

No solo cuando se toca `colors.ts`. Si en la conversación se decide o se
cambia cualquier cosa de diseño — un valor de color, qué token cubre qué
rol, que un hueco pendiente ya se resolvió, una regla de espaciado,
tipografía, radios, lo que sea — `design.md` se actualiza en el mismo
turno, para que nunca quede desincronizado de lo que realmente se decidió.
Esto aplica aunque el pedido no mencione el archivo explícitamente (p. ej.
"vamos a usar Rival también para los badges de warning" implica editar
`design.md`, no solo el código si lo hay).

## Regla 3 — tras tocar `colors.ts`, correr el validador de contraste

```
pnpm check:contrast
```

Verifica cada par texto/fondo contra WCAG 2.1 y obliga a clasificar todo
token nuevo en `scripts/check-contrast.mjs` (falla a propósito si no lo
haces). Si falla un par:

- Si el texto es normal (se espera que se lea bien): es un fallo real,
  hay que corregir el valor o preguntar al usuario cómo ajustarlo — no
  bajar el mínimo ni eximirlo sin más.
- Si el token es deliberadamente de bajo contraste (p. ej. una etiqueta
  "bloqueada"/disabled), se puede eximir en `EXEMPT`, pero con un
  comentario que explique por qué, igual que ya está documentado para
  `textDim` y para los tokens con alfa (`border`, `overlay`, etc.).

`scripts/check-contrast.mjs` carga `colors.ts` directamente con Node, así
que ese archivo **no puede tener imports**. Necesita Node 22.18+ (type
stripping de `.ts` sin flag); si `pnpm check:contrast` falla con
`ERR_UNKNOWN_FILE_EXTENSION`, la versión de Node instalada es más vieja de
lo que pide `AGENTS.md` y hay que actualizarla, no añadir flags al script.

## Decisión vigente: tema único, oscuro

ProofIt no tiene modo claro (`Colors` es un solo objeto, sin
`Colors.light`). No reintroduzcas branching de `useColorScheme()` para
elegir colores de la app a menos que el usuario pida explícitamente volver
a un tema claro — ver `docs/design.md` § Decisión: tema único, oscuro.