Documentar
Patrones
Cómo documentar un patrón de pantalla como una receta paso a paso que un agente pueda seguir, con sus variantes y antipatrones, y cómo enlazarlo con su marco de referencia en Figma.
Última revisión:
Un componente dice cómo es una pieza. Un patrón dice cómo se combinan varias para resolver una pantalla: un inicio de sesión, un listado con filtros, un detalle. Para un agente que tiene que crear una pantalla nueva, el patrón es la documentación más útil del sistema.
En esta página
Por qué los patrones
Anthropic recomienda dar a un agente ejemplos canónicos del comportamiento esperado antes que listas de casos límite (Anthropic: Effective context engineering for AI agents). Un patrón es exactamente eso: el ejemplo canónico de una pantalla.
Sin patrones, un agente que tiene que construir un formulario elige componentes uno a uno y los combina a su manera. Con un patrón, sigue una receta que el equipo ya validó. La ayuda de Figma para las guidelines pone los patrones establecidos entre lo primero que conviene escribir (Figma: About guidelines).
Qué lleva un patrón
| Sección | Qué escribe |
|---|---|
| Problema | Qué necesita hacer el usuario |
| Componentes | La lista de componentes que usa, como enlaces a sus documentos |
| Receta | Los pasos en orden, con componente, props y tokens de cada uno |
| Variantes | Los cambios para los casos habituales |
| Antipatrones | Los errores frecuentes, con su motivo |
| Referencia | El enlace al marco de Figma |
La plantilla
docs/patterns/login.md
---
name: Login
type: pattern
status: stable
components: [Card, TextField, Button, Link, Alert]
figma: https://www.figma.com/design/<archivo>?node-id=<nodo>
---
# Patrón: inicio de sesión
## Problema
El usuario se identifica con email y contraseña.
## Receta
1. Contenedor: `Card` centrada, ancho máximo 400 px, relleno `space.inset.lg`.
2. Título: estilo `heading.md`, texto "Inicia sesión".
3. `TextField` type="email", label "Email", autocomplete="email".
4. `TextField` type="password", label "Contraseña", con botón para mostrarla.
5. `Link` "¿Has olvidado tu contraseña?", alineado a la derecha.
6. `Button` variant="primary", ancho completo, texto "Entrar".
7. Errores del servidor: `Alert` variant="error" encima del formulario, no en los campos.
## Variantes
- Con inicio de sesión externo: un `Button` variant="secondary" por proveedor, debajo de un `Divider` con el texto "o".
## Antipatrones
- Dos botones principales: "Entrar" y "Crear cuenta" no pueden ser los dos `primary`.
- Validar la contraseña mientras se escribe: el error aparece antes de que el usuario termine.El patrón en Figma
En la librería, cada patrón tiene un marco de referencia en la página Patterns, con las anotaciones de su comportamiento (Estructura de la librería). El documento enlaza al marco y el marco enlaza al documento con un dev resource (Dev resources).
Recomendación
Documenta primero los dos patrones de tu piloto. Después, los que más se repiten en tus productos: en la mayoría de los sistemas, cinco o diez patrones cubren casi todas las pantallas.
En resumen
- Un patrón es el ejemplo canónico de una pantalla: lo que más ayuda a un agente a crear pantallas nuevas.
- La receta da los pasos en orden, con componentes, props y tokens.
- Cada patrón tiene un marco de referencia en Figma, enlazado con su documento.