@damiangilgonzalez/harness 1.3.7

package/skills/mejor-accesibilidad/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: mejor-accesibilidad
+description: "Use to bring the project up to accessibility standards and best practices — native elements vs. ARIA, focus rings, full keyboard support, focus trapping, tap target sizes, form labels, announced errors, accessible names, reduced motion, live regions, alt text, heading structure, and zoom."
+tags: ["accessibility", "a11y", "aria", "keyboard-navigation"]
+profiles: [ui, full]
+---
+
+# Accesibilidad
+
+Casi toda la accesibilidad es gratis si usas la plataforma. Los elementos nativos vienen con soporte de teclado, las etiquetas reales se anuncian solas y un anillo de foco visible es una regla CSS.
+
+Escribe cada arreglo en el sistema de estilos del proyecto, y usa los valores exactos de abajo en vez de sustitutos que se les parezcan.
+
+Revisar son dos recorridos. Solo teclado, donde cada flujo se completa sin raton. Y luego lector de pantalla, donde cada control anuncia un nombre, un rol y su estado. Ante la duda, coge el defecto de la plataforma antes que una reconstruccion propia, y quita ARIA antes que anadirlo.
+
+La medicion de contraste y los arreglos de color son de `mejor-colores`. El dimensionado de texto y el zoom de inputs en iOS son de `mejor-tipografia`. El layout espacial RTL es de `mejor-layout`.
+
+## Elementos nativos primero
+
+La primera regla de ARIA: no uses ARIA cuando existe un elemento nativo. `<button>` para acciones, `<a href>` para navegacion, nunca `<div onClick>`. Un enlace de verdad debe soportar Cmd/Ctrl/clic central. Nada de ARIA es mejor que ARIA mal puesto. Ver [semantics-and-aria.md](semantics-and-aria.md) para landmarks, boton-frente-a-enlace y estados deshabilitados.
+
+## Anillos de foco visibles
+
+Estiliza `:focus-visible`, no `:focus` a secas. Los usuarios de teclado reciben anillo y los de raton normalmente no. Prefiere el indicador del navegador sin modificar.
+
+Un anillo propio necesita un token de foco del proyecto u otro color explicito. Verifica el indicador entero contra cada color adyacente que cruza, incluido `currentColor`. Usa al menos un perimetro solido de `2px` o un area visible equivalente. Nunca uses `outline: none` sin un reemplazo verificado, y preserva los colores del sistema en modo de colores forzados. Las recetas estan en [focus-and-keyboard.md](focus-and-keyboard.md).
+
+## Soporte completo de teclado
+
+Toda interaccion con puntero necesita un camino de teclado. Sigue los patrones del ARIA APG: Escape cierra las capas, las flechas mueven dentro de un widget compuesto, Tab mueve entre widgets, Enter y Espacio activan.
+
+Usa solo `tabindex="0"` para unirse al orden natural de tabulacion y `tabindex="-1"` para foco programatico. Los valores positivos rompen ese orden. Los widgets compuestos usan roving tabindex, donde el elemento activo es `0` y todos los demas `-1`.
+
+## Atrapa y restaura el foco
+
+Los modales ponen `inert` en el contenido de fondo, mueven el foco dentro al abrirse y lo devuelven al disparador al cerrarse. Anade `overscroll-behavior: contain` para que el fondo no haga scroll.
+
+## Area minima de pulsacion
+
+La base de nivel AA de WCAG 2.5.8 es un objetivo de 24x24 pixeles CSS, o una de sus excepciones (espaciado, control equivalente, en linea, agente de usuario y esencial). Apunta a 44x44px en tactil y 40x40px en escritorio donde la densidad lo permita. Extiende con un pseudo-elemento cuando el elemento visible deba seguir siendo mas pequeno.
+
+Nunca dejes que las areas extendidas se solapen. Da `pointer-events: none` a las capas decorativas, para que un resplandor no se trague los clics del control de debajo. Tamanos y reglas de colision en [hit-areas.md](hit-areas.md).
+
+## Etiqueta y tipa cada control
+
+Cada input lleva un `<label for>` o un `<label>` que lo envuelve. Un placeholder nunca es una etiqueta. Etiqueta y control comparten un unico objetivo de pulsacion, sin zona muerta entre una casilla y su texto.
+
+Anade `autocomplete` con un `name` con significado, mas el `type` y el `inputmode` que invocan el teclado correcto. Nunca bloquees pegar: la gente pega contrasenas y codigos de un solo uso. Ver [forms.md](forms.md).
+
+## Errores que se anuncian
+
+Manten el boton de envio habilitado hasta que arranque la peticion, y entonces deshabilitalo con un spinner y la etiqueta original. Valida al enviar. Marca los campos que fallan con `aria-invalid="true"`, apunta `aria-describedby` al texto de error en linea y pon el foco en el primer campo invalido.
+
+Usa el `disabled` nativo cuando un control no este disponible de verdad. Coge `aria-disabled="true"` solo cuando deba seguir siendo enfocable, y entonces bloquea puntero, teclado y comportamiento de formulario en codigo, y estiliza el estado explicitamente.
+
+## Nombres accesibles en todas partes
+
+Los botones de solo icono necesitan un `aria-label` descriptivo. El texto visible de la etiqueta debe aparecer en el nombre accesible. Los elementos decorativos llevan `aria-hidden="true"`, nunca sobre un elemento enfocable.
+
+## No te apoyes solo en el color
+
+El estado necesita una pista redundante: un icono, texto o un subrayado junto al color. Averigua que requisito de contraste WCAG aplica y usa `mejor-colores` para medir el par renderizado. Cuando falle, reporta el par y el requisito que no alcanza, y deja los colores en paz salvo que te lo pidan.
+
+## Respeta prefers-reduced-motion
+
+Envuelve el movimiento en `@media (prefers-reduced-motion: no-preference)` para que sea opt-in. Bajo movimiento reducido, sustituye deslizamientos y escalas por fundidos de opacidad, y elimina del todo el parallax y la reproduccion automatica.
+
+Dos reglas se mantienen sea cual sea la preferencia: el contenido que se reproduce solo necesita un control de pausa visible, y los toasts que llevan una accion o un error se quedan hasta que se descartan. Ver [motion-and-zoom.md](motion-and-zoom.md).
+
+## Anuncia el contenido dinamico
+
+Tres mecanismos, tres trabajos. `aria-describedby` lleva la validacion especifica de un campo. Una region viva cortes (`role="status"`) lleva actualizaciones no urgentes no ligadas a un control, como toasts y recuentos de resultados. `role="alert"` lleva errores urgentes no ligados, y nada mas.
+
+Los anuncios corteses repetidos necesitan una region vacia estable renderizada antes de que su texto se actualice. Las alertas insertadas dinamicamente tienen soporte irregular, asi que pruébalas en los lectores de pantalla que te importen. Ver [screen-readers.md](screen-readers.md).
+
+## Texto alternativo segun el proposito
+
+Las imagenes decorativas llevan `alt=""`. Las informativas describen el significado. Las funcionales describen la accion: un boton con icono de busqueda es `alt="Buscar"`, no `alt="lupa"`.
+
+## La estructura es navegacion
+
+Usa encabezados que describan sus secciones y formen un esquema coherente. Da a la pagina un unico `<h1>` y anida los niveles por debajo sin saltarte ninguno. Expon un unico landmark `<main>` primario visible. Cuando la navegacion repetida o el chrome lo preceden, haz que un enlace "Saltar al contenido" sea el primer elemento enfocable. Los encabezados con ancla llevan `scroll-margin-top`.
+
+## Sobrevive al zoom y al redimensionado de texto
+
+La pagina debe funcionar al 200% de zoom y refluir a 320px de ancho sin scroll horizontal. Usa `min-height` en vez de `height` fijo en contenedores de texto. Prefiere breakpoints en `rem` donde encajen en el codebase, y nunca dejes que el meta viewport limite cuanto puede ampliar el lector.
+
+## Antes de terminar
+
+| Error | Arreglo |
+| --- | --- |
+| Color de foco propio que se asume que funciona en todas partes | Verificalo contra cada color adyacente y en modo de colores forzados |
+| Actualizacion cortes repetida que se anuncia de forma inconsistente | Manten una region de estado vacia estable y actualiza su texto |
+| Region viva `assertive` para un toast rutinario | Usa `polite`; reserva `assertive` para errores |
+| `aria-hidden="true"` sobre un elemento enfocable | Quitalo o haz el elemento no enfocable |
+| Envio deshabilitado hasta que el formulario es valido | Dejalo habilitado; valida al enviar y enfoca el primer error |
+| Tratamiento de hover que se queda pegado tras un toque en tactil | Pon el estilo de hover tras `@media (hover: hover)` |
+| Tooltip sobre un control `disabled` nativo | Texto al lado, o `aria-disabled` para que siga siendo enfocable |
+
+## Como reportar
+
+**Severidad.** `ALTA` impide una tarea, oculta contenido a la tecnologia asistiva o crea un fallo sistemico. `MEDIA` hace una interaccion apreciablemente mas dificil. `BAJA` es pulido aislado.
+
+**Verificacion.** Sin navegador: nombres accesibles en cada elemento interactivo, manejadores de teclado en controles no nativos, estilos de foco, guardas de `prefers-reduced-motion` y etiquetas de formulario ligadas a sus inputs. Con navegador: tabula el flujo en orden, lee nombres y roles computados del arbol de accesibilidad, confirma un indicador de foco visible en cada parada y pasa una auditoria automatica. Reporta como `No verificado` toda comprobacion que no pudieras ejecutar.
+
+**Formato.** Agrupa los hallazgos bajo el principio que incumplen, ordenados por severidad, una fila por causa raiz listando todas sus ubicaciones:
+
+| Severidad | Ubicacion | Antes | Despues | Por que |
+| --- | --- | --- | --- | --- |
+
+Termina con `Bloquear` si queda alguna `ALTA`, y `Aprobar` en caso contrario. Nunca `Aprobar` cobertura que no inspeccionaste. Si no hay nada, di "Sin hallazgos accionables de accesibilidad" y reporta la verificacion.

