brief-de-diseño

Brief de diseño

Si se lo deja solo, un agente de codificación diseña desde la memoria, y la memoria da el promedio de todo: el héroe centrado, el gradiente morado, tres tarjetas con un icono cada una. Los productos reales ya han resuelto cada pantalla que estás a punto de construir, y ya existen componentes terminados que son mejores que cualquier cosa improvisada en una sola sesión. Así que trata tus propios instintos de diseño como promedio y deja de inventar. El trabajo es encontrar, comparar, elegir y adaptar.

Dos fuentes hacen el trabajo, y hacen trabajos diferentes:

Fuente	Qué te da	Para qué usarla
Refero	Pantallas, flujos y estilos de productos reales lanzados	Decidir qué debe hacer y cómo debe verse una pantalla
21st.dev	Componentes terminados hechos por personas y valorados por la comunidad	El componente real que va en el código

Refero te dice qué construir; 21st.dev te entrega la pieza. Usa ambas. Un componente elegido sin referencia suele ser bonito pero incorrecto para la pantalla, y una referencia sin componente se reconstruye a mano, mal.

Configuración

# Refero (un servidor MCP). Luego ejecuta /mcp e inicia sesión.
claude mcp add --transport http refero https://api.refero.design/mcp

# CLI de 21st.dev
npx @21st-dev/cli login     # abre el navegador; después el comando es `21st`
21st whoami                 # verifica que has iniciado sesión

Las búsquedas y vistas previas son gratuitas en 21st.dev. Extraer el código de un componente usa una cuota diaria (21st usage muestra lo que queda), así que compara primero y extrae solo lo que hayas elegido.

Si una herramienta falta o no tiene sesión iniciada, indícaselo al usuario una vez, con el comando que lo soluciona, y continúa con la que funciona. No caigas silenciosamente en la UI construida a mano.

Orden de trabajo

1. Definir la dirección: colores y tipografía.
2. Encontrar el patrón para cada pantalla y flujo en Refero.
3. Elegir el componente para cada sección de 21st.dev.
4. Adaptar todo a un único conjunto de tokens.
5. Verificar el resultado contra el estándar de calidad, en la aplicación en ejecución.

Para cualquier cosa más grande que un componente, escribe el plan de UI antes de codificar (plantilla al final). Es una tabla pequeña, y es lo que evita que una pantalla se improvise a mitad de la construcción.

1. Dirección

• Los colores y la tipografía provienen de lo que el usuario ya tiene: su DESIGN.md, su sistema de diseño existente, o una referencia que nombre. No lo anules.
• Si no ha dado nada, fundamenta la dirección en estilos de Refero de productos de primera clase: refero_search_styles, luego refero_get_style en los dos o tres más fuertes. No recurras por defecto al tema estándar del framework, ni a la paleta de marca de la plataforma en la que estás construyendo. Así es como todos los proyectos en esa plataforma terminan pareciéndose.
• Elige un estilo dominante y conserva sus rasgos marcados. Toma prestado uno o dos detalles de los demás. Promediar varias referencias da el término medio seguro que estabas tratando de evitar.
• Soporta modo claro y oscuro.
• Entrega un solo diseño. No ofrezcas al usuario tres conjuntos de opciones para elegir a menos que las pida; elegir es el trabajo que te dieron.
• Escribe el resultado como tokens (roles de color, escala tipográfica, espaciado, radio, sombras) antes de instalar cualquier componente, para que cada decisión posterior se resuelva en un token.

2. Patrones de Refero

Herramienta	Responde	Consulta de ejemplo
refero_search_styles, luego refero_get_style	¿Cómo debería verse y sentirse?	sitio web fintech premium con tipografía contenida
refero_search_screens, luego refero_get_screen	¿Qué hay en esta pantalla y en qué estados?	estado vacío del dashboard, filtros de tabla de datos
refero_search_flows, luego refero_get_flow	¿Cuáles son los pasos de este recorrido?	onboarding de registro, cancelación de suscripción

Las búsquedas de pantallas y flujos necesitan una platform: web o ios.

