# Component QA Protocol

Aplica a `1-StudioLimb-Production-System-Native-Modes-RC-0.12.0.fig` y `2-StudioLimb-Production-System-Starter-Compat-RC-0.12.0.fig`. Ningún componente se marca `Approved` por inspección visual aislada: debe pasar structure, states, themes, responsive, content, accessibility y handoff.

## 1. Severidad y criterio de release

| Nivel | Definición | Ejemplos | Regla |
|---|---|---|---|
| P0 | Impide usar o recuperar el sistema. | Main component eliminado, library corrupta, archivo que no abre. | Bloquea release. |
| P1 | Produce UI incorrecta o inaccesible en un flujo principal. | Contraste insuficiente, focus ausente, variante rota, dark ilegible. | Bloquea release. |
| P2 | Degrada eficiencia o consistencia sin bloquear. | Layer naming incorrecto, descripción incompleta, wrap poco elegante. | Corregir o documentar antes de release. |
| P3 | Mejora deseable sin impacto funcional inmediato. | Más ejemplos, copy más natural. | Puede entrar al backlog. |

Una release requiere `0 P0`, `0 P1` y propietario/fecha para todo P2 aceptado.

## 2. Registro mínimo de una prueba

```text
Test ID:
Date / tester:
Distribution: Native Modes | Starter Compat
Figma version / OS:
Component and variant:
Theme: Light | Dark
Viewport: Desktop | Tablet | Mobile | Fluid width
Content fixture:
Expected:
Actual:
Severity:
Evidence link:
Owner / target release:
Status: Open | Fixed | Retest | Accepted
```

## 3. Quality gates universales

### A. Structure — `STR`

- [ ] `STR-01` Main component está únicamente en el área Components de `01 — Components, Patterns & Templates`.
- [ ] `STR-02` Nombre exacto `Category / Component`; no hay duplicados normalizados.
- [ ] `STR-03` Layers internos son semánticos; no existen `Frame 123`, `Rectangle`, `Group` o nombres generados.
- [ ] `STR-04` Auto Layout está activo en todos los contenedores que fluyen con contenido.
- [ ] `STR-05` `Hug`, `Fill` y `Fixed` corresponden a la intención documentada.
- [ ] `STR-06` No se usan grupos donde un frame con Auto Layout sea necesario.
- [ ] `STR-07` Las propiedades expuestas permiten editar label, iconos y visibilidad sin entrar en nested instances.
- [ ] `STR-08` Los iconos son nested instances; no vectores detached dentro de cada variante.
- [ ] `STR-09` No hay valores de color primitivo aplicados directamente a componentes.
- [ ] `STR-10` Spacing, radius, stroke y dimensiones repetidas están conectados a variables.
- [ ] `STR-11` Text layers usan text styles y `Auto height`, salvo truncamiento documentado.
- [ ] `STR-12` El bounding box no contiene capas invisibles accidentales ni hit areas incoherentes.

### B. Variants and properties — `VAR`

- [ ] `VAR-01` No hay combinaciones imposibles o duplicadas.
- [ ] `VAR-02` El orden de propiedades es `Type`, `Size`, `State`, booleanas y text props.
- [ ] `VAR-03` Valores usan lenguaje consistente (`Default`, no mezcla de `Normal`, `Rest`, `Base`).
- [ ] `VAR-04` Boolean props comienzan con verbo (`Show icon`).
- [ ] `VAR-05` Instance swap restringe preferred values al set correcto.
- [ ] `VAR-06` Un cambio de property no altera dimensiones sin que esté documentado.
- [ ] `VAR-07` Reset de overrides devuelve una instancia utilizable, no contenido placeholder roto.
- [ ] `VAR-08` Starter y Native tienen paridad visual y funcional.

### C. Themes — `THM`

- [ ] `THM-01` Light y dark cambian mediante mode o property, nunca con recolor manual.
- [ ] `THM-02` Canvas, surfaces y raised surfaces conservan jerarquía en ambos temas.
- [ ] `THM-03` Texto normal alcanza `4.5:1`; texto grande, `3:1`.
- [ ] `THM-04` Bordes, focus y símbolos esenciales alcanzan `3:1` contra colores adyacentes.
- [ ] `THM-05` Primary, danger y links se prueban en default, hover, pressed, focus y disabled.
- [ ] `THM-06` Success, warning, danger e info combinan icono/label con color.
- [ ] `THM-07` Disabled continúa legible pero no se confunde con enabled.
- [ ] `THM-08` Scrim separa overlay y fondo sin ocultar la ubicación del usuario.

### D. Responsive — `RSP`