package/skills/mejor-accesibilidad/evals/cases.yaml

@@ -0,0 +1,32 @@
+skill: mejor-accesibilidad
+
+should_trigger:
+  - prompt: "Revisa que este formulario cumple accesibilidad."
+    why: "Disparador directo de mejor-accesibilidad."
+  - prompt: "Necesito soporte completo de teclado en este componente."
+    why: "Disparador directo de mejor-accesibilidad."
+  - prompt: "Comprueba que los errores se anuncian correctamente a lectores de pantalla."
+    why: "Disparador directo de mejor-accesibilidad."
+  - prompt: "Make sure this modal traps focus and has accessible names."
+    why: "Disparador directo de mejor-accesibilidad."
+  - prompt: "Ajusta los anillos de foco de este boton."
+    why: "Disparador directo de mejor-accesibilidad."
+
+should_not_trigger:
+  - prompt: "Elige la paleta de colores de la marca."
+    route_to: "mejor-colores"
+    why: "Elegir la paleta de colores es el trabajo de mejor-colores, no de mejor-accesibilidad."
+  - prompt: "Escribe el copy del boton de enviar."
+    route_to: "mejor-redaccion"
+    why: "Escribir el copy de un boton es el trabajo de mejor-redaccion, no de mejor-accesibilidad."
+  - prompt: "Anade una animacion al icono del menu."
+    route_to: "animar"
+    why: "Anadir una animacion es el trabajo de animar, no de mejor-accesibilidad."
+  - prompt: "Revisa el layout responsive de esta pagina."
+    route_to: "mejor-layout"
+    why: "Revisar el layout responsive es el trabajo de mejor-layout, no de mejor-accesibilidad."
+
+capability:
+  - scenario: "El usuario quiere que el proyecto cumpla estandares de accesibilidad."
+    must_include:
+      - "teclado"

