@damiangilgonzalez/harness 1.3.7

package/skills/mejor-accesibilidad/semantics-and-aria.md

@@ -0,0 +1,84 @@
+# Semantics and ARIA
+
+Native elements first, landmarks, accessible names and the ARIA rules that keep custom widgets honest.
+
+## The rules of ARIA
+
+1. If a native HTML element with the semantics and behavior you need exists, use it instead of repurposing another element with ARIA.
+2. Don't change native semantics unless you really have to.
+3. Every interactive ARIA control must be keyboard-operable; a role is a promise of the full keyboard model, states and behavior.
+4. Never put `role="presentation"` or `aria-hidden="true"` on a focusable element.
+5. All interactive elements must have an accessible name.
+
+No ARIA is better than bad ARIA. A screen reader trusts your roles, so a wrong one is worse than none.
+
+## Button vs link vs div
+
+| Element | Use for | Why |
+| --- | --- | --- |
+| `<a href>` | Navigation: anything that goes somewhere or changes the URL | Free Cmd/Ctrl/middle-click, right-click → copy link, Enter activation |
+| `<button>` | Actions: submit, toggle, open, delete | Free focus, Enter *and* Space activation, form semantics |
+| `<div onClick>` | Nothing | No role, no focus, no keyboard; screen readers see plain text |
+
+```tsx
+// Bad: invisible to keyboard and screen readers
+<div onClick={openSettings}>Settings</div>
+
+// Good: focus, Enter/Space activation and semantics for free
+<button onClick={openSettings}>Settings</button>
+```
+
+If it looks clickable it must be clickable, and if it's clickable it must be a real interactive element. Rebuilding a link as a button, or the reverse, breaks user expectations. A "button" that navigates is a styled `<a>`.
+
+Where a native element is truly impossible, the full polyfill is `role="button"` plus `tabindex="0"` plus Enter and Space handlers, which is why the native element is always less code.
+
+## Landmarks and headings
+
+- Expose one visible primary `<main>` landmark. `<header>`, `<nav>`, `<aside>`, `<footer>` map to landmarks screen-reader users jump between.
+- Multiple landmarks of the same type need distinguishing labels: `<nav aria-label="Primary">`, `<nav aria-label="Breadcrumbs">`.
+- Do not report the one-`<h1>` or the no-skipped-levels convention as a standalone WCAG failure without a concrete navigation or comprehension impact. Headings are structure, not styling; style a heading level with CSS instead of picking the tag by size.
+- `<title>` matches the current context, most specific first: `Billing · Settings · Acme`.
+
+## Accessible names
+
+Name precedence: `aria-labelledby` > `aria-label` > native label (`<label>`, text content, `alt`) > `title` attribute.
+
+- Prefer visible text or `aria-labelledby` over `aria-label`, which is invisible, drifts out of sync with the UI and is handled inconsistently by translation tools.
+- Icon-only buttons always need a name: `<button aria-label="Close">` with the icon `aria-hidden="true"`.
+- WCAG 2.5.3 Label in Name: a button showing "Send" with `aria-label="Submit message"` breaks voice control users who say "click Send".
+- Accessible names must exist even when the design omits visible labels.
+
+```tsx
+// Good: name from visible text, icon hidden
+<button>
+  <TrashIcon aria-hidden="true" /> Delete
+</button>
+
+// Good: icon-only, explicit name
+<button aria-label="Delete">
+  <TrashIcon aria-hidden="true" />
+</button>
+```
+
+Add `translate="no"` to brand names, code tokens and identifiers so auto-translation doesn't garble them.
+
+## Common ARIA mistakes
+
+| Mistake | Why it fails |
+| --- | --- |
+| `aria-label` on a plain `<div>` or `<span>` | Most screen readers ignore names on non-interactive, role-less elements |
+| `<button role="button">` | Redundant role; adds noise, no benefit |
+| `aria-hidden="true"` on or above a focusable element | Creates elements you can Tab to but that don't exist for screen readers |
+| `aria-labelledby`/`aria-describedby` pointing at a missing ID | Silently produces no name or description |
+| `role="menu"` on a nav list | `menu` promises app-style arrow-key behavior; site navigation is `<nav>` with a list |
+
+## Disabled states
+
+Native `disabled` supplies the platform's complete disabled behavior. It removes the control from the tab order, suppresses activation, applies `:disabled` and excludes form controls from submission. Use it when a native control is genuinely unavailable. `aria-disabled="true"` only announces the state, changing neither focusability, nor behavior, nor styling.
+
+- Never disable submit buttons. Keep them enabled, validate on submit and focus the first error ([forms.md](forms.md)).
+- A natively `disabled` control suppresses pointer events and leaves the tab order, so a tooltip on it never opens for keyboard or touch users and is unreliable for mouse users. Put the reason in visible text beside the control, or switch to `aria-disabled="true"`, which keeps it focusable and hoverable and can carry a tooltip.
+- Use `aria-disabled="true"` where keeping a control discoverable in the tab order is intentional, or where a custom control cannot use native `disabled`.
+- With `aria-disabled="true"`, block pointer and keyboard activation in the handler, prevent form submission where applicable, add explicit styling including forced-colors support and explain nearby why the action is unavailable.
+- Never set both `disabled` and `aria-disabled` on the same element.
+- Disabled controls are exempt from contrast minimums. Keep them legible anyway.

