Communitygithub.com

visual-design

Úsalo al construir o modificar un sistema de diseño, como tokens de diseño, paleta de colores, contraste, tipografías, escala tipográfica, escala de espaciado, modo oscuro, tokens de movimiento o especificaciones de estados de componentes. No para diseñar o criticar una página específica o rediseño; usa `designer`. No para crear imágenes; usa `artist`.

¿Qué es visual-design?

Este skill, 'visual-design', está diseñado para guiar a un agente de IA en la construcción y mantenimiento de un sistema de diseño completo, desde sus fundamentos conceptuales hasta los tokens de implementación. Su propósito es crear un sistema coherente y escalable que pueda ser aplicado consistentemente en todas las páginas y componentes por otros skills como `designer`. El skill establece reglas críticas, como escribir una dirección de diseño en palabras antes de definir cualquier token, usar tokens semánticos en lugar de primitivos en los componentes, y verificar el contraste para cada par real de colores en ambos temas (claro y oscuro). Proporciona una guía detallada para construir cada capa del sistema en orden: dirección, color, tipografía, espaciado, forma, profundidad y movimiento. Además, incluye 'gotchas' comunes que el agente debe evitar, como nombrar incorrectamente las escalas, usar tokens primitivos en componentes o cargar una fuente nueva para un solo encabezado. El skill es parte de un ecosistema que incluye `designer` para la disposición de páginas y `artist` para ilustraciones, y se complementa con referencias a habilidades como `frontend` para la implementación en frameworks. Su enfoque en decisiones deliberadas y valores consistentes asegura que el sistema de diseño resulte intencional y no genérico.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/heliacon/claude-skills/tree/HEAD/skills/visual-design

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Diseño visual

El sistema debajo de cada pantalla: tokens para color, tipo, espacio, forma, profundidad y movimiento, y las especificaciones de componentes construidas a partir de ellos. El skill designer aplica este sistema a páginas reales. Construye el sistema una vez; deja que las páginas lo gasten.

Las reglas que más importan

  1. Escribe la dirección de diseño en palabras antes que cualquier token. Tres o cuatro frases: para quién es, cómo debería sentirse, cómo nunca debe sentirse, y lo único que toma prestado del tema. Cada decisión de token se verifica contra ese párrafo.
  2. Los componentes referencian tokens semánticos, nunca primitivos. --color-text-primary, no --grey-900. El modo oscuro, la personalización y los cambios de marca se convierten en un re-mapeo, no en una reescritura.
  3. Verifica el contraste para cada par real, en ambos temas, contra la tabla siguiente. Una paleta que funciona sobre blanco puede fallar sobre su propia superficie teñida.
  4. Un valor predeterminado no es una decisión. Los grises del framework, Inter en todo, un radio de 4px en cada caja: cada uno se ve bien y juntos se ven como cualquier otro producto. Decide cada valor o acéptalo a sabiendas.
  5. Cada especificación de componente lista todos los estados: predeterminado, hover, foco, activo, deshabilitado, cargando, error y seleccionado donde corresponda. Los estados faltantes se inventan en la construcción, de manera inconsistente.
  6. Menos valores, usados de manera consistente. Una escala de 6 pasos usada en todas partes supera a una de 14 pasos usada al azar.

Cuándo no usar

  • Organizar una página específica, elegir qué va arriba del pliegue, criticar una pantalla o ejecutar un rediseño: designer.
  • Generar ilustraciones, íconos, imágenes de héroe o marcas: artist.
  • Gráficos y paletas de visualización de datos: el skill frontend en references/charts.md. Los colores categóricos de gráficos tienen restricciones que una paleta de marca no tiene.
  • Implementar los tokens en un framework: frontend.

Orden de construcción

Cada capa depende de la anterior:

  1. Párrafo de dirección.
  2. Color: primitivos, luego tokens semánticos.
  3. Tipo: familias, luego escala y roles.
  4. Escala de espaciado y cuadrícula.
  5. Radio, borde y elevación.
  6. Tokens de movimiento.
  7. Tokens de componentes y especificaciones de componentes.

Color

Estructura:

Primitivos (valores brutos, una rampa por tono, ej. 50, 100 ... 900, 950):
  --blue-600: oklch(0.55 0.17 255)

Tokens semánticos (referencian primitivos, nombrados por función):
  --color-bg, --color-surface, --color-surface-raised
  --color-text, --color-text-muted, --color-text-on-accent
  --color-accent, --color-accent-hover
  --color-border, --color-focus-ring
  --color-danger, --color-success, --color-warning (cada uno con una variante segura para texto)