package/skills/mejor-accesibilidad/focus-and-keyboard.md

@@ -0,0 +1,131 @@
+# Focus and keyboard
+
+Focus rings, skip links, tabindex, focus trapping and the APG keyboard patterns.
+
+## Focus rings
+
+Style `:focus-visible`, not bare `:focus`. The browser shows it for keyboard and assistive-tech focus and suppresses it for mouse clicks, where focus is already obvious. Never write `outline: none` or `focus:outline-none` without a visible replacement, which removes keyboard navigation for sighted keyboard users.
+
+Prefer the browser's unmodified focus indicator, which adapts to platform and forced-color settings without the author predicting every background. Adding only `outline-offset` preserves it. A custom `outline: 2px solid` with no color renders `currentColor`, which is not automatically accessible, because the outline may cross colors unlike the text's own background. The preference order:
+
+```css
+/* Best: keep the browser ring, just give it breathing room */
+:focus-visible {
+  outline-offset: 2px;
+}
+
+/* Custom ring when the design requires one: use the project's verified token */
+:focus-visible {
+  outline: 2px solid var(--focus-ring);
+  outline-offset: 2px;
+}
+```
+
+```tsx
+// Tailwind: use the project's focus token or established focus-ring utility
+<button className="focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--focus-ring)]">
+  Save
+</button>
+```
+
+A custom focus indicator must meet the applicable project or WCAG target for visible area and change of contrast. Inspect the whole perimeter against every adjacent color it crosses: component fills, page surfaces, images, gradients, hover and selected states. A token, brand color, or `currentColor` passes only when that rendered check does.
+
+In `forced-colors: active` (Windows High Contrast), keep the default color adjustment or name a system color such as `Highlight`. `forced-color-adjust: none` freezes the authored color, so use it only where you have checked the control stays perceivable.
+
+Group focus styles with `:focus-within` when a wrapper should light up while an inner input has focus (e.g. a search box with an icon inside the border).
+
+## Skip link
+
+Target `<main id="main">` and visually hide the link until focused:
+
+```css
+.skip-link {
+  position: absolute;
+  inset-inline-start: -999px;
+}
+.skip-link:focus {
+  inset-inline-start: 16px;
+  top: 16px;
+}
+```
+
+```html
+<body>
+  <a class="skip-link" href="#main">Skip to content</a>
+  <header>…</header>
+  <main id="main">…</main>
+</body>
+```
+
+Give in-page anchor targets `scroll-margin-top`, such as `80px` under a sticky header, so the target isn't hidden when jumped to.
+
+## tabindex rules
+
+- `tabindex="0"`: adds an element to the natural tab order. Only for custom interactive elements that aren't natively focusable.
+- `tabindex="-1"`: focusable via JavaScript only (`el.focus()`). Use for headings you move focus to, modal containers and roving-tabindex members.
+- Positive `tabindex`: never. It hijacks the tab order for the whole page. Fix the DOM order instead.
+
+### Roving tabindex
+
+Composite widgets, meaning tabs, menus, toolbars and radio groups, occupy one Tab stop. The active item has `tabindex="0"`, all others `tabindex="-1"`, and arrow keys move both focus and the `0`:
+
+```tsx
+<div role="tablist">
+  {tabs.map((tab, i) => (
+    <button
+      role="tab"
+      tabIndex={i === activeIndex ? 0 : -1}
+      aria-selected={i === activeIndex}
+      onKeyDown={handleArrowKeys} // ArrowLeft/ArrowRight move activeIndex, wrapping
+    >
+      {tab.label}
+    </button>
+  ))}
+</div>
+```
+
+## Focus trapping and restoration
+
+Modals must trap focus. Put `inert` on everything behind the dialog, which removes background content from the tab order and from assistive tech in one move:
+
+```tsx
+// On open
+document.getElementById("app-content").inert = true;
+const dialog = dialogRef.current;
+(dialog.querySelector("[autofocus]") ??
+  dialog.querySelector("button, [href], input, select, textarea"))?.focus();
+
+// On close
+document.getElementById("app-content").inert = false;
+triggerRef.current?.focus(); // always return focus to the element that opened it
+```
+
+Prefer native `<dialog>` with `showModal()`, which gives you the trap, the `inert` background and Escape handling for free. A custom overlay that can't use it needs `role="dialog"`, `aria-modal="true"` and an accessible name via `aria-labelledby`. Either way:
+
+- On open, focus the first focusable element. For destructive confirmations, focus the least destructive action instead.
+- On close, return focus to the trigger, or to the nearest logical container if the trigger is gone.
+- Add `overscroll-behavior: contain` on the dialog so scrolling inside never scrolls the page behind it.
+
+## Keyboard patterns (ARIA APG)
+
+Native elements come with these behaviors; custom widgets must implement them. A role is a promise. Give something `role="tab"` and users expect the full tab keyboard model.
+
+| Widget | Keys |
+| --- | --- |
+| Dialog | Tab/Shift+Tab cycle inside (wrap at ends); Escape closes |
+| Tabs | Arrow keys move between tabs (wrapping); Tab exits to the panel; Home/End jump to first/last |
+| Menu button | Enter/Space/ArrowDown opens and focuses first item; ArrowUp opens and focuses last; arrows navigate; Escape closes and refocuses the button |
+| Disclosure / accordion | Header is a `<button aria-expanded>`; Enter and Space toggle |
+| Combobox | ArrowDown opens/moves into the list; Enter accepts; Escape closes and returns to the input; typing filters |
+| Listbox / radio group | Arrow keys move selection; one Tab stop for the whole group |
+
+Universal rules:
+
+- Escape dismisses whatever opened last: tooltip, then menu, then dialog.
+- Arrow keys, not Tab, move within a composite widget; Tab moves between widgets.
+- Tabs choose activation mode: automatic (panel switches on arrow focus) when panels render instantly, manual (Enter/Space to activate) when switching is expensive.
+- Enter submits the focused input's form. In `<textarea>`, Enter inserts a newline and ⌘/Ctrl+Enter submits.
+
+## SPA route changes
+
+Client-side navigation doesn't reset focus or announce anything. On route change, update `document.title` to match the new context, then move focus to the new view's `<h1>` (given `tabindex="-1"`) or to `<main>`. Restore scroll position on back and forward navigation, and scroll to top on forward navigation.

