@maccesar/aiskills 1.12.0 → 1.16.0

package/skills/humaniza/references/structures-es.md

@@ -0,0 +1,132 @@
+# Estructuras a evitar
+
+Basado en el patrón detectado por Stop Slop, adaptado al español.
+
+## Contrastes binarios
+
+Crean falso drama. Afirma el punto directo.
+
+| Patrón | Problema |
+|--------|----------|
+| "No porque X, sino porque Y" / "No por X, sino por Y" | Giro telegrafiado |
+| "X no es el problema. Y lo es." | Reformulación formulaica |
+| "La respuesta no es X. Es Y." | Giro predecible |
+| "No se trata de X, sino de Y" | Mecánico |
+| "La pregunta no es X, sino Y" | Distracción retórica |
+| "No es X, es Y" | Contraste mecánico |
+| "No solo X, sino también Y" | Muletilla aditiva |
+| "deja de ser X y empieza a ser Y" | Falso arco de transformación |
+| "no significa X, sino Y" | Negación-seguida-de-afirmación |
+
+**En lugar de:** Afirma Y directo. "El problema es Y." "Aquí importa Y." Suelta la negación.
+
+## Listado negativo
+
+Enumerar lo que algo *no* es antes de decir lo que *sí* es. Striptease retórico.
+
+| Patrón | Problema |
+|--------|----------|
+| "No es X... No es Y... Es Z." | Acumulación dramática con negación |
+| "No fue X. No fue Y. Fue Z." | Misma estructura, pasado |
+
+**En lugar de:** Di Z. El lector no necesita la pista de aterrizaje.
+
+## Fragmentación dramática
+
+Fragmentos de oración para énfasis que leen a profundidad fabricada.
+
+| Patrón | Problema |
+|--------|----------|
+| "[Sustantivo]. Eso es todo." / "[Sustantivo]. Eso es." | Simplicidad performativa |
+| "X. Y. Y Z." | Drama staccato |
+| "Esto activa algo. [Palabra]." | Revelación artificial |
+
+**En lugar de:** Oraciones completas. Confía en el contenido, no en la presentación.
+
+## Setups retóricos
+
+Anuncian perspicacia en lugar de entregarla.
+
+| Patrón | Problema |
+|--------|----------|
+| "¿Qué tal si...?" / "¿Y si...?" | Postura socrática |
+| "He aquí lo que quiero decir:" / "Esto es lo que quiero decir:" | Vista previa redundante |
+| "Piénsalo." | Indicación condescendiente |
+| "Y eso está bien." / "Y no pasa nada." | Permiso innecesario |
+| "Imagina que..." | Falso gancho narrativo |
+
+**En lugar de:** Di el punto directo. Deja que el lector saque conclusiones.
+
+## Agencia falsa
+
+Darle a objetos inanimados verbos humanos. A la IA le encanta porque evita nombrar al actor.
+
+| Patrón | Problema |
+|--------|----------|
+| "la queja se convierte en solución" | La queja no hizo nada. Alguien la resolvió. |
+| "la decisión emerge" | Las decisiones no emergen. Alguien decide. |
+| "la cultura cambia" | Las culturas no cambian solas. La gente cambia su comportamiento. |
+| "la conversación avanza hacia" | Las conversaciones no avanzan solas. Alguien las dirige. |
+| "los datos nos dicen" | Los datos están ahí. Alguien los lee y saca conclusiones. |
+| "el mercado recompensa" | Los mercados no recompensan. Los compradores pagan por cosas. |
+| "la plataforma permite" | La plataforma no permite nada. Alguien la construyó para eso. |
+| "el sistema detecta" | El sistema no detecta nada. Alguien programó esa detección. |
+
+**En lugar de:** Nombra al humano. "El equipo lo resolvió esa semana" gana a "la queja se convierte en solución".
+
+## Narrador desde la distancia
+
+Flotando sobre la escena en vez de poner al lector en ella.
+
+| Patrón | Problema |
+|--------|----------|
+| "Nadie diseñó esto." | Observación incorpórea |
+| "Esto pasa porque..." | Voz de conferencista |
+| "Por eso es que..." | Misma voz distante |
+| "La gente tiende a..." | Sociólogo de sillón |
+| "Uno tiende a pensar que..." | Generalización impersonal |
+| "Se tiende a creer que..." | Distanciamiento innecesario |
+
+**En lugar de:** Pon al lector en la escena. "Tú no te sientas un día y decides..." gana a "Nadie diseñó esto".
+
+## Voz pasiva
+
+Cada oración necesita un sujeto haciendo algo. La voz pasiva esconde al actor.
+
+| Patrón | Solución |
+|--------|----------|
+| "fue creado por" | Nombra quién lo creó |
+| "se cree que" | Nombra quién lo cree |
+| "se tomaron decisiones" | Nombra quién decidió |
+| "se llegó a la conclusión" | Nombra quién concluyó |
+| "fue implementado" | Nombra quién implementó |
+| "ha sido reportado que" | Nombra quién reportó |
+
+**En lugar de:** Encuentra al actor. Ponlo al frente de la oración.
+
+## Inicios de oración a evitar
+
+| Patrón | Solución |
+|--------|----------|
+| Oraciones que empiezan con qué, cuándo, dónde, cómo, quién, por qué | Reestructura. Lidera con el sujeto o el verbo. |
+| Párrafos que empiezan con "entonces", "así que" | Empieza con contenido |
+| Oraciones que empiezan con "mira", "oye" | Elimínalas |
+
+Los interrogativos (qué, cómo, por qué) como abridores se vuelven muleta. "Lo que hace difícil esto es..." cambia a "La dificultad es..." o mejor, nombra la dificultad específica.
+
+## Patrones de ritmo
+
+| Patrón | Solución |
+|--------|----------|
+| Listas de tres elementos | Usa dos o uno |
+| Preguntas respondidas inmediatamente | Deja que las preguntas respiren o elimínalas |
+| Todo párrafo termina con golpe de efecto | Varía los finales |
+| Rayas (—) en prosa narrativa | Elimínalas. Usa comas o puntos. |
+| Fragmentación staccato | No apiles oraciones cortas sucesivas |
+| "No siempre. No perfectamente." | Muletilla disfrazada de seguridad |
+
+## Vaguedad con extremos
+
+| Patrón | Problema |
+|--------|----------|
+| Extremos vagos: todo, todos, siempre, nunca, nadie, absolutamente | Falsa autoridad. Usa datos específicos. |

