Skill para Claude Code · basada en Refactoring UI, de Adam Wathan y Steve Schoger

Las reglas de Refactoring UI, aplicadas por Claude en tu código y en Figma

Cuando le pides a Claude que construya o revise una interfaz, la skill le da las escalas de espaciado, tipografía y color del libro, un checklist de revisión y los valores exactos que tiene que usar.

Instalar la skillVer una revisión real

En tu terminal:

cp -R refactoring-ui ~/.claude/skills/

Tarjeta / revisada

1

Taller · 14 nov · 3 horas

Diseño de interfaces

Tres horas de práctica con tus propias pantallas.

3
249 €· 12 plazas libres
4LM

Laura Méndez

Diseñadora de producto

5Reservar plazaCompartir
  1. 1

    Peso y color antes que tamaño. Título a 24px/700; la descripción baja a grey-600.

  2. 2

    Sin etiquetas. "Plazas: 12" pasa a "12 plazas libres".

  3. 3

    Más espacio fuera que dentro. 8px dentro de cada bloque, 24px entre bloques.

  4. 4

    Menos bordes. Un cambio de fondo separa a la instructora.

  5. 5

    Una sola acción primaria. Cancelar desaparece; Compartir pasa a enlace.

Así es una revisión

Sigue el checklist en orden de impacto: jerarquía y espaciado antes que color o sombras. Cada hallazgo dice dónde está, qué falla, qué principio lo explica y el cambio exacto, con las clases o tokens que ya usa tu proyecto.

Si no le pides que lo arregle, solo informa. Si se lo pides, aplica los cambios sin inventar valores nuevos.

> /refactoring-ui revisa src/components

  1. 1. Jerarquía

    ProductCard.tsx:12

    El título (30px, peso 400) y el precio (24px, peso 400) pesan lo mismo, así que nada destaca.

    El tamaño no lo es todo: da énfasis con peso y color.

    - <h3 className="text-3xl">{name}</h3>+ <h3 className="text-2xl font-bold">{name}</h3>- <p className="text-2xl">{price}</p>+ <p className="text-lg font-bold text-gray-900">{price}</p>

  2. 2. Espaciado

    CheckoutForm.tsx:40

    Hay 20px entre cada etiqueta y su campo, y otros 20px hasta la etiqueta siguiente. Los grupos no se distinguen.

    Más espacio alrededor de un grupo que dentro de él.

    - <div className="space-y-5">+ <div className="space-y-6">-   <label className="mb-5 block">+   <label className="mb-2 block">

  3. 3. Color

    Banner.tsx:8

    Subtítulo en gris sobre fondo verde azulado: se ve apagado y sucio.

    Sobre color, nada de gris: elige a mano un tono del mismo matiz.

    - <p className="text-gray-400">+ <p className="text-teal-100">

Las reglas

Un resumen de cada capítulo del libro. La skill tiene un archivo de referencia por capítulo, con sus ejemplos y valores, y Claude solo abre el que necesita para la tarea.

Empezar

references/process-and-systems.md
  • Diseña primero la funcionalidad, no la carcasa: la barra lateral puede esperar.
  • Jerarquía en escala de grises; el color entra al final.
  • Elige por eliminación entre valores vecinos de una escala.
  • Una personalidad: fuente, color, radio y tono del texto cuentan lo mismo.

Jerarquía

references/hierarchy.md
  • Peso y color antes que tamaño: 24px/700 gana a 30px/400.
  • Tres colores de texto: oscuro, gris y gris claro.
  • Sobre fondo de color, nada de gris: mismo matiz elegido a mano, hsl(183 70% 84%).
  • Una acción primaria por vista; las demás, contorno o enlace.
  • Las etiquetas son el último recurso: 12 plazas libres.

Espaciado

references/layout-spacing.md
  • Empieza con demasiado espacio y ve quitando.
  • Escala con saltos de al menos un 25 %: 4 8 12 16 24 32 48 64.
  • Más espacio entre grupos que dentro: 8 dentro, 24 fuera.
  • No llenes la pantalla: si basta con 600 px, usa 600 px.

Tipografía

references/typography.md
  • Escala hecha a mano en px o rem, nunca en em.
  • Entre 45 y 75 caracteres por línea: max-width: 34em.
  • Interlineado inverso al tamaño: texto 1.5, titulares 1.
  • Mayúsculas con aire, +0.05em; titulares grandes, más juntos.

Color

references/color.md
  • HSL y tonos definidos del 100 al 900. Nada de darken().
  • Más saturación cuanto más te alejas del 50 % de luminosidad.
  • Grises teñidos: azulados si son fríos, amarillentos si son cálidos.
  • Contraste mínimo 4.5:1, y nunca informes solo con color.

