tribunal-kit 2.4.5 → 3.0.0

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

@@ -0,0 +1,134 @@
+---
+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
+
+> Magic numbers in CSS (`padding: 13px`) are technical debt.
+> A Design System is not a component library. It is a mathematical relationship between visual tokens.
+
+---
+
+## 1. The Token Extraction Protocol
+
+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.
+
+### 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 */
+}
+```
+
+### Tier 2: The Refactor 
+(Using Tailwind v4 CSS-First as the standard delivery mechanism)
+
+```css
+@theme {
+    --color-primary: hsl(var(--brand-primary));
+    --spacing-3: var(--space-3);
+    --radius-md: var(--radius-md);
+}
+```
+
+---
+
+## 2. Standardizing the 3 "C" Configurations 
+
+If building a design system inside React/Next.js, standardize the system through 3 primary mechanisms.
+
+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",
+    },
+  }
+);
+```
+
+---
+
+## 3. Auditing the Accessibility Baseline
+
+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`).
+
+---
+
+## 🤖 LLM-Specific Traps (Design System Extraction)
+
+1. **Literal Naming:** Naming variables `--color-light-red` instead of `--color-danger` or `--color-primary`. Literal names break instantly when the dark mode theme flips the palette.
+2. **Ignoring the Spacing Geometry:** Leaving `margin-top: 17px` and `padding-left: 11px` unaddressed instead of mathematically rounding them into a strict 4px/8px geometric scale (`mt-4`, `pl-3`).
+3. **Re-inventing Tailwind:** Extracting 400 CSS utility classes manually into a custom CSS file instead of properly mapping the design tokens into the existing Tailwind `@theme` engine.
+4. **Prop Drilling Hell:** Converting a button to a component, but exposing 15 individual CSS class props (`textColor`, `paddingSize`, `borderR`) instead of grouping them logically into a `Variant` CVA scale.
+5. **Dark Mode Blindness:** Extracting a beautiful Light Mode system and failing to invert the HSL lightness scale for the dark mode `:root` selector, resulting in invisible text.
+6. **Rgb Hex Hardcoding:** Extracting hex codes (`#FFFFFF`) directly instead of defining them as `H S L` variable channels, destroying the ability to inject dynamic `opacity` (e.g., `bg-primary/50`).
+7. **One-Off Snowflake Classes:** Creating a unique component explicitly for one page (e.g., `<CheckoutSubmitButton>`) instead of designing a generic `<Button intent="checkout">`.
+8. **Font Sizing vs Line Height:** Extracting `font-size` tokens, but ignoring the paired `line-height` standardizations, causing typography block rendering to collapse vertically.
+9. **Hover-State Void:** Extracting the static appearance of elements perfectly but entirely ignoring the `hover:`, `focus:`, and `active:` micro-interaction states that defined the original UX.
+10. **The Component Dump:** Scanning a 2,000 line page and trying to extract 15 components simultaneously inside a single LLM response. The extraction must be phased iteratively Component by Component.
+
+---
+
+## 🏛️ Tribunal Integration
+
+### ✅ Pre-Flight Self-Audit
+```
+✅ Are magic numbers strictly eradicated and mapped to a geometric mathematical scale (e.g., 4px grids)?
+✅ Are color tokens named semantically (`--primary`, `--danger`) rather than literally (`--blue`)?
+✅ Have hex codes been transformed to HSL structures to support dynamic opacity modification?
+✅ Is the `[data-theme='dark']` inversion matrix properly established alongside the root tokens?
+✅ Has `class-variance-authority` (cva) been used to cleanly manage component intent states?
+✅ Did I mathematically normalize inconsistent padding (e.g., fixing 11px and 13px both into 12px)?
+✅ Are global focus rings standardized to ensure accessibility consistency across interactive points?
+✅ Did I define the paired line-height geometries alongside the core typography font sizing tokens?
+✅ Have hover and transition states been deeply captured and centralized?
+✅ Did I phase the extraction process component-by-component to avoid hallucinating massive context blocks?
+```