tribunal-kit 2.4.6 → 3.1.0

package/.agent/skills/gsap-expert/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: gsap-expert
+description: GreenSock Animation Platform (GSAP 3.12+) mastery. Core tweens, timelines, ScrollTrigger, ScrollSmoother, plugins, React useGSAP hook, responsive animations, performance. Use when building scroll-driven animations, complex sequencing, SVG morphing, or any animation beyond CSS capabilities.
+allowed-tools: Read, Write, Edit, Glob, Grep
+version: 3.2.0
+last-updated: 2026-04-07
+applies-to-model: gemini-3-1-pro, claude-3-7-sonnet
+---
+
+# GSAP Expert — 3.12+ Dense Reference
+
+## Hallucination Traps (Read First)
+- ❌ `gsap.registerPlugin(ScrollTrigger)` optional → ✅ **REQUIRED** before any use — must call before component mounts
+- ❌ `easeInOut`, `Power2.easeOut` (GSAP 2 syntax) → ✅ `"power2.inOut"` (string, GSAP 3)
+- ❌ `raw useEffect` for GSAP in React → ✅ `useGSAP` from `@gsap/react` — handles cleanup automatically
+- ❌ Timeline position as 2nd arg → ✅ position is the **3rd** arg: `tl.to(el, { x: 100 }, "<")`
+- ❌ `markers: true` in production → ✅ Debug only — never ship. `gsap.config({ markers: false })`
+- ❌ Animate `width`, `height`, `top`, `left` → ✅ Only `x`, `y`, `scale`, `rotation`, `opacity` (GPU composited)
+- ❌ 1 ScrollTrigger per list item → ✅ Use `ScrollTrigger.batch()` for lists — 1 battery per N items
+- ❌ `dependencies` option spelled `deps` → ✅ option is `dependencies` (not `deps`)
+- ❌ GSAP in Next.js Server Components → ✅ Always `"use client"` — GSAP is browser-only
+
+---
+
+## Core Tweens
+
+```javascript
+gsap.to(".box", { x: 100, opacity: 1, duration: 1, ease: "power2.out" });
+gsap.from(".box", { y: -50, opacity: 0, duration: 0.8 });
+gsap.fromTo(".box", { x: -100 }, { x: 0, duration: 1, ease: "expo.out" });
+gsap.set(".box", { transformOrigin: "center center", willChange: "transform" });
+
+// Stagger (multiple elements)
+gsap.from(".item", { opacity: 0, y: 30, stagger: 0.08, ease: "power3.out" });
+gsap.from(".item", { opacity: 0, stagger: { each: 0.1, from: "center", grid: "auto" } });
+```
+
+---
+
+## Timelines
+
+```javascript
+const tl = gsap.timeline({ defaults: { ease: "power2.out", duration: 0.6 } });
+
+tl.from(".hero-title", { y: 60, opacity: 0 })
+  .from(".hero-sub",   { y: 40, opacity: 0 }, "-=0.4")   // overlap 0.4s
+  .from(".hero-cta",   { scale: 0.9, opacity: 0 }, "<0.1") // 0.1s after prev starts
+  .to(".hero-img",     { x: 0, opacity: 1 }, 0.3);        // absolute 0.3s into tl
+
+// Position symbols:
+// "<"      → same start time as previous tween
+// ">"      → after previous ends
+// "-=0.5"  → 0.5s before previous ends (overlap)
+// "+=0.5"  → 0.5s after previous ends (gap)
+// "2"      → absolute 2s from timeline start
+
+// Runtime control
+tl.play(); tl.pause(); tl.reverse(); tl.seek(1.5); tl.timeScale(2); // 2x speed
+```
+
+---
+
+## ScrollTrigger
+
+```javascript
+import { gsap } from "gsap";
+import { ScrollTrigger } from "gsap/ScrollTrigger";
+gsap.registerPlugin(ScrollTrigger); // REQUIRED — call once at module level
+
+// Basic scroll-triggered animation
+gsap.from(".section", {
+  scrollTrigger: {
+    trigger: ".section",
+    start: "top 80%",   // "triggerEdge viewportEdge"
+    end: "bottom 20%",
+    scrub: 1,           // smooth scrubbing (seconds to catch up) | true = instant
+    pin: true,          // pin element during scroll
+    anticipatePin: 1,   // prevents jump on pin
+    markers: false,     // NEVER true in production
+  },
+  y: 100, opacity: 0,
+});
+
+// Batch — for lists (1 ST instance per group, not per item)
+ScrollTrigger.batch(".card", {
+  onEnter: (elements) => gsap.from(elements, { opacity: 0, y: 40, stagger: 0.08 }),
+  start: "top 85%",
+});
+
+// Pin + scrub storytelling
+const tl = gsap.timeline({
+  scrollTrigger: { trigger: ".scene", pin: true, scrub: true, end: "+=3000" }
+});
+tl.from(".layer-1", { x: -200 }).from(".layer-2", { x: 200 }, "<");
+
+// Cleanup — MANDATORY on SPA route unmount
+ScrollTrigger.killAll(); // in component cleanup / router onChange
+```
+
+---
+
+## React Integration (`useGSAP`)
+
+```tsx
+import { useGSAP } from "@gsap/react";
+import { gsap } from "gsap";
+import { ScrollTrigger } from "gsap/ScrollTrigger";
+import { useRef } from "react";
+
+gsap.registerPlugin(ScrollTrigger); // once, outside component
+
+export function HeroSection() {
+  const container = useRef<HTMLDivElement>(null);
+
+  useGSAP(() => {
+    // ✅ All GSAP code here is automatically scoped & cleaned up
+    gsap.from(".hero-title", { y: 60, opacity: 0, duration: 0.8 });
+
+    gsap.from(".hero-card", {
+      scrollTrigger: { trigger: ".hero-card", start: "top 80%" },
+      y: 40, opacity: 0, stagger: 0.1,
+    });
+  }, { scope: container, dependencies: [] }); // re-runs when dependencies change
+
+  return <div ref={container}><h1 className="hero-title">...</h1></div>;
+}
+
+// With cleanup for dynamic content:
+useGSAP(() => {
+  const ctx = gsap.context(() => {
+    gsap.from(".item", { opacity: 0, stagger: 0.05 });
+  }, container);
+  return () => ctx.revert(); // explicit cleanup if needed beyond useGSAP scope
+}, { scope: container, dependencies: [items] });
+```
+
+---
+
+## Responsive Animations (`gsap.matchMedia`)
+
+```javascript
+// Replaces window.matchMedia listeners + resize handlers
+const mm = gsap.matchMedia();
+
+mm.add("(min-width: 768px)", () => {
+  gsap.to(".sidebar", { x: 0, duration: 0.5 });
+  // Return cleanup function
+  return () => gsap.set(".sidebar", { x: -300 });
+});
+
+mm.add("(max-width: 767px)", () => {
+  gsap.to(".mobile-menu", { y: 0, duration: 0.4 });
+});
+
+// In React — use inside useGSAP
+useGSAP(() => {
+  const mm = gsap.matchMedia();
+  mm.add("(prefers-reduced-motion: no-preference)", () => {
+    gsap.from(".hero", { y: 100, duration: 1 });
+  });
+  mm.add("(prefers-reduced-motion: reduce)", () => {
+    gsap.set(".hero", { opacity: 1 }); // instant, no animation
+  });
+});
+```
+
+---
+
+## Plugin Reference
+
+| Plugin | Use For | Registration |
+|--------|---------|-------------|
+| `ScrollTrigger` | Scroll-driven animations | `gsap.registerPlugin(ScrollTrigger)` |
+| `ScrollSmoother` | Smooth native scroll momentum | Requires `ScrollTrigger` + Club GSAP |
+| `Flip` | Stateful layout morphing (FLIP technique) | `gsap.registerPlugin(Flip)` |
+| `Draggable` | Interactive drag/sort/resize | `gsap.registerPlugin(Draggable)` |
+| `SplitText` | Character/word/line text splits | Call `.revert()` after use to prevent SEO damage |
+| `DrawSVG` | SVG stroke-dasharray animations | Club GSAP |
+| `MorphSVG` | SVG path morphing | Club GSAP |
+| `ScrollToPlugin` | Programmatic scroll-to | `gsap.registerPlugin(ScrollToPlugin)` |
+
+---
+
+## Performance Rules
+
+```
+✅ Animate: x, y, scale, rotation, skewX/Y, opacity (GPU composited transforms)
+❌ Never:   width, height, top, left, padding, margin (triggers layout/paint)
+✅ Use willChange: "transform" on elements that will animate
+✅ overwrite: "auto" to kill conflicting tweens automatically
+✅ ScrollTrigger.batch() for lists — NOT 1 instance per item
+✅ gsap.ticker.lagSmoothing(0) in high-framerate contexts (optional)
+❌ Don't animate SVG path 'd' attribute directly — use MorphSVG plugin
+```

