# Improve Ui

> Audita una interfaz contra su diseño, detecta problemas de UI verificados y escribe planes autocontenidos sin tocar código. Útil para revisar, refinar o limpiar sin cambiar la identidad, ver deriva del design system o preparar un handoff.

Fuente: https://skillsagentes.com/skills/ibelick/ui-skills/improve-ui
Markdown: https://skillsagentes.com/skills/ibelick/ui-skills/improve-ui.md

Repositorio: https://github.com/ibelick/ui-skills
Autor: ibelick
Licencia: MIT
Actualizado: el mes pasado
Coste de contexto: 91 tok instalada, 2k tok al activarse, 2.5k tok con todos los archivos del bundle
Bundle: 3 archivos, 10 KB
Permisos que pide: ninguno declarado

## Instalación

Un skill son archivos markdown: los mismos archivos valen para cualquier agente y lo único que cambia es el directorio de destino, es decir la bandera `--agent`. Añade `-g` para instalarlo en todos los proyectos de la máquina.

```bash
# Claude Code
npx -y skills add ibelick/ui-skills --skill improve-ui --agent claude-code
# Cursor
npx -y skills add ibelick/ui-skills --skill improve-ui --agent cursor
# Codex
npx -y skills add ibelick/ui-skills --skill improve-ui --agent codex
# Gemini CLI
npx -y skills add ibelick/ui-skills --skill improve-ui --agent gemini
# Windsurf
npx -y skills add ibelick/ui-skills --skill improve-ui --agent windsurf
# Cline
npx -y skills add ibelick/ui-skills --skill improve-ui --agent cline
```

## Qué hace

- Audita una superficie de producto concreta trazando su ruta real de renderizado y nunca modifica el código fuente.
- Reconstruye el sistema de diseño local y solo admite hallazgos con pruebas de contrato, runtime y corrección.
- Escribe planes de implementación autocontenidos en `design-plans/` para que otro agente los ejecute.
- Detiene el informe en tres hallazgos y pide que elijas antes de convertirlos en planes.

## Cuándo usarla

- Te piden revisar, refinar, mejorar o limpiar una interfaz sin reemplazar su identidad.
- Hay que investigar si una superficie se ha desviado del design system.
- Hay que preparar un handoff de diseño para que otro agente implemente los cambios.

## Qué la activa

- "Revisa esta interfaz y dime qué problemas de UI tiene."
- "Refina la página de inicio sin cambiar su identidad."
- "Investiga si este módulo se está alejando del design system."
- "Prepara un handoff de diseño para la pantalla de ajustes."
- "Limpia la interfaz de la ficha de producto y propón mejoras."

## Archivos

- SKILL.md — 8 KB
- agents/openai.yaml — 386 B
- references/plan-template.md — 2 KB

## SKILL.md

Reproducido tal cual desde ibelick/ui-skills bajo MIT. Esta sección es el documento original y está en inglés.

# Improve UI

Audit one coherent product surface against the system that actually governs it. Preserve the product's identity, reuse existing owners, and prefer no finding to an unsupported one. Write plans only for changes the user selects; another agent executes them.

## Boundaries

- Never modify product source. Create or edit files only under `design-plans/`.
- Do not install dependencies, run formatters, commit, push, or otherwise mutate the working tree.
- Do not update design documentation. Record accepted documentation changes in the plan for its executor.
- Use rendered evidence only when the user provides it or explicitly requests visual inspection.
- Make every plan self-contained; its executor has no context from the audit or conversation.

## 1. Select the surface

Honor the user's scope. If the request is broad, select one deployable application and one coherent surface family representing a primary product task. State the selection; do not synthesize the whole repository into one product.

Start from the surface's routes and layouts. Trace the rendered path through compositions, shared components, variants, resolved tokens, and styles. Do not begin with a repository-wide search for inconsistencies.

A connection exists only when it is proven through rendering, imports, props, resolved configuration, CSS inheritance, or a generated artifact loaded by the surface. Shared names, similar tokens, repository proximity, and conceptual relationships do not establish a connection. Exclude other applications, previews, configurators, generated registries, legacy systems, and enterprise variants unless they participate in the traced path.

## 2. Reconstruct the local system