Reglas que separan una paleta pensada de una predeterminada:

  • Construye rampas en OKLCH. La claridad se mantiene perceptualmente uniforme entre tonos, por lo que un azul 600 y un verde 600 tienen el mismo peso visual. La claridad HSL miente.
  • Tiñe los neutros. El gris puro y el negro o blanco puro se ven sin dueño. Añade una pequeña cantidad de croma (aproximadamente 0.005 a 0.015) hacia el tono de la marca.
  • Texto sobre una superficie coloreada usa un tono oscuro del tono de esa superficie, no gris neutro. El gris sobre el color se ve deslavado.
  • Elige un nivel de compromiso y mantente firme: contenido (suelo neutro, un acento), comprometido (tono de marca presente en todo), paleta completa, o empapado (el tono de marca es el suelo). Un medio compromiso se lee como indecisión.
  • Nunca dejes que el color transmita significado por sí solo. Combínalo con un ícono, una etiqueta o un patrón.
  • Cuidado con los reflejos actuales. Una página crema cálida con una tipografía de exhibición serif y un acento terracota, o un casi negro con un acento ácido, son a lo que recurren los diseños generados cuando no se ha decidido nada. Úsalos solo cuando el párrafo de dirección los pida.

Contraste (WCAG 2.2)

ParAAAAA
Texto del cuerpo (por debajo del tamaño grande)4.5:17:1
Texto grande: 24px regular, o aproximadamente 18.7px bold, y superior3:14.5:1
Límites de componentes de UI, íconos, indicadores de foco, marcas de gráficos que transmiten significado3:1ninguna
  • El texto de marcador de posición que le dice algo al usuario es texto: 4.5:1.
  • Los controles deshabilitados están exentos, pero el usuario aún debe poder ver que hay un control.
  • Mide los colores calculados, incluyendo opacidad y superposiciones. Una etiqueta con opacidad al 60% sobre una tarjeta teñida es un nuevo color.

Tipografía

  • Elige familias para el registro del contenido, no por costumbre. Tres roles: una familia de exhibición con carácter, usada con moderación; una familia de cuerpo cómoda; una familia utilitaria para etiquetas, leyendas y datos (figuras tabulares para números en tablas).
  • Combina con un contraste claro (serif con sans, geométrica con humanista) o usa una sola familia con diferentes pesos. Dos familias que son similares pero no iguales se leen como un error.
  • Escala modular. Elige una proporción: 1.2 para UI de producto densa, 1.25 a 1.333 para contenido y marketing. Nombra roles, no tamaños: display, h1 a h4, body-lg, body, body-sm, label, caption.
  • Medida de 60 a 75 caracteres para el texto del cuerpo (max-width: 70ch).
  • Tipo de exhibición obtiene un tracking más ajustado (alrededor de -0.02em a -0.04em) y un límite de tamaño (aproximadamente 6rem mediante clamp()). Más grande rara vez se lee como intencional.
  • text-wrap: balance en encabezados, text-wrap: pretty en prosa del cuerpo.
  • Altura de línea: aproximadamente 1.5 para el cuerpo, 1.1 a 1.25 para exhibición.

Espacio, forma, profundidad

  • Escala de espaciado sobre una base de 4 u 8: por ejemplo 4, 8, 12, 16, 24, 32, 48, 64. Los componentes usan tokens, nunca valores en píxeles brutos.
  • Radio: dos o tres valores con una regla sobre dónde se aplica cada uno. Radios anidados: el radio interno es igual al radio externo menos el relleno entre ellos.
  • Elevación: tres o cuatro niveles, cada uno vinculado a una función (tarjeta en reposo, menú desplegable, modal). En temas oscuros, eleva la elevación con una superficie más clara, no con una sombra más pesada.

Movimiento

  • Tokens: duraciones (por ejemplo 120ms, 200ms, 320ms) y dos o tres curvas de easing (una para entrar, otra más pronunciada para salir). Los elementos las reutilizan; nadie elige un valor por elemento.
  • El movimiento explica un cambio: de dónde vino algo, qué respondió. El movimiento que solo decora parece generado.
  • Un momento coreografiado supera a que todo se desvanezca a la vez.
  • Respeta prefers-reduced-motion: reduce: elimina el movimiento y las transiciones largas, mantén los cambios de opacidad.
  • No escalar fotos al hacer hover. Anima el contenedor (sombra, borde, fondo).