package/.agent/skills/i18n-localization/SKILL.md

@@ -1,216 +1,104 @@
 ---
 name: i18n-localization
-description: Internationalization and localization patterns. Detecting hardcoded strings, managing translations, locale files, RTL support.
+description: Internationalization (i18n) and localization mastery. Abstracting hardcoded strings, managing JSON/YAML translation dictionaries, bidirectional routing (RTL support for Arabic/Hebrew), Pluralization algorithms, date/currency formatting, and SSR locale detection in Next.js/React. Use when preparing an application for global multilingual scaling.
 allowed-tools: Read, Write, Edit, Glob, Grep
-version: 1.0.0
-last-updated: 2026-03-12
+version: 2.0.0
+last-updated: 2026-04-02
 applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
 ---
 
-# Internationalization & Localization
-
-> Internationalization (i18n) is preparing code to support multiple languages.
-> Localization (l10n) is the work of adapting to a specific locale.
-> Do i18n once, properly. Do l10n for each market.
+# i18n & Localization — Global Scale Mastery
 
 ---
 
-## The Core Rule: No Hardcoded Strings
-
-Every user-visible string in the source code is a localization problem waiting to happen.
-
-```ts
-// ❌ Hardcoded — untranslatable
-<button>Save Changes</button>
-<p>You have {count} messages</p>
-<p>Error: Invalid email address</p>
+## 1. The i18n Architecture (Next.js / React)
 
-// ✅ Key-referenced — translatable
-<button>{t('common.save')}</button>
-<p>{t('inbox.messageCount', { count })}</p>
-<p>{t('errors.invalidEmail')}</p>
-```
-
----
-
-## Translation File Structure
-
-Organize translation keys hierarchically — flat files become unmaintainable past ~50 keys:
+Do not hardcode strings inside UI components. Use a standardized library (e.g., `next-intl` or `react-i18next`).
 