Profundidad

references/depth.md
  • La luz viene de arriba: borde superior claro, sombra por debajo.
  • Sombras como elevación: botón e1, menú e3, modal e5.
  • Cada sombra son dos: una amplia y suave, otra corta y oscura.
  • Solapa elementos para crear capas.

Imágenes

references/images.md
  • Texto sobre foto: capa oscura hsl(0 0% 0% / .55) o foto coloreada.
  • No amplíes iconos de 16 px: mételos en un círculo de color.
  • Las capturas se recortan, no se encogen.
  • Fotos de usuarios en contenedor fijo con object-fit: cover.

Acabado

references/finishing-touches.md
  • Menos bordes: sombra, cambio de fondo o más espacio.
  • Bordes de acento en tarjetas, alertas y navegación activa.
  • El estado vacío es lo primero que ve alguien nuevo. Diséñalo.
  • Mejora los controles por defecto: viñetas con icono, checkboxes con tu color.

Escalas en vez de valores sueltos

Si tu proyecto ya tiene tokens, la skill usa esos. Si no, parte de estos: están endesign-tokens.css y, para Figma, en figma-tokens.js. Esta página usa los mismos, con otro color de acento.

Espaciado

Base 16. Cada paso, al menos un 25 % mayor que el anterior.

  • 4
  • 8
  • 12
  • 16
  • 24
  • 32
  • 48
  • 64
  • 96
  • 128

Tipografía

12 a 72 px. Dos pesos para texto, uno más para títulos.

  • 12Reservar plaza
  • 14Reservar plaza
  • 16Reservar plaza
  • 18Reservar plaza
  • 20Reservar plaza
  • 24Reservar plaza
  • 30Reservar plaza
  • 36Reservar plaza

Color

Grises azulados en diez tonos y un acento. El 500 es el base.

50100200300400500600700800900

Elevación

Cinco sombras de dos capas. Cuanto más arriba, más atención.

e1

botón

e2

tarjeta

e3

menú

e4

popover

e5

modal

También en Figma

Con el servidor MCP de Figma conectado, pega el enlace de un frame. Las reglas son las mismas; cambian las herramientas: auto layout con variables en lugar de clases, y estilos en lugar de CSS.

/refactoring-ui revisa <enlace al frame>
Hace una captura del frame y lo mide con figma-audit.js: espaciado y tipografía fuera de escala, contraste, líneas demasiado largas, colores sin variable. Luego revisa a ojo la jerarquía.
/refactoring-ui crea los tokens en este archivo
Crea variables de color, espaciado y radio, estilos de texto y cinco estilos de sombra, con los mismos nombres que en CSS para que Dev Mode y el código coincidan.
/refactoring-ui corrige este frame
Duplica el frame y aplica los cambios usando variables y estilos, nunca valores sueltos. Te enseña el antes y el después.
{
  "summary": {
    "fontSizes": [11, 13, 14, 16, 18, 22, 28, 32],
    "textColors": ["#1b2733", "#5d6b78", "#8a96a3", "#9aa5b1",
                   "#b4bec8", "#ffffff@0.70", "#e12d39"],
    "radii": [4, 6, 8, 12, 20],
    "warnings": [
      "8 distinct font sizes — tighten to the type scale",
      "5 corner radii [4,6,8,12,20] — pick one family"
    ]
  },
  "issues": {
    "spacing-off-scale":  { "count": 14 },
    "low-contrast-text":  { "count": 3, "examples": [
      { "name": "Caption", "ratio": 2.61 } ] },
    "grey-or-transparent-text-on-color": { "count": 2 }
  }
}
Resultado de figma-audit.js en un frame de ejemplo (recortado).

Instalar

Es una carpeta de Markdown y un par de scripts, sin dependencias. Cópiala en las skills de Claude Code y se activará sola cuando pidas diseñar, pulir o revisar una interfaz, o cuando digas que algo se ve mal.

  1. Para todos tus proyectos

    cp -R refactoring-ui ~/.claude/skills/

  2. O solo para uno

    cp -R refactoring-ui <proyecto>/.claude/skills/

  3. Y pídeselo a Claude, o llámala directamente

    /refactoring-ui revisa este componente

Qué contiene

refactoring-ui/├── SKILL.md  # flujos, reglas y escalas├── assets/│   ├── design-tokens.css  # tokens en CSS│   ├── figma-tokens.js  # los mismos, en Figma│   └── figma-audit.js  # auditoría de frames└── references/  # un archivo por capítulo    ├── hierarchy.md    ├── …    ├── review-checklist.md    └── figma.md