@caddis/cli 0.3.0 → 0.4.0

package/bundles/codex/.codex/skills/docs/writing-plans/SKILL.md

@@ -0,0 +1,387 @@
+---
+name: writing-plans
+context: fork
+description: Use when you have a spec or requirements for a multi-step task, before touching code
+---
+
+# Writing Plans
+
+## Overview
+
+Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.
+
+Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.
+
+**Announce at start:** "I'm using the writing-plans skill to create the implementation plan."
+
+**Context:** This should be run in a dedicated worktree (created by brainstorming skill).
+
+> **Prefer `/caddis:feature-plan`.** It is the canonical planning entry point and produces a plan
+> the harness can resume, track and gate. This skill remains for free-form planning prose.
+
+**Save plans to:** `.caddis/plans/YYYY-MM-DD-<feature-name>.md`
+
+**Document metadata:** Before creating or updating a plan, apply `.github/instructions/document-frontmatter.instructions.md`. The YAML frontmatter block must be the first content in the file. New plans require `Original Author`, `Creation Date`, and `Creating Model`; revised plans must preserve those fields and add or update `Last Author`, `Last Updated`, and `Last Model Used`.
+
+## Bite-Sized Task Granularity
+
+**Each step is one action (2-5 minutes):**
+- "Write the failing test" - step
+- "Run it to make sure it fails" - step
+- "Implement the minimal code to make the test pass" - step
+- "Run the tests and make sure they pass" - step
+- "Commit" - step
+
+## Plan Document Header
+
+**Every plan MUST start with this header (YAML frontmatter first, then title):**
+
+```markdown
+---
+chain_id: <chain_id>
+type: plan
+status: current
+approval: pending
+Original Author: <active author or agent name>
+Creation Date: <YYYY-MM-DDTHH:MM:SSZ>
+Creating Model: <exact runtime model identifier or display name>
+---
+
+# [Feature Name] Implementation Plan
+
+> **For the implementing agent:** Follow this plan task-by-task, executing each step sequentially.
+
+**Goal:** [One sentence describing what this builds]
+
+**Architecture:** [2-3 sentences about approach]
+
+**Tech Stack:** [Key technologies/libraries]
+
+---
+```
+
+> ⚠️ The YAML frontmatter block (`---` delimiters) is required for Orchestrator artefact contract validation. Do NOT use blockquote-style metadata (`> **approval:** pending`) — it will not be parsed.
+> Preserve the original metadata fields on later edits, and add or update `Last Author`, `Last Updated`, and `Last Model Used` when the plan is revised. Use full ISO 8601 UTC timestamps for `Creation Date` and `Last Updated`.
+
+## Task Structure
+
+```markdown
+### Task N: [Component Name]
+
+**Files:**
+- Create: `exact/path/to/file.py`
+- Modify: `exact/path/to/existing.py:123-145`
+- Test: `tests/exact/path/to/test.py`
+
+**Step 1: Write the failing test**
+
+```python
+def test_specific_behavior():
+    result = function(input)
+    assert result == expected
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `pytest tests/path/test.py::test_name -v`
+Expected: FAIL with "function not defined"
+
+**Step 3: Write minimal implementation**
+
+```python
+def function(input):
+    return expected
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `pytest tests/path/test.py::test_name -v`
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add tests/path/test.py src/path/file.py
+git commit -m "feat: add specific feature"
+```
+```
+
+## Manual Execution Protocol
+
+**Every plan MUST include a Manual Execution Protocol section** at the top (after header, before phases). This tells the user exactly how to run each phase session:
+
+```markdown
+## Manual Execution Protocol
+
+For each phase below, follow this workflow:
+
+1. **Open** a new chat session with the agent specified in the phase header
+2. **Load skills** listed in the phase's "Skills to load" section
+3. **Attach files** listed in the phase's "Files to attach" section
+4. **Paste** the self-contained Phase Prompt into the chat
+5. **Validate** using the phase's Validation Checklist — every item must pass
+6. **Get green light** before moving to the next phase
+
+**Drift rule:** If you find bugs introduced by Phase N, fix them in the SAME session
+before starting Phase N+1. Never carry implementation debt forward between phases.
+
+**Dependency sequencing rule:** Write phases in execution order \u2014 every phase's dependencies must appear before that phase in the plan. If Phase 3 requires output from Phase 4, reorder before writing. No forward dependencies.
+```
+
+## Phase 0 — Context & Decisions
+
+**Every multi-phase plan MUST include a Phase 0** before the implementation phases. Phase 0 is not an implementation phase — it is a ground-truth inventory that prevents agents from making assumptions.
+
+Phase 0 contains four mandatory tables:
+
+### Technology Decision Table
+
+```markdown
+### Technology Decisions
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| Charting library | Recharts | Tree-shakeable, React-native, typed API |
+| Animation | Framer Motion | AnimatePresence for tab transitions, spring physics |
+| State management | Zustand | Lightweight, no boilerplate, devtools support |
+| ... | ... | ... |
+```
+
+Every technology choice that is NOT already in `project-config.md` must appear here with a rationale.
+
+### Data Parity / Availability Matrix
+
+```markdown
+### Data Availability
+
+| Feature / Tab | Data Field | Available? | Strategy |
+|---------------|-----------|------------|----------|
+| Executive Overview | `ceoInsight` | ✅ Full | Live API |
+| Product Deep-Dive | `satisfactionScores` | ❌ Empty `{}` | Show empty state: "Coming in future release" |
+| Geography | `byGeography` | ⚠️ Partial (was present May-Oct) | Show empty state with explanation |
+| ... | ... | ... | ... |
+```
+
+For any data field that may be empty, partial, or absent: document the exact empty state message text.
+
+### Existing Scaffold Audit
+
+```markdown
+### Existing Scaffold — DO NOT Recreate
+
+| File | Purpose | Current State |
+|------|---------|---------------|
+| `frontend/src/api/client.ts` | API client with JWT auth | ✅ Working — build on top |
+| `frontend/src/types/nps.ts` | 30+ TypeScript interfaces | ✅ Working — import, don't recreate |
+| `frontend/src/components/layout/AppShell.tsx` | App shell | ⚠️ Cold zinc theme — needs warm overhaul |
+| ... | ... | ... |
+```
+
+The "Current State" column tells agents what exists and whether to modify or leave it alone.
+
+### Dependency Split
+
+```markdown
+### Dependencies
+
+**Already installed** (DO NOT reinstall):
+- react, react-dom, typescript, vite
+- @tanstack/react-query, @tanstack/react-router
+- tailwindcss, zustand
+
+**Not yet installed** (install in Phase 1):
+- recharts, framer-motion, leaflet, react-leaflet
+- d3-force, d3-scale
+```
+
+## Enhanced Per-Phase Template
+
+**Every implementation phase MUST use this structure.** The sections OUTSIDE the prompt block are for the user (what to prepare before opening a session). The prompt block is for the agent (what to paste into the session).
+
+```markdown
+## Phase N — {Name}
+
+**Agent:** `@{agent-name}`
+**Objective:** {One sentence describing what this phase builds}
+
+### Skills to load
+
+- `.github/skills/{path}/SKILL.md` — {why}
+- `.github/skills/{path}/SKILL.md` — {why}
+
+### Instructions to follow
+
+- `.github/instructions/{name}.instructions.md`
+- `.github/instructions/{name}.instructions.md`
+
+### Files to attach
+
+- `path/to/file.ext` — {why this file is needed}
+- `path/to/file.ext` (from Phase N-1)
+- `.caddis/plans/{this-plan}.md` (this file)
+
+### Phase Prompt
+
+\`\`\`
+{Self-contained prompt — copy-paste ready. 30-60 lines.
+References plan sections for detail. Does NOT duplicate code blocks.
+Includes PRINCIPLES, SKILLS TO READ, IMPORTANT warnings, and numbered deliverable list.}
+\`\`\`
+
+### What to build
+
+#### N.1 {Deliverable Name}
+
+**File:** `exact/path/to/file.ext`
+
+{Component interface / function signature}
+
+**Data binding:**
+- Uses `data.field.path` for {purpose}
+- Uses `data.other.field` for {purpose}
+
+**Behavior:**
+- {Specific interactive behavior}
+- {Animation spec with exact values}
+
+**Empty state:** When `data.field` is `{}` or `[]`:
+> "{Exact message text to display}"
+
+**IMPORTANT:** {Trap-specific warning — e.g., "DO NOT recreate api/client.ts",
+"field uses snake_case in BOTH API and TS types — no transformation needed"}
+
+#### N.2 {Next Deliverable}
+...
+
+### Validation Checklist — Phase N complete when
+
+- [ ] `npm run build` succeeds (or equivalent build command)
+- [ ] {Specific behavioral criterion — e.g., "KpiFlipCard flip animation works independently on each card"}
+- [ ] {Data binding criterion — e.g., "NpsSummaryTable renders 5 rows with correct data from surveys + trend"}
+- [ ] {Visual criterion — e.g., "Dark mode: all components render correctly with soft dark tokens"}
+- [ ] {Integration criterion — e.g., "Row click switches to Tab 2 and scrolls to chart"}
+- [ ] Zero hardcoded data — all from props/hooks
+- [ ] Zero hardcoded colors — all from CSS vars or constants
+```
+
+### Key rules for the "What to build" subsections
+
+1. **Data binding is mandatory for UI components.** Every component spec must list the exact JSON field paths it consumes (e.g., `surveys.{product}.nps`, `trend.historicalNPS.byProduct.{product}`). This eliminates the #1 implementer failure mode: guessing which field to bind.
+
+2. **Empty state specs are mandatory.** For every data field that might be empty, specify the exact message text. Do NOT say "show appropriate empty state" — write the message.
+
+3. **IMPORTANT warnings for traps.** If a file already exists and must NOT be recreated, say so. If a field uses unexpected casing (snake_case where camelCase is expected), warn explicitly. These prevent the most common implementation errors.
+
+4. **Complete code blocks when the component is foundational.** For theme files, config files, utility functions, and CSS — include the full source code in the plan. For application components — specify interface, behavior, and data binding; let the agent write the implementation.
+
+## Remember
+- Exact file paths always
+- Complete code in plan (not "add validation")
+- Exact commands with expected output
+- Reference relevant skills with @ syntax
+- DRY, YAGNI, TDD, frequent commits
+- **Every phase MUST end with a numbered exit gate task** (e.g., "Task N.X: Exit Gate") that includes pass/fail checks, commit message format, and an explicit "STOP — do not proceed to next phase" instruction
+- **Every phase/step must specify the executing agent and include a ready-to-use prompt with `═══ PROMPT START` / `═══ PROMPT END` markers**
+- **Use 4-backtick fences (`` ```` ``) for the outer prompt block** so nested code blocks render correctly
+- **After writing all phases, run the Cross-Reference Audit against ALL source documents**
+- **Every plan MUST include a Manual Execution Protocol and Phase 0 — Context & Decisions**
+- **Every UI phase MUST include data binding specs (exact JSON paths) per component**
+- **Every data field that might be empty MUST have an explicit empty state message**
+- **Drift rule: fix bugs from Phase N before starting Phase N+1**
+
+## Cross-Reference Audit
+
+**Run this AFTER all phases are written, BEFORE finalizing the plan.**
+
+Walk through every FR, NFR, risk, and design decision from ALL input documents. For each, verify it maps to a specific, actionable plan step. Output a traceability matrix:
+
+```markdown
+## Source Document Traceability
+
+| Requirement | Source | Plan Phase/Step | Status |
+|-------------|--------|-----------------|--------|
+| FR-101 | PRD §3.1 | Phase 1, Step 2 | ✅ Covered |
+| NFR-208 | PRD §4.2 | Phase 5, Step 1 | ✅ Covered |
+| Risk-003 | Arch §9 | Phase 3, Step 3 | ✅ Covered |
+| ALT-002 | Arch §7.4 | N/A | ⚠️ Out of Scope — rationale: deferred to v2 |
+```
+
+**Rules:**
+- A requirement without a plan step → add a step or mark "Out of Scope" with rationale
+- A cited section reference (§N) → verify the section number matches the actual document
+- Zero-tolerance: no unmapped requirements in a finalized plan
+
+## Agent & Prompt Assignment
+
+**Every phase/step MUST include a ready-to-use prompt block.** This is non-negotiable because plans are executed across multiple sessions by different agents.
+
+### Prompt Block Template
+
+> **CRITICAL**: Use 4-backtick fences (` ```` `) for the outer prompt block so nested code blocks (yaml, python, etc.) inside the prompt render correctly. Add `═══ PROMPT START` and `═══ PROMPT END` markers so users can clearly see where to copy from/to.
+
+```markdown
+### Ready-to-Use Prompt (Phase N — Step M)
+
+> **How to use:** Copy the prompt block below (between ═══ START and ═══ END markers) into a new chat session. **Include all code blocks** — they're context for the agent, not for you to apply manually.
+> **Agent:** `@{agent-name}` (see `.github/agents/{agent-name}.agent.md`)
+> **Skills to load:** `.github/skills/{skill-path}/SKILL.md`
+> **Instructions (auto-applied):** `{instruction1}.instructions.md`, `{instruction2}.instructions.md`
+> **Project config:** `.github/project-config.md` (profile: `{profile}`)
+
+> ═══ PROMPT START — Copy everything between START and END into a new chat ═══
+
+\`\`\`\`
+{One-sentence task description}
+
+**Agent context:** You are the `@{agent-name}` agent. Load `.github/project-config.md` before starting.
+
+**Read these files FIRST (in order):**
+1. `.caddis/plans/{plan-file}.md` — **THIS PLAN** — read "Phase N — Step M"
+2. {Architecture/PRD doc} — {specific sections}
+3. {Target file(s)} — current state
+
+**What to do:**
+- {Actionable instruction 1}
+- {Actionable instruction 2}
+
+**Acceptance criteria:**
+- {Testable criterion 1}
+- {Testable criterion 2}
+
+**Scope boundary:**
+- Exit gate: Task N.X (the last task in this phase)
+- Do NOT proceed to Phase N+1 after the exit gate passes
+- Do NOT offer additional work beyond the exit gate tasks
+- Commit with: `feat({feature}): Phase N — {description}` and STOP
+\`\`\`\`
+
+> ═══ PROMPT END ═══════════════════════════════════════════════════════════
+```
+
+### Agent Selection Guide
+
+| Task Type | Agent | Agent File |
+|-----------|-------|------------|
+| Models, services, logic | `@implement` | `implement.agent.md` |
+| Streamlit UI, components | `@streamlit-developer` | `streamlit-developer.agent.md` |
+| Tests, fixtures | `@tester` | `tester.agent.md` |
+| SQL queries, schema | `@sql-expert` | `sql-expert.agent.md` |
+| Docs, README | `@docs` | `docs.agent.md` |
+| Code review | `@code-review` | `code-review.agent.md` |
+
+## Execution Handoff
+
+After saving the plan, offer execution choice:
+
+**"Plan complete and saved to `.caddis/plans/<filename>.md`. Two execution options:**
+
+**1. This session** — I implement each task sequentially, reviewing between tasks
+
+**2. Separate session** — Open a new session with the `@implement` agent and provide the plan path
+
+**Which approach?"**
+
+**If separate session chosen:**
+- Guide them to open new session
+- Reference the `@implement` agent (`.github/agents/implement.agent.md`)
+- Provide the plan file path for the implementing agent to read