package/skills/mejor-colores/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: mejor-colores
+description: "Use to build a color system or answer anything about color in the project — generating palettes, using semantic tokens, converting between formats, measuring contrast, choosing a gradient's interpolation space, and setting up dark mode."
+tags: ["color", "design-tokens", "contrast", "dark-mode"]
+profiles: [ui, full]
+---
+
+# Colores
+
+Un sistema de color es un conjunto pequeno de rampas, nombradas por rol y verificadas contra los fondos sobre los que se renderizan de verdad. La mayoria de los fallos de color son fallos de sistema: un valor elegido aislado, un token tomado prestado porque quedaba bien, un par que nadie midio.
+
+Nunca reportes un valor de contraste que no mediste, y nunca estimes un color que puedes calcular. El color es una de las pocas cuestiones de interfaz con respuesta exacta, asi que produce la respuesta exacta.
+
+Los requisitos de contraste son de `mejor-accesibilidad`. Superficies, sombras y color de iconos son de `mejor-ui`.
+
+## Adáptate al sistema de color del proyecto
+
+Reutiliza los tokens y la notacion del proyecto. Una segunda representacion anadida para arreglar un valor hace la paleta mas dificil de razonar. Un sistema consistente en hex vale mas que hex con `oklch()` desperdigado.
+
+Para un sistema nuevo, `oklch()` es el mejor defecto, porque sus numeros se comportan como describen las reglas de rampa de abajo. En cualquier otro caso, una libreria de color produce la misma rampa en la notacion del propio proyecto ([color-formats.md](color-formats.md)).
+
+## Un sistema son rampas, no colores
+
+Una rampa neutra, una rampa de acento y solo las rampas de estado que el producto renderiza de verdad. Una rampa `warning` que nadie importa es mantenimiento por cero pixeles. Un segundo tono de acento se gana su sitio solo cuando dos cosas deben distinguirse de un vistazo.
+
+## Cada paso tiene un trabajo
+
+Una rampa no es un degradado del que elegir a ojo. Cada paso existe porque un rol lo necesita: fondo de pagina, hover de componente, borde, relleno solido, texto de cuerpo. No generes un paso que ningun rol consume. Tanto la convencion `50`-`950` de Tailwind como la `1`-`12` de Radix mapean a esos roles ([palette-structure.md](palette-structure.md)).
+
+## Nombra las primitivas por tono y las semanticas por rol
+
+Las primitivas nombran un valor (`--blue-500`) y nunca se aplican en un componente. Los tokens semanticos nombran un trabajo (`--color-text-secondary`), apuntan a una primitiva y son la unica capa que referencian los componentes.
+
+Esa costura es lo que hace posible el theming. Sin ella, el modo oscuro significa auditar cada uso para deducir cual queria decir "el acento" y cual solo queria azul ([token-naming.md](token-naming.md)).
+
+## Usa un token solo en su rol
+
+Nunca tomes prestado un token porque su valor sea el correcto hoy. Un separador usado como color de texto funciona hasta que los bordes se aclaran, y entonces el texto se va con ellos. Si un rol no tiene token, anade el token.
+
+## Manten el tono a lo largo de la rampa
+
+Cuatro propiedades definen una rampa bien formada:
+
+- Los pasos avanzan de forma pareja en luminosidad *percibida*, no en lo que el formato llame luminosidad.
+- El tono se mantiene constante de punta a punta.
+- La viveza tiene su pico a mitad de rampa y cae en los dos extremos.
+- Los pasos van mas densos en el extremo claro que en el oscuro.
+
+Ambos extremos se quedan cortos del negro y el blanco puros, que no pueden llevar tono. Usa una libreria de color en vez de hacerlo a ojo ([palette-generation.md](palette-generation.md)).
+
+## Un color, un significado
+
+Usa un color para un unico proposito en toda la interfaz, tratando como el mismo color cualquier cosa dentro de `15°` de tono. Si el acento significa "interactivo", ese tono sobre texto estatico le dice al usuario que pulse algo que no es pulsable, y un elemento interactivo renderizado en neutro engana igual de mal. El color nunca es el unico portador de significado, cosa que posee `mejor-accesibilidad`.
+
+## Rellena exactamente una accion por vista
+
+Cuando el color de relleno codifica el enfasis principal, una sola accion primaria lo recibe y sus pares se quedan neutras. Pon el color en el fondo, no en la etiqueta. Un boton relleno se lee como primario desde el otro lado de la sala; texto en color de acento sobre un boton neutro se lee como un enlace.
+
+Varios fondos de color estan bien cuando codifican estados o categorias distintas en vez de competir como iguales.
+
+## Mide el par renderizado y luego reporta
+
+Mide un primer plano contra el fondo sobre el que se renderiza de verdad, no contra el fondo de la pagina. Cuando un par falla, reporta el par, su valor medido y el umbral que no alcanza, y luego deja los colores en paz. Son una decision de diseno. Cambialos solo cuando te lo pidan, y vuelve a medir despues ([contrast.md](contrast.md)).
+
+## Elige el espacio de interpolacion de un degradado
+
+El espacio es un look, no un ajuste de correccion.
+
+- **`in oklab`** es el mejor defecto: brillo parejo, sin sorpresas de tono.
+- **`in oklch`** viaja por la rueda de tonos en vez de por el centro, manteniendose vivo y barriendo todos los tonos entre las paradas. Cógelo cuando un degradado de dos tonos se vuelve gris por el medio.
+- **El sRGB por defecto** oscurece y apaga el punto medio. Es lo que ya tienen casi todas las interfaces, porque es lo que sale sin pedir nada.
+
+Ver [color-usage.md](color-usage.md).
+
+## Antes de terminar
+
+| Error | Arreglo |
+| --- | --- |
+| Un valor crudo donde el proyecto tiene un token | Reutiliza o anade el token de rol, en la notacion del proyecto |
+| Un `oklch()` suelto metido en un codebase de hex | Manten la notacion establecida salvo que la migracion este en el alcance |
+| Una primitiva como `--blue-500` usada directamente en un componente | Apunta un token semantico a ella |
+| Token nombrado por su apariencia (`--color-blue-button`) o por su primer uso (`--color-sidebar-gray`) | Nombralo por su rol: `--color-accent-solid`, `--color-bg-surface` |
+| `--color-primary` significando la marca y `--color-text-primary` significando texto de cuerpo | Reserva `accent` para la marca; deja que `primary` signifique "el mas prominente de su grupo" |
+| Token semantico usado fuera de su rol (separador como texto) | Anade un token para el rol que falta; nunca tomes prestado por valor |
+| Rampa construida variando la luminosidad HSL | Reconstruyela contra luminosidad percibida con tono constante |
+| Rampa espaciada uniformemente en todo el rango | Aprieta el extremo claro hasta que `50` y `100` se lean como dos superficies |
+| El mismo numero de saturacion reutilizado entre tonos | Iguala la proporcion del maximo de cada tono, no el valor crudo |
+| Tono de estado que choca con el tono de acento | Muevelo hasta que destructivo y primario se lean distintos uno al lado del otro |
+| Modo oscuro hecho invirtiendo mecanicamente la paleta clara | Invierte como punto de partida, luego reduce viveza, ensancha el extremo oscuro y revisa cada par |
+| `prefers-color-scheme` fijando unos tokens y una clase `.dark` fijando otros | Elige un unico mecanismo de conmutacion y usalo en todo |
+| Contraste arreglado cambiando el tono | Cambia la luminosidad, que es el canal al que responde el contraste |
+| Color P3 sin respaldo sRGB | Declara el valor sRGB primero y sobreescríbelo dentro de `@media (color-gamut: p3)` |
+
+## Como reportar
+
+**Severidad.** `ALTA` hace el contenido ilegible o asigna un color semantico enganoso. `MEDIA` es un fallo apreciable de tema, token o gama. `BAJA` es pulido aislado.
+
+**Verificacion.** Sin navegador: valores de token, gama de cada color declarado, presencia de ambos bloques de tema y contraste calculado desde el par de tokens declarado. Con navegador: el fondo realmente renderizado tras el texto, incluida la opacidad y cualquier imagen debajo, medido en claro y en oscuro. Un par que falla se reporta, no se repinta. 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 color" y reporta la verificacion.

