tribunal-kit 2.4.6 → 3.1.0

package/.agent/skills/extract-design-system/SKILL.md

@@ -1,74 +1,100 @@
----
-name: extract-design-system
-description: UI reverse-engineering expert. Analyzes images, CSS dumps, or HTML structures to programmatically extract primitive design tokens (Colors, Typography, Spacing, Shadows) into pure JSON or Tailwind config.
-allowed-tools: Read, Write, Edit, Glob, Grep
-version: 1.0.0
-last-updated: 2026-03-30
-applies-to-model: claude-3-7-sonnet, gemini-2.5-pro
----
-
-# Extract Design System
-
-You are a Design System Extraction Engine. Your primary objective is to reverse-engineer given UI representations (screenshots, web page layouts, or raw CSS files) into highly structured, mathematically sound design tokens.
-
-## Core Directives
-
-1. **Token Primitives First:**
-   - Never extract a hardcoded hex color directly into a component. Always abstract it to a root primitive. E.g., `#0f172a` becomes `slate-900` or `--primary-background`.
-   - Organize extractions strictly by domain: `Colors`, `Typography` (font-family, line-height, kerning), `Spacing/Sizing` (rem/px scales), `Shadows/Elevation`, and `Border Radii`.
-
-2. **Mathematical Scales:**
-   - Ensure all spacing and sizing extracted locks onto a geometric grid (typically a 4px or 8px baseline). 
-   - If an extracted padding is `15px`, aggressively round and normalize it to `16px` (`rem` equivalent: `1rem` / `p-4`) in the system configuration.
-
-3. **Output Standardization:**
-   - By default, construct configurations that seamlessly graft into standard frameworks (e.g., generating `tailwind.config.ts` themes, or creating CSS variable blocks in `globals.css`).
-   - For generic outputs, emit raw JSON arrays defining the design system structure.
-
-4. **Component Identification:**
-   - Beyond simple tokens, identify repeated UI patterns (Buttons, Input Fields, Cards). Extract their base states alongside `hover`, `active`, `focus`, and `disabled` variants perfectly.
-
-## Execution
-When asked to extract a design system from a source, immediately compile a comprehensive `tokens` file dictating exact HSL or Hex values. You must explain *why* certain rounding decisions were made (e.g., snapping to the 4px grid) before generating configurations.
+---
+name: extract-design-system
+description: Design system extraction and tokenization mastery. Identifying repeated HTML/CSS patterns, extracting CSS variables, generating design tokens (colors, spacing, typography), building reusable component schemas, and standardizing ad-hoc styles into cohesive global systems. Use when refactoring messy CSS into a unified design system.
+allowed-tools: Read, Write, Edit, Glob, Grep
+version: 2.0.0
+last-updated: 2026-04-02
+applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
+---
 
+# Extract Design System — Tokenization Mastery
 
 ---
 
-## 🤖 LLM-Specific Traps
+## 1. The Token Extraction Protocol
 
-AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden:
+When reviewing a messy, legacy UI file (`<div style="background: #e23e2a; border-radius: 6px; padding: 12px">`), the agent must extract these hardcoded values into Global Tokens.
 
-1. **Over-engineering:** Proposing complex abstractions or distributed systems when a simpler approach suffices.
-2. **Hallucinated Libraries/Methods:** Using non-existent methods or packages. Always `// VERIFY` or check `package.json` / `requirements.txt`.
-3. **Skipping Edge Cases:** Writing the "happy path" and ignoring error handling, timeouts, or data validation.
-4. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
-5. **Silent Degradation:** Catching and suppressing errors without logging or re-raising.
+### Tier 1: Core Design Tokens (The Foundation)
+Tokens should be semantic, not literal. `color-brand` > `color-red`.
 