+### Step 1: Dictionary Abstraction
 ```json
-// en.json
+// messages/en.json
 {
-  "common": {
-    "save": "Save Changes",
-    "cancel": "Cancel",
-    "loading": "Loading…",
-    "error": "Something went wrong"
-  },
-  "auth": {
-    "login": "Sign In",
-    "logout": "Sign Out",
-    "register": "Create Account",
-    "errors": {
-      "invalidEmail": "Enter a valid email address",
-      "passwordTooShort": "Password must be at least {{min}} characters"
-    }
-  },
-  "inbox": {
-    "messageCount_one": "{{count}} message",
-    "messageCount_other": "{{count}} messages"
+  "Dashboard": {
+    "welcomeMessage": "Welcome back, {name}!",
+    "unreadAlerts": "{count, plural, =0 {No unread alerts} one {You have 1 unread alert} other {You have # unread alerts}}"
   }
 }
 ```
 
-**Key naming conventions:**
-- `feature.element` or `feature.element.state`
-- Error keys under `.errors`
-- Never use the English text as the key (`"Save Changes": "Save Changes"`)
-
----
-
-## Pluralization
-
-Pluralization rules differ per language. Use your i18n library's plural system — never manual `if count > 1`:
-
-```ts
-// ❌ Only works for English
-const label = count === 1 ? 'message' : 'messages';
-
-// ✅ i18next handles per-language plural rules
-t('inbox.messageCount', { count })
+### Step 2: Component Implementation
+```tsx
+// ❌ BAD: Hardcoded English text and manual variable interpolation
+export function Header({ user, alertCount }) {
+  return <h1>Welcome back, {user.name}! You have {alertCount} alerts.</h1>;
+}
 
-// Translation files handle the variants:
-// English: { "messageCount_one": "{{count}} message", "messageCount_other": "{{count}} messages" }
-// Arabic:  6 plural forms (zero, one, two, few, many, other)
-// Russian: 3 plural forms with complex rules
+// ✅ GOOD: i18n Abstraction (using next-intl)
+import { useTranslations } from 'next-intl';
+
+export function Header({ user, alertCount }) {
+  const t = useTranslations('Dashboard');
+  
+  return (
+    <header>
+      <h1>{t('welcomeMessage', { name: user.name })}</h1>
+      <p>{t('unreadAlerts', { count: alertCount })}</p>
+    </header>
+  );
+}
 ```
 
 ---
 
-## Date, Number & Currency Formatting
-
-Never format these manually. Use the browser's `Intl` API:
-
-```ts
-// Date
-const date = new Date();
-new Intl.DateTimeFormat('en-US').format(date);  // "2/20/2026"
-new Intl.DateTimeFormat('de-DE').format(date);  // "20.2.2026"
-
-// Number
-new Intl.NumberFormat('en-US').format(1234567.89);  // "1,234,567.89"
-new Intl.NumberFormat('de-DE').format(1234567.89);  // "1.234.567,89"
-
-// Currency
-new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }).format(99.99);
-// "$99.99"
-new Intl.NumberFormat('de-DE', { style: 'currency', currency: 'EUR' }).format(99.99);
-// "99,99 €"
-```
-
----
+## 2. Advanced Native Formatting (`Intl`)
 
-## RTL (Right-to-Left) Support
+Do not install `moment.js` or write massive regex string parsers to format currencies in Euros vs Dollars. The browser handles this natively with the `Intl` API.
 
-Arabic, Hebrew, Persian, Urdu are RTL languages. Supporting them requires more than flipping direction.
+```typescript
+// Data/Currency Formatting correctly tied to the active locale
+const locale = 'de-DE';
 