package/skills/mejor-colores/color-formats.md

@@ -0,0 +1,90 @@
+# Color formats
+
+Which notation to write colors in, how to convert between them and what happens at the edges of a display's gamut. Every other rule in this skill is stated perceptually and holds whatever notation you write.
+
+## Choosing a notation
+
+| Notation | Good for | Weakness |
+| --- | --- | --- |
+| Hex | Universal support, compact, what design tools hand you | Opaque. No channel is readable or editable by hand |
+| `rgb()` | Same reach as hex, readable alpha | Channels do not correspond to anything a designer thinks about |
+| `hsl()` | Channels look like design controls | Its lightness is not perceptual and its hue drifts; a ramp built by varying lightness bunches at one end and shifts hue |
+| `oklch()` | Perceptually uniform lightness, stable hue, predictable ramps | Baseline 2023, so very old browser matrices need a fallback |
+
+**Match whatever the project already uses.** Notation is not a defect: a project on hex is not doing it wrong.
+
+**For a genuinely new color system, `oklch()` is the best default.** Even lightness steps stay even, and a fixed hue stays fixed. See [palette-generation.md](palette-generation.md).
+
+```css
+oklch(L C H)          /* lightness 0–1, chroma 0–~0.4, hue 0–360 */
+oklch(L C H / alpha)  /* alpha uses a slash, never a comma */
+```
+
+## Converting
+
+Convert when the user asks, when an agreed migration is in scope, or when the project is standardizing on a notation and this value is the straggler. Never convert an isolated value in a project that deliberately uses something else and never because this skill happened to load.
+
+When conversion is in scope, change the values and nothing else:
+
+- Leave CSS keywords alone: `currentColor`, `inherit`, `transparent`, `initial`, `unset`.
+- Leave gradient functions alone. Convert the color stops inside them; do not touch the interpolation method.
+- Leave colors in third-party configs that expect a specific format.
+- Preserve comments and formatting.
+
+```css
+/* Before */
+color: #3b82f6;
+border: 1px solid rgba(0, 0, 0, 0.1);
+
+/* After */
+color: oklch(0.623 0.188 259.815);
+border: 1px solid oklch(0 0 0 / 0.1);
+```
+
+Bulk conversion is a migration, not cleanup. It shifts every rendered color by a rounding margin and touches files nobody asked about, so it has to be the task rather than a side effect.
+
+## Gamut
+
+Every sRGB color exists in Display P3, but not the reverse. P3 covers roughly 50% more colors, which matters only for the most saturated values. A color at 60% of maximum vividness looks the same on both.
+
+A color more vivid than its display can render gets clipped, and clipping is not graceful. It flattens neighbouring steps into one rendered color, so the top of a ramp can lose its distinctions on an sRGB screen. Maximum vividness varies by hue and lightness. Cyans top out far lower than reds and purples, so a clipping ramp clips at some steps and not others.
+
+The fix is to reduce vividness while holding hue and lightness. Generate ramps against sRGB unless the product is display-restricted, and add P3 as an enhancement:
+
+```css
+.accent {
+  background: #3b82f6;
+}
+
+@media (color-gamut: p3) {
+  .accent {
+    background: oklch(0.62 0.24 259);
+  }
+}
+```
+
+Order matters. The sRGB value comes first so every display gets something, and the P3 rule overrides only where it will render. A P3 color with no fallback is a `HIGH` finding; it does not degrade, it fails.
+
+For browser matrices predating `oklch()` support, the same layering works with `@supports`:
+
+```css
+.accent {
+  background: #3b82f6;
+}
+
+@supports (color: oklch(0 0 0)) {
+  .accent {
+    background: oklch(0.62 0.19 259);
+  }
+}
+```
+
+Check the project's actual browser matrix before adding this. On a modern baseline it is dead weight.
+
+## Modern CSS worth knowing
+
+- **`color-mix()`** derives one color from another, as in `color-mix(in oklab, var(--color-accent-solid) 15%, white)` for a tinted background. Useful for states, but keep generated values out of the token layer, since a mixed color cannot be inspected in a design tool.
+- **Relative color syntax** adjusts one channel of an existing color. `oklch(from var(--color-accent-solid) calc(l - 0.1) c h)` darkens the accent by hand. Powerful and easy to overuse, since a token defined by three chained derivations is unreadable.
+- **`light-dark()`** puts both appearances in one declaration. See [palette-generation.md](palette-generation.md).
+
+All three compute at render time, so their output cannot be contrast-checked statically. Measure the rendered result.