• Busca lo que está literalmente en la pantalla ("pricing page annual monthly toggle"), no adjetivos. Los adjetivos pertenecen a la búsqueda de estilos.
• Prueba tres a cinco enfoques por pantalla, incluido un producto conocido que lo haga bien. El primer resultado rara vez es el mejor.
• Consulta también los estados, no solo la pantalla feliz: vacío, cargando, error, éxito.
• Cuando una pantalla se acerque, refero_get_similar_screens encuentra sus parientes rápidamente.
• Mantén dos o tres referencias por pantalla y anota qué tomas de cada una: estructura, jerarquía, estados, redacción. Las referencias informan la pantalla. No son una plantilla para copiar.

3. Componentes de 21st.dev

21st.dev es un catálogo curado de componentes terminados, no generación por IA. Para cada pieza de UI (encabezado, inputs, tarjetas, desplegables, chat, estados de carga, animaciones), busca, compara y usa el mejor.

21st search "<componente>" --type c --limit 10     # solo componentes
21st get <id>                                     # imprime el código y demo del que elegiste
21st add <autor>/<slug>                           # instálalo (shadcn por debajo)
npx shadcn@latest add "https://21st.dev/r/<autor>/<slug>"   # la misma instalación con shadcn estándar
21st logo <marca>                                 # logotipos reales de marcas como SVG, gratis

Cómo elegir:

1. Busca por el espacio, no por el estado de ánimo. "Tabla de precios", "menú de comandos", "subida de archivos", no "sección moderna limpia". Prueba dos o tres redacciones.
2. Compara varios, y nunca tomes el primer resultado. Abre las vistas previas. Un nombre y una descripción no te dicen cómo se ve o se mueve un componente.
3. Prefiere los más descargados o marcados como favoritos. Los recuentos están en la página de cada componente en 21st.dev. La popularidad es evidencia de que un componente funciona en proyectos reales. No prueba el ajuste, que es la siguiente verificación.
4. Verifica el ajuste contra la referencia de Refero para esa pantalla. Debería hacer el mismo trabajo con la densidad adecuada y tener los estados que necesitas (hover, focus, disabled, loading, empty). Verifica que se sostenga en ancho de teléfono y con el teclado, y mira las dependencias que trae.
5. Adapta una o dos cosas a tus tokens: color, radio, fuente. Si te encuentras reescribiendo el componente, elegiste el incorrecto. Vuelve atrás y elige de nuevo.
6. Mantén la coherencia entre hermanos. Componentes de diferentes autores deben leerse como un solo producto una vez que se les cambie la apariencia.
7. Construye a mano solo el pegamento que no tenga candidato, y dilo explícitamente.

Reporta cada elección para que el usuario pueda cambiarla: sección · componente · autor · motivo en una línea.

4. Estándar de calidad

• Logotipos reales, no iconos genéricos y puntos de colores.
• Poco texto. Sin muros de copy; deja que la interfaz lo lleve.
• Patrones de UI reales: pestañas, desplegables, modales, interruptores, gráficos. No todo es una pila de tarjetas.
• Buenos estados de carga, vacío y error, con progreso para acciones lentas.
• Movimiento, y sonido y hápticos donde encajen.
• Todo descubrible: cada página accesible desde donde la gente ya está, y cualquier cosa cliqueable parece cliqueable.
• Onboarding de baja fricción.
• Los flujos se mantienen dentro de la aplicación en lugar de enviar a la gente a sitios de terceros.
• Responsive, y la versión móvil se siente nativa en lugar de un escritorio encogido.
• Una queja es un patrón. Cuando el usuario señale una cosa, encuentra y arregla sus hermanas en toda la aplicación.

Mediocre nunca es una opción.

5. Verifica en la aplicación en ejecución

Abre la aplicación en el navegador o simulador y úsala: modo claro y oscuro, ancho de escritorio y teléfono, los estados vacío y de carga. Compara cada pantalla con sus referencias y corrige la desviación. La investigación no es la meta; la pantalla renderizada sí lo es.

Plantilla de plan de UI

**Dirección:** <el DESIGN.md del usuario, o estilos de Refero: nombre, nombre> · claro y oscuro
**Tokens:** <roles de color, fuentes, radio, espaciado>

| Pantalla o flujo | Referencias de Refero | Qué tomamos | Componente de 21st.dev |
|---|---|---|---|
| Onboarding | <app: pantalla>, <app: flujo> | Tres pasos, barra de progreso, omitir | <autor>/<slug> |

**Construido a mano (sin candidato):** <qué, y por qué>