Check for `DESIGN.md`, repository guidance, and surface-local design documentation. Use a source only after proving it is current and governs the selected surface; drafts, proposals, migrations, and task lists describe future intent unless explicitly accepted and current. Absence of design documentation is not a finding.

Inspect only the tokens, variables, themes, primitives, variants, and compositions relevant to the traced path. Resolve aliases and variants to their definitions. Classify an implementation as local or legacy only when the repository says so.

Record:

```markdown
## Design language
- Audited surface:
- Design sources:
- Documented decisions:
- Governing owners and consumers:
- Explicit exceptions:
```

Write `None documented` under `Explicit exceptions` unless a cited source explicitly identifies the exception.

## 3. Prove findings

Before applying the proof gate, inspect every traced surface's user-facing labels, active-state presentation, responsive branches, and sibling variants for internal contradictions. Treat the results only as candidates.

A finding is in scope only when its correction primarily changes visual presentation, interface copy, layout, component styling, or conformance to a documented design rule. If the correction primarily changes whether product behavior works, reject it.

Search results, repetition, and implementation differences produce candidates, not findings. Keep a candidate only when all three proofs exist:

1. **Contract** — Cite a binding design decision for this property and scope, or a direct contradiction in user-facing presentation or content within the same task. “Prefer,” “generally,” names, omissions, repetition, and absence of an exception do not establish a contract.
2. **Runtime** — Prove that the cited owner, value, or behavior reaches the affected surface through the traced runtime path. Do not compare separate ownership layers or lifecycle states.
3. **Correction** — State one change required by the evidence. If it depends on an existing token, variant, primitive, or exemplar, name it exactly. If the evidence cannot determine the correct choice, the intended condition is ambiguous, the proposal contains alternatives, or the correction requires inventing product intent, reject the candidate.

Source can prove token, typography, color, spacing, layout, copy, component-variant, responsive-presentation, and explicit design-contract violations. It cannot turn functional behavior, state management, or interaction correctness into design findings. Hierarchy, prominence, density, clarity, discoverability, usability, and perceived coherence require rendered or user evidence.

Discard accessibility and HTML/ARIA semantic findings unless the user explicitly requests them. Discard broken routes, redirects, data wiring, action failures, metadata, package API, performance, architecture, and code-quality findings unless the user requested them or a product-specific design contract governs them.

Assign confidence only after all proofs pass. Reuse an existing owner when the evidence supports it; do not create a shared primitive from repetition alone.

## 4. Vet findings

Before reporting, re-open every cited source and try to falsify each candidate. Delete it when:

- The problem does not exactly match the cited implementation.
- The rule does not govern that property and surface.
- Counterevidence shows the difference is valid or deliberate.
- The evidence supports multiple corrections.
- The correction invents product intent.
- Another finding describes the same root problem.

Only findings that survive this pass may enter the table.

## 5. Report

Order surviving findings by confidence, user impact, reach, and correction cost. Stop at three.

Use this structure:

```markdown
## Design language
- Audited surface:
- Design sources:
- Documented decisions:
- Governing owners and consumers:
- Explicit exceptions:

## Findings
| # | Problem | Evidence | Proposed change | Scope | Confidence |
| --- | --- | --- | --- | --- | --- |

## Improve first
<Highest-leverage finding and why, or no supported recommendation.>
```

Evidence must establish the contract, runtime relationship, and deterministic interface consequence. Proposed change must contain one correction. Delete unsupported or overlapping rows before returning.

Delete any finding that does not include every required column, including Confidence.

Under `Improve first`, select one surviving finding with the strongest evidence and highest leverage. Never combine findings.

If no candidate survives, write `No supported findings were found.` under `## Findings` and `No supported recommendation.` under `## Improve first`.

If findings survive, stop and ask which to turn into plans. If the user already selected a finding or explicitly requested a plan for a described improvement, continue with that scope. If asked to fix or improve directly, offer a plan; never implement it.

## 6. Specify selected changes

Read [references/plan-template.md](references/plan-template.md). Write one plan per selected change, never one per symptom.

Before writing, re-open every cited source, record the current commit when available, identify exact reusable primitives and exemplars, and trace affected surfaces. Reconcile an existing plan instead of duplicating it.