package/skills/mejor-colores/color-usage.md

@@ -0,0 +1,118 @@
+# Color usage
+
+Deploying color once the system exists: meaning, emphasis, gradients and appearance variants. For picking values see [palette-generation.md](palette-generation.md), for naming them [token-naming.md](token-naming.md), for checking pairs [contrast.md](contrast.md).
+
+## One color, one meaning
+
+Users read a near-miss in hue as a slightly different shade, not as a different color.
+
+```css
+/* Bad: the accent means both "link" and "decorative heading" */
+a { color: #3b82f6; }
+.section-title { color: #4f8ef7; }
+
+/* Good: interactive elements own the accent; headings stay neutral */
+a { color: var(--color-accent-text); }
+.section-title { color: var(--color-text-primary); }
+```
+
+The rule runs both ways. A color must not be *absent* where its meaning occurs. If the accent means interactive, an interactive element rendered neutral is just as misleading.
+
+Color is never the only carrier of meaning. Pair it with an icon, a label, or a shape. `better-accessibility` owns that requirement.
+
+## Use tokens in their role
+
+Apply a semantic token only for the role it names. `--color-text-secondary` is muted foreground text. Use it as a background and every future theme change that assumes the role breaks, because a value that happened to work as both stops working as both.
+
+```css
+/* Bad: separator token repurposed as a text color because it looked right */
+.caption { color: var(--color-border); }
+
+/* Bad: text token repurposed as a background */
+.tag { background: var(--color-text-secondary); }
+```
+
+The role inventory in [token-naming.md](token-naming.md) is the list of roles a system needs.
+
+## One colored action per view
+
+Preserve an established component hierarchy that communicates emphasis another way. Do not recolor controls merely to impose this recipe.
+
+```html
+<!-- Good: one filled primary action, neutral secondaries -->
+<button class="bg-accent-solid text-white">Save</button>
+<button class="text-neutral-700">Cancel</button>
+
+<!-- Bad: every action colored, so nothing is primary -->
+<button class="bg-accent-solid text-white">Save</button>
+<button class="bg-accent-solid text-white">Duplicate</button>
+<button class="bg-accent-solid text-white">Export</button>
+```
+
+Selected states may use the accent on the glyph and label. An active tab or a checked segment is state, not emphasis.
+
+## Gradients
+
+**The interpolation space is a look, not a correctness setting.** Three are worth knowing, and the difference between them is most visible in the middle of the gradient:
+
+```css
+/* sRGB: the default and the classic. Midpoint darkens and mutes. */
+background: linear-gradient(#3b82f6, #ec4899);
+
+/* oklab: even brightness across the transition. The best default. */
+background: linear-gradient(in oklab, #3b82f6, #ec4899);
+
+/* oklch: travels around the hue wheel, staying vivid throughout. */
+background: linear-gradient(in oklch, #3b82f6, #ec4899);
+```
+
+`oklab` and sRGB are **rectangular**, interpolating in a straight line through the color space. `oklch` is **polar**, interpolating the hue angle, so it arcs around the wheel through every hue between the stops. That is why it stays saturated and why it can produce hues nobody asked for. A blue-to-pink gradient routes through purple, which is either the look or a surprise.
+
+**The gray dead zone is a rectangular-space problem.** Two hues on opposite sides of the wheel sit either side of the neutral axis. A straight line between them passes near gray, and the middle goes lifeless. Either switch to a polar space, which routes around the axis, or add a third stop between the two and keep the space you have.
+
+With a polar space you also control which way it goes around:
+
+```css
+/* The short way round, usually what you want */
+background: linear-gradient(in oklch shorter hue, #3b82f6, #ec4899);
+
+/* The long way, sweeps most of the spectrum */
+background: linear-gradient(in oklch longer hue, #3b82f6, #ec4899);
+```
+
+**Banding shows up on large areas.** A gradient spanning a hero with little contrast between its stops steps visibly on 8-bit displays. Widen the contrast, shrink the area, or overlay a subtle noise texture.
+
+**Keep text off gradients where you can.** Contrast varies continuously across one, so a single measurement does not describe it. Where text must sit on a gradient, measure the worst region rather than the average, or put a scrim behind it.
+
+## Color across cultures
+
+Color meaning is not universal. Where a color is load-bearing in finance, status, or alerts, verify the meaning holds in every locale you ship to.
+
+| Color | Common Western reading | Elsewhere |
+| --- | --- | --- |
+| Red | Danger, loss, errors | Luck, prosperity; **gains** in Chinese financial UIs |
+| Green | Success, gains, go | Losses in Chinese financial UIs |
+| White | Purity, cleanliness | Mourning in parts of East Asia |
+| Gold | Premium, luxury | Religious significance in some regions |
+
+The classic case is stock tickers, which show gains in green for English locales and red for Chinese ones. Where the product ships to such markets, make gain and loss per-locale tokens rather than hardcoded values.
+
+## Light, dark and increased contrast
+
+Every custom color needs a light and a dark variant, derived per [palette-generation.md](palette-generation.md). Beyond that, users who enable increased contrast expect visibly stronger differentiation:
+
+```css
+:root {
+  --color-accent-solid: #3b82f6;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root { --color-accent-solid: #60a5fa; }
+}
+
+@media (prefers-contrast: more) {
+  :root { --color-accent-solid: #1d4ed8; }
+}
+```
+
+The increased-contrast variant widens the foreground/background gap by at least 15 points of perceived lightness over the default. Re-verify against APCA's preferred thresholds, Lc 90 body and Lc 75 non-body. Widening the gap without remeasuring is not fixing it.