----
+```css
+:root {
+  /* Colors (HSL is preferred for programmatic manipulation) */
+  --brand-primary: 360, 76%, 53%; /* The specific red */
+  --surface-default: 0, 0%, 100%;
+  --surface-muted: 210, 40%, 96%;
+
+  /* Typography */
+  --font-sans: 'Inter', system-ui, sans-serif;
+  
+  /* Space / Geometry (8px grid scale) */
+  --space-1: 0.25rem;  /* 4px */
+  --space-2: 0.5rem;   /* 8px */
+  --space-3: 0.75rem;  /* 12px */
+  --space-4: 1rem;     /* 16px */
+  
+  /* Radaii */
+  --radius-sm: 4px;
+  --radius-md: 6px;    /* Extracted from the 6px legacy element */
+}
+```
 
-## 🏛️ Tribunal Integration (Anti-Hallucination)
+### Tier 2: The Refactor 
+(Using Tailwind v4 CSS-First as the standard delivery mechanism)
 
-**Slash command: `/review` or `/tribunal-full`**
-**Active reviewers: `logic-reviewer` · `security-auditor`**
+```css
+@theme {
+    --color-primary: hsl(var(--brand-primary));
+    --spacing-3: var(--space-3);
+    --radius-md: var(--radius-md);
+}
+```
 
-### ❌ Forbidden AI Tropes
+---
 
-1. **Blind Assumptions:** Never make an assumption without documenting it clearly with `// VERIFY: [reason]`.
-2. **Silent Degradation:** Catching and suppressing errors without logging or handling.
-3. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
+## 2. Standardizing the 3 "C" Configurations 
 
-### ✅ Pre-Flight Self-Audit
+If building a design system inside React/Next.js, standardize the system through 3 primary mechanisms.
 