Do not invent values when the repository provides a token or component contract. Introduce a primitive only after proving why the existing system cannot express the decision and which consumers should share it.

If asked to reconcile, recheck existing plans against current source and documented decisions; update stale evidence, affected surfaces, and status.

## Dónde encaja

- Categoría: [Diseño y UI](https://skillsagentes.com/categorias/diseno-ui.md) — Sistemas de diseño, trabajo con componentes y acabado visual.
- Creador: [ibelick](https://skillsagentes.com/creators/ibelick.md) — 7 skills en el directorio
- [Todas las skills](https://skillsagentes.com/skills.md)
- [Ranking de instalaciones](https://skillsagentes.com/ranking.md)

## Otras skills del mismo repositorio

- [Create Design Md](https://skillsagentes.com/skills/ibelick/ui-skills/create-design-md.md): Crea o actualiza un DESIGN.md desde un repositorio o web pública: documenta el lenguaje de diseño, reconstruye el sistema visual y extrae tokens y pautas de evidencia. No modifica código fuente ni convierte patrones accidentales en diseño.
- [Ui Skills Root](https://skillsagentes.com/skills/ibelick/ui-skills/ui-skills-root.md): Úsalo antes de trabajo relacionado con UI para seleccionar el contexto de UI Skills más pequeño y útil a través de la CLI ui-skills.
- [Baseline Ui](https://skillsagentes.com/skills/ibelick/ui-skills/baseline-ui.md): Pule rápido el código de interfaz corrigiendo espaciado, jerarquía, tipografía y pequeños problemas de layout. Úsalo cuando la interfaz necesite una limpieza o un pulido rápido.
- [Fixing Accessibility](https://skillsagentes.com/skills/ibelick/ui-skills/fixing-accessibility.md): Audita y corrige problemas de accesibilidad HTML: ARIA, navegación por teclado, gestión del foco, contraste de color y errores de formulario. Úsalo al añadir controles interactivos, formularios, diálogos o revisar WCAG.
- [Fixing Motion Performance](https://skillsagentes.com/skills/ibelick/ui-skills/fixing-motion-performance.md): Audita y corrige problemas de rendimiento en animaciones: layout thrashing, propiedades del compositor, movimiento ligado al scroll y desenfoques. Úsalo si las animaciones van a tirones o revisas el rendimiento de animaciones CSS/JS.

## Skills relacionadas

- [Baseline Ui](https://skillsagentes.com/skills/ibelick/ui-skills/baseline-ui.md): Pule rápido el código de interfaz corrigiendo espaciado, jerarquía, tipografía y pequeños problemas de layout. Úsalo cuando la interfaz necesite una limpieza o un pulido rápido.
- [Ui Skills Root](https://skillsagentes.com/skills/ibelick/ui-skills/ui-skills-root.md): Úsalo antes de trabajo relacionado con UI para seleccionar el contexto de UI Skills más pequeño y útil a través de la CLI ui-skills.
- [Create Design Md](https://skillsagentes.com/skills/ibelick/ui-skills/create-design-md.md): Crea o actualiza un DESIGN.md desde un repositorio o web pública: documenta el lenguaje de diseño, reconstruye el sistema visual y extrae tokens y pautas de evidencia. No modifica código fuente ni convierte patrones accidentales en diseño.
- [Fixing Accessibility](https://skillsagentes.com/skills/ibelick/ui-skills/fixing-accessibility.md): Audita y corrige problemas de accesibilidad HTML: ARIA, navegación por teclado, gestión del foco, contraste de color y errores de formulario. Úsalo al añadir controles interactivos, formularios, diálogos o revisar WCAG.
- [Fixing Metadata](https://skillsagentes.com/skills/ibelick/ui-skills/fixing-metadata.md): Audita y corrige metadatos HTML: títulos, descripciones, canónicas, Open Graph, Twitter cards, favicons, JSON-LD y robots. Úsalo al añadir SEO, arreglar vistas previas, revisar Open Graph, configurar canónicas o publicar páginas nuevas.

---

Skills Agentes · [Índice de páginas en markdown](https://skillsagentes.com/sitemap.md) · [Inicio](https://skillsagentes.com/index.md)