package/skills/mejor-colores/contrast.md

@@ -0,0 +1,79 @@
+# Contrast
+
+Contrast is measured between a **foreground color**, meaning text, an icon, or a UI element, and the **background color** it actually renders against, usually the nearest ancestor that paints one. Identify that background first. Measuring against the page background when the element sits on a card gives the wrong answer.
+
+**Report, don't repaint.** When a check fails, report the pair, its measured value and the threshold it misses, and leave the colors unchanged. They are a design decision. Apply the fix below only when asked.
+
+`better-accessibility` decides when contrast is required and whether a given pair must pass. This file covers measuring the pair and, on request, changing it.
+
+## APCA thresholds (recommended)
+
+APCA (Accessible Perceptual Contrast Algorithm) models perceived contrast more accurately than WCAG 2 and is the better default for design decisions. Lc (Lightness Contrast) measures perceived contrast between foreground and background. These levels simplify APCA's full font-size and weight lookup table:
+
+| Content type | Minimum | Preferred |
+| --- | --- | --- |
+| Body text (columns or blocks of text) | Lc 75 | Lc 90 |
+| Non-body text (labels, headlines) | Lc 60 | Lc 75 |
+| Large text (≥36px) | Lc 45 | Lc 60 |
+| UI components | Lc 30 | n/a |
+
+Lc 30 is also APCA's minimum for disabled and placeholder text. The floor for a non-text element to be discernible at all is Lc 15.
+
+Lc is signed: positive means dark text on a light background, negative means light text on a dark background. Compare the absolute value against the threshold.
+
+## WCAG 2 thresholds (for legal compliance)
+
+WCAG 2 is still required for formal WCAG 2.x conformance claims. Its luminance ratio is both too strict and too lenient depending on the pair, but it has the legal standing.
+
+| Content type | AA | AAA |
+| --- | --- | --- |
+| Normal text (<24px / <18.5px bold) | 4.5:1 | 7:1 |
+| Large text (≥24px / ≥18.5px bold) | 3:1 | 4.5:1 |
+| UI components and graphical objects | 3:1 | n/a |
+
+WCAG defines large text in points: 18pt ≈ `24px`, 14pt bold ≈ `18.5px`.
+
+When a project must claim WCAG conformance, WCAG is the gate and APCA is the tiebreaker for anything above it.
+
+## Fixing a failing pair (on request)
+
+**Change lightness first.** It is the channel contrast responds to. Hue and saturation move the measured value far less, so fixing contrast by changing hue is wasted effort.
+
+Move the foreground away from the background in perceived lightness, holding hue and saturation, then remeasure. Keeping hue fixed is what stops a contrast fix becoming a palette change.
+
+```css
+/* Failing: text too close to its background in lightness (Lc ≈ 50) */
+color: #7d93b0;
+background: #eef2f7;
+
+/* Fixed: darker text, same hue (Lc ≈ 90) */
+color: #2b3a4f;
+background: #eef2f7;
+```
+
+Two constraints on the fix:
+
+- **Mid-lightness backgrounds cap what is achievable.** On a background near 75% perceived lightness, even pure black text reaches only about Lc 60. Body text needs a background near one extreme, so a mid-range background is the thing that has to change.
+- **Pushing lightness can push the color out of gamut.** Reduce saturation as needed to keep it renderable. See [color-formats.md](color-formats.md).
+
+Always remeasure after changing a value. Do not assume a fix landed.
+
+## Quick approximations
+
+Useful for a first pass and approximations. Verify by measuring before reporting a result.
+
+For body text targeting |Lc| ≥ 75:
+
+- **Light background (above ~90% perceived lightness):** foreground below ~35%.
+- **Dark background (below ~25% perceived lightness):** foreground above ~90%.
+
+The gap is asymmetric because APCA is polarity-aware. Mirrored pairs do not score identically, which is why a pair passing in light mode can fail in dark.
+
+**Light or dark background?** The crossover is around 73% perceived lightness. Above it use dark text; at or below it light text scores higher. That is higher than intuition suggests. Between roughly 60% and 73% the background already looks light, yet white text still measures meaningfully better than black.
+
+## What to check
+
+- **Every pair, in every appearance.** A pair passing in light mode can fail in dark. The palettes are not mirror images.
+- **Translucent surfaces.** A color on a `backdrop-filter` header or an overlay shifts with whatever scrolls behind it. Test against the lightest and darkest content it can sit over, or make the surface opaque enough that the shift cannot break the pair.
+- **Computed colors.** `color-mix()`, relative color syntax and opacity modifiers resolve at render time; measure the rendered result, not the declaration.
+- **Text over images.** There is no single background color. Measure the worst region, or guarantee one with a scrim.

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