- [ ] `RSP-01` Se prueba a 1440, 768 y 390 px.
- [ ] `RSP-02` Se prueban anchos intermedios 1024, 600 y 320 px; no aparecen saltos no documentados.
- [ ] `RSP-03` El contenido hace reflow o wrap antes de quedar cortado.
- [ ] `RSP-04` Min/max width impide columnas o dialogs inutilizables.
- [ ] `RSP-05` Orden visual y orden de foco continúan alineados tras reflow.
- [ ] `RSP-06` No se encogen targets interactivos por debajo de 44×44 en patrones táctiles.
- [ ] `RSP-07` Overflow horizontal solo existe donde es deliberado y está señalado.
- [ ] `RSP-08` Component swap conserva labels, estado y contenido relevante.

### E. Content — `CNT`

- [ ] `CNT-01` Label mínimo de dos caracteres.
- [ ] `CNT-02` Label largo de 40 caracteres.
- [ ] `CNT-03` Título de dos líneas y descripción de seis.
- [ ] `CNT-04` Valor vacío, `null`, restringido y borrado tienen representación distinta.
- [ ] `CNT-05` Números con 1, 4, 7 y 12 dígitos no rompen layout.
- [ ] `CNT-06` Inglés y español funcionan sin reducir font size.
- [ ] `CNT-07` Imagen faltante, vertical, horizontal y 1:1 respetan crop/fit documentado.
- [ ] `CNT-08` Error de campo y error global pueden coexistir.
- [ ] `CNT-09` Text resize/zoom de referencia a 200% no oculta acciones esenciales.

### F. Accessibility annotations — `A11Y`

- [ ] `A11Y-01` Todo control tiene accessible name visible o anotado.
- [ ] `A11Y-02` Focus visible tiene al menos 2 px y contraste `3:1`.
- [ ] `A11Y-03` Focus order está numerado en patterns y templates.
- [ ] `A11Y-04` Keyboard behavior está descrito para composites.
- [ ] `A11Y-05` Selected, expanded, checked, invalid y busy están anotados cuando aplican.
- [ ] `A11Y-06` Mensajes dinámicos indican `status`, `alert` o ninguna live region según urgencia.
- [ ] `A11Y-07` Error identifica campo, causa y forma de corregirlo.
- [ ] `A11Y-08` Icon-only controls tienen tooltip y nombre accesible; el tooltip no es el único nombre.
- [ ] `A11Y-09` Motion no es esencial y existe conducta reduced-motion.
- [ ] `A11Y-10` Anotaciones ARIA se presentan como recomendación a validar en código, no garantía automática.

### G. Handoff — `HOF`

- [ ] `HOF-01` Component description explica propósito y cuándo no usarlo.
- [ ] `HOF-02` Responsive behavior describe reflow, wrap, hide y swap.
- [ ] `HOF-03` Loading, empty, error, disabled y permission están especificados cuando aplican.
- [ ] `HOF-04` Web code syntax existe para variables relevantes.
- [ ] `HOF-05` Assets tienen formato, tamaño, nombre y densidad.
- [ ] `HOF-06` Acceptance criteria son observables, no “se ve bien”.
- [ ] `HOF-07` No quedan comments o decisiones abiertas al marcar Ready for Dev.
- [ ] `HOF-08` Un front-end reviewer explica el comportamiento sin ayuda del autor.

## 4. Matriz de cobertura por componente

Leyenda: `D` default, `H` hover, `P` pressed, `F` focus, `X` disabled, `L` loading, `E` empty/error según contexto, `S` selected/success, `O` open. Una celda marcada es obligatoria en light y dark. Los estados de interacción se prueban también como prototype cuando corresponda.

