@damiangilgonzalez/harness 1.3.7

package/skills/mejor-tipografia/spacing-and-sizing.md

@@ -0,0 +1,121 @@
+# Spacing and sizing
+
+A sensible scale and comfortable spacing do more for typography than any effect.
+
+## Units
+
+| Unit | Behavior |
+| --- | --- |
+| `px` | Fixed |
+| `em` | Scales with the current font size |
+| `rem` | Scales with the root font size |
+| `%` on `font-size` | Relative to the parent's font size, behaves like `em` |
+
+## Type scale
+
+A small set of sizes used across a product, deviated from as little as possible. Hard-coding sizes with no system behind them breaks down at scale.
+
+```css
+:root {
+  --text-sm: 0.875rem;
+  --text-base: 1rem;
+  --text-lg: 1.125rem;
+  --text-xl: 1.5rem;
+  --text-2xl: 2rem;
+}
+```
+
+Pick an existing scale or define one. Tailwind's (`text-xs` through `text-9xl`, each class pairing a size with a matching line height) is a solid ready-made choice.
+
+Solo, the default names work fine given clear rules for where each size is used. On a team, name sizes semantically. `text-sm` tells you the size but not the use, where `text-body-sm` carries both.
+
+A role-based scale pairs each size with its line-height and weight, making a role one decision instead of three. A starting point for a product interface:
+
+| Role | Size | Line-height | Weight |
+| --- | --- | --- | --- |
+| Display | `2.25rem` (36px) | `1.1` | `600` |
+| Title | `1.5rem` (24px) | `1.2` | `600` |
+| Heading | `1.125rem` (18px) | `1.3` | `600` |
+| Body | `1rem` (16px) | `1.5` | `400` |
+| Caption | `0.8125rem` (13px) | `1.4` | `400` |
+
+Emphasis within a role is one weight step up (`400` → `500`), not a size change.
+
+## Heading hierarchy
+
+Assign each heading level to a descending step of the scale, so hierarchy comes from the scale instead of one-off sizes:
+
+```css
+h1 { font-size: var(--text-2xl); }
+h2 { font-size: var(--text-xl); }
+h3 { font-size: var(--text-lg); }
+```
+
+In Tailwind the same mapping is utility classes per level (`text-2xl`, `text-xl`, `text-lg`), centralized in a component or `@layer base` rather than repeated inline.
+
+When reviewing, compare the computed size of headings within each semantic section. A child rendering more prominently than its parent breaks the hierarchy. Deep levels may share a size where the scale runs out of comfortable steps, as long as weight or letter-spacing keeps them distinct. A heading is never smaller than body text unless it is deliberately a label-style overline.
+
+Heading semantics and outline quality belong to `better-accessibility`. Pick the element from the document structure, then use this skill to make that structure visually legible. Never pick a heading element for its browser-default size.
+
+## Kerning and letter-spacing
+
+- **Kerning** adjusts specific pairs such as `AV` or `Ye`. It is built into the font and applied automatically. Switch it off only deliberately, with `font-kerning: none`.
+- **`letter-spacing`** adds the same space between every character.
+
+```css
+/* Good */
+.display-heading {
+  letter-spacing: -0.02em;
+}
+
+.uppercase-label {
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+```
+
+## Line-height
+
+| Text | Value |
+| --- | --- |
+| Headings | ~`1.1` |
+| Body copy | `1.5`–`1.6` |
+
+Tailwind's `leading-snug`, `leading-normal` and `leading-relaxed` are sensible defaults that rarely need overriding. A tightly-leaded paragraph is harder to read than a taller row is to fit.
+
+```css
+/* Bad: card description at heading leading */
+.card-description { line-height: 1.1; }
+
+/* Good: it wraps to 3 lines, so it reads as body text */
+.card-description { line-height: 1.4; }
+```
+
+## Text trimming with text-box
+
+Fonts reserve space above and below the letters, which is why text sits slightly too low in buttons and badges. `text-box` trims it. Two parts: which edges to trim (`trim-both`, `trim-start`, `trim-end`) and where:
+
+| Keyword | Trims at |
+| --- | --- |
+| `cap` | The cap height (top) |
+| `alphabetic` | The baseline (bottom) |
+| `text` | The font's own text edge, keeping room for descenders |
+
+```css
+/* trim top and bottom */
+.badge {
+  text-box: trim-both cap alphabetic;
+}
+
+/* trim only the top */
+.heading {
+  text-box: trim-start cap;
+}
+
+/* trim only the bottom */
+.label {
+  text-box: trim-end alphabetic;
+}
+```
+
+Supported in Chromium (133+) and Safari (18.2+), not yet Firefox. Treat it as progressive enhancement, where unsupported browsers keep the default leading.