@@ -0,0 +1,32 @@
+skill: mejor-colores
+
+should_trigger:
+  - prompt: "Genera la paleta de colores de este sistema de diseno."
+    why: "Disparador directo de mejor-colores."
+  - prompt: "Necesito tokens semanticos de color para modo claro y oscuro."
+    why: "Disparador directo de mejor-colores."
+  - prompt: "Mide el contraste de este texto sobre este fondo."
+    why: "Disparador directo de mejor-colores."
+  - prompt: "Build a color system with semantic tokens and check contrast ratios."
+    why: "Disparador directo de mejor-colores."
+  - prompt: "Elige el espacio de interpolacion de este degradado."
+    why: "Disparador directo de mejor-colores."
+
+should_not_trigger:
+  - prompt: "Revisa el soporte de teclado de este formulario."
+    route_to: "mejor-accesibilidad"
+    why: "Revisar el soporte de teclado es el trabajo de mejor-accesibilidad, no de mejor-colores."
+  - prompt: "Escribe el copy de este mensaje de error."
+    route_to: "mejor-redaccion"
+    why: "Escribir el copy de un mensaje de error es el trabajo de mejor-redaccion, no de mejor-colores."
+  - prompt: "Anade una transicion al abrir este menu."
+    route_to: "animar"
+    why: "Anadir una transicion es el trabajo de animar, no de mejor-colores."
+  - prompt: "Ajusta el interlineado de este parrafo."
+    route_to: "mejor-tipografia"
+    why: "Ajustar el interlineado es el trabajo de mejor-tipografia, no de mejor-colores."
+
+capability:
+  - scenario: "El usuario construye o pregunta sobre un sistema de color."
+    must_include:
+      - "contraste"