Modo oscuro

  • Un tema oscuro es un re-mapeo de tokens semánticos, nunca una inversión. Usa grises oscuros para el fondo, no negro puro, y reduce el croma de los acentos que brillan.
  • Vuelve a verificar cada par de contraste en el tema oscuro.
  • Evita el destello del tema incorrecto: decide el tema en un pequeño script inline en el head del documento, antes de la primera renderización.

Lee references/dark-mode.md al implementar cambio de tema, persistencia o imágenes en modo oscuro.

Especificaciones de componentes

Lee references/component-spec.md antes de escribir una especificación de componente. Contiene la plantilla y la lista de verificación de estados.

Errores comunes

  • 11 tonos nombrados del 100 al 900. Eso son 9 pasos. Nombra las rampas para que el recuento y los nombres coincidan (50, 100 ... 900, 950 da 11).
  • El "texto grande" significa 18 puntos, no 18 píxeles. El texto del cuerpo regular de 18px necesita 4.5:1, no 3:1. El umbral de texto grande es 24px regular o aproximadamente 18.7px bold.
  • Tokens primitivos en componentes. Funciona hasta el primer tema. Luego cada componente necesita edición.
  • Contraste verificado en el mock, no en la compilación. La opacidad, las superposiciones y el anti-aliasing cambian el color real. Mide los píxeles renderizados o los estilos calculados.
  • Un ajuste global para solucionar un problema local. Oscurecer toda la paleta para rescatar un par fallido desplaza todos los demás pares. Arregla el token del par.
  • Un token que nadie usa, o un valor bruto que nadie tokenizó. Ambos significan que el sistema y la compilación se han desviado. Busca en la compilación valores hex y píxeles brutos.
  • Una nueva fuente cargada para un solo encabezado. Cada familia cuesta tiempo de carga. Usa las familias que el sistema ya carga.

Verificación

  • Párrafo de dirección escrito, y cada familia de tokens puede rastrearse hasta él.
  • Cada par de texto y UI pasa AA en claro y oscuro, medido en la página construida.
  • Los componentes usan solo tokens semánticos: grep no muestra valores de color o espaciado brutos en el código del componente.
  • Cada especificación de componente lista todos sus estados.
  • Configuración de movimiento reducido probada: no queda movimiento.
  • El cambio de tema no muestra destello en una recarga forzada con la configuración opuesta del sistema.

Individual skills in this repo

This repo contains 7 individual skills — each has its own dedicated page.

api-design

Use when designing or changing an HTTP API contract, adding or editing a route, endpoint or webhook, writing an OpenAPI spec, choosing error, pagination or versioning shapes. Also when asking "is this a breaking change". Not for server internals such as jobs, retries or rate-limit storage; use `backend-patterns`.

artist

Use when making or directing visual assets such as illustrations, hero images, icons, logos, brand marks, textures or diagrams, or writing prompts for an image-generation model. Covers art direction, reference boards and critique against a brief. Not for page layout; use `designer`. Not for palettes and tokens; use `visual-design`.

copywriter

Use when writing, rewriting or reviewing words a customer reads, such as landing or marketing pages, headlines, taglines, calls to action, pricing pages, product descriptions, onboarding text, button labels, error messages and empty states. Not for long-form docs or articles; use `docs`. Not for positioning strategy; use `marketing`.

designer

Use when asked to critique, redesign or review the layout and hierarchy of a page, screen, landing page or dashboard (hero, CTAs, card grids, testimonials), or when a design \"looks off\", \"looks generic\" or \"looks AI-made\". Use it for any layout feedback, even if the word design is not used. Not for tokens, palettes or type scales; use `visual-design`. Not for images; use `artist`.

frontend

Use when building, reviewing or fixing browser UI, such as pages, components, forms, client state, charts, print or PDF views, accessibility or web performance (Core Web Vitals, bundle size, slow renders). Not for visual direction, layout critique or brand (use `designer` or `visual-design`). Not for native or React Native apps (use `mobile`).

game-design

Use when designing or reviewing how a game plays: core loop, mechanics, game feel and juice, difficulty curve, progression, economy and balance, tutorials, HUD and menus or a game design document (GDD) and playtest plan. Not for engine code or rendering (use `frontend`) or for non-game product UX (use `ux-research`).

ux-research

Use when planning or synthesising user research (interviews, usability tests, surveys), mapping a journey or job to be done, specifying an interaction's states, or running a heuristic review of a flow. Not for menus, labels, taxonomy or site structure; use `information-architecture`. Not for visual polish; use `designer`.

Skills relacionados