package/skills/mejor-tipografia/variable-fonts-and-opentype.md

@@ -0,0 +1,105 @@
+# Variable fonts and OpenType
+
+What a font file can do beyond drawing letters and how to reach those abilities from CSS.
+
+## Static vs variable
+
+- **Static font:** one weight and one style per file. Regular, medium and bold is three files.
+- **Variable font:** a whole range in one file. Any value in it works, such as `font-weight: 589`.
+
+A variable font is not automatically better. At one or two weights, static files can be smaller. At several weights, optical sizes, or custom axes, a variable font usually wins.
+
+## Load intended weights and styles
+
+Use a weight or style the active family does not provide and the browser may synthesize it, so load the faces the design uses. `none` disables weight, style, small-cap, superscript and subscript synthesis together and can erase distinctions when the real face is unavailable. Verify the whole fallback stack and every emphasis state before setting it.
+
+```css
+.brand-wordmark {
+  /* Safe only after this isolated treatment is verified */
+  font-synthesis: none;
+}
+```
+
+For body and interface text, keep synthesis enabled unless a verified font setup supplies every requested form. If only one mode is unwanted, use the specific longhand (`font-synthesis-weight`, `font-synthesis-style` and related properties) instead of the blanket shorthand.
+
+## Axes
+
+Variable-font controls, each with a four-letter tag. A font supports only the axes its designer included.
+
+| Axis | Tag | Controls |
+| --- | --- | --- |
+| Weight | `wght` | Stroke thickness (like `font-weight`) |
+| Optical size | `opsz` | Details and spacing tuned for the display size |
+| Width | `wdth` | Glyph width |
+| Slant | `slnt` | Slant angle |
+| Custom | e.g. `GRAD` (Roboto Flex) | Whatever the designer built |
+
+Inter's variable file exposes only `wght` and `opsz`.
+
+Optical sizes predate variable fonts, and many families still ship them as separate files. Heldane Text is sturdier and more spaced for reading sizes, Heldane Display finer for large ones.
+
+## Properties over axis tags
+
+When a property exists, use it. `font-weight` keeps working when a non-variable fallback renders, where `font-variation-settings` silently does nothing. Save raw tags for custom axes with no property of their own:
+
+```css
+/* Good: common axes use the properties */
+.heading {
+  font-weight: 650;
+  font-optical-sizing: auto;
+}
+
+/* Good: custom axis with no property of its own */
+.heading-grade {
+  font-variation-settings: "GRAD" 80;
+}
+
+/* Bad: weight via raw tag breaks on fallback fonts */
+.heading {
+  font-variation-settings: "wght" 650;
+}
+```
+
+## OpenType features
+
+OpenType is the standard behind almost every modern font. Features are extra built-in options and, unlike axes, work the same on static and variable fonts. A font ships only the features its designer included.
+
+| Tag | Feature |
+| --- | --- |
+| `tnum` | Tabular numbers: every digit the same width |
+| `zero` | Slashed zero: `0` distinct from `O` |
+| `liga` | Ligatures: joins pairs like "fi" into one shape |
+| `ss01`–`ss20` | Stylistic sets (numbered slots) |
+| `cv01`–`cv99` | Character variants (numbered slots) |
+
+Same rule as axes. Prefer the `font-variant-*` properties and reserve `font-feature-settings` for tags with no property:
+
+```css
+/* Good: common features use the properties */
+.price {
+  font-variant-numeric: tabular-nums;
+}
+
+/* Good: slashed zero via the property too */
+.id {
+  font-variant-numeric: slashed-zero;
+}
+
+/* Good: niche feature with no property of its own */
+.logo {
+  font-feature-settings: "ss01" 1;
+}
+```
+
+Tabular numbers matter for changing values. Without them each digit has a different width and the layout shifts as values update.
+
+## Small caps, superscripts, subscripts
+
+- **Small capitals:** uppercase letters drawn at a smaller size. Enable real ones with `font-variant-caps`.
+- **Superscripts** sit above the normal line, the 2 in x², and **subscripts** below it, as in H₂O. Enable proper glyphs with `font-variant-position`.
+
+Both require the font to include the glyphs.
+
+## Stylistic sets and character variants
+
+`ss01` = stylistic set, slot 01. `cv11` = character variant, slot 11. What each slot does differs font to font, which is why they are numbered, not named. Check the font's docs. In Inter, `ss01` switches to open digits and `cv11` swaps in a single-story `a`.