package/skills/mejor-colores/palette-generation.md

@@ -0,0 +1,104 @@
+# Palette generation
+
+Producing the values once the structure is decided. For which ramps to build and what each step is for, see [palette-structure.md](palette-structure.md).
+
+## Start from the brand color
+
+A brand color arrives as one value, usually a hex. Two decisions come before any ramp exists:
+
+**Which step does it occupy?** A brand color meant for buttons and links belongs on the solid-fill step: `500` in Tailwind, `9` in Radix. Then `bg-brand-500` renders the actual brand color, not an approximation.
+
+**Is it pinned or snapped?** Pin a contractually fixed brand color. It stays exact, the ramp builds outward from it and that one step spaces slightly unevenly. Otherwise snap it onto the ramp so every step spaces evenly. That looks better almost always, and nobody notices without a swatch held to the screen.
+
+A brand color that fails contrast behind white text is still the brand color, just not the solid-fill step. Put it where it lands and use a darker step for interactive fills. Never quietly darken the brand.
+
+## What a correct ramp looks like
+
+Properties of the finished ramp, checkable against any output in any notation:
+
+- **Steps are evenly spaced in perceived lightness.** Not in the number your format calls "lightness". HSL's is not perceptual, and evenly spaced HSL values bunch at one end.
+- **Hue is constant end to end.** Every step is recognisably the same color. A wandering hue reads as two colors blended and will not sit correctly against a neutral built on a different hue.
+- **Vividness peaks in the middle and falls off at both ends.** The lightest and darkest steps are nearly neutral; the middle carries the color. Holding full vividness into the extremes gives a `50` that glows and a `950` like ink spilled on the brand.
+- **Steps are denser at the light end.** Light backgrounds need finer distinctions than dark ones. Keep `50` to `200` close together and `800` to `950` further apart. Even spacing across the whole range makes the pale end unusable, because `50` and `100` stop reading as two surfaces.
+- **No two adjacent steps are indistinguishable.** If `200` and `300` look identical on a calibrated screen, the ramp has more steps than decisions. Drop one.
+- **Both ends stop short of pure black and white.** A ramp that reaches them loses its identity exactly where the page background lives.
+
+## Use a color library
+
+Never compute these by hand or by eye. `culori`, `colorjs.io` and `chroma.js` all convert between notations, measure perceived lightness and interpolate perceptually. Read the brand color in whatever format it arrives, do the math in a perceptual space and emit the project's notation:
+
+```js
+import { formatHex, interpolate, samples } from 'culori'
+
+// Perceptual interpolation, hex in and hex out.
+const ramp = interpolate(['#eff6ff', '#3b82f6', '#172554'], 'lab')
+const steps = samples(11).map((t) => formatHex(ramp(t)))
+```
+
+The output format is the project's choice. For a ramp the interpolation space is not, because the steps have to land evenly in perceived lightness and sRGB interpolation produces muddy mid-steps. Decorative gradients are the opposite case, where the space is a deliberate look ([color-usage.md](color-usage.md)).
+
+```css
+:root {
+  --brand-50: #eff6ff;
+  --brand-100: #dbeafe;
+  --brand-200: #bfdbfe;
+  --brand-300: #93c5fd;
+  --brand-400: #60a5fa;
+  --brand-500: #3b82f6;
+  --brand-600: #2563eb;
+  --brand-700: #1d4ed8;
+  --brand-800: #1e40af;
+  --brand-900: #1e3a8a;
+  --brand-950: #172554;
+}
+```
+
+## Several hues at once
+
+With an accent plus status ramps, the ramps must agree step for step. `danger-500` and `brand-500` should read as equally bright and vivid, or a red button looks heavier than a blue one at the same step.
+
+- **Match perceived lightness exactly.** Same step, same brightness, across every hue.
+- **Match vividness relatively, not absolutely.** Hues do not share a maximum vividness. A saturated yellow and a saturated blue are not equally far from gray, and no format makes them so. Set each ramp to the same *proportion* of what its own hue reaches. Copying a saturation number across hues leaves one washed out.
+
+Yellows and cyans are the usual casualties, peaking much lower than reds and blues. Copy the numbers across and the warning color looks weak beside the danger one.
+
+## Dark mode
+
+A dark palette is not the light one reversed. Reversal is the starting point, not the output.
+
+Swap the semantic roles first, then tune the values:
+
+```css
+:root {
+  --color-bg: var(--brand-50);
+  --color-text: var(--brand-950);
+}
+
+.dark {
+  --color-bg: var(--brand-950);
+  --color-text: var(--brand-50);
+}
+```
+
+Three things almost always need hand-tuning after the swap:
+
+- **Vividness comes down.** A color that reads as confident on white reads as neon on near-black. Dark appearances need the accent a step or two less vivid.
+- **The dark end needs more separation.** Steps distinguishable as pale backgrounds collapse into each other as dark surfaces.
+- **Contrast does not survive the mirror.** A pair passing in light mode can fail reversed, because contrast is not symmetric. Recheck every foreground against its real background in both appearances ([contrast.md](contrast.md)).
+
+### Choosing the switching mechanism
+
+Pick one and use it throughout:
+
+- **`prefers-color-scheme` alone** is correct with no theme toggle. Nothing to persist, nothing to hydrate.
+- **A `.dark` class** is required as soon as users can override the system setting. The media query then sets only the initial value.
+- **`light-dark()`** collapses both values into one declaration, the least code when the project also sets `color-scheme`. It reads that property rather than a class, so a class-based toggle must set `color-scheme` too.
+
+```css
+:root {
+  color-scheme: light dark;
+  --color-bg: light-dark(#ffffff, #172554);
+}
+```
+
+Mixing mechanisms is the common failure. A media query setting some tokens and a class setting others gives a half-themed interface the moment a user overrides their system preference.