package/skills/mejor-accesibilidad/forms.md

@@ -0,0 +1,84 @@
+# Forms
+
+Labels, autocomplete, error messaging, input types and submit behavior.
+
+## Labels
+
+Every control needs a programmatic label: `<label for>` pointing at the input's `id`, or a wrapping `<label>`. A placeholder is never a label. It disappears the moment the user types and usually fails contrast.
+
+```html
+<!-- Good: explicit association -->
+<label for="email">Email</label>
+<input id="email" type="email" autocomplete="email" />
+
+<!-- Good: wrapping label, so label and control share one hit target -->
+<label>
+  <input type="checkbox" /> Send me updates
+</label>
+```
+
+Label and control share one hit target, so clicking "Send me updates" toggles the checkbox with no dead zone between them. Mark required fields with native `required` plus a visible indicator explained once per form ("* required").
+
+A placeholder used *in addition to* a label shows an example of the expected format: `placeholder="name@company.com"`.
+
+## Error messaging
+
+The complete pattern:
+
+```html
+<label for="email">Email</label>
+<input
+  id="email"
+  type="email"
+  autocomplete="email"
+  aria-invalid="true"
+  aria-describedby="email-error"
+/>
+<p id="email-error">Enter a valid email address.</p>
+```
+
+- `aria-invalid="true"` on the failing field, removed once fixed.
+- `aria-describedby` links the field to its inline error so screen readers announce it with the field.
+- Errors render inline beside their fields, with an icon or text. Never a red border alone, which is a color-only cue.
+- On submit, focus the first invalid field.
+- Allow incomplete submission so validation can surface. Never disable submit until valid (see below).
+- Accept free text and validate after. Never block typing or filter characters as the user types. Trim values before validating, because autocomplete and text expansion add trailing spaces.
+
+## Autocomplete and input types
+
+`autocomplete` with a meaningful `name` fills forms in one tap and is a WCAG requirement (1.3.5) for fields about the user. The common tokens:
+
+| Field | `autocomplete` |
+| --- | --- |
+| Name | `name` (or `given-name` / `family-name`) |
+| Email | `email` |
+| Phone | `tel` |
+| Address | `street-address`, `address-line1`, `postal-code`, `country` |
+| Card | `cc-number`, `cc-exp`, `cc-csc`, `cc-name` |
+| Login | `username`, `current-password` |
+| Signup / reset | `new-password` |
+| 2FA code | `one-time-code` |
+
+Prefix with a section where relevant: `autocomplete="shipping street-address"`.
+
+Correct `type` and `inputmode` pick the right mobile keyboard:
+
+| Input | Use |
+| --- | --- |
+| Email, URL, phone | `type="email"`, `type="url"`, `type="tel"` |
+| OTP / PIN / card number | `type="text" inputmode="numeric"` (keeps text semantics, no spinner) |
+| Money, decimals | `type="text" inputmode="decimal"` |
+| True numeric quantity | `type="number"` |
+
+Disable spellcheck on emails, codes and usernames: `spellcheck="false"`.
+
+## Never fight the user's tools
+
+- Stay compatible with password managers and 2FA autofill: real `<form>`, correct `autocomplete`, no fake inputs.
+
+## Submit behavior
+
+- Keep submit enabled until the request starts, then disable it and show a spinner *beside the original label*. "Save" with a spinner, not a bare spinner. The label is what tells assistive tech which button is busy.
+- Announce results. Success goes through a polite live region. On failure, focus the first invalid field, which is itself the announcement. Reserve `role="alert"` for form-level errors not tied to a field ([screen-readers.md](screen-readers.md)).
+- Warn on unsaved changes before navigation, and never lose typed input to a re-render. Hydration must preserve focus and value.
+- Enter submits from any focused input; in `<textarea>`, ⌘/Ctrl+Enter submits.