package/skills/mejor-tipografia/wrapping-and-punctuation.md

@@ -0,0 +1,55 @@
+# Wrapping and punctuation
+
+Where lines start, where they end, where they break and which characters they use.
+
+## Measure (line length)
+
+Long lines make it harder for the eye to find the start of the next. For long-form text, aim for 60–75 characters per line.
+
+Any unit works. `65ch` measures characters directly, one `ch` being the width of the `0` in the current font, and a pixel or rem cap is just as good. At a `16px` body size the 60–75 character range lands roughly between `560px` and `680px` depending on the font, so Tailwind's `max-w-xl` (`576px`) and `max-w-2xl` (`672px`) both fit. What matters is that a cap exists and the line length sits in range. Recheck it if the body font size changes.
+
+## Alignment
+
+`text-align` controls where each line starts and ends. `justify` stretches spaces until both edges line up, which works in specific editorial layouts and nowhere else in an interface.
+
+## Wrapping
+
+| Property | Use |
+| --- | --- |
+| `text-wrap: balance` | Distributes text evenly across multiple lines |
+| `text-wrap: pretty` | Avoids leaving a single short word on the final line |
+| `overflow-wrap: break-word` | Lets long words, links and IDs break before escaping the container |
+| `white-space: nowrap` | Keeps labels and badges on one line where a break looks broken |
+
+Use `balance` on headings and `pretty` on descriptions. Skip both in long-form text, because browsers ignore `balance` past a few lines anyway, and evening out a whole paragraph wastes space and makes it harder to read.
+
+## Truncation
+
+- Single line: `text-overflow: ellipsis`, which needs `overflow: hidden` and `white-space: nowrap`.
+- Multiple lines: `line-clamp` allows any number of lines before the ellipsis.
+
+Truncation hides content. Where the missing text matters, make the full value available in a tooltip or an expanded view.
+
+## Case
+
+`text-transform` changes how case appears without changing the underlying text. Write copy naturally and control presentation with CSS, so a redesign never means rewriting copy.
+
+## Smart punctuation
+
+Keyboard characters are not always the best characters:
+
+| Instead of | Use |
+| --- | --- |
+| Straight quotes `"..."` | Curly quotes that curve around the text (keep straight quotes in code) |
+| Hyphen in ranges | En dash: `2010–2020` |
+| Two hyphens for an aside | Em dash character |
+| Three periods `...` | The single ellipsis character `…` |
+| Regular space in `16 px` | ` ` so the value never breaks apart |
+| Uncontrolled word breaks | `­` to mark where a word may break |
+
+## Internationalization
+
+Two refinements for mixed-direction text:
+
+- **Long paragraphs align by their own language.** A one- or two-line snippet follows the surrounding UI's direction. A paragraph of three or more lines aligns to its own script instead, so an English paragraph stays start-aligned LTR even inside an RTL interface. `text-align: start` with the correct `lang`/`dir` on the paragraph element handles this.
+- **Never reverse digits.** Numbers keep their order in every direction, so a phone number or "541" reads identically in RTL. Browsers handle this through the Unicode bidi algorithm. Never fight it with manual reordering, and wrap mixed number and text values in `<bdi>` where adjacent RTL text disturbs them.

