El skill de diseño de UI: componentes a partir de tokens, no a ojo

Pídele a cualquier agente de código "una card bonita" y te devuelve algo que se ve bien por sí solo pero mal dentro de tu app: un color hex que es casi tu azul de marca, un padding de «17px» porque así cuadraba el screenshot, un botón al que no llegas con el teclado. El problema no es el gusto del modelo, es que nadie le dio las reglas, así que improvisó. Un skill de diseño de UI es la forma de darle esas reglas una sola vez y que se apliquen siempre. Para cuando termines esto vas a saber qué es el skill en realidad, en qué condiciones exactas se dispara, cómo funciona por dentro y tendrás un ejemplo listo para copiar y adaptar a tus propios tokens.

Un skill no es un prompt que pegas ni una opción que activas. Es una carpeta pequeña que Claude Code descubre, cuya descripción lee y con la que decide, por su cuenta, si la tarea actual lo necesita. Si fijas bien los límites, un "hazme un panel de ajustes" se vuelve sin más un panel que encaja con tu sistema y que ya trae sus estados de foco. Si los fijas mal, el skill o nunca carga o se mete en cada request. De eso trata esto: de fijarlos bien.

01 · Qué hace el skill en realidad

El skill de diseño de UI tiene un trabajo muy acotado: producir componentes de interfaz que obedezcan un sistema de diseño en vez de adivinar. Lo logra inyectando, en el momento de generar, un conjunto de restricciones estrictas y la ubicación donde viven tus tokens. Cuando está activo, "hazme una card" deja de significar "hazme una card que parezca una card" y pasa a significar "hazme una card usando la escala de espaciado, los tokens de color semánticos, el par de fuentes y cada estado de accesibilidad que este proyecto ya estandarizó".

En concreto, un skill activo cambia tres cosas en la salida:

1. Los valores salen de tokens, nunca de literales. El espaciado apunta a la escala (space-4, no «16px»). El color apunta a un token semántico (bg-surface, no «#1a1a1a» ni un valor arbitrario de Tailwind «bg-[#1a1a1a]»). Si hace falta un token que no existe, el skill lo dice claro en vez de inventarse uno.
2. La accesibilidad viene de fábrica, no parchada después. Todo elemento interactivo se alcanza con el teclado y tiene un anillo de foco visible, los inputs llevan labels de verdad, las imágenes llevan alt y la animación respeta prefers-reduced-motion.
3. Salen todos los estados, no solo el feliz. Los estados de carga, vacío y error vienen junto con el componente, porque ahí es donde las interfaces reales pasan casi toda su vida: mirando un spinner o pidiendo disculpas por un request que falló.

02 · Cuándo debe dispararse (y cuándo no)

Esta es la parte que más se le escapa a la gente, así que va de una vez. En Claude Code un skill se carga de forma diferida: sus instrucciones completas no entran en contexto hasta que Claude lee la descripción y decide que la tarea coincide. Ese campo de descripción es todo el mecanismo de disparo. No es un adorno.

Una buena descripción nombra las situaciones para las que sirve el skill, con las palabras que un usuario usaría de verdad:

---
name: ui-design
description: >
  Use when building or restyling a React/Tailwind UI component
  (button, card, modal, form, table, nav). Enforces design tokens
  instead of hardcoded colors and magic numbers, and requires
  accessible, fully-stated components. Do NOT use for backend code,
  data modeling, or pure logic with no rendered output.
---

Dos formas de fallar que conviene prevenir:

• Demasiado vaga, una descripción tipo "para tareas de diseño" o nunca se dispara (Claude no distingue qué entra y qué no) o se dispara con todo (y ahora el handler de una API route se lleva un sermón sobre anillos de foco). Nombra tipos de componente concretos y el stack.
• Demasiado ambiciosa, si el skill se atribuye cualquier tarea que toque el frontend, va a cargar hasta en un cambio de texto de una línea y quemar contexto. La línea explícita de "Do NOT use for…" cumple una función real: le dice a Claude dónde está el límite.

03 · Cómo funciona por dentro

Un skill es un directorio, normalmente «.claude/skills/ui-design/» dentro de un repo, o «~/.claude/skills/ui-design/» si es personal, con un SKILL.md que trae frontmatter YAML (el «name» y la «description» de arriba) y un cuerpo en Markdown. El cuerpo es el conjunto de instrucciones que se inyecta cuando el skill se dispara. Al lado pueden convivir archivos de apoyo: una referencia de tokens, un componente de ejemplo, un checklist.

El ciclo de vida es sencillo:

1. Descubrimiento. Al iniciar la sesión, Claude Code escanea los directorios de skills y lee solo el frontmatter de cada SKILL.md. Sale barato: nombres y descripciones, nada más.
2. Match. En cada tarea, Claude compara el request contra esas descripciones. La mayoría de los turnos no coinciden con nada y no se carga nada.
3. Inyección. Cuando hay match, el cuerpo completo del SKILL.md entra en contexto, junto con cualquier archivo que le indique a Claude que lea (tu archivo de tokens, por ejemplo).
4. Generación bajo restricciones. Ahora Claude escribe el componente con las reglas a la vista.

El cuerpo es donde dejas escritas las reglas para que se apliquen siempre, en lugar de volver a escribirlas en cada prompt:

When building or restyling any component, you MUST:

- Read the token source first (tailwind.config + tokens.css). Use those
  values only. No hex literals. No arbitrary Tailwind values like p-[17px].
- If a token you need does not exist, STOP and say so. Do not invent one.
- Make every interactive element keyboard-reachable with a visible
  focus-visible ring. Real <label> on every input. alt on every image.
- Wrap any animation in a prefers-reduced-motion guard.
- Ship loading, empty, AND error states — never only the happy path.
- Return the component plus a one-line note on which tokens it used.

La línea de "devuelve una nota de una línea con los tokens que usó" es pequeña pero clave: vuelve auditables las decisiones del modelo, así cazas un literal colado directo en el diff y no tres pantallas más abajo.

04 · Una invocación concreta y qué devuelve

Veamos un caso con forma real. El proyecto ya tiene una escala de espaciado y tokens de color semánticos. Pides, en lenguaje normal:

Hazme un toast de "guardado" que confirme que se guardó un borrador. Necesita un estado de carga mientras el guardado está en curso y un estado de error si falla.

La descripción coincide con "building a … component", el skill se dispara, lee el archivo de tokens y devuelve algo así, fíjate que no hay ni un solo color literal ni número mágico:

// Tokens used: bg-surface, text-fg, border-subtle, space-3/space-4,
// text-success, text-danger. No literals.
type ToastState = "saving" | "saved" | "error"

export function SaveToast({ state }: { state: ToastState }) {
  const label =
    state === "saving" ? "Saving draft…"
    : state === "saved" ? "Draft saved"
    : "Couldn't save — retrying"

  return (
    <div
      role="status"
      aria-live="polite"
      className="flex items-center gap-space-3 rounded-md border
                 border-subtle bg-surface px-space-4 py-space-3 text-fg
                 motion-safe:animate-in motion-safe:fade-in"
    >
      <StatusDot state={state} />
      <span className={
        state === "error" ? "text-danger"
        : state === "saved" ? "text-success"
        : "text-fg"
      }>
        {label}
      </span>
    </div>
  )
}

Fíjate en lo que hizo el skill sin que se lo pidieras. Te dio los tres estados, no solo "saved". Usó «role="status"» con «aria-live="polite"» para que un lector de pantalla anuncie el cambio. Resguardó la animación tras «motion-safe:» para que quien tenga reduced-motion vea un toast quieto. Cada valor es un token, y el comentario de arriba los lista para que audites el diff en cinco segundos. Ese comentario de cabecera es el comprobante: lo que te permite confiar en la salida sin releer el archivo entero.

05 · Configuración y trampas

El skill vale tanto como aquello hacia donde lo apuntes y qué tan bien lo acotes. Los ajustes que importan:

Configuración

• Alcance: proyecto vs. personal. Ponlo en el repo («.claude/skills/») cuando los tokens son propios del proyecto y quieres que el equipo y el CI usen las mismas reglas. Ponlo en «~/.claude/skills/» cuando es tu default personal en todos los proyectos.
• Fuente de tokens. El ajuste más importante de todos es la ruta que el SKILL.md le indica a Claude que lea. Apúntala a la fuente de verdad real, tu config de Tailwind y tu CSS de tokens, no a una copia vieja pegada dentro del skill, que se va a desincronizar el día que alguien renombre un color.
• Nivel de exigencia. Decide si un token que falta es un freno en seco ("STOP and say so") o un fallback suave. Para un sistema de diseño que de verdad mantienes, que sea freno en seco; la fricción es justamente lo que buscas.

Trampas

• Le encantan los valores arbitrarios de Tailwind. La trampa más común es recurrir a «p-[17px]» o «bg-[#1f2937]» para que el screenshot quede pixel-perfect. Eso es el sistema rompiéndose en cuanto cambie el diseño. Prohíbe la sintaxis de valor arbitrario de forma explícita en el cuerpo y revisa el diff en busca de corchetes.
• Se salta los estados que le dan pereza. El estado de carga y sobre todo el de error son lo primero que desaparece bajo el "que funcione y ya". Ahí es donde viven las interfaces reales. Pídelos por nombre y rechaza la salida que solo trae el camino feliz.
• Una descripción vaga lo desactiva sin avisar. Si alguna vez te preguntas "¿por qué no se disparó el skill?", la respuesta casi siempre es la descripción, no el cuerpo. Reléela como matcher, no como prosa.
• No puede inventar tu criterio. El skill aplica consistencia con un sistema que tú definiste. No te va a decir si tu escala de espaciado es buena o si tus colores tienen suficiente contraste en el origen. Si entran tokens basura, sale basura consistente.

Un skill de diseño de UI no es magia ni pretende serlo. Es una forma de dejar escritas una sola vez las reglas aburridas e innegociables, usa los tokens, hazlo alcanzable, saca todos los estados, y que un agente rápido las aplique sin que haya que recordárselas. La palanca está en las restricciones, no en la creatividad; el skill mantiene a Claude consistente para que gastes tu atención en las decisiones que un sistema no puede tomar por ti.