@booklib/skills 1.2.0 → 1.3.1

package/CONTRIBUTING.md

@@ -0,0 +1,122 @@
+# Contributing
+
+Thanks for wanting to add a skill. A skill packages expert knowledge from a book into reusable instructions that AI agents can apply to real tasks.
+
+## What makes a good skill?
+
+A skill is worth adding when the source book:
+- Contains specific, actionable advice (not just general philosophy)
+- Covers a topic useful to software engineers or designers
+- Has enough depth to fill a meaningful SKILL.md (300+ lines)
+
+## Adding a new skill
+
+### 1. Create the folder
+
+```
+skill-name/
+├── SKILL.md          # Required
+├── examples/
+│   ├── before.md     # Code or artifact before applying the skill
+│   └── after.md      # The improved version
+└── evals/
+    └── evals.json    # Test cases
+```
+
+The folder name must be lowercase, hyphen-separated, and match the `name` field in `SKILL.md` exactly.
+
+### 2. Write SKILL.md
+
+```markdown
+---
+name: skill-name
+description: >
+  What this skill does and when to trigger it. Include specific
+  keywords agents should look for. Max 1024 characters.
+---
+
+# Skill Title
+
+You are an expert in [domain] grounded in [Book Title] by [Author].
+
+## When to use this skill
+
+[Describe trigger conditions — what user requests or code patterns activate this skill]
+
+## Core principles
+
+[The key ideas from the book, organized for an AI agent to apply]
+
+## How to apply
+
+[Step-by-step process the agent follows]
+
+## Examples
+
+[At least one concrete before/after showing the skill in action]
+```
+
+**Requirements:**
+- `name`: lowercase letters and hyphens only, matches folder name
+- `description`: 1–1024 characters, describes what it does AND when to use it
+- Body: clear instructions an AI agent can follow immediately
+
+**Keep SKILL.md under 500 lines.** Move deep reference material to `references/` and link to it.
+
+### 3. Add before/after examples
+
+`examples/before.md` — code or artifact that violates the book's principles.
+`examples/after.md` — the same thing improved by applying the skill.
+
+These power the `npx @booklib/skills demo <name>` command.
+
+### 4. Add evals
+
+`evals/evals.json` — array of test cases verifying the skill works:
+
+```json
+{
+  "evals": [
+    {
+      "id": "eval-01-short-description",
+      "prompt": "The prompt to send to the agent (include code or a scenario)",
+      "expectations": [
+        "The agent should do X",
+        "The agent should flag Y",
+        "The agent should NOT do Z"
+      ]
+    }
+  ]
+}
+```
+
+Aim for 3–5 evals per skill covering:
+1. A clear violation of the book's principles
+2. A subtle or intermediate case
+3. Already-good code (the agent should recognize it and not manufacture issues)
+
+### 5. Submit a PR
+
+```bash
+git checkout -b skill/book-name
+# add your skill folder
+git add skill-name/
+git commit -m "feat: add skill-name skill"
+gh pr create --title "feat: add skill-name" --body "..."
+```
+
+PR checklist:
+- [ ] Folder name matches `name` in SKILL.md
+- [ ] `description` is under 1024 characters
+- [ ] SKILL.md is under 500 lines
+- [ ] `examples/before.md` and `examples/after.md` exist
+- [ ] `evals/evals.json` has at least 3 test cases
+- [ ] README.md skills table updated
+
+## Requesting a skill
+
+Open an issue titled **"Skill Request: [Book Name]"** and describe why the book would make a good skill. Community members can then pick it up.
+
+## Questions
+
+Use [GitHub Discussions](../../discussions) for questions, ideas, and feedback.

package/README.md

@@ -63,7 +63,7 @@ npx @booklib/skills add effective-kotlin
 npx @booklib/skills add --all
 
 # Add globally (available in all projects)
-npx @booklib/skills add --all --global
+npx @booklib/skills add --all --globalcl
 
 # List available skills
 npx @booklib/skills list