package/skills/mejor-ui/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: mejor-ui
+description: "Use to polish and improve a project's UI — concentric border radii, optical alignment, surface depth, shadows vs. borders, interruptible animations, staggered entrances, icon transitions, press scaling, theme-switch transition suppression, and motion containment."
+tags: ["ui-polish", "visual-design", "motion"]
+profiles: [ui, full]
+---
+
+# Acabado de UI
+
+El acabado sale de un monton de detalles pequenos que se acumulan. Esta skill es la referencia de cuales merecen la pena y que valores toman.
+
+Al revisar, ralentiza la interfaz. Lo que se siente raro al 10% de velocidad es lo que esta sutilmente mal a velocidad normal.
+
+Conserva la libreria de componentes, los tokens y la densidad del proyecto, y ajustate a su lenguaje de movimiento salvo donde una regla de abajo prescriba una interaccion exacta.
+
+Cada duracion, curva, escala y desenfoque de abajo es un valor concreto, no un rango que aproximar. `cubic-bezier(0.2, 0, 0, 1)` no es `cubic-bezier(0.4, 0, 0.2, 1)`, y `0.96` no es `0.95`. Usa lo que esta escrito.
+
+El wrapping de texto, el renderizado de fuentes, los numeros tabulares y el espaciado del texto son de `mejor-tipografia`. Las areas de pulsacion, el foco, el soporte de teclado, ARIA y el movimiento reducido son de `mejor-accesibilidad`. La agrupacion, el espaciado de secciones, los breakpoints y el RTL espacial son de `mejor-layout`.
+
+## Radio de borde concentrico
+
+Radio exterior = radio interior + padding. Radios descuadrados en elementos anidados es lo que mas a menudo hace que una interfaz se sienta rara. Las recetas de radio, sombra y contorno estan en [surfaces.md](surfaces.md).
+
+## Alineacion optica antes que geometrica
+
+Cuando el centrado geometrico se ve raro, alinea opticamente. Los botones con icono, los triangulos de reproduccion y los iconos asimetricos necesitan todos un empujon manual.
+
+## Sombras para elevacion, bordes para estructura
+
+Donde un borde existe solo para crear profundidad, prefiere valores de `box-shadow` transparentes en capas. Conserva los bordes que comunican estructura o estado: divisores, separadores y estados seleccionado o de foco.
+
+## Animaciones interrumpibles
+
+Usa transiciones CSS para los cambios de estado interactivos, porque se pueden interrumpir a mitad de animacion. Reserva los keyframes para secuencias por fases que se reproducen una vez.
+
+## Divide y escalona las animaciones de entrada
+
+Para una entrada por fases poco frecuente donde la secuencia comunica jerarquia, parte el contenido en trozos semanticos y escalonalos ~100ms. Animar un unico contenedor te da menos por el mismo coste. Deja sin escalonar las interacciones de alta frecuencia. Ver [enter-exit.md](enter-exit.md).
+
+## Animaciones de salida sutiles
+
+Usa un `translateY` fijo pequeno en vez de la altura completa. Las salidas deben ser mas suaves que las entradas. Usa `ease-out` en ambas direcciones.
+
+## Animaciones contextuales de iconos
+
+Anima los iconos con `opacity`, `scale` y `blur` en vez de conmutar la visibilidad. Usa exactamente estos valores: escala de `0.25` a `1`, opacidad de `0` a `1`, desenfoque de `4px` a `0px`.
+
+Con una libreria de movimiento (`motion` o `framer-motion` en `package.json`), usa la ruta de import de ese paquete, o la de los imports cercanos donde existan ambos. Usa `transition: { type: "spring", duration: 0.3, bounce: 0 }`. El rebote es siempre `0`.
+
+Sin libreria, manten los dos iconos en el DOM con uno posicionado en absoluto, y funde entre ellos con `cubic-bezier(0.2, 0, 0, 1)`. Eso te da entrada y salida sin dependencias. Las dos recetas estan en [icon-transitions.md](icon-transitions.md).
+
+## Contornos de imagen
+
+Da a las imagenes un contorno de `1px` a baja opacidad para una profundidad consistente. Negro puro en modo claro (`oklch(0 0 0 / 0.1)`), blanco puro en oscuro (`oklch(1 0 0 / 0.1)`). Nunca un casi-negro tipo slate o zinc, y nunca un neutro tenido. Un contorno tenido recoge la superficie de debajo y se lee como suciedad en el borde de la imagen.
+
+## Escala al pulsar
+
+Un `scale(0.96)` al hacer clic da al boton feedback tactil. Siempre `0.96`; por debajo de `0.95` se siente exagerado. Anade una prop `static` para apagarlo donde el movimiento distraiga. Ver [recetas para CSS, Tailwind y Motion](animations.md#scale-on-press).
+
+## Sin animacion en la carga de pagina
+
+Usa `initial={false}` en `AnimatePresence` para dejar las animaciones de entrada fuera del primer render. Comprueba que no rompa las entradas de pagina intencionadas.
+
+## Suprime las transiciones al cambiar de tema
+
+Un cambio de tema modifica color, fondo, borde y sombra en casi todos los elementos a la vez. Todas las transiciones sobre esas propiedades se disparan juntas y el cambio se emborrona en vez de saltar limpio. Inyecta `*,*::before,*::after{transition:none !important}`, fuerza un reflow y quitalo en el siguiente fotograma. Ver la [receta](animations.md#suppress-transitions-on-theme-switch).
+
+## Transiciona solo lo que cambia
+
+Nombra siempre las propiedades exactas: `transition-property: scale, opacity`. El `transition-transform` de Tailwind cubre `transform, translate, scale, rotate`.
+
+## Usa `will-change` con moderacion
+
+Solo para `transform`, `opacity` y `filter`, que la GPU puede componer. Nunca `will-change: all`. Anadelo cuando veas tirones en el primer fotograma, no antes. Ver [performance.md](performance.md).
+
+## Ajusta el grosor del icono al peso del texto
+
+Un icono junto a texto lleva el peso optico del texto: trazo de `1.5px` junto a texto regular (400), `2px` junto a semibold (600). Un unico grosor de trazo por set de iconos y una unica libreria de iconos por superficie. El dimensionado y el volteo RTL estan en [icons.md](icons.md).
+
+## Un solo SVG, recoloreado por estado
+
+Los iconos usan `currentColor` y toman los estados hover, seleccionado y deshabilitado del color y la opacidad de CSS, nunca de assets separados. La variante de contorno es la de por defecto; el relleno marca el estado activo.
+
+## Contencion del movimiento
+
+Da a las interacciones de alta frecuencia feedback instantaneo, o una transicion de `150ms` o menos sobre opacidad y color. Una animacion propia ahi cobra su coste de atencion en cada disparo.
+
+Todo cambio de estado animado necesita ademas una pista estatica: color, un icono o una etiqueta. El movimiento nunca es el unico canal de feedback.
+
+## Antes de terminar
+
+| Error | Arreglo |
+| --- | --- |
+| Los iconos se ven descentrados | Empujalos opticamente con padding, o arregla el SVG |
+| Entrada o salida por fases brusca | Escalona las entradas poco frecuentes; manten las salidas sutiles |
+| El cambio de tema funde toda la pagina | Desactiva las transiciones durante el cambio, fuerza un reflow, restaura en el siguiente fotograma |
+| `transition: all` en elementos | Especifica las propiedades exactas |
+| Tiron en el primer fotograma de la animacion | Anade `will-change: transform` (con moderacion) |
+| Icono de trazo fino junto a texto en negrita | Ajusta el grosor de trazo al peso del texto |
+
+## Como reportar
+
+**Severidad.** `ALTA` rompe una interaccion, hace el movimiento inusable, o deja un cambio de estado visible solo mientras corre la animacion. `MEDIA` es una inconsistencia visible en superficies, iconos o movimiento. `BAJA` es pulido aislado.
+
+**Verificacion.** Sin navegador: cada estado que define el componente (hover, foco, activo, cargando y vacio), mas las duraciones y easings leidos del codigo. Con navegador: recorre cada estado y reproduce el movimiento al 10% de velocidad en el panel de Animaciones. 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 acabado de UI" y reporta la verificacion.

package/skills/mejor-ui/animations.md

@@ -0,0 +1,205 @@
+# Animations
+
+Interruptible transitions, press feedback and the restraint that decides whether to animate at all. Staged entrances and exits live in [enter-exit.md](enter-exit.md); icon swaps in [icon-transitions.md](icon-transitions.md).
+
+## Interruptible animations
+
+Users change intent mid-interaction. Animations that cannot be interrupted make the interface feel broken.
+
+### CSS transitions vs. keyframes
+
+| | CSS Transitions | CSS Keyframe Animations |
+| --- | --- | --- |
+| **Behavior** | Interpolate toward latest state | Run on a fixed timeline |
+| **Interruptible** | Yes, retargets mid-animation | No, restarts from beginning |
+| **Use for** | Interactive state changes (hover, toggle, open/close) | Staged sequences that run once (enter animations, loading) |
+| **Duration** | Fixed; retargets the value mid-flight, not the timeline | Fixed timeline, restarts from the beginning |
+
+```css
+/* Good: interruptible transition for a toggle */
+.drawer {
+  transform: translateX(-100%);
+  transition: transform 200ms ease-out;
+}
+.drawer.open {
+  transform: translateX(0);
+}
+
+/* Clicking again mid-animation smoothly reverses, no jank */
+```
+
+```css
+/* Bad: keyframe animation for interactive element */
+.drawer.open {
+  animation: slideIn 200ms ease-out forwards;
+}
+
+/* Closing mid-animation snaps or restarts, feels broken */
+```
+
+Prefer CSS transitions for interactive elements. Reserve keyframes for one-shot sequences.
+
+## Scale on press
+
+A subtle scale-down on click gives buttons tactile feedback. Always `scale(0.96)`, never below `0.95`, which feels exaggerated. Use CSS transitions so a release mid-press returns smoothly.
+
+Not every button needs it. Add a `static` prop that disables the scale where the motion would distract.
+
+### CSS example
+
+```css
+.button {
+  transition-property: scale;
+  transition-duration: 150ms;
+  transition-timing-function: ease-out;
+}
+
+.button:active {
+  scale: 0.96;
+}
+```
+
+### Tailwind example
+
+```tsx
+<button className="transition-transform duration-150 ease-out active:scale-[0.96]">
+  Click me
+</button>
+```
+
+### Motion example
+
+```tsx
+<motion.button whileTap={{ scale: 0.96 }}>
+  Click me
+</motion.button>
+```
+
+### Static prop pattern
+
+Extract the scale class into a variable and apply it conditionally on a `static` prop:
+
+```tsx
+const tapScale = "active:not-disabled:scale-[0.96]";
+
+function Button({ static: isStatic, className, children, ...props }) {
+  return (
+    <button
+      className={cn(
+        "transition-transform duration-150 ease-out",
+        !isStatic && tapScale,
+        className,
+      )}
+      {...props}
+    >
+      {children}
+    </button>
+  );
+}
+
+// Usage
+<Button>Click me</Button>           {/* scales on press */}
+<Button static>Submit</Button>       {/* no scale */}
+```
+
+## Skip animation on page load
+
+Use `initial={false}` on `AnimatePresence` to stop enter animations firing on first render. An element already in its default state animates on later state changes, not on page load.
+
+### When it works
+
+```tsx
+// Good: icon doesn't animate in on mount, only on state change
+<AnimatePresence initial={false} mode="popLayout">
+  <motion.span
+    key={isActive ? "active" : "inactive"}
+    initial={{ opacity: 0, scale: 0.25, filter: "blur(4px)" }}
+    animate={{ opacity: 1, scale: 1, filter: "blur(0px)" }}
+    exit={{ opacity: 0, scale: 0.25, filter: "blur(4px)" }}
+  >
+    <Icon />
+  </motion.span>
+</AnimatePresence>
+```
+
+Works well for icon swaps, toggles, tabs and segmented controls, anything with a default state on page load.
+
+### When it breaks
+
+Never use `initial={false}` where the component relies on its `initial` prop for a first-time enter animation, such as a staggered page hero or a loading state. Removing it skips the entire entrance.
+
+```tsx
+// Bad: initial={false} would skip the staggered page enter entirely
+<AnimatePresence initial={false}>
+  <motion.div initial="hidden" animate="visible" variants={...}>
+    ...
+  </motion.div>
+</AnimatePresence>
+```
+
+Verify the component still looks right on a full page refresh before applying this.
+
+## Suppress transitions on theme switch
+
+Flipping the theme changes `color`, `background-color`, `border-color` and `box-shadow` on nearly every element at once. Everything carrying a transition on those properties animates together, so the switch reads as a slow smear rather than an instant change. Disable transitions for the swap and restore them right after.
+
+Inject a stylesheet that turns off every transition, force a reflow so the new colors commit while it still applies, then drop it on the next frame:
+
+```tsx
+"use client";
+
+import { useEffect } from "react";
+
+export function DisableThemeTransitions() {
+  useEffect(() => {
+    const mql = window.matchMedia("(prefers-color-scheme: dark)");
+
+    const handleChange = () => {
+      const style = document.createElement("style");
+      style.append(
+        document.createTextNode(
+          "*,*::before,*::after{transition:none !important}"
+        )
+      );
+      document.head.append(style);
+
+      const _flushReflow = document.body.offsetHeight;
+
+      requestAnimationFrame(() => {
+        requestAnimationFrame(() => style.remove());
+      });
+    };
+
+    mql.addEventListener("change", handleChange);
+    return () => mql.removeEventListener("change", handleChange);
+  }, []);
+
+  return null;
+}
+```
+
+`document.body.offsetHeight` is read for its side effect, forcing a synchronous style flush so the new theme resolves while the override is still in the document and no transition starts. The nested `requestAnimationFrame` removes the override only after that paint, restoring transitions before the next interaction.
+
+That covers the OS-level change. An in-app toggle needs the same treatment around its own flip: apply the override, change the theme, flush, remove. `next-themes` ships this as `disableTransitionOnChange`.
+
+## Motion restraint
+
+Motion is a budget, not a garnish. Three rules decide whether an animation belongs at all:
+
+- **Give high-frequency interactions instant feedback instead of animation.** Every keystroke, every list-row hover, every tab switch in a work tool. Reserve expressive motion for infrequent moments (first load of a view, success states, empty states); high-frequency interactions get instant feedback or the subtlest possible transition (`opacity`/`background-color` at ≤150ms).
+- **Motion is never the only feedback channel.** Every state change an animation communicates stays visible when it doesn't run: a color change, an icon swap, a label. Users with reduced motion enabled and anyone who blinked still need to see what happened.
+- **Brief and precise beats prominent.** Where a shorter, smaller animation says the same thing, use it. When in doubt cut the duration, not the clarity.
+
+```css
+/* Good: high-frequency hover gets a minimal transition */
+.row:hover {
+  background-color: var(--surface-hover);
+  transition: background-color 100ms ease-out;
+}
+
+/* Bad: every hover replays a full entrance */
+.row:hover .row-icon {
+  animation: bounceIn 500ms;
+}
+```
+