-```html
-<!-- Set direction on html element based on locale -->
-<html lang="ar" dir="rtl">
+// ✅ Currency
+const price = new Intl.NumberFormat(locale, { style: 'currency', currency: 'EUR' }).format(1200.50);
+// Output in Germany: "1.200,50 €"
 
-<!-- Or dynamically -->
-<html lang={locale} dir={isRTL(locale) ? 'rtl' : 'ltr'}>
-```
+// ✅ Dates
+const date = new Intl.DateTimeFormat(locale, { dateStyle: 'full' }).format(new Date());
+// Output in Germany: "Freitag, 2. April 2026"
 
-```css
-/* Use logical properties — they flip automatically with direction */
-/* ❌ Physical: only works for LTR */
-padding-left: 1rem;
-margin-right: 2rem;
-border-left: 2px solid;
-
-/* ✅ Logical: works for both LTR and RTL */
-padding-inline-start: 1rem;
-margin-inline-end: 2rem;
-border-inline-start: 2px solid;
+// ✅ Relative Time
+const rtf = new Intl.RelativeTimeFormat(locale, { numeric: 'auto' });
+rtf.format(-2, 'day'); // Output: "vorgestern" (the day before yesterday)
 ```
 
 ---
 
-## Detecting Hardcoded Strings (Code Audit)
-
-Look for:
-- JSX text content directly in tags: `<p>some text</p>` (not `<p>{t(...)}</p>`)
-- Template literals with user-facing copy: `` `Welcome, ${name}!` ``
-- Alert/toast calls with string literals: `toast.success('Saved!')`
-- Error messages: `new Error('Invalid input')` shown to users
-- `placeholder`, `aria-label`, `title` attributes hardcoded
-
----
+## 3. Bidirectional Architecture (RTL)
 
-## Scripts
+For languages like Arabic and Hebrew, the UI must fundamentally flip horizontally. Right-To-Left (RTL) breaks standard CSS `marginLeft` and `marginRight`.
 
-| Script | Purpose | Run With |
-|---|---|---|
-| `scripts/i18n_checker.py` | Scans codebase for hardcoded strings | `python scripts/i18n_checker.py <project_path>` |
+**The Solution:** Logical CSS Properties.
+Tailwind v4 (and modern CSS) natively supports logical direction.
 
----
-
-## Output Format
-
-When this skill produces a recommendation or design decision, structure your output as:
+```css
+/* ❌ BAD: Hardcoded physical space */
+.btn { margin-left: 10px; } /* Will break layout in Hebrew */
 
-```
-━━━ I18N Localization Recommendation ━━━━━━━━━━━━━━━━
-Decision:    [what was chosen / proposed]
-Rationale:   [why — one concise line]
-Trade-offs:  [what is consciously accepted]
-Next action: [concrete next step for the user]
-─────────────────────────────────────────────────
-Pre-Flight:  ✅ All checks passed
-             or ❌ [blocking item that must be resolved first]
+/* ✅ GOOD: Logical spacing (Tailwind: ms-4, me-4) */
+.btn { margin-inline-start: 10px; } /* Automatically flips in RTL mode */
 ```
 
-
+*In React HTML tag:* `<html lang="ar" dir="rtl">`
 
 ---
 
-## 🤖 LLM-Specific Traps
+## 4. Routing and SSR Detection
 
-AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden:
+Users should not face English UI natively in Japan. Detect their browser headers at the edge routing layer.
 
-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.
+In Next.js Middleware:
+1. Parse the incoming `Accept-Language` header.
+2. Intercept requests to `/dashboard`.
+3. Rewrite URL to the detected locale (e.g., `/ja/dashboard`).
 
 ---
-
-## 🏛️ Tribunal Integration (Anti-Hallucination)
-
-**Slash command: `/review` or `/tribunal-full`**
-**Active reviewers: `logic-reviewer` · `security-auditor`**
-
-### ❌ 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.
-
-### ✅ Pre-Flight Self-Audit
-
-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?
-```
-
-### 🛑 Verification-Before-Completion (VBC) Protocol
-
-**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.