| # | Componente | D | H | P | F | X | L | E | S/O | Prueba específica |
|---:|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|---|
| 1 | Button | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |  |  | Loading conserva ancho y label accesible. |
| 2 | Icon Button | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |  |  | Hit area 44; tooltip y accessible name. |
| 3 | Link | ✓ | ✓ | ✓ | ✓ | ✓ |  |  |  | Se distingue sin depender solo de color. |
| 4 | Field | ✓ |  |  |  | ✓ |  | ✓ | ✓ | Help, error y success no cambian estructura. |
| 5 | Input | ✓ | ✓ |  | ✓ | ✓ |  | ✓ | ✓ | Empty, filled, read-only y autofill reference. |
| 6 | Textarea | ✓ | ✓ |  | ✓ | ✓ |  | ✓ |  | Counter y texto largo no colisionan. |
| 7 | Select | ✓ | ✓ |  | ✓ | ✓ |  | ✓ | O | Open usa Menu y conserva trigger focus. |
| 8 | Search | ✓ | ✓ |  | ✓ | ✓ | ✓ | ✓ |  | Clear solo con valor; loading no mueve layout. |
| 9 | Checkbox | ✓ | ✓ | ✓ | ✓ | ✓ |  | ✓ | ✓ | Unchecked, checked e indeterminate. |
| 10 | Radio | ✓ | ✓ | ✓ | ✓ | ✓ |  | ✓ | ✓ | Se valida dentro de grupo y con flechas. |
| 11 | Switch | ✓ | ✓ | ✓ | ✓ | ✓ |  |  | ✓ | Off/on visibles sin color; efecto inmediato. |
| 12 | Segmented Control | ✓ | ✓ |  | ✓ | ✓ |  |  | ✓ | 2, 3 y 4 items; un selected. |
| 13 | File Upload | ✓ |  |  | ✓ | ✓ | ✓ | ✓ | ✓ | Drag over, retry y remove preservan filename. |
| 14 | Breadcrumbs | ✓ | ✓ |  | ✓ |  |  |  |  | Current page no es enlace; collapse mobile. |
| 15 | Tabs | ✓ | ✓ |  | ✓ | ✓ |  |  | ✓ | Arrow keys, overflow y selected indicator. |
| 16 | Pagination | ✓ | ✓ |  | ✓ | ✓ |  |  | ✓ | First/last boundaries y mobile Simple. |
| 17 | Header | ✓ |  |  |  |  |  |  | O | Desktop/tablet/mobile content priority. |
| 18 | Sidebar | ✓ | ✓ |  | ✓ | ✓ |  |  | ✓ | Expanded/collapsed, tooltip y current item. |
| 19 | Mobile Nav | ✓ |  |  | ✓ |  |  |  | O | Focus trap, close y scroll lock anotados. |
| 20 | Avatar | ✓ |  |  |  |  | ✓ | ✓ | ✓ | Image, initials, icon y status. |
| 21 | Badge | ✓ |  |  |  |  |  |  |  | Seis tones y label largo. |
| 22 | Status | ✓ |  |  |  |  |  |  |  | Dot + label en seis tones. |
| 23 | Card | ✓ | ✓ |  | ✓ | ✓ |  |  | ✓ | Click target no compite con acciones internas. |
| 24 | List Item | ✓ | ✓ |  | ✓ | ✓ |  |  | ✓ | Leading/trailing y wrap de descripción. |
| 25 | Table | ✓ | ✓ |  | ✓ | ✓ | ✓ | ✓ | ✓ | Sort, selection, sticky header y mobile list. |
| 26 | Key Value | ✓ |  |  | ✓ |  | ✓ | ✓ |  | Long values, concealed y empty. |
| 27 | Alert | ✓ |  |  | ✓ |  |  | ✓ | ✓ | Tone, dismiss y live-region decision. |
| 28 | Toast | ✓ |  |  | ✓ |  | ✓ | ✓ | ✓ | Enter/exit, pause timeout y persistent error. |
| 29 | Progress | ✓ |  |  |  |  | ✓ | ✓ | ✓ | Indeterminate/determinate y reduced motion. |
| 30 | Skeleton | ✓ |  |  |  |  | ✓ |  |  | Structure match y reduced motion. |
| 31 | Empty State | ✓ |  |  | ✓ |  |  | ✓ |  | First use, no results, error, no access. |
| 32 | Dialog |  |  |  | ✓ | ✓ | ✓ | ✓ | O | Trap, Escape, focus return y mobile width. |
| 33 | Drawer |  |  |  | ✓ |  | ✓ |  | O | Internal scroll, persistent close y focus. |
| 34 | Menu | ✓ | ✓ |  | ✓ | ✓ |  |  | ✓ | Roving focus, keyboard, separator y danger. |
| 35 | Tooltip |  | ✓ |  | ✓ |  |  |  | O | Hover + focus; no essential action. |

## 5. Pruebas específicas de interacción

### Buttons and links

- [ ] El orden de énfasis Primary → Secondary → Tertiary es evidente en ambos themes.
- [ ] Danger no se usa para cancelación o navegación.
- [ ] Loading impide doble envío y no cambia el ancho del botón.
- [ ] Icon-only no depende del gráfico para comunicar el nombre.
- [ ] Un botón con label de 40 caracteres hace wrap o crece según regla documentada; nunca corta sin explicación.

### Fields

- [ ] Placeholder y label tienen roles visuales distintos.
- [ ] Required se comunica con texto/símbolo y la explicación del símbolo está disponible.
- [ ] Disabled y read-only no son visualmente idénticos.
- [ ] Error no sustituye el valor ingresado.
- [ ] Hint desaparece solo si el mensaje de error aporta la información necesaria.
- [ ] Focus ring no queda oculto por un contenedor con clipping.

### Selection controls

- [ ] Checkbox admite indeterminate; radio no.
- [ ] Radio group mantiene exactamente una selección cuando es requerido.
- [ ] Switch solo representa una preferencia de efecto inmediato.
- [ ] Estado checked/on es detectable en grayscale.
- [ ] Label completo activa el control en la especificación de implementación.