-Review these questions before confirming output:
-```
-✅ Did I rely ONLY on real, verified tools and methods?
-✅ Is this solution appropriately scoped to the user's constraints?
-✅ Did I handle potential failure modes and edge cases?
-✅ Have I avoided generic boilerplate that doesn't add value?
+1. **Colors (Dark Mode First):** Every single color extracted must have an inverse defined for `[data-theme='dark']`.
+2. **Container Queries:** Media queries (`@media (min-width)`) define the *device*. Container queries (`@container (min-width)`) define the *component context*. Always extract component sizing to rely on container-driven layouts for ultimate reusability.
+3. **Compound Variants (CVA):** Group extracted CSS classes into logical component states rather than passing 10 boolean props.
+
+```typescript
+// ✅ Efficient Extracted Component Architecture
+import { cva } from "class-variance-authority";
+
+const buttonStyles = cva(
+  "inline-flex items-center justify-center rounded-md font-medium transition-colors", // Base
+  {
+    variants: {
+      intent: {
+        primary: "bg-primary text-white hover:bg-primary/90",
+        destructive: "bg-red-500 text-white hover:bg-red-600",
+        outline: "border border-input hover:bg-accent",
+      },
+      size: {
+        sm: "h-9 px-3 text-sm",
+        default: "h-10 px-4 py-2",     // Extracted standard size
+        lg: "h-11 px-8",
+      },
+    },
+    defaultVariants: {
+      intent: "primary",
+      size: "default",
+    },
+  }
+);
 ```
 
-### 🛑 Verification-Before-Completion (VBC) Protocol
+---
+
+## 3. Auditing the Accessibility Baseline
 
-**CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
-- ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
-- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
+A Design System must mandate accessibility at the token level, preventing developers from manually breaking contrast ratios later.
+
+1. Extracted primary text colors must hit a **4.5:1 contrast ratio** against the extracted background surfaces.
+2. Focus rings must be decoupled and standardized globally (`ring-2 ring-primary ring-offset-2`).
+
+---

package/.agent/skills/framer-motion-expert/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: framer-motion-expert
+description: Framer Motion 12+ for React. Declarative animations, layout transitions, gestures, scroll-linked motion, AnimatePresence, useAnimate, LazyMotion. Use when building component animations, page transitions, shared layout animations, or gesture-driven UI.
+allowed-tools: Read, Write, Edit, Glob, Grep
+version: 3.1.0
+last-updated: 2026-04-06
+---
+
+# Framer Motion 12+ — Dense Reference
+
+## Hallucination Traps (Read First)
+- ❌ `<Motion>` (capital M) → ✅ `motion.div` (lowercase dot notation)
+- ❌ `motion()` wrapper function → ✅ `motion.div`, `motion.span`, etc.
+- ❌ `exitBeforeEnter` prop → ✅ `mode="wait"` on `<AnimatePresence>` (removed in FM7+)
+- ❌ `exit` works without `<AnimatePresence>` → ✅ REQUIRES AnimatePresence wrapper
+- ❌ `<AnimatePresence>` children without unique `key` → ✅ ALWAYS set `key`
+- ❌ `stiffness + damping` AND `duration + bounce` together → ✅ pick ONE pair
+- ❌ `m.div` without `<LazyMotion>` wrapper → ✅ REQUIRES LazyMotion parent
+- ❌ `layout` animations with `domAnimation` feature set → ✅ requires `domMax`
+- ❌ Force-animating `width`/`height`/`top`/`left` → ✅ use `x`,`y`,`scale`,`opacity` (GPU)
+- ❌ `viewport.once` defaults to true → ✅ defaults to **false** — add `once: true` for entrance anims
+
+---
+
+## Core Primitives
+
+### `motion.X` / Declarative Animation
+```tsx
+import { motion } from "framer-motion";
+<motion.div
+  initial={{ opacity: 0, y: 20 }}
+  animate={{ opacity: 1, y: 0 }}
+  exit={{ opacity: 0, y: -20 }}
+  transition={{ duration: 0.3, ease: "easeOut" }}
+/>
+```
+
+### Variants (Stagger / Orchestration)
+```tsx
+const container = {
+  hidden: {},
+  visible: { transition: { staggerChildren: 0.08, delayChildren: 0.1 } },
+};
+const item = {
+  hidden: { opacity: 0, y: 20, filter: "blur(4px)" },
+  visible: { opacity: 1, y: 0, filter: "blur(0px)", transition: { duration: 0.4 } },
+};
+<motion.ul variants={container} initial="hidden" animate="visible">
+  {list.map(e => <motion.li key={e.id} variants={item}>{e.name}</motion.li>)}
+</motion.ul>
+// Variant names propagate to children automatically — no need to set initial/animate on each child
+```
+
+### Transitions
+```tsx
+// Tween (default)
+transition={{ duration: 0.5, ease: "easeInOut", delay: 0.2, repeat: Infinity, repeatType: "reverse" }}
+// Spring (physics)
+transition={{ type: "spring", stiffness: 300, damping: 20 }} // OR use duration+bounce, not both
+transition={{ type: "spring", duration: 0.8, bounce: 0.25 }}
+// Per-property
+transition={{ x: { type: "spring", stiffness: 300 }, opacity: { duration: 0.2 } }}
+```
+
+---
+
+## Gestures
+
+```tsx
+// Hover/Tap/Focus
+<motion.button
+  whileHover={{ scale: 1.05 }}
+  whileTap={{ scale: 0.95 }}
+  whileFocus={{ boxShadow: "0 0 0 3px rgba(66,153,225,0.6)" }}
+  transition={{ type: "spring", stiffness: 400, damping: 15 }}
+/>
+// Drag
+<motion.div
+  drag="x"                                   // "x" | "y" | true
+  dragConstraints={{ left: -100, right: 100 }}
+  dragElastic={0.2}                          // 0=hard stop, 1=free
+  dragMomentum={true}
+  dragSnapToOrigin
+/>
+// Scroll-triggered
+<motion.div
+  initial={{ opacity: 0, y: 50 }}
+  whileInView={{ opacity: 1, y: 0 }}
+  viewport={{ once: true, amount: 0.3 }}    // ← once: true is almost always what you want
+/>
+```
+
+---
+
+## Layout Animations
+
+```tsx
+// layout prop — auto-animates position/size changes
+<motion.div layout transition={{ type: "spring", stiffness: 200 }}>
+  {/* layout="position" = only position, layout="size" = only size */}
+</motion.div>
+
+// layoutId — shared element transition (morph between renders)
+// List thumbnail → expanded modal:
+<motion.div key={item.id} layoutId={`card-${item.id}`} />   // in list
+<motion.div layoutId={`card-${selectedId}`} className="modal" /> // in modal
+// ❌ TRAP: Cross-tree layoutId requires <LayoutGroup> wrapper
+import { LayoutGroup } from "framer-motion";
+<LayoutGroup><Sidebar /><MainContent /></LayoutGroup>
+```
+
+### AnimatePresence
+```tsx
+<AnimatePresence mode="sync"> {/* "sync"|"wait"|"popLayout" */}
+  {items.map(item => (
+    <motion.div key={item.id} /* ← REQUIRED */
+      initial={{ opacity: 0, height: 0 }}
+      animate={{ opacity: 1, height: "auto" }}
+      exit={{ opacity: 0, height: 0 }}
+    />
+  ))}
+</AnimatePresence>
+// mode="wait" — waits for exit before entering
+// initial={false} on AnimatePresence — skip first-render animation
+```
+
+---
+
+## Scroll Animations
+
+```tsx
+import { useScroll, useTransform } from "framer-motion";
+// Page scroll progress (0–1)
+const { scrollYProgress } = useScroll();
+const y = useTransform(scrollYProgress, [0, 1], [0, -200]);
+const opacity = useTransform(scrollYProgress, [0, 0.5], [1, 0]);
+<motion.div style={{ y, opacity }} />
+
+// Element-scoped scroll
+const ref = useRef(null);
+const { scrollYProgress } = useScroll({ target: ref, offset: ["start end", "end start"] });
+```
+
+---
+
+## Hooks
+
+### `useAnimate` — Imperative sequences
+```tsx
+import { useAnimate, stagger } from "framer-motion";
+const [scope, animate] = useAnimate(); // ← returns [scope, animate] NOT [ref, controls]
+await animate(".item", { opacity: 1 }, { delay: stagger(0.1) });
+<div ref={scope}>...</div>
+```
+
+### `useMotionValue` + `useTransform` — No re-renders
+```tsx
+const x = useMotionValue(0);
+const rotateY = useTransform(x, [-200, 200], [-45, 45]);
+// ✅ useMotionValue does NOT trigger React re-renders — key perf advantage over useState
+<motion.div style={{ x, rotateY }} drag="x" />
+```
+
+### `useSpring` / `useVelocity`
+```tsx
+const springX = useSpring(x, { stiffness: 300, damping: 30 });
+const xVel = useVelocity(x);
+const skewX = useTransform(xVel, [-1000, 0, 1000], [-15, 0, 15]);
+```
+
+---
+
+## Performance & Bundle
+
+```tsx
+// LazyMotion — ~5KB vs ~30KB full bundle
+import { LazyMotion, domAnimation, m } from "framer-motion";
+// domAnimation ≈ 5KB | domMax ≈ 20KB (needed for layout/drag)
+<LazyMotion features={domAnimation}><m.div animate={{ opacity: 1 }} /></LazyMotion>
+```
+
+### Accessibility
+```tsx
+import { useReducedMotion } from "framer-motion";
+const reduce = useReducedMotion();
+// opacity/color: always safe | position/scale/rotation: must be disabled when reduce=true
+<motion.div animate={{ x: reduce ? 0 : 100, opacity: 1 }} transition={{ duration: reduce ? 0 : 0.5 }} />
+```
+
+### Rules
+- ✅ Animate: `x`, `y`, `scale`, `rotation`, `opacity` (GPU composited)
+- ❌ Never animate: `width`, `height`, `top`, `left`, `padding`, `margin` (causes layout thrashing)
+- ✅ `useMotionValue` for animation-driven values — never `useState`
+- ❌ Nest `AnimatePresence` only when necessary — each adds reconciler overhead
+- `"use client"` required in Next.js — `motion.div` cannot run in Server Components