@maccesar/aiskills 1.12.0 → 1.15.0

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

package/skills/refactoring-ui/references/06-dark-mode.md

@@ -0,0 +1,117 @@
+# Dark Mode
+
+> **Scope note**: *Refactoring UI* was written before dark mode was an industry default and does not address it explicitly. **However**, the book's HSL chapter (in `03-visual-treatment.md`) — handpicking shades by hue/saturation/lightness, not deriving them via `lighten()`/`darken()` — is exactly the foundation dark mode needs. This file extends those principles to a second color mode.
+
+---
+
+## Don't Invert — Rebuild
+
+Inverting a light theme produces a "negative" image: muddy colors, weird text contrast, accents that lose punch. Dark mode is its own design pass.
+
+The bookkeeping change: every color token now has a **mode pair**. Plan for it from the start, even if you only ship light first.
+
+```css
+:root {
+  --bg-canvas: hsl(220 14% 96%);
+  --bg-surface: hsl(0 0% 100%);
+  --text-primary: hsl(220 13% 18%);
+  --text-secondary: hsl(220 9% 46%);
+  --border: hsl(220 13% 91%);
+  --brand-500: hsl(217 91% 60%);
+}
+
+:root[data-theme='dark'] {
+  --bg-canvas: hsl(220 13% 10%);
+  --bg-surface: hsl(220 13% 14%);
+  --text-primary: hsl(220 14% 96%);
+  --text-secondary: hsl(220 9% 65%);
+  --border: hsl(220 13% 22%);
+  --brand-500: hsl(217 91% 65%);   /* nudged lighter for dark bg */
+}
+```
+
+## Dark Backgrounds Aren't Black
+
+Pure `#000` reads as a hole in the screen. Pull the lightness up to ~8–12%, keep a small amount of saturation, and lean slightly warm or cool depending on your brand.
+
+| Backdrop | Lightness | Notes |
+|---|---|---|
+| App canvas (outermost) | 8–12% | Lowest layer — slightly tinted, not pure black |
+| Surface (cards, panels) | 12–16% | One step above canvas — implies "raised" without a shadow |
+| Elevated surface (modals, popovers) | 16–22% | Highest layer — even lighter |
+
+The trick: in dark mode, **lighter = closer to the viewer**, the opposite of light mode. A higher elevation doesn't get a darker shadow — it gets a lighter surface.
+
+## Text Contrast in Dark Mode
+
+Pure white text on a near-black background is *too much* contrast — the text vibrates and reading becomes tiring at length.
+
+- Primary text: ~96% lightness (slightly off-white) — e.g., `hsl(220 14% 96%)`
+- Secondary text: ~65% lightness — significantly muted compared to light mode's secondary
+- Tertiary / placeholder: ~45–50%
+
+WCAG ratios still apply (4.5:1 small text, 3:1 large), and slightly off-white still passes against a near-black canvas with room to spare.
+
+## Accent Colors Usually Need a Lightness Bump
+
+A brand color tuned for white backgrounds often looks too dark and dim against a dark canvas. Most palettes need the accent **lightness raised 5–10%** for the dark variant.
+
+Test against both backgrounds. If the brand color fails contrast in dark mode, derive a lighter variant rather than swapping for an unrelated color — keeps brand identity coherent.
+
+## Shadows: Mostly Gone, Sometimes Inverted
+
+Shadows are made of light obstruction. On a dark canvas, the absence of light is the canvas itself — a dark shadow on dark background is invisible.
+
+Options:
+
+1. **Skip shadows entirely**: use lighter surfaces and tinted borders to communicate elevation
+2. **Top highlight**: an inset top border (lighter color) to show that the element catches the imagined light source, with no shadow below
+3. **Very soft dark shadow**: works only when the element is on a lighter surface (e.g., a dropdown over the canvas) — large blur, low opacity
+
+A `box-shadow: 0 2px 4px rgba(0,0,0,0.3)` that was crisp in light mode is invisible on a `hsl(220 13% 10%)` canvas. Recheck every shadow when adding dark mode.
+
+## Images and Photos in Dark Mode
+
+Photos with bright backgrounds (typically light themes) "blow out" against a dark canvas — they pop too hard. Two tactics:
+
+- **Lower image brightness slightly** in dark mode (e.g., `filter: brightness(0.9)`) — only for decorative/hero images, never for content the user is reading
+- **Frame with a subtle border** — separates the bright rectangle from the dark canvas without dimming the photo
+
+Same principle for video posters and avatar images.
+
+## SVG Icons and Logos
+
+Single-color icons should be currentColor-driven so they pick up the mode's text color:
+
+```html
+<svg fill="currentColor" ...>
+```
+
+Multi-color logos need a dark variant. Don't fake it with `filter: invert()` — colors land in the wrong hue and brand recognition suffers.
+
+## Theme Toggle: Three Defaults
+
+1. **Match system preference** (`prefers-color-scheme`) — best first-paint experience
+2. **Respect explicit user override** — store in `localStorage`; persists across sessions
+3. **Apply before first paint** — set the theme class on `<html>` from a tiny inline script in `<head>` BEFORE any rendering, to avoid a flash of the wrong theme
+
+```html
+<script>
+  (function () {
+    var stored = localStorage.getItem('theme');
+    var prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+    var theme = stored || (prefersDark ? 'dark' : 'light');
+    document.documentElement.dataset.theme = theme;
+  })();
+</script>
+```
+
+## Anti-Patterns
+
+- ❌ Pure black (`#000`) for the canvas — feels like a void, hurts at length
+- ❌ Pure white text — vibrates against dark bg, tiring to read
+- ❌ `filter: invert(1)` to "do" dark mode — produces wrong hues, breaks images
+- ❌ Same brand color in both modes without checking contrast — fails WCAG silently
+- ❌ Keeping every shadow from light mode unchanged — invisible against dark bg
+- ❌ Theme toggle applied AFTER first paint — flash of opposite theme on every load
+- ❌ Inverting photos and screenshots — colors shift unnaturally, recognition suffers