### Navigation

- [ ] Tabs, menu y radio groups tienen modelo de teclado diferente y correctamente anotado.
- [ ] El current item no depende solo del color.
- [ ] El foco no salta a elementos ocultos en collapsed/mobile.
- [ ] Navegación mobile conserva acceso a primary action y account controls.
- [ ] Breadcrumb collapse conserva inicio y current page.

### Table

- [ ] Header y celdas se alinean con contenido corto, largo y numérico.
- [ ] Sort indica dirección y columna con texto/semántica además de icono.
- [ ] Selection parcial activa checkbox indeterminate del header.
- [ ] Bulk action bar no cambia el contexto sin explicación.
- [ ] Loading conserva estructura; empty ocupa el área de resultados; error ofrece retry.
- [ ] Sticky header no oculta contenido enfocado.
- [ ] A 390 px se usa list pattern o scroll documentado, nunca shrink ilegible.

### Overlays

- [ ] Trigger → overlay → cierre → trigger conserva recorrido de foco.
- [ ] Escape cierra solo el overlay superior.
- [ ] Click outside no cierra una acción destructiva a medio completar sin confirmación.
- [ ] Dialog/Drawer tienen nombre visible y descripción cuando aporta contexto.
- [ ] Acciones continúan visibles cuando el contenido hace scroll.
- [ ] Tooltip se puede descartar y no bloquea contenido adyacente.

## 6. Matriz mínima de combinaciones

No es necesario renderizar el producto cartesiano completo. Usar pairwise coverage y estas combinaciones obligatorias:

| Suite | Theme | Viewport | Content | Estado |
|---|---|---|---|---|
| Baseline | Light | Desktop | Normal EN | Default |
| Dark interaction | Dark | Desktop | Normal EN | Hover/Focus/Pressed |
| Mobile stress | Light | Mobile | Long ES | Filled/Selected |
| Dark mobile error | Dark | Mobile | Error ES | Error/Retry |
| Tablet async | Light | Tablet | Loading | Loading/Empty/Success |
| Narrow fluid | Dark | 320 px | Long EN | Open/Overflow |
| Zoom reference | Light | 768 at 200% visual test | Long ES | Focus |
| Reduced motion | Both | Desktop + Mobile | Normal | Loading/Open/Toast |

Componentes de alto riesgo (`Input`, `Select`, `Checkbox`, `Tabs`, `Table`, `Dialog`, `Menu`) sí requieren todas las combinaciones theme × viewport relevantes.

## 7. Auditoría de tokens

- [ ] JSON pasa parse y validación estructural DTCG.
- [ ] Todo token tiene `$type` propio o heredado.
- [ ] Toda referencia `{path}` resuelve a un token existente y del mismo tipo.
- [ ] Todos los colors sRGB tienen tres componentes entre 0 y 1, alpha entre 0 y 1 y hex de seis dígitos.
- [ ] Dimensions usan `px`; durations usan `s` para compatibilidad de importación Figma.
- [ ] CSS contiene una custom property para cada token canónico.
- [ ] CSS no referencia custom properties inexistentes.
- [ ] `data-theme=light`, `data-theme=dark`, system dark y reduced motion producen valores definidos.
- [ ] No existen valores de color hard-coded dentro de componentes Figma.
- [ ] Code syntax web coincide con `tokens/design-tokens.css`.

## 8. Revisión final por rol

| Rol | Debe aprobar |
|---|---|
| Design-system specialist | Structure, variants, variables, descriptions y deprecation. |
| Product designer | Utilidad, patterns, content states y eficiencia de composición. |
| Front-end developer | Responsive, behavior, tokens CSS y acceptance criteria. |
| Accessibility reviewer | Contraste, focus, keyboard, status y annotations. |
| QA no autor | Starter parity, reset de overrides, stress suite y package integrity. |

Ningún autor puede ser el único aprobador de su propio componente.

## 9. Release checklist

- [ ] Ejecutar suites Universal, High-risk y Token audit.
- [ ] Revisar 35 component descriptions.
- [ ] Confirmar paridad en las dos distribuciones.
- [ ] Abrir una copia limpia del archivo; no probar solo el working file.
- [ ] Rebrandear brand color, font y radius en la copia limpia.
- [ ] Construir una pantalla nueva desde Assets, no copiando el template.
- [ ] Probar update/migration desde la versión anterior cuando exista.
- [ ] Eliminar componentes ocultos, assets sin uso y páginas temporales.
- [ ] Actualizar Cover, Start Here, Changelog y compatibility statement.
- [ ] Verificar enlaces de documentación, licencia y soporte.
- [ ] Exportar previews desde la release aprobada.
- [ ] Registrar versión, hash del paquete y aprobadores.