@@ -79,6 +79,23 @@ git clone https://github.com/ZLStas/skills.git
 cp -r skills/effective-kotlin /path/to/project/.claude/skills/
 ```
 
+## Automatic Skill Routing
+
+You don't need to know which skill to apply — the **[skill-router](./skill-router/)** meta-skill does it for you.
+
+When an AI agent receives a task, it can invoke `skill-router` first to identify the 1–2 most relevant skills based on the file, language, domain, and work type. The router then returns a ranked recommendation with rationale, so the right expertise is applied automatically.
+
+```
+User: "Review my order processing service"
+
+→ skill-router selects:
+   Primary:   domain-driven-design   — domain model design (Aggregates, Value Objects)
+   Secondary: microservices-patterns — service boundaries and inter-service communication
+   Skip:      clean-code-reviewer    — premature at design stage; apply later on implementation code
+```
+
+This means skills compose: `skill-router` acts as an orchestrator that picks the right specialist skills for the context, without requiring the user to know the library upfront.
+
 ## Skills
 
 | Skill | Description |
@@ -89,13 +106,14 @@ cp -r skills/effective-kotlin /path/to/project/.claude/skills/
 | [data-pipelines](./data-pipelines/) | Data pipeline practices from James Densmore's *Data Pipelines Pocket Reference* — ingestion, streaming, transformation, and orchestration |
 | [design-patterns](./design-patterns/) | Apply and review GoF design patterns from *Head First Design Patterns* — creational, structural, and behavioral patterns |
 | [domain-driven-design](./domain-driven-design/) | Design and review software using patterns from Eric Evans' *Domain-Driven Design* — tactical and strategic patterns, and Ubiquitous Language |
-| [effective-python](./effective-python-skill/) | Python best practices from Brett Slatkin's *Effective Python* (2nd Edition) — Pythonic thinking, functions, classes, concurrency, and testing |
+| [effective-python](./effective-python/) | Python best practices from Brett Slatkin's *Effective Python* (2nd Edition) — Pythonic thinking, functions, classes, concurrency, and testing |
 | [effective-java](./effective-java/) | Java best practices from Joshua Bloch's *Effective Java* (3rd Edition) — object creation, generics, enums, lambdas, and concurrency |
 | [effective-kotlin](./effective-kotlin/) | Best practices from Marcin Moskała's *Effective Kotlin* (2nd Ed) — safety, readability, reusability, and abstraction |
 | [kotlin-in-action](./kotlin-in-action/) | Practices from *Kotlin in Action* (2nd Ed) — functions, classes, lambdas, nullability, and coroutines |
 | [lean-startup](./lean-startup/) | Practices from Eric Ries' *The Lean Startup* — MVP testing, validated learning, Build-Measure-Learn loop, and pivots |
 | [microservices-patterns](./microservices-patterns/) | Expert guidance on microservices patterns from Chris Richardson's *Microservices Patterns* — decomposition, sagas, API gateways, event sourcing, CQRS, and service mesh |
 | [refactoring-ui](./refactoring-ui/) | UI design principles from *Refactoring UI* by Adam Wathan & Steve Schoger — visual hierarchy, layout, typography, and color |
+| [skill-router](./skill-router/) | **Meta-skill.** Automatically selects the 1–2 most relevant skills for a given file, PR, or task — routes by language, domain, and work type with conflict resolution. Use this when the right skill isn't obvious, or let the AI invoke it automatically before applying any skill |
 | [storytelling-with-data](./storytelling-with-data/) | Data visualization and storytelling from Cole Nussbaumer Knaflic's *Storytelling with Data* — effective visuals, decluttering, and narrative structure |
 | [system-design-interview](./system-design-interview/) | System design principles from Alex Xu's *System Design Interview* — scaling, estimation, and real-world system designs |
 | [using-asyncio-python](./using-asyncio-python/) | Asyncio practices from Caleb Hattingh's *Using Asyncio in Python* — coroutines, event loop, tasks, and signal handling |

package/ROADMAP.md

@@ -0,0 +1,36 @@
+
+- [x] Add repo description: "Book knowledge distilled into AI agent skills — Clean Code, DDD, Effective Kotlin, and more"
+- [x] Add topics: `claude-code`, `agent-skills`, `anthropic-skills`, `ai-skills`, `claude-skills`, `effective-kotlin`, `clean-code`, `design-patterns`, `code-review`, `book-skills`
+- [x] Add website link (npm package page: https://www.npmjs.com/package/@booklib/skills)
+- [ ] Pin the repo on GitHub profile
+
+
+
+- [x] Keep generic name `@booklib/skills` on npm (already the case)
+- [x] Verify compatibility with agentskills.io spec for all `SKILL.md` files — fixed `effective-python-skill/` → `effective-python/` folder rename
+
+
+
+- [x] Add before/after examples to each skill's folder (`examples/before.md`, `examples/after.md`)
+- [x] Add `evals/` with real test cases for every skill
+
+
+
+- [x] Create `CONTRIBUTING.md` with guide on how to add a new book-skill
+- [x] Open 10 "Skill Request: [Book Name]" issues to invite contributions (#2–#11)
+- [x] Add GitHub Discussions to the repo
+
+
+
+- [x] Make `npx @booklib/skills list` output visually appealing with descriptions
+- [x] Add `--demo` flag showing before/after for each skill
+- [x] Add `--info <skill-name>` to preview what a skill does before installing
+- [ ] Write npm package README with GIFs showing the CLI in action
+
+
+
+- [x] Expand each skill to include `references/` docs with deeper content
+- [ ] Add `scripts/` with reusable automation where applicable
+- [x] Create a "skill quality checklist" and badge system for completeness (`QUALITY.md`)
+- [x] `skills check <name>` — automated quality validator (Bronze/Silver/Gold/Platinum)
+- [x] `skills eval <name>` — eval runner against Claude API (needs `ANTHROPIC_API_KEY`)

package/animation-at-work/evals/evals.json

@@ -0,0 +1,44 @@
+{
+  "evals": [
+    {
+      "id": "eval-01-no-easing-layout-properties-inconsistent-duration",
+      "prompt": "Review these CSS animations:\n\n```css\n/* Modal open animation */\n.modal {\n  display: none;\n  width: 600px;\n  padding: 40px;\n  background: white;\n  border-radius: 8px;\n  position: fixed;\n  top: 50%;\n  left: 50%;\n  margin-top: -200px;\n  margin-left: -300px;\n}\n\n.modal.visible {\n  display: block;\n  animation: modal-open 0.4s linear;\n}\n\n@keyframes modal-open {\n  from {\n    margin-top: -400px;\n    opacity: 0;\n    width: 400px;\n  }\n  to {\n    margin-top: -200px;\n    opacity: 1;\n    width: 600px;\n  }\n}\n\n/* Button hover */\n.btn:hover {\n  background-color: #0056b3;\n  padding: 14px 28px;\n  border-radius: 12px;\n  transition: all 2s linear;\n}\n\n/* Notification badge */\n.badge-new {\n  animation: pulse 0.8s linear infinite;\n}\n\n@keyframes pulse {\n  0%   { transform: scale(1); }\n  50%  { transform: scale(1.2); }\n  100% { transform: scale(1); }\n}\n```",
+      "expectations": [
+        "Flags `linear` easing on the modal open animation: linear motion feels robotic for UI elements entering the screen; recommends `ease-out` for elements entering (ease-out: fast start, gentle stop conveys natural deceleration)",
+        "Flags animating `margin-top` and `width` in the modal keyframes: these are layout properties that trigger full reflow on every frame; recommends replacing with `transform: translateY()` and `transform: scale()` or opacity (Ch 3 / Performance: only animate composite properties — transform and opacity)",
+        "Flags `transition: all 2s linear` on the button hover: 2 seconds is far too slow for a hover feedback interaction; functional UI feedback should be 100-200ms; recommends `transition: background-color 150ms ease-out` (Ch 1: duration guidance — micro-interactions 100-200ms)",
+        "Flags `transition: all` as an anti-pattern: it animates every changing property including layout properties like padding and border-radius that trigger reflow; recommends specifying only the intended properties",
+        "Flags animating `padding` and `border-radius` on the button hover for the same layout-thrashing reason",
+        "Flags the `linear` easing on the pulse badge animation: while linear is acceptable for continuous looping motion, there is no `prefers-reduced-motion` media query to disable or reduce this infinite animation for users with vestibular disorders",
+        "Notes the modal uses `display: none` switching to `display: block` which cannot be animated directly; the animation will jump; recommends using opacity/transform with visibility or pointer-events instead"
+      ]
+    },
+    {
+      "id": "eval-02-hover-animation-too-slow",
+      "prompt": "Review these CSS hover and focus animations:\n\n```css\n/* Navigation link hover */\n.nav-link {\n  color: #333;\n  text-decoration: none;\n  border-bottom: 2px solid transparent;\n  transition: border-bottom-color 1.5s ease-in-out,\n              color 1.5s ease-in-out;\n}\n\n.nav-link:hover,\n.nav-link:focus {\n  color: #0066cc;\n  border-bottom-color: #0066cc;\n}\n\n/* Card hover lift effect */\n.card {\n  box-shadow: 0 1px 3px rgba(0,0,0,0.12);\n  transition: box-shadow 1.2s ease,\n              top 1.2s ease;\n  position: relative;\n  top: 0;\n}\n\n.card:hover {\n  box-shadow: 0 8px 25px rgba(0,0,0,0.15);\n  top: -4px;\n}\n\n/* Icon button feedback */\n.icon-btn:active {\n  transform: scale(0.9);\n  transition: transform 800ms ease;\n}\n```",
+      "expectations": [
+        "Flags the 1.5s transition on `.nav-link` hover as far too slow for a hover feedback: users expect near-instant response (100-200ms) for hover states; a 1.5s delay makes the interface feel broken or laggy (Ch 1: duration guidance — micro-interactions 100-200ms; functional animations under 1s)",
+        "Flags the 1.2s transition on `.card` hover for the same reason: hover lift effects should be 150-250ms to feel responsive",
+        "Flags animating `top` on the card hover: `top` is a layout property that triggers reflow; recommends replacing with `transform: translateY(-4px)` which is GPU-accelerated (performance: animate composite properties only)",
+        "Flags animating `box-shadow` on the card: box-shadow is not a composite-only property (Ch. 3: only transform and opacity are GPU-composited and avoid layout/paint triggers); recommends replacing with a transform-based approach",
+        "Flags the 800ms active/press feedback on `.icon-btn`: press feedback should be the fastest animation in the UI (100-150ms); 800ms means the animation outlasts the press itself and confuses the user",
+        "Flags `ease-in-out` on all hover effects: `ease-in-out` is appropriate for elements that move and stay on screen, but for hover state changes `ease-out` is more natural (fast onset, settles gently)",
+        "Notes the absence of a `prefers-reduced-motion` media query anywhere in the stylesheet"
+      ]
+    },
+    {
+      "id": "eval-03-clean-animation-transform-opacity-consistent-easing",
+      "prompt": "Review these CSS and JavaScript animations:\n\n```css\n/* Dropdown menu enter/exit */\n.dropdown {\n  opacity: 0;\n  transform: translateY(-8px);\n  pointer-events: none;\n  transition: opacity 200ms ease-out,\n              transform 200ms ease-out;\n}\n\n.dropdown.open {\n  opacity: 1;\n  transform: translateY(0);\n  pointer-events: auto;\n}\n\n/* Toast notification slide-in */\n.toast {\n  transform: translateX(110%);\n  transition: transform 300ms ease-out;\n}\n\n.toast.show {\n  transform: translateX(0);\n}\n\n.toast.hide {\n  transform: translateX(110%);\n  transition: transform 200ms ease-in;\n}\n\n/* Button press feedback */\n.btn:active {\n  transform: scale(0.96);\n  transition: transform 100ms ease-in;\n}\n\n/* Reduced motion support */\n@media (prefers-reduced-motion: reduce) {\n  *,\n  *::before,\n  *::after {\n    animation-duration: 0.01ms !important;\n    animation-iteration-count: 1 !important;\n    transition-duration: 0.01ms !important;\n  }\n}\n```\n\n```js\n// Page section fade-in on scroll (Web Animations API)\ndocument.querySelectorAll('.section').forEach(section => {\n  const observer = new IntersectionObserver(entries => {\n    entries.forEach(entry => {\n      if (entry.isIntersecting) {\n        entry.target.animate(\n          [{ opacity: 0, transform: 'translateY(20px)' },\n           { opacity: 1, transform: 'translateY(0)' }],\n          { duration: 400, easing: 'ease-out', fill: 'forwards' }\n        );\n        observer.unobserve(entry.target);\n      }\n    });\n  }, { threshold: 0.15 });\n  observer.observe(section);\n});\n```",
+      "expectations": [
+        "Recognizes this is a well-designed set of animations and says so explicitly",
+        "Praises animating only `transform` and `opacity` throughout: these are GPU-composited properties that avoid layout reflow and paint (performance: composite-only properties)",
+        "Praises using `ease-out` for entering elements (dropdown open, toast show, scroll fade-in) and `ease-in` for exiting elements (toast hide) — correct easing directionality (Ch 1: ease-out for entering, ease-in for leaving)",
+        "Praises consistent duration scale: 100ms for press feedback, 200ms for dropdown, 300ms for toast entry, 400ms for scroll reveal — all within appropriate ranges and ordered by interaction importance (Ch 1: duration guidance)",
+        "Praises the `prefers-reduced-motion` media query that effectively disables all transitions and animations for users who need it (Ch 5: accessibility, vestibular disorders)",
+        "Praises `pointer-events: none` on the hidden dropdown to prevent interaction with invisible elements without removing from DOM (correct implementation detail)",
+        "Praises using Web Animations API with IntersectionObserver for scroll-triggered animations: avoids scroll-event jank and unobserves after trigger preventing repeat animations (Ch 3: Web Animations API for playback control)",
+        "Does NOT manufacture issues to appear thorough; any suggestions are explicitly framed as minor optional improvements"
+      ]
+    }
+  ]
+}

package/animation-at-work/examples/after.md

@@ -0,0 +1,64 @@
+# After
+
+The navigation drawer animation switches to composite-only properties (`transform` + `opacity`), uses `ease-out` easing, a 250ms duration, and respects `prefers-reduced-motion`.
+
+```css
+/* Nav drawer — animate only composite properties (transform, opacity) */
+.nav-drawer {
+  /* Position off-screen using transform — not width/height */
+  transform: translateX(-280px);
+  opacity: 0;
+  width: 280px;         /* fixed dimensions, never animated */
+  height: 100vh;
+  overflow: hidden;
+  background-color: #1a1a2e;
+  /* ease-out: fast start → gentle stop — natural for entering elements (Ch 1) */
+  transition:
+    transform 250ms ease-out,
+    opacity   200ms ease-out;
+  /* Hint the browser to promote this element to its own compositor layer */
+  will-change: transform;
+}
+
+.nav-drawer.open {
+  transform: translateX(0);
+  opacity: 1;
+}
+
+/* Menu items stagger in using animation-delay for follow-through (Ch 1) */
+.nav-drawer .menu-item {
+  opacity: 0;
+  transform: translateX(-12px);
+  transition:
+    opacity   180ms ease-out,
+    transform 180ms ease-out;
+}
+
+.nav-drawer.open .menu-item {
+  opacity: 1;
+  transform: translateX(0);
+}
+
+/* Stagger each item for natural overlapping action */
+.nav-drawer.open .menu-item:nth-child(1) { transition-delay: 60ms; }
+.nav-drawer.open .menu-item:nth-child(2) { transition-delay: 90ms; }
+.nav-drawer.open .menu-item:nth-child(3) { transition-delay: 120ms; }
+.nav-drawer.open .menu-item:nth-child(4) { transition-delay: 150ms; }
+
+/* Accessibility: remove all motion for users who prefer it (Ch 5) */
+@media (prefers-reduced-motion: reduce) {
+  .nav-drawer,
+  .nav-drawer .menu-item {
+    transition: opacity 150ms linear !important;
+    transform: none !important;
+  }
+}
+```
+
+Key improvements:
+- `transform: translateX()` replaces `width`/`height` animation — `transform` and `opacity` are the only composite-only properties that animate on the GPU without triggering layout recalculation (Ch 3: Performance — composite-only properties)
+- Duration reduced from 1.5s to 250ms — functional UI animations should be 200–500ms; 1.5s feels sluggish and blocks the user (Ch 1: Timing and duration)
+- `ease-out` replaces `linear` — entering elements should start fast and slow to a stop; linear easing feels robotic for UI elements (Ch 1: 12 Principles — ease in / ease out)
+- `will-change: transform` promotes the drawer to its own compositor layer, enabling smooth 60fps animation on mobile devices (Ch 3: will-change)
+- Staggered `transition-delay` on menu items creates overlapping action — the drawer and its children don't all stop simultaneously, producing a more natural feel (Ch 1: 12 Principles — follow-through and overlapping action)
+- `@media (prefers-reduced-motion: reduce)` is implemented — users with vestibular disorders receive a simple fade instead of a lateral sweep (Ch 5: Accessibility — prefers-reduced-motion)

package/animation-at-work/examples/before.md

@@ -0,0 +1,35 @@
+# Before
+
+A CSS animation on a navigation drawer that animates `width` and `height` (layout-triggering properties) with `linear` easing and a 1.5-second duration, with no `prefers-reduced-motion` support.
+
+```css
+.nav-drawer {
+  width: 0;
+  height: 0;
+  overflow: hidden;
+  background-color: #1a1a2e;
+}
+
+.nav-drawer.open {
+  width: 280px;
+  height: 100vh;
+  /* Animates layout properties — forces browser to recalculate layout
+     on every frame, causing jank on low-powered devices */
+  transition: width 1.5s linear, height 1.5s linear;
+}
+
+.nav-drawer .menu-item {
+  opacity: 0;
+  /* Also animates layout property margin */
+  margin-left: -280px;
+  transition: opacity 1.5s linear, margin-left 1.5s linear;
+}
+
+.nav-drawer.open .menu-item {
+  opacity: 1;
+  margin-left: 0;
+}
+
+/* No prefers-reduced-motion support — users with vestibular
+   disorders experience the full 1.5s sweep animation */
+```

package/animation-at-work/scripts/audit_animations.py

@@ -0,0 +1,295 @@
+#!/usr/bin/env python3
+"""
+audit_animations.py - Audit CSS/SCSS for animation anti-patterns.
+
+Usage:
+    python audit_animations.py <file_or_directory>
+
+Scans .css and .scss files for animation anti-patterns documented in
+"Animation at Work" by Rachel Nabors.
+
+Checks performed:
+  1. Animating layout-triggering properties (use transform instead)
+  2. transition: all (too broad)
+  3. Transitions > 500ms or animations > 1000ms (too slow)
+  4. Durations < 100ms (too fast to perceive)
+  5. linear easing on UI transitions (use ease-out or cubic-bezier)
+  6. Missing prefers-reduced-motion in files that animate
+  7. infinite animations without a pause mechanism
+
+Outputs: file, line, offending CSS, and recommended fix.
+Summary at end: total issues by category.
+"""
+
+import argparse
+import pathlib
+import re
+import sys
+from collections import defaultdict
+from typing import NamedTuple
+
+
+class Issue(NamedTuple):
+    file: str
+    line: int
+    category: str
+    snippet: str
+    advice: str
+
+
+# Properties that trigger layout recalculation — animating them is expensive.
+LAYOUT_TRIGGERING = [
+    "width", "height", "top", "left", "right", "bottom",
+    "margin", "margin-top", "margin-right", "margin-bottom", "margin-left",
+    "padding", "padding-top", "padding-right", "padding-bottom", "padding-left",
+]
+
+CATEGORIES = {
+    "layout_property": "Layout-triggering property animated",
+    "transition_all": "transition: all used",
+    "too_slow": "Duration too long (sluggish UI)",
+    "too_fast": "Duration too short (imperceptible)",
+    "linear_easing": "Linear easing on UI transition",
+    "no_reduced_motion": "Missing prefers-reduced-motion",
+    "infinite_no_pause": "Infinite animation without pause mechanism",
+}
+
+
+def parse_duration_ms(value: str) -> float | None:
+    """Convert a CSS duration string (e.g. '0.3s', '300ms') to milliseconds."""
+    value = value.strip()
+    if value.endswith("ms"):
+        try:
+            return float(value[:-2])
+        except ValueError:
+            return None
+    if value.endswith("s"):
+        try:
+            return float(value[:-1]) * 1000
+        except ValueError:
+            return None
+    return None
+
+
+def find_css_files(path: pathlib.Path) -> list[pathlib.Path]:
+    if path.is_file():
+        if path.suffix in {".css", ".scss"}:
+            return [path]
+        print(f"WARNING: {path} is not a .css or .scss file — skipping.")
+        return []
+    return sorted(path.rglob("*.css")) + sorted(path.rglob("*.scss"))
+
+
+def audit_file(filepath: pathlib.Path) -> list[Issue]:
+    issues: list[Issue] = []
+    try:
+        lines = filepath.read_text(encoding="utf-8", errors="replace").splitlines()
+    except OSError as exc:
+        print(f"ERROR reading {filepath}: {exc}")
+        return []
+
+    file_str = filepath.as_posix()
+    full_text = "\n".join(lines)
+
+    has_animation = bool(
+        re.search(r"\b(transition|animation)\s*:", full_text)
+    )
+    has_reduced_motion = "prefers-reduced-motion" in full_text
+
+    for lineno, raw_line in enumerate(lines, start=1):
+        line = raw_line.strip()
+        if not line or line.startswith("//") or line.startswith("/*"):
+            continue
+
+        # 1. Animating layout-triggering properties
+        transition_match = re.match(r"transition\s*:\s*(.+)", line, re.IGNORECASE)
+        if transition_match:
+            props_part = transition_match.group(1)
+            for prop in LAYOUT_TRIGGERING:
+                if re.search(r"\b" + re.escape(prop) + r"\b", props_part, re.IGNORECASE):
+                    issues.append(Issue(
+                        file=file_str,
+                        line=lineno,
+                        category="layout_property",
+                        snippet=line[:120],
+                        advice=(
+                            f"Animating '{prop}' triggers layout recalculation on every frame. "
+                            "Use 'transform: translate/scale' or 'opacity' instead — "
+                            "these are compositor-only and do not cause reflow."
+                        ),
+                    ))
+
+        # 2. transition: all
+        if re.search(r"transition\s*:\s*all\b", line, re.IGNORECASE):
+            issues.append(Issue(
+                file=file_str,
+                line=lineno,
+                category="transition_all",
+                snippet=line[:120],
+                advice=(
+                    "'transition: all' animates every animatable property, including "
+                    "layout-triggering ones you may not intend. List specific properties: "
+                    "e.g., 'transition: opacity 0.2s ease-out, transform 0.2s ease-out'."
+                ),
+            ))
+
+        # 3 & 4. Duration checks — transition and animation shorthand
+        duration_patterns = [
+            re.compile(r"transition\s*:[^;]+", re.IGNORECASE),
+            re.compile(r"animation\s*:[^;]+", re.IGNORECASE),
+            re.compile(r"transition-duration\s*:\s*([^;]+)", re.IGNORECASE),
+            re.compile(r"animation-duration\s*:\s*([^;]+)", re.IGNORECASE),
+        ]
+        for pat in duration_patterns:
+            m = pat.search(line)
+            if not m:
+                continue
+            value_str = m.group(0)
+            is_animation = "animation" in value_str.lower() and "transition" not in value_str.lower()
+            for dur_match in re.finditer(r"\d+(?:\.\d+)?(?:ms|s)\b", value_str):
+                dur_ms = parse_duration_ms(dur_match.group(0))
+                if dur_ms is None:
+                    continue
+                slow_limit = 1000 if is_animation else 500
+                if dur_ms > slow_limit:
+                    issues.append(Issue(
+                        file=file_str,
+                        line=lineno,
+                        category="too_slow",
+                        snippet=line[:120],
+                        advice=(
+                            f"Duration {dur_ms:.0f}ms feels sluggish for UI feedback. "
+                            f"Keep UI transitions under {slow_limit}ms. "
+                            "Aim for 200-300ms for most interactions."
+                        ),
+                    ))
+                elif dur_ms < 100 and dur_ms > 0:
+                    issues.append(Issue(
+                        file=file_str,
+                        line=lineno,
+                        category="too_fast",
+                        snippet=line[:120],
+                        advice=(
+                            f"Duration {dur_ms:.0f}ms is below the human perception threshold (~100ms). "
+                            "The animation will not be noticed. Use 100-200ms for snappy transitions."
+                        ),
+                    ))
+
+        # 5. Linear easing on transitions
+        if re.search(r"transition\s*:", line, re.IGNORECASE):
+            if re.search(r"\blinear\b", line, re.IGNORECASE):
+                issues.append(Issue(
+                    file=file_str,
+                    line=lineno,
+                    category="linear_easing",
+                    snippet=line[:120],
+                    advice=(
+                        "Linear easing feels mechanical and unnatural for UI elements. "
+                        "Use 'ease-out' for elements entering the screen, 'ease-in' for "
+                        "elements leaving, or a custom cubic-bezier for branded motion."
+                    ),
+                ))
+
+        # 7. Infinite animation without pause mechanism
+        if re.search(r"animation-iteration-count\s*:\s*infinite\b", line, re.IGNORECASE):
+            # Check nearby lines (±10) for a paused state or play-state control
+            start = max(0, lineno - 10)
+            end = min(len(lines), lineno + 10)
+            context_block = "\n".join(lines[start:end])
+            if "animation-play-state" not in context_block and "paused" not in context_block:
+                issues.append(Issue(
+                    file=file_str,
+                    line=lineno,
+                    category="infinite_no_pause",
+                    snippet=line[:120],
+                    advice=(
+                        "Infinite animations can be distracting and drain battery on mobile. "
+                        "Add 'animation-play-state: paused' controlled via :hover, :focus, "
+                        "or a JS toggle so users can pause it."
+                    ),
+                ))
+
+    # 6. Missing prefers-reduced-motion
+    if has_animation and not has_reduced_motion:
+        issues.append(Issue(
+            file=file_str,
+            line=0,
+            category="no_reduced_motion",
+            snippet="(entire file)",
+            advice=(
+                "This file contains animations but no '@media (prefers-reduced-motion: reduce)' "
+                "block. Add one to disable or reduce motion for users who request it — "
+                "required for WCAG 2.1 AA compliance."
+            ),
+        ))
+
+    return issues
+
+
+def print_issues(issues: list[Issue]) -> None:
+    for issue in issues:
+        loc = f"{issue.file}:{issue.line}" if issue.line else issue.file
+        category_label = CATEGORIES.get(issue.category, issue.category)
+        print(f"\n[{category_label}]")
+        print(f"  Location : {loc}")
+        print(f"  CSS      : {issue.snippet}")
+        print(f"  Fix      : {issue.advice}")
+
+
+def print_summary(issues: list[Issue]) -> None:
+    counts: dict[str, int] = defaultdict(int)
+    for issue in issues:
+        counts[issue.category] += 1
+    print("\n" + "=" * 60)
+    print("SUMMARY")
+    print("=" * 60)
+    if not counts:
+        print("No issues found.")
+        return
+    for cat, label in CATEGORIES.items():
+        count = counts.get(cat, 0)
+        if count:
+            print(f"  {count:3d}  {label}")
+    print(f"  ---")
+    print(f"  {sum(counts.values()):3d}  Total issues")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Audit CSS/SCSS files for animation anti-patterns."
+    )
+    parser.add_argument(
+        "path",
+        help="A .css/.scss file or directory to scan recursively.",
+    )
+    args = parser.parse_args()
+
+    target = pathlib.Path(args.path)
+    if not target.exists():
+        print(f"ERROR: Path not found: {target}")
+        sys.exit(1)
+
+    files = find_css_files(target)
+    if not files:
+        print("No .css or .scss files found.")
+        sys.exit(0)
+
+    print(f"Scanning {len(files)} file(s) ...\n")
+
+    all_issues: list[Issue] = []
+    for f in files:
+        file_issues = audit_file(f)
+        all_issues.extend(file_issues)
+
+    if all_issues:
+        print_issues(all_issues)
+    else:
+        print("No animation anti-patterns detected.")
+
+    print_summary(all_issues)
+
+    sys.exit(1 if all_issues else 0)
+
+
+if __name__ == "__main__":
+    main()