package/skills/humaniza/scripts/check_ai_patterns.py

@@ -0,0 +1,216 @@
+#!/usr/bin/env python3
+"""
+check_ai_patterns.py — Deterministic scanner for AI-writing tics in Spanish.
+
+Reads patterns from sibling `references/lexicon-es-mx.md` and reports every
+hit found in the input text with line number, category, matched phrase, and
+a replacement suggestion when the lexicon supplies one.
+
+Usage:
+    python check_ai_patterns.py <text_file>
+    python check_ai_patterns.py < input.txt
+    cat input.txt | python check_ai_patterns.py
+
+Stdlib only. Python 3.8+.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+from typing import Iterator, NamedTuple
+
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+LEXICON_PATH = SCRIPT_DIR.parent / "references" / "lexicon-es-mx.md"
+
+
+class Hit(NamedTuple):
+    line_no: int
+    column: int
+    category: str
+    matched: str
+    suggestion: str  # empty string if none
+
+
+def _parse_section_header(line: str) -> str:
+    """Return the header text if line is `## ...`, else empty string."""
+    if line.startswith("## "):
+        return line[3:].strip().rstrip(":")
+    return ""
+
+
+def _split_phrases(content: str) -> list[str]:
+    """
+    Split a comma-separated phrase block into individual phrases.
+    Strips whitespace and a trailing period.
+    """
+    cleaned = content.strip().rstrip(".")
+    return [p.strip() for p in cleaned.split(",") if p.strip()]
+
+
+def _parse_replacement_line(line: str) -> tuple[str, str] | None:
+    """
+    Parse a lexicon line of the form `- phrase -> suggestion` or
+    `phrase -> suggestion`. Returns (phrase, suggestion) or None.
+    """
+    stripped = line.lstrip("-").strip()
+    if "->" not in stripped:
+        return None
+    left, _, right = stripped.partition("->")
+    phrase = left.strip()
+    suggestion = right.strip()
+    # Strip any inline parenthetical hint on the phrase side, e.g. `aplicar a (trabajo)`.
+    # We keep the visible form so the user can locate it, but build a search regex
+    # that ignores the hint. Here, we keep the phrase as-is and let the search
+    # tolerate the parenthetical by stripping it for matching only.
+    return phrase, suggestion
+
+
+def load_lexicon(path: Path) -> dict[str, list[tuple[str, str]]]:
+    """
+    Parse the lexicon markdown file into a dict of:
+        category -> list of (phrase, suggestion) tuples.
+
+    Suggestion is an empty string when the lexicon offers none.
+    """
+    if not path.exists():
+        return {}
+
+    categories: dict[str, list[tuple[str, str]]] = {}
+    current_category = ""
+    current_inline_block: list[str] = []
+
+    def flush_inline_block() -> None:
+        if not current_category or not current_inline_block:
+            return
+        text = " ".join(current_inline_block)
+        phrases = _split_phrases(text)
+        for p in phrases:
+            categories.setdefault(current_category, []).append((p, ""))
+        current_inline_block.clear()
+
+    for raw_line in path.read_text(encoding="utf-8").splitlines():
+        line = raw_line.rstrip()
+
+        header = _parse_section_header(line)
+        if header:
+            flush_inline_block()
+            current_category = header
+            continue
+
+        if not current_category:
+            continue
+
+        if not line.strip():
+            flush_inline_block()
+            continue
+
+        replacement = _parse_replacement_line(line)
+        if replacement is not None:
+            phrase, suggestion = replacement
+            categories.setdefault(current_category, []).append((phrase, suggestion))
+            continue
+
+        if line.startswith("-"):
+            # Bullet item without `->`: treat as a plain phrase.
+            phrase = line.lstrip("-").strip()
+            if phrase:
+                categories.setdefault(current_category, []).append((phrase, ""))
+            continue
+
+        # Otherwise, this is part of an inline comma-separated block.
+        current_inline_block.append(line)
+
+    flush_inline_block()
+    return categories
+
+
+def _compile_pattern(phrase: str) -> re.Pattern[str]:
+    """
+    Build a case-insensitive regex matching the phrase as a whole-word boundary,
+    tolerating an optional parenthetical hint (e.g. `aplicar a (trabajo)` matches
+    `aplicar a`).
+    """
+    bare = re.sub(r"\s*\([^)]*\)\s*", "", phrase).strip()
+    escaped = re.escape(bare)
+    # Allow optional whitespace inside multi-word phrases.
+    escaped = escaped.replace(r"\ ", r"\s+")
+    return re.compile(rf"(?<!\w){escaped}(?!\w)", re.IGNORECASE)
+
+
+def scan_text(
+    text: str,
+    categories: dict[str, list[tuple[str, str]]],
+) -> Iterator[Hit]:
+    """Yield a Hit for every phrase match found in the text."""
+    compiled = [
+        (category, phrase, suggestion, _compile_pattern(phrase))
+        for category, items in categories.items()
+        for phrase, suggestion in items
+    ]
+
+    for line_no, line in enumerate(text.splitlines(), start=1):
+        for category, phrase, suggestion, pattern in compiled:
+            for match in pattern.finditer(line):
+                yield Hit(
+                    line_no=line_no,
+                    column=match.start() + 1,
+                    category=category,
+                    matched=match.group(0),
+                    suggestion=suggestion,
+                )
+
+
+def read_input() -> str:
+    if len(sys.argv) > 1:
+        arg = sys.argv[1]
+        if arg in ("-h", "--help"):
+            print(__doc__)
+            sys.exit(0)
+        return Path(arg).read_text(encoding="utf-8")
+    return sys.stdin.read()
+
+
+def format_hit(hit: Hit) -> str:
+    location = f"line {hit.line_no}:{hit.column}"
+    body = f'[{hit.category}] "{hit.matched}"'
+    if hit.suggestion:
+        body += f"  →  {hit.suggestion}"
+    return f"{location}  {body}"
+
+
+def main() -> int:
+    categories = load_lexicon(LEXICON_PATH)
+    if not categories:
+        print(
+            f"WARNING: lexicon not found or empty at {LEXICON_PATH}",
+            file=sys.stderr,
+        )
+        return 2
+
+    text = read_input()
+    hits = list(scan_text(text, categories))
+
+    if not hits:
+        print("OK: no AI-writing tics detected.")
+        return 0
+
+    print(f"Found {len(hits)} potential AI-writing tic(s):\n")
+    for hit in hits:
+        print(format_hit(hit))
+
+    by_category: dict[str, int] = {}
+    for hit in hits:
+        by_category[hit.category] = by_category.get(hit.category, 0) + 1
+
+    print("\nSummary by category:")
+    for category, count in sorted(by_category.items(), key=lambda x: -x[1]):
+        print(f"  {count:>3}  {category}")
+
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/refactoring-ui/SKILL.md

@@ -1,32 +1,65 @@
 ---
 name: refactoring-ui
-description: Design advisor for UI/UX work, drawing on principles from "Refactoring UI" by Adam Wathan & Steve Schoger. Use when the user asks for UI/UX design advice, design reviews, visual hierarchy improvements, color system help, typography guidance, spacing decisions, depth/shadow usage, image handling, or finishing touches on any interface.
-when_to_use: >
-  - User asks "how do I make this look better?"
-  - User asks about color palettes, type scales, or spacing systems
-  - User asks about visual hierarchy or emphasis
-  - User is designing a UI component, page, or layout
-  - User wants a design review or critique
-  - User asks about shadows, depth, or layering
-  - User asks about handling images in UI
-  - User asks about empty states, borders, or decorative elements
-source: "Inspired by 'Refactoring UI' by Adam Wathan & Steve Schoger — refactoringui.com"
-anti_hallucination_note: >
-  Recommendations in this skill summarize design principles in the maintainer's own words.
-  Do NOT invent ratios, scale values, or technical numbers that are not in the reference
-  files. If a topic is not covered, say so explicitly rather than inventing advice.
+description: 'Use when the user asks for UI/UX design advice, design reviews, visual hierarchy improvements, color system help, typography guidance, spacing decisions, depth/shadow usage, image handling, or finishing touches on any interface. Inspired by "Refactoring UI" by Adam Wathan & Steve Schoger. Triggers: "how do I make this look better?", color palettes, type scales, spacing systems, visual hierarchy, design reviews, shadows/depth, image handling, empty states, borders.'
 ---
 
 # Refactoring UI Skill
 
 Design advice grounded in the principles taught by Adam Wathan & Steve Schoger in their book *Refactoring UI*. **The book itself contains the original prose, illustrations, side-by-side examples, and case studies — buy it at https://refactoringui.com for the full material.** This skill provides reformulated guidance for use as an AI assistant reference.
 
-## How to Use This Skill
+## Required workflow (read before responding)
 
-1. Read the relevant reference file(s) before answering
-2. Base advice on the reference content — not training data or unrelated design systems
-3. Speak in your own words; do not reproduce the book's prose, illustrations, or examples verbatim
-4. Do not invent numbers, ratios, or specific technical rules that are not in the references
+The SKILL.md alone is an **index** of references. The detail you need
+to give accurate answers lives in the reference files. **Reading this
+SKILL.md is not enough.**
+
+### Step 1 — Open the relevant reference files
+
+| Task involves | Required reading |
+|---|---|
+| Color systems, typography, spacing scales — defining the system | [references/01-foundations.md](references/01-foundations.md) |
+| Layout, white space, visual hierarchy, page-level structure | [references/02-page-mechanics.md](references/02-page-mechanics.md) |
+| Color usage, HSL, greys, contrast, shadows, depth, images | [references/03-visual-treatment.md](references/03-visual-treatment.md) |
+| Empty states, borders, accents, finishing touches | [references/04-polish.md](references/04-polish.md) |
+| Motion, microinteractions, transitions, hover/press states, loading | [references/05-motion.md](references/05-motion.md) |
+| Dark mode, multi-theme color tokens, theme toggle, contrast strategy | [references/06-dark-mode.md](references/06-dark-mode.md) |
+| Modals, forms, tables — component-specific layout and behavior patterns | [references/07-component-patterns.md](references/07-component-patterns.md) |
+
+### Step 2 — Output contract
+
+Every design recommendation, ratio, value, or rule you cite MUST be
+backed by a citation in the form:
+
+`[source: references/<file>.md]`
+
+Example: *"Use weight and color, not just font size, to establish hierarchy [source: references/02-page-mechanics.md]"*
+
+### Step 3 — If you must answer from memory
+
+If you write a claim without having read the reference that backs it,
+prepend `FROM_MEMORY (unverified):` to that claim. Do not hide it.
+
+### Banned behaviors
+
+- ❌ Inventing ratios, scale values, contrast numbers, or rules not in the references
+- ❌ Reproducing the book's prose, illustrations, or examples verbatim — paraphrase only
+- ❌ Mixing in advice from unrelated design systems (Material, HIG, Tailwind defaults) as if it were *Refactoring UI* doctrine
+- ❌ Marking the answer complete without listing which reference files you read
+
+## When to use
+
+- User asks "how do I make this look better?"
+- User asks about color palettes, type scales, or spacing systems
+- User asks about visual hierarchy or emphasis
+- User is designing a UI component, page, or layout
+- User wants a design review or critique
+- User asks about shadows, depth, or layering
+- User asks about handling images in UI
+- User asks about empty states, borders, or decorative elements
+
+## Source
+
+Inspired by 'Refactoring UI' by Adam Wathan & Steve Schoger — refactoringui.com
 
 ## Reference Files
 
@@ -36,18 +69,21 @@ Design advice grounded in the principles taught by Adam Wathan & Steve Schoger i
 | `references/02-page-mechanics.md`   | Visual hierarchy, layout, white space, spacing scales, typography                       |
 | `references/03-visual-treatment.md` | Color systems (HSL, shades, greys, contrast), depth and shadows, image handling         |
 | `references/04-polish.md`           | Finishing touches: borders, accents, empty states, decorative defaults, design intuition |
+| `references/05-motion.md`           | Motion system (durations, easings), hover/press states, loading patterns, prefers-reduced-motion — **complementary** (not from RUI) |
+| `references/06-dark-mode.md`        | Dark mode color tokens, text contrast, shadow handling, images, theme toggle — **complementary** (extrapolates RUI's HSL principles) |
+| `references/07-component-patterns.md` | Modals (focus, layout), forms (labels, validation), tables (density, alignment) — **complementary** (extends RUI principles to specific components) |
 
 ## Anti-Patterns to Watch For
 
-- Designing layouts/navs/shells before designing real features
-- Using font size as the only tool for hierarchy (ignoring weight and color)
-- Using opacity to create grey text on colored backgrounds
-- Starting with too little white space and adding it later
-- Using `em` for type scales (compounds when nested)
-- Using color as the only signal for a UI state
-- Designing with placeholder images instead of real content
-- Shrinking a logo down to use as a favicon
-- Using preprocessor `lighten()` / `darken()` to derive shades
+- Designing layouts/navs/shells before designing real features [source: references/01-foundations.md]
+- Using font size as the only tool for hierarchy (ignoring weight and color) [source: references/02-page-mechanics.md]
+- Using opacity to create grey text on colored backgrounds [source: references/02-page-mechanics.md]
+- Starting with too little white space and adding it later [source: references/02-page-mechanics.md]
+- Using `em` for type scales (compounds when nested) [source: references/02-page-mechanics.md]
+- Using color as the only signal for a UI state [source: references/03-visual-treatment.md]
+- Designing with placeholder images instead of real content [source: references/03-visual-treatment.md]
+- Shrinking a logo down to use as a favicon [source: references/03-visual-treatment.md]
+- Using preprocessor `lighten()` / `darken()` to derive shades [source: references/03-visual-treatment.md]
 
 ## Attribution
 

package/skills/refactoring-ui/references/05-motion.md

@@ -0,0 +1,124 @@
+# Motion: Microinteractions, Transitions, Hover
+
+> **Scope note**: motion is **not** covered in *Refactoring UI* by Adam Wathan & Steve Schoger. This file is complementary guidance, written in the same spirit as the book — favor restraint, build from a small fixed system, and avoid effects that exist to draw attention to themselves. It does not paraphrase the book.
+
+---
+
+## The Restraint Principle Carries Over
+
+The book's central idea — "make the right things stand out by quieting the rest" — applies directly to motion. Animation in a UI is for **communicating state changes**, not for entertainment.
+
+- If the user wouldn't notice the animation is gone, it shouldn't be there
+- If the animation shows that something happened (state change, success, error), keep it
+- "Wow" animations are a tax on every interaction after the first
+
+## Pre-Build a Motion System
+
+Like type/color/spacing scales, define a fixed menu of durations and easings up front. Pick from that menu instead of inventing per-component.
+
+**Sample duration scale (in milliseconds):**
+
+| Token | Duration | Use |
+|---|---|---|
+| `instant` | 0–80 | Press/active states. Should feel like no delay. |
+| `fast` | 100–200 | Hover effects, small state changes (icons, toggles, focus rings) |
+| `normal` | 200–400 | Modal/drawer entry, expand/collapse, page-level transitions |
+| `slow` | 400–600 | Decorative reveals, onboarding sequences |
+| `+1s` | ≥ 1000 | Almost always wrong in a working UI — reserve for very specific moments |
+
+**Sample easing scale:**
+
+| Token | Curve | Use |
+|---|---|---|
+| `enter` | `cubic-bezier(0, 0, 0.2, 1)` (ease-out) | Elements appearing — fast start, slow finish |
+| `exit` | `cubic-bezier(0.4, 0, 1, 1)` (ease-in) | Elements leaving — slow start, fast finish (they "fall away") |
+| `standard` | `cubic-bezier(0.4, 0, 0.2, 1)` (ease-in-out) | State changes that aren't directional |
+| `linear` | linear | Loaders, progress, anything tied to real time |
+
+## Animate Cheap Properties
+
+Only `transform` and `opacity` are GPU-composited and frame-stable. Animating other properties forces layout/paint per frame and stutters on mid-range hardware.
+
+| Cheap | Expensive |
+|---|---|
+| `transform: translate(...)`, `scale(...)`, `rotate(...)` | `width`, `height`, `top`, `left`, `margin`, `padding` |
+| `opacity` | `box-shadow` (animatable, but slow at large blur) |
+| `filter: blur()` (sparingly) | `background-color` on large surfaces |
+
+To slide a panel in: animate `transform: translateX(100%)` → `translateX(0)`, not `right: -400px` → `right: 0`.
+
+## Hover States
+
+The book's principle (use color/weight/contrast for hierarchy, not just one tool) applies to hover too — combine signals subtly.
+
+A solid hover combines two of:
+
+- A small lightness shift on the background (1–2 steps on your shade scale)
+- A border or shadow change
+- An icon color change
+
+Avoid:
+
+- Scaling up the whole element (1.05×, 1.1×) — chunky and dated
+- A bright glow — feels like 2008
+- Animating font size on hover — text reflow is jarring
+
+```css
+.button {
+  background: var(--brand-500);
+  transition: background-color 150ms cubic-bezier(0, 0, 0.2, 1);
+}
+.button:hover {
+  background: var(--brand-600);
+}
+```
+
+## Press / Active States
+
+Visual pressure should feel like the element was pushed *into* the page — the inverse of "raised."
+
+- Shadow shrinks or disappears
+- A tiny `transform: translateY(1px)` works for cards
+- The hover background usually deepens one more step on press
+
+Press states should feel **instant** — duration `instant` (0–80ms), not `fast`.
+
+## Loading
+
+In order of preference:
+
+1. **Optimistic UI** — assume success, update immediately, roll back on error. No spinner.
+2. **Skeleton screen** — placeholder shapes matching the final layout. Communicates structure while content loads.
+3. **Inline progress** — a thin progress bar at the top of the affected region, or shimmer on a single field.
+4. **Spinner** — only when 1–3 don't fit. Add a "Cancel" if the operation is long.
+
+Skeleton screens beat spinners because they reduce the perceived wait — the layout doesn't shift when content arrives.
+
+If you must use a spinner, **only show it after ~150ms** of waiting. Most operations finish faster than that; a spinner that flashes in and out is worse than no spinner.
+
+## Respect `prefers-reduced-motion`
+
+Some users disable motion at the OS level (motion sickness, vestibular disorders, focus). The browser exposes this preference:
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  * {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+```
+
+Or, more deliberately, swap motion for an instant state change inside specific components. Never disable a state change entirely (the user still needs to see that something happened) — only the *animation between* states.
+
+## Anti-Patterns
+
+- ❌ Animating layout-affecting properties (`width`, `top`, `margin`) — jank
+- ❌ One-off durations per component — kills consistency
+- ❌ Easing on a linear curve for entries — feels mechanical
+- ❌ Spinners that appear under 150ms — flashy noise
+- ❌ Decorative animations that fire on every page load — annoying by the second visit
+- ❌ Ignoring `prefers-reduced-motion` — accessibility regression
+- ❌ Long durations (>600ms) for state changes — feels sluggish