package/bundles/codex/.codex/skills/frontend/css-architecture/SKILL.md

@@ -0,0 +1,305 @@
+---
+name: css-architecture
+description: CSS architecture, design token strategy, Tailwind conventions, CSS Modules, container queries, dark mode, responsive patterns, and animation architecture. Use for design token naming, CSS custom properties, Tailwind config, container queries, dark mode implementation, fluid typography, or CSS animation decisions. Complements frontend-design (what to achieve) with how to implement it.
+---
+
+# CSS Architecture Skill
+
+How to implement what `frontend-design` specifies. Covers design token strategy, Tailwind conventions, responsive patterns, dark mode, and animation architecture.
+
+## 1. Design Token Strategy — CSS Custom Properties
+
+### Hierarchy (global → component)
+```css
+/* Layer 1: Primitive tokens (raw values) */
+:root {
+  --color-slate-900: #0f172a;
+  --color-slate-100: #f1f5f9;
+  --color-amber-500: #f59e0b;
+  --space-4: 1rem;
+  --space-8: 2rem;
+  --radius-md: 0.5rem;
+  --font-sans: 'Inter Variable', system-ui, sans-serif;
+
+  /* Layer 2: Semantic tokens (intent) */
+  --color-bg: var(--color-slate-900);
+  --color-surface: hsl(220 15% 12%);
+  --color-text: var(--color-slate-100);
+  --color-accent: var(--color-amber-500);
+  --color-border: hsl(220 15% 20%);
+
+  /* Layer 3: Component tokens */
+  --button-bg: var(--color-accent);
+  --button-text: var(--color-slate-900);
+  --card-padding: var(--space-8);
+}
+```
+
+### Naming Conventions
+- Primitive: `--color-{hue}-{shade}`, `--space-{n}`, `--radius-{size}`
+- Semantic: `--color-{role}` (bg, surface, text, accent, border, error, success)
+- Component: `--{component}-{property}` (button-bg, card-radius)
+- Never skip semantic layer — primitives must not be used directly in components.
+
+## 2. Tailwind Conventions
+
+### v3 Config (`tailwind.config.ts`)
+```ts
+import type { Config } from 'tailwindcss'
+import { fontFamily } from 'tailwindcss/defaultTheme'
+
+const config: Config = {
+  content: ['./src/**/*.{ts,tsx,mdx}'],
+  darkMode: 'class',  // or 'media'
+  theme: {
+    extend: {
+      colors: {
+        // Map to CSS custom properties so tokens work everywhere
+        bg: 'hsl(var(--color-bg) / <alpha-value>)',
+        surface: 'hsl(var(--color-surface) / <alpha-value>)',
+        accent: 'hsl(var(--color-accent) / <alpha-value>)',
+        border: 'hsl(var(--color-border) / <alpha-value>)',
+      },
+      fontFamily: {
+        sans: ['var(--font-sans)', ...fontFamily.sans],
+        display: ['var(--font-display)', ...fontFamily.serif],
+      },
+      borderRadius: { DEFAULT: 'var(--radius-md)' },
+      animation: {
+        'fade-up': 'fadeUp 0.4s ease-out',
+        'fade-in': 'fadeIn 0.3s ease-out',
+      },
+      keyframes: {
+        fadeUp: { from: { opacity: '0', transform: 'translateY(12px)' }, to: { opacity: '1', transform: 'none' } },
+        fadeIn: { from: { opacity: '0' }, to: { opacity: '1' } },
+      },
+    },
+  },
+  plugins: [
+    require('@tailwindcss/typography'),
+    require('@tailwindcss/container-queries'),
+  ],
+}
+export default config
+```
+
+### v4 Config (CSS-first)
+```css
+/* globals.css — Tailwind v4 uses @theme, no tailwind.config.ts */
+@import "tailwindcss";
+
+@theme {
+  --color-accent: oklch(75% 0.18 85);
+  --font-sans: 'Inter Variable', system-ui, sans-serif;
+  --radius-default: 0.5rem;
+}
+```
+
+### `@apply` Rules
+- Use `@apply` sparingly — only for repeated utility combos in shared components (`btn`, `card`).
+- Prefer component classes over `@apply` in large components — Tailwind utility classes in JSX are more readable.
+- Never `@apply` responsive or state variants (`hover:`, `md:`) — those are JSX-only.
+
+## 3. CSS Modules vs Tailwind — Decision Criteria
+
+| Use Tailwind | Use CSS Modules |
+|---|---|
+| UI components, layouts, spacing | Complex animations with `@keyframes` that need JS access |
+| Responsive design | Component styles that conflict with Tailwind's reset |
+| Dark mode | Styles requiring CSS `calc()` with token math |
+| One-off utility combos | Legacy codebases with existing `.module.css` patterns |
+| New projects | Server-rendered styles that must avoid className hydration |
+
+**Hybrid**: Tailwind for layout/spacing/color, CSS Modules for complex animation or context-dependent logic.
+
+## 4. Container Queries
+
+Responsive based on parent container width, not viewport.
+
+```tsx
+// tailwind.config.ts: add @tailwindcss/container-queries plugin
+// Install: pnpm add -D @tailwindcss/container-queries
+
+export function Card({ children }: { children: React.ReactNode }) {
+  return (
+    // Mark the container
+    <div className="@container rounded-lg bg-surface p-6">
+      <div className="grid @sm:grid-cols-2 @lg:grid-cols-3 gap-4">
+        {children}
+      </div>
+    </div>
+  )
+}
+```
+
+```css
+/* Pure CSS container queries */
+.card { container-type: inline-size; }
+
+@container (min-width: 400px) {
+  .card-body { display: grid; grid-template-columns: 1fr 1fr; }
+}
+```
+
+**Use container queries when**: a component is used in multiple layout contexts (sidebar vs main vs modal) and needs different layouts in each.
+
+## 5. Dark Mode
+
+### Class Toggle (recommended for app control)
+```tsx
+// Toggle on <html> element
+document.documentElement.classList.toggle('dark')
+
+// Tailwind: darkMode: 'class' in config
+// CSS: dark: prefix on utilities
+<div className="bg-white dark:bg-slate-900 text-slate-900 dark:text-slate-100">
+```
+
+### CSS Custom Property Token Switching
+```css
+:root {
+  --color-bg: hsl(0 0% 100%);
+  --color-text: hsl(220 15% 10%);
+  --color-accent: hsl(220 90% 55%);
+}
+
+.dark {
+  --color-bg: hsl(220 15% 8%);
+  --color-text: hsl(220 10% 90%);
+  --color-accent: hsl(220 90% 65%);
+}
+
+/* With prefers-color-scheme fallback */
+@media (prefers-color-scheme: dark) {
+  :root:not(.light) {
+    --color-bg: hsl(220 15% 8%);
+    --color-text: hsl(220 10% 90%);
+  }
+}
+```
+
+## 6. Responsive Patterns — Mobile-First
+
+```tsx
+// Mobile-first: base = mobile, md: = tablet, lg+ = desktop
+<div className="
+  flex flex-col gap-4          /* mobile */
+  md:flex-row md:gap-6         /* tablet */
+  lg:gap-8                     /* desktop */
+">
+```
+
+### Fluid Typography with `clamp()`
+```css
+/* Min, preferred (viewport-relative), max */
+.hero-heading {
+  font-size: clamp(2rem, 5vw + 1rem, 5rem);
+  line-height: clamp(1.1, 1.2, 1.3);
+}
+
+/* In Tailwind (custom utility) */
+/* tailwind.config.ts > theme.extend.fontSize */
+'fluid-xl': 'clamp(1.5rem, 3vw + 0.5rem, 2.5rem)',
+```
+
+### Breakpoint Tokens
+```ts
+// Consistent with Tailwind defaults
+const breakpoints = { sm: '640px', md: '768px', lg: '1024px', xl: '1280px', '2xl': '1536px' }
+```
+
+## 7. Animation Architecture
+
+### Decision Matrix
+| Use Case | Solution |
+|---|---|
+| Simple enter/exit | CSS `@keyframes` + `transition` |
+| Complex sequences / orchestrated | Framer Motion |
+| Physics-based spring | Framer Motion `spring` |
+| Hover/focus micro-interactions | CSS `transition` (no JS cost) |
+| Scroll-driven | CSS `@scroll-timeline` or Framer `useInView` |
+| Page transitions | Framer `AnimatePresence` |
+
+### CSS Transitions
+```css
+/* ✅ GPU-accelerated properties only */
+.card {
+  transition: transform 200ms ease-out, opacity 200ms ease-out,
+              box-shadow 200ms ease-out;
+}
+.card:hover {
+  transform: translateY(-2px);
+  box-shadow: 0 8px 32px hsl(0 0% 0% / 0.15);
+}
+```
+
+### `@keyframes` Structure
+```css
+@keyframes slideIn {
+  from { opacity: 0; transform: translateX(-16px); }
+  to   { opacity: 1; transform: none; }
+}
+
+/* Apply with animation shorthand */
+.panel { animation: slideIn 300ms ease-out both; }
+```
+
+### `prefers-reduced-motion` — Non-Negotiable
+```css
+/* Global reset for reduced motion */
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```
+
+## 8. Anti-Patterns
+
+| Anti-Pattern | Problem | Fix |
+|---|---|---|
+| `!important` | Specificity wars, hard to override | Refactor selector or use CSS layers (`@layer`) |
+| Specificity wars | `.sidebar .card .button {}` | BEM naming or CSS Modules scoping |
+| Magic numbers z-index (`z-[9999]`) | Unpredictable stacking | Named z-index tokens in config |
+| Inline style overrides | Bypasses design system | Add utility class or extend Tailwind theme |
+| Animating layout properties | Reflow on every frame | Animate `transform` + `opacity` only |
+| `@apply` for large blocks | Reduces readability benefit of Tailwind | Component extraction instead |
+| Global selector bleed in CSS Modules | `.module.css` affects non-module elements | Scope all selectors with `:local()` or class names |
+
+## 9. Z-Index Layer System
+
+```ts
+// tailwind.config.ts
+extend: {
+  zIndex: {
+    base: '0',
+    above: '10',
+    dropdown: '100',
+    sticky: '200',
+    overlay: '300',
+    modal: '400',
+    toast: '500',
+    tooltip: '600',
+  }
+}
+```
+
+```tsx
+// Use named z-index in JSX
+<div className="z-modal">…</div>
+```
+
+## 10. Checklist
+
+- [ ] CSS custom properties defined at 3 layers (primitive → semantic → component)
+- [ ] No primitive tokens used directly in component styles
+- [ ] Tailwind version confirmed before writing config
+- [ ] `@apply` used only for repeated utility combos, not state variants
+- [ ] Container queries used for multi-context components
+- [ ] Dark mode uses token switching (not duplicated utility classes)
+- [ ] All animations respect `prefers-reduced-motion`
+- [ ] Fluid typography with `clamp()` for hero/heading text
+- [ ] Z-index uses named tokens, not inline integers
+- [ ] No `!important` in component styles