package/skills/mejor-accesibilidad/hit-areas.md

@@ -0,0 +1,94 @@
+# Hit areas
+
+Target sizes, expanding hit areas without changing visual size and collision rules.
+
+## Target sizes
+
+Separate the conformance baseline from larger usability targets:
+
+| Standard | Minimum |
+| --- | --- |
+| WCAG 2.5.8 (AA) | 24×24px, the hard floor |
+| WCAG 2.5.5 (AAA) | 44×44px |
+| Apple HIG | 44×44pt |
+| Material Design | 48×48dp |
+
+WCAG 2.5.8 Level AA requires a 24×24 CSS-pixel target or one of its exceptions. Treat 44px as the recommended touch target for primary controls and 40px as a useful desktop target where density permits. Smaller controls are not automatic failures. Check the spacing, equivalent-control, inline, user-agent and essential exceptions before reporting one.
+
+Under the spacing exception, an undersized target passes when a 24px circle centered on its bounding box intersects no other target and no other undersized target's circle. In the simple case, 20px targets need a 4px gap.
+
+The visible element can stay small; the hit area is what must be big. Anything that looks clickable must be clickable across its whole visual extent, with no dead zones. A checkbox and its label share one hit target.
+
+## Expanding the hit area
+
+Where the visible element is smaller, say a 20×20 checkbox, extend the hit area with a pseudo-element. Put it on the wrapping `<label>` or `<button>`, never on the `<input>`, because replaced elements don't render `::before`/`::after` reliably.
+
+### CSS example
+
+```css
+/* Small checkbox with expanded 44px hit area, on the wrapping label */
+.checkbox-label {
+  position: relative;
+  width: 20px;
+  height: 20px;
+}
+
+.checkbox-label::after {
+  content: "";
+  position: absolute;
+  top: 50%;
+  left: 50%; /* physical centering: direction-independent */
+  transform: translate(-50%, -50%);
+  width: 44px;
+  height: 44px;
+}
+```
+
+### Tailwind example
+
+```tsx
+<button className="relative size-5 after:absolute after:top-1/2 after:left-1/2 after:size-11 after:-translate-1/2">
+  <CheckIcon />
+</button>
+```
+
+### Layout alternative
+
+Where the element can afford real box size, skip the pseudo-element and let the box be the target. That hands the browser real geometry for scrolling and gestures:
+
+```css
+.icon-button {
+  min-width: 44px;
+  min-height: 44px;
+  display: inline-grid;
+  place-items: center;
+}
+```
+
+## Collision rule
+
+Where the extended hit area overlaps another interactive element, shrink the pseudo-element to the largest size that does not collide. Two interactive elements never have overlapping hit areas.
+
+## Decorative layers
+
+A decorative layer painted over interactive content absorbs every pointer event its box covers: a gradient scrim, a glow, a blurred sheen, a full-bleed `::after`. The control underneath looks live and does nothing, and no hit-area sizing fixes it.
+
+Give each one `pointer-events: none` (Tailwind `pointer-events-none`) so events reach the control below, plus `aria-hidden="true"` to keep it out of the accessibility tree:
+
+```css
+.card-glow {
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+}
+```
+
+Keep pointer events on any layer the user is meant to hit: a modal scrim that dismisses on click is a control, not decoration.
+
+## Touch behavior
+
+- Add `touch-action: manipulation` to interactive elements to remove the double-tap-to-zoom delay on mobile.
+- Set `touch-action: none` on a surface implementing its own pan, zoom, or drag gestures, so the browser stops claiming them for scrolling and pinch-zoom. Scope it to that surface; at page level it removes scrolling.
+- Set `-webkit-tap-highlight-color` to match the design instead of the default gray flash.
+- Put hover-only styling behind `@media (hover: hover)`. On touch, `:hover` latches after a tap and holds until the user taps elsewhere, so it reads as a stuck selected state. Tailwind 4's `hover:` variant already compiles under this query.
+- Prefer generous targets and clear affordances over finicky interactions such as tiny drag handles and precise hover zones.

package/skills/mejor-accesibilidad/motion-and-zoom.md

@@ -0,0 +1,79 @@
+# Motion and zoom
+
+`prefers-reduced-motion`, zoom and reflow, and unit choices that respect user settings.
+
+## prefers-reduced-motion
+
+Make motion opt-in. Wrap animations in `@media (prefers-reduced-motion: no-preference)` so users who asked for reduced motion get the static version by default, rather than you chasing every animation with an override.
+
+```css
+/* Good: motion is opt-in */
+.card {
+  /* static styles */
+}
+@media (prefers-reduced-motion: no-preference) {
+  .card {
+    transition: transform 200ms ease-out;
+  }
+}
+```
+
+```tsx
+// Tailwind: motion-safe / motion-reduce variants
+<div className="motion-safe:transition-transform motion-safe:hover:-translate-y-1" />
+```
+
+For an existing codebase where opt-in isn't feasible, the global kill switch is the fallback:
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+```
+
+`0.01ms` rather than `none`, so `animationend` and `transitionend` still fire and JS waiting on them doesn't hang.
+
+### What to disable vs reduce
+
+Reduced motion means reduced, not eliminated. It targets vestibular triggers, not feedback.
+
+| Disable entirely | Replace | Keep |
+| --- | --- | --- |
+| Parallax scrolling | Slide/scale/zoom transitions → opacity crossfade | Loading spinners and progress |
+| Autoplaying video, GIFs, looping decoration | Smooth scrolling → instant jump | Instant state changes (hover color, focus ring) |
+| Spinning, large-scale movement across the screen | Auto-rotating carousels → start paused | Brief functional feedback (button press) |
+
+Animations are interruptible and driven by user input. Nothing autoplays or refuses to stop, and under reduced motion carousels start paused.
+
+## Autoplay and timed UI
+
+Motion the user didn't ask for and UI acting on its own schedule:
+
+- **No autoplaying media without visible controls** (WCAG 2.2.2). Anything moving, blinking, or updating on its own for more than 5 seconds needs a visible pause or stop control, muted looping hero videos included.
+- **Prefer explicit dismissal over timers.** Auto-dismissal suits low-stakes confirmations and nothing else. A toast carrying an action, an error, or information the user may need stays until dismissed. Where one must time out, 5 seconds is the floor, and hovering or focusing it pauses the timer.
+- **Never put critical information only in a timed element.** A vanished toast with the only link to an undo action is data loss on a schedule.
+
+## Zoom and reflow
+
+- **200% zoom** (WCAG 1.4.4). All content and functionality survives text scaled to 200%, and the viewport leaves the reader able to zoom.
+- **Reflow at 320px** (WCAG 1.4.10). At 400% zoom on a 1280px viewport, equivalent to a 320px one, the page must work with vertical scrolling alone. Genuinely 2D content is the exception: tables, maps and code blocks scroll inside their own container.
+
+Fixed heights are what break under zoom. Use `min-height` on anything containing text and let containers grow.
+
+### rem vs px
+
+Respect how the codebase is set up. Where the project sizes in `px`, or on an established Tailwind scale, stay consistent and never introduce mixed units into someone else's system. Where you do have the choice, in new code or a codebase already on `rem`, `rem` respects the user's base font size and `px` ignores it:
+
+| Use `rem` | Use `px` |
+| --- | --- |
+| `font-size` | Borders and hairlines |
+| `max-width` of text containers | Focus outline width and offset |
+| Media-query breakpoints (`@media (min-width: 48rem)`) | `box-shadow` details |
+| Spacing that should scale with text | Fixed-size decorations |
+
+Breakpoints are where the choice matters most. At a larger base font size an `em` or `rem` query switches to the mobile layout when the text needs it, and a `px` query does not.

package/skills/mejor-accesibilidad/screen-readers.md

@@ -0,0 +1,101 @@
+# Screen readers
+
+Visually hidden content, live regions, toasts, alt text and SVG.
+
+## Visually hidden content
+
+The canonical `.sr-only` pattern hides content visually while keeping it in the accessibility tree:
+
+```css
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0 0 0 0);
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border: 0;
+}
+```
+
+Use `1px` boxes, not `0`, because some screen readers skip zero-sized elements. `white-space: nowrap` stops words being read as one run-together string. Never `display: none` or `visibility: hidden`, which remove the content from assistive tech entirely.
+
+Tailwind ships this as `sr-only`. Skip links add a focus variant that un-hides it, `focus:not-sr-only` or an override on `:focus`.
+
+Use it for context sighted users get visually: `<span class="sr-only">Opens in new tab</span>`, table captions, or an icon-only control's label where `aria-label` isn't an option.
+
+## Choosing how to announce a change
+
+Work down this list and stop at the first match:
+
+1. **Focus moves there anyway**, as with an opened modal or the first invalid field. Nothing extra needed; the focus move is the announcement.
+2. **Tied to a specific control**, such as a field error or character count: `aria-describedby` on the control, announced with the field.
+3. **Non-urgent, not tied to a control**, such as a toast, "Saved", a result count, or a loading state: a polite live region, `role="status"`.
+4. **Urgent and not tied to a control**, such as a form-level failure or session expiry: `role="alert"`.
+
+## Live regions
+
+Live regions announce content that changes without a page load: toasts, validation, search-result counts, loading states.
+
+| Mechanism | Politeness | Use for |
+| --- | --- | --- |
+| `role="status"` (= `aria-live="polite"` + `aria-atomic="true"`) | Waits for a pause | Toasts, "Saved", result counts, loading updates |
+| `role="alert"` (= `aria-live="assertive"` + `aria-atomic="true"`) | Interrupts immediately | Errors and urgent problems only |
+
+Rules for reliable announcements:
+
+- For repeated polite updates, keep a stable empty region in the DOM before changing its text. Inserting a new polite region with its content is announced inconsistently.
+- Dynamically inserted `role="alert"` content is usually announced, but behavior varies. Use it only for urgent errors not tied to a control, and test the target browser and screen-reader combinations.
+- Default to polite. Overusing `assertive` is the most common live-region mistake, because it interrupts whatever the user was reading.
+- Keep messages short and self-contained. `aria-atomic="true"` re-reads the whole region on change.
+- Never move focus to a toast. Announce it and leave focus where the user is working. Give toasts a generous timeout or a dismiss button, and never put the only path to an action inside an auto-dismissing one.
+
+```tsx
+// Region rendered from the start, message injected later
+<div role="status" className="sr-only">
+  {statusMessage}
+</div>
+```
+
+For loading states: set `aria-busy="true"` on the updating region, announce "Loading…" politely, then announce the outcome ("Loaded, 12 results").
+
+## aria-hidden
+
+`aria-hidden="true"` removes an element and its whole subtree from assistive tech. Use it for decorative icons and content duplicated for visual effect. Never put it on or above a focusable element, which creates stops you can Tab to that do not exist for a screen reader. Hiding something interactive means removing it from the tab order too.
+
+## Alt text
+
+Choose by purpose, not by what the image looks like:
+
+| Purpose | Alt | Example |
+| --- | --- | --- |
+| Decorative, or redundant with adjacent text | `alt=""` (empty, but present) | Logo next to the company name in text |
+| Informative | Describe the meaning it adds | `alt="Ticket QR code"` |
+| Functional (image is the link/button) | Describe the action or destination | Search icon → `alt="Search"`, not `alt="magnifying glass"` |
+| Image of text | The exact text (better: use real text) | `alt="50% off everything"` |
+| Complex (chart, diagram) | Short summary in `alt`, full data as a table or text nearby | `alt="Revenue by quarter, described below"` |
+
+A missing `alt` is worse than an empty one, because screen readers fall back to reading the file name.
+
+## SVG
+
+- Decorative SVG: `aria-hidden="true"` and `focusable="false"`, the latter for legacy Edge and IE tabbing. No title needed.
+- Meaningful inline SVG: `role="img"` plus `aria-label="…"`, or a `<title>` as the first child referenced by `aria-labelledby`.
+- Simple cases: `<img src="icon.svg" alt="…">` is the most reliable delivery.
+
+```tsx
+// Decorative icon inside a labeled button
+<button aria-label="Close">
+  <svg aria-hidden="true" focusable="false">…</svg>
+</button>
+
+// Standalone meaningful icon
+<svg role="img" aria-label="Verified account">…</svg>
+```
+
+## Video and audio
+
+Prerecorded video needs captions; provide transcripts for audio. Never autoplay with sound, and always render controls.