tribunal-kit 9.2.4 → 9.2.5

package/skills/harden/SKILL.md

@@ -1,55 +1,55 @@
----
-name: harden
-description: "Use when Make interfaces production-resilient with robust empty states, error boundaries, loading skeletons, offline indicators, and internationalization (i18n) layout support."
-version: 5.0.0
-last-updated: 2026-09-13
-skills:
-  - polish
-  - baseline-ui
-  - resilience-reviewer
-tools: Read, Grep, Glob, Bash, Edit, Write
-scripts-binding:
-  - .agent/scripts/lint_runner.js
-  - .agent/scripts/verify_all.js
----
-
-# Harden — Production UI Resilience & Edge Case Protection
-
----
-
-## 🛠️ Technical Architecture & Reference Recipes
-
----
-
----
-
-## 5 Resilience Domains
-
-### 1. Zero-Data Empty States
-
-- Never render empty blank slates or blank boxes.
-- Always render a dedicated empty state component featuring:
-  - Contextual icon or subtle illustration
-  - Clear heading explaining the zero state (_"No active projects found"_)
-  - Secondary helper copy (_"Get started by creating your first project."_)
-  - Prominent primary action CTA button (_"Create Project"_)
-
-### 2. Error Boundary UI & Retry Hooks
-
-- Wrap high-risk component trees in React/framework Error Boundaries.
-- Display localized inline error callouts with explicit "Retry" action buttons rather than crashing the full page view.
-
-### 3. Cumulative Layout Shift (CLS) Loading Skeletons
-
-- Match skeleton placeholder dimensions EXACTLY to incoming data elements.
-- Use animated pulse keyframes (`@keyframes pulse { 0%, 100% { opacity: 1; } 50% { opacity: 0.4; } }`).
-
-### 4. Extreme String Expansion (i18n)
-
-- German, French, and Spanish strings are 30% - 50% longer than English.
-- Avoid fixed button or container widths (`width: 120px`). Use `min-width` with flexible auto sizing and `flex-wrap: wrap` or text truncation.
-
-### 5. Offline & Network Disconnection Handling
-
-- Detect `navigator.onLine` state and display subtle offline status banners.
-- Disable mutation buttons during offline mode with explicit tooltip explanation.
+---
+name: harden
+description: "Use when Make interfaces production-resilient with robust empty states, error boundaries, loading skeletons, offline indicators, and internationalization (i18n) layout support."
+version: 5.0.0
+last-updated: 2026-09-13
+skills:
+  - polish
+  - baseline-ui
+  - resilience-reviewer
+tools: Read, Grep, Glob, Bash, Edit, Write
+scripts-binding:
+  - .agent/scripts/lint_runner.js
+  - .agent/scripts/verify_all.js
+---
+
+# Harden — Production UI Resilience & Edge Case Protection
+
+---
+
+## 🛠️ Technical Architecture & Reference Recipes
+
+---
+
+---
+
+## 5 Resilience Domains
+
+### 1. Zero-Data Empty States
+
+- Never render empty blank slates or blank boxes.
+- Always render a dedicated empty state component featuring:
+  - Contextual icon or subtle illustration
+  - Clear heading explaining the zero state (_"No active projects found"_)
+  - Secondary helper copy (_"Get started by creating your first project."_)
+  - Prominent primary action CTA button (_"Create Project"_)
+
+### 2. Error Boundary UI & Retry Hooks
+
+- Wrap high-risk component trees in React/framework Error Boundaries.
+- Display localized inline error callouts with explicit "Retry" action buttons rather than crashing the full page view.
+
+### 3. Cumulative Layout Shift (CLS) Loading Skeletons
+
+- Match skeleton placeholder dimensions EXACTLY to incoming data elements.
+- Use animated pulse keyframes (`@keyframes pulse { 0%, 100% { opacity: 1; } 50% { opacity: 0.4; } }`).
+
+### 4. Extreme String Expansion (i18n)
+
+- German, French, and Spanish strings are 30% - 50% longer than English.
+- Avoid fixed button or container widths (`width: 120px`). Use `min-width` with flexible auto sizing and `flex-wrap: wrap` or text truncation.
+
+### 5. Offline & Network Disconnection Handling
+
+- Detect `navigator.onLine` state and display subtle offline status banners.
+- Disable mutation buttons during offline mode with explicit tooltip explanation.

package/skills/harness-protocol/SKILL.md

@@ -1,48 +1,48 @@
----
-name: harness-protocol
-description: "Use when Rules and guidelines for the Marathon long-running agent harness"
-version: 5.0.0
-last-updated: 2026-09-13
-skills:
-  - agentic-patterns
-  - behavioral-modes
-  - plan-writing
-tools: Read, Grep, Glob, Bash, Edit, Write
-scripts-binding:
-  - .agent/scripts/session_manager.js
-  - .agent/scripts/verify_all.js
-  - .agent/scripts/lint_runner.js
----
-
-# Harness Protocol — Long-Running Agent Harness Rules
-
----
-
-## 🛠️ Technical Architecture & Reference Recipes
-
----
-
-## Rules
-
-1. Each session must start with `tk marathon init "spec"`
-2. Agents must verify they have completed their current task before running `tk marathon mark pass`
-3. If an agent encounters an unrecoverable error, they must run `tk marathon mark fail`
-4. The harness is responsible for tracking overall progression.
-5. All agents must follow the Verification-Before-Completion (VBC) protocol.
-
-## Pre-Flight Checklist
-
-- Check marathon session state
-- Confirm VBC guidelines are followed
-
-## VBC Protocol
-
-- Verify task is complete before marking pass
-
-
-## 4. Ultrawork and Continuous Validation
-
-The Harness supports "Ultrawork" — long-running autonomous batch processing and background continuous validation inspired by Oh-My-OpenAgent (OmO) Team Mode.
-- **Background Execution**: Agents in a marathon session should execute autonomously in the background via the Durable Session Log.
-- **Continuous Validation**: Sub-agents continually validate output via the VBC protocol without polling the user.
-- **Human-in-the-Loop (HitL)**: Interrupt execution and request user approval *only* at explicit Human Gates (e.g., executing a destructive command or finalizing a milestone). Do not yield to the user for intermediate successes.
+---
+name: harness-protocol
+description: "Use when Rules and guidelines for the Marathon long-running agent harness"
+version: 5.0.0
+last-updated: 2026-09-13
+skills:
+  - agentic-patterns
+  - behavioral-modes
+  - plan-writing
+tools: Read, Grep, Glob, Bash, Edit, Write
+scripts-binding:
+  - .agent/scripts/session_manager.js
+  - .agent/scripts/verify_all.js
+  - .agent/scripts/lint_runner.js
+---
+
+# Harness Protocol — Long-Running Agent Harness Rules
+
+---
+
+## 🛠️ Technical Architecture & Reference Recipes
+
+---
+
+## Rules
+
+1. Each session must start with `tk marathon init "spec"`
+2. Agents must verify they have completed their current task before running `tk marathon mark pass`
+3. If an agent encounters an unrecoverable error, they must run `tk marathon mark fail`
+4. The harness is responsible for tracking overall progression.
+5. All agents must follow the Verification-Before-Completion (VBC) protocol.
+
+## Pre-Flight Checklist
+
+- Check marathon session state
+- Confirm VBC guidelines are followed
+
+## VBC Protocol
+
+- Verify task is complete before marking pass
+
+
+## 4. Ultrawork and Continuous Validation
+
+The Harness supports "Ultrawork" — long-running autonomous batch processing and background continuous validation inspired by Oh-My-OpenAgent (OmO) Team Mode.
+- **Background Execution**: Agents in a marathon session should execute autonomously in the background via the Durable Session Log.
+- **Continuous Validation**: Sub-agents continually validate output via the VBC protocol without polling the user.
+- **Human-in-the-Loop (HitL)**: Interrupt execution and request user approval *only* at explicit Human Gates (e.g., executing a destructive command or finalizing a milestone). Do not yield to the user for intermediate successes.

package/skills/huggingface-spaces/SKILL.md

@@ -159,7 +159,7 @@ Short version:
 
 - **Gradio patterns** (themes, `gr.Examples`, streaming, custom HTML components, `gr.Server`): [`references/gradio.md`](references/gradio.md).
 - **Docker**: https://huggingface.co/docs/hub/spaces-sdks-docker. Examples: `hf spaces list --filter docker`.
-- **Static**: https://huggingface.co/docs/hub/spaces-sdks-static. For built SPAs, set `app_build_command: npm run build` and `app_file: dist/index.html` in frontmatter.
+- **Static**: https://huggingface.co/docs/hub/spaces-sdks-static. For built SPAs, set `app_build_command: npm run build` and `app_file: src/index.html` in frontmatter.
 - **ZeroGPU specifics** (decorator semantics, sizing, AoTI, generators, concurrency, pickle / `gr.State` across the worker boundary): [`references/zerogpu.md`](references/zerogpu.md) — read this whenever the Space targets ZeroGPU.
 
 

package/skills/human-gate-negotiation/SKILL.md

@@ -1,30 +1,30 @@
----
-name: human-gate-negotiation
-description: "Use when preparing concise impact reports before approval requests for high-risk, non-idempotent actions."
-version: 1.0.0
-last-updated: 2026-09-25
-skills:
-  - fabel-protocol
-tools: Read, Grep, Glob, Bash, Edit, Write
-scripts-binding:
-  - .agent/scripts/harness_manager.js
----
-
-# Human Gate Negotiation
-
-## Context
-When an agent attempts a high-risk operation (deploying to production, running `rm -rf`, running a database migration), it MUST be paused, and explicit approval must be sought from the Human Gate. 
-
-## The Impact Report Format
-Never just ask "Can I run this?". You must provide a structured report outlining the consequences of the action so the human can make an informed decision.
-
-**Mandatory Report Structure:**
-1. **Proposed Action**: The exact command or script to be executed.
-2. **Purpose**: Why this is necessary.
-3. **Files/Resources Affected**: Which systems will be mutated.
-4. **Expected Side Effects**: Downtime, data loss, irreversible state changes.
-5. **Verification Status**: Proof that tests passed before reaching this gate.
-6. **Rollback Instructions**: How to undo this action if it fails in production.
-
-## Agent Behavior
-Once the report is generated, the agent must enter a sleep/wait state and CANNOT proceed until the human explicitly provides an approval token.
+---
+name: human-gate-negotiation
+description: "Use when preparing concise impact reports before approval requests for high-risk, non-idempotent actions."
+version: 1.0.0
+last-updated: 2026-09-25
+skills:
+  - fabel-protocol
+tools: Read, Grep, Glob, Bash, Edit, Write
+scripts-binding:
+  - .agent/scripts/harness_manager.js
+---
+
+# Human Gate Negotiation
+
+## Context
+When an agent attempts a high-risk operation (deploying to production, running `rm -rf`, running a database migration), it MUST be paused, and explicit approval must be sought from the Human Gate. 
+
+## The Impact Report Format
+Never just ask "Can I run this?". You must provide a structured report outlining the consequences of the action so the human can make an informed decision.
+
+**Mandatory Report Structure:**
+1. **Proposed Action**: The exact command or script to be executed.
+2. **Purpose**: Why this is necessary.
+3. **Files/Resources Affected**: Which systems will be mutated.
+4. **Expected Side Effects**: Downtime, data loss, irreversible state changes.
+5. **Verification Status**: Proof that tests passed before reaching this gate.
+6. **Rollback Instructions**: How to undo this action if it fails in production.
+
+## Agent Behavior
+Once the report is generated, the agent must enter a sleep/wait state and CANNOT proceed until the human explicitly provides an approval token.

package/skills/i18n-localization/SKILL.md

@@ -1,134 +1,134 @@
----
-name: i18n-localization
-description: "Use when 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."
-version: 5.0.0
-last-updated: 2026-09-13
-skills:
-  - nextjs-react-expert
-  - adapt
-  - baseline-ui
-tools: Read, Grep, Glob, Bash, Edit, Write
-scripts-binding:
-  - .agent/scripts/lint_runner.js
-  - .agent/scripts/verify_all.js
----
-
-# i18n & Localization — Global Scale Mastery
-
----
-
-## 🛠️ Technical Architecture & Reference Recipes
-
----
-
-## Hallucination Traps (Read First)
-
-- ❌ Concatenating translated strings (`'Hello ' + name`) -> ✅ Use interpolation: `t('greeting', { name })` to handle word order differences
-- ❌ Hardcoding date/number formats -> ✅ Use `Intl.DateTimeFormat` and `Intl.NumberFormat` with the user's locale
-- ❌ Assuming all languages read left-to-right -> ✅ Arabic, Hebrew, Farsi are RTL; use CSS `dir='auto'` and logical properties
-- ❌ Using string length for validation on translated text -> ✅ Translations can be 30-200% longer than English; design for expansion
-
----
-
----
-
-## 1. The i18n Architecture (Next.js / React)
-
-Do not hardcode strings inside UI components. Use a standardized library (e.g., `next-intl` or `react-i18next`).
-
-### Step 1: Dictionary Abstraction
-
-```json
-// messages/en.json
-{
-  "Dashboard": {
-    "welcomeMessage": "Welcome back, {name}!",
-    "unreadAlerts": "{count, plural, =0 {No unread alerts} one {You have 1 unread alert} other {You have # unread alerts}}"
-  }
-}
-```
-
-### 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>
-  );
-}
-
-// ✅ 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>
-  );
-}
-```
-
----
-
-## 2. Advanced Native Formatting (`Intl`)
-
-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.
-
-```typescript
-// Data/Currency Formatting correctly tied to the active locale
-const locale = 'de-DE';
-
-// ✅ Currency
-const price = new Intl.NumberFormat(locale, { style: 'currency', currency: 'EUR' }).format(1200.5);
-// Output in Germany: "1.200,50 €"
-
-// ✅ Dates
-const date = new Intl.DateTimeFormat(locale, { dateStyle: 'full' }).format(new Date());
-// Output in Germany: "Freitag, 2. April 2026"
-
-// ✅ Relative Time
-const rtf = new Intl.RelativeTimeFormat(locale, { numeric: 'auto' });
-rtf.format(-2, 'day'); // Output: "vorgestern" (the day before yesterday)
-```
-
----
-
-## 3. Bidirectional Architecture (RTL)
-
-For languages like Arabic and Hebrew, the UI must fundamentally flip horizontally. Right-To-Left (RTL) breaks standard CSS `marginLeft` and `marginRight`.
-
-**The Solution:** Logical CSS Properties.
-Tailwind v4 (and modern CSS) natively supports logical direction.
-
-```css
-/* ❌ BAD: Hardcoded physical space */
-.btn {
-  margin-left: 10px;
-} /* Will break layout in Hebrew */
-
-/* ✅ 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">`
-
----
-
-## 4. Routing and SSR Detection
-
-Users should not face English UI natively in Japan. Detect their browser headers at the edge routing layer.
-
-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`).
+---
+name: i18n-localization
+description: "Use when 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."
+version: 5.0.0
+last-updated: 2026-09-13
+skills:
+  - nextjs-react-expert
+  - adapt
+  - baseline-ui
+tools: Read, Grep, Glob, Bash, Edit, Write
+scripts-binding:
+  - .agent/scripts/lint_runner.js
+  - .agent/scripts/verify_all.js
+---
+
+# i18n & Localization — Global Scale Mastery
+
+---
+
+## 🛠️ Technical Architecture & Reference Recipes
+
+---
+
+## Hallucination Traps (Read First)
+
+- ❌ Concatenating translated strings (`'Hello ' + name`) -> ✅ Use interpolation: `t('greeting', { name })` to handle word order differences
+- ❌ Hardcoding date/number formats -> ✅ Use `Intl.DateTimeFormat` and `Intl.NumberFormat` with the user's locale
+- ❌ Assuming all languages read left-to-right -> ✅ Arabic, Hebrew, Farsi are RTL; use CSS `dir='auto'` and logical properties
+- ❌ Using string length for validation on translated text -> ✅ Translations can be 30-200% longer than English; design for expansion
+
+---
+
+---
+
+## 1. The i18n Architecture (Next.js / React)
+
+Do not hardcode strings inside UI components. Use a standardized library (e.g., `next-intl` or `react-i18next`).
+
+### Step 1: Dictionary Abstraction
+
+```json
+// messages/en.json
+{
+  "Dashboard": {
+    "welcomeMessage": "Welcome back, {name}!",
+    "unreadAlerts": "{count, plural, =0 {No unread alerts} one {You have 1 unread alert} other {You have # unread alerts}}"
+  }
+}
+```
+
+### 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>
+  );
+}
+
+// ✅ 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>
+  );
+}
+```
+
+---
+
+## 2. Advanced Native Formatting (`Intl`)
+
+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.
+
+```typescript
+// Data/Currency Formatting correctly tied to the active locale
+const locale = 'de-DE';
+
+// ✅ Currency
+const price = new Intl.NumberFormat(locale, { style: 'currency', currency: 'EUR' }).format(1200.5);
+// Output in Germany: "1.200,50 €"
+
+// ✅ Dates
+const date = new Intl.DateTimeFormat(locale, { dateStyle: 'full' }).format(new Date());
+// Output in Germany: "Freitag, 2. April 2026"
+
+// ✅ Relative Time
+const rtf = new Intl.RelativeTimeFormat(locale, { numeric: 'auto' });
+rtf.format(-2, 'day'); // Output: "vorgestern" (the day before yesterday)
+```
+
+---
+
+## 3. Bidirectional Architecture (RTL)
+
+For languages like Arabic and Hebrew, the UI must fundamentally flip horizontally. Right-To-Left (RTL) breaks standard CSS `marginLeft` and `marginRight`.
+
+**The Solution:** Logical CSS Properties.
+Tailwind v4 (and modern CSS) natively supports logical direction.
+
+```css
+/* ❌ BAD: Hardcoded physical space */
+.btn {
+  margin-left: 10px;
+} /* Will break layout in Hebrew */
+
+/* ✅ 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">`
+
+---
+
+## 4. Routing and SSR Detection
+
+Users should not face English UI natively in Japan. Detect their browser headers at the edge routing layer.
+
+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`).

package/skills/impeccable/SKILL.md

@@ -1,52 +1,52 @@
----
-name: impeccable
-description: "Use when Flagship design engineering skill for creating production-grade, anti-generic frontend interfaces with supreme craftsmanship, visual hierarchy, typography, spatial systems, and micro-interactions."
-version: 5.0.0
-last-updated: 2026-09-13
-skills:
-  - better-ui
-  - better-colors
-  - baseline-ui
-tools: Read, Grep, Glob, Bash, Edit, Write
-scripts-binding:
-  - .agent/scripts/lint_runner.js
-  - .agent/scripts/verify_all.js
----
-
-# Impeccable — Production-Grade Frontend Craft
-
----
-
-## 🛠️ Technical Architecture & Reference Recipes
-
----
-
----
-
-## Core Pillars of Impeccable UI
-
-### 1. Typography & Typographic Rhythm
-
-- **Optical Sizing & Tracking**: Large display headings (32px+) require tight letter-spacing (`letter-spacing: -0.03em`). Small caption text (12px) requires positive tracking (`letter-spacing: +0.01em`).
-- **Tabular Numbers**: Any numeric data that updates, increments, or displays in columns MUST use `font-variant-numeric: tabular-nums` or `font-feature-settings: "tnum"` to prevent visual jitter.
-- **Text Wrapping & Balance**: Headings MUST use `text-wrap: balance` to prevent typographic orphans. Body paragraphs MUST use `text-wrap: pretty` (where supported) or max `65ch` width.
-
-### 2. Color Systems & Gamut Precision
-
-- **OKLCH Color Space**: Prefer `oklch()` over `hsl()` or `hex` for smooth perceptual uniformity across hue and lightness shifts.
-- **Subtle Surface Steps**: Define surface colors with small perceptual lightness steps ($L \pm 2\%$) to create hierarchy without harsh dividers.
-- **Adaptive Contrast**: Text contrast MUST adapt automatically across light/dark themes with high legibility ratios ($\ge 7:1$ for primary, $\ge 4.5:1$ for secondary).
-
-### 3. Motion & Micro-Interactions
-
-- **Intentional Motion**: Animations exist ONLY to convey spatial continuity, provide press feedback, or indicate state changes.
-- **Duration Constraints**: Micro-interactions $\le 160\text{ms}$; dropdowns/popovers $\le 220\text{ms}$; page transitions $\le 300\text{ms}$.
-- **Physically Grounded Entrances**: Elements scale in from `scale(0.96)` and opacity `0`, anchored to their trigger origin.
-- **DOM Entry (@starting-style)**: Use `@starting-style` with `transition-behavior: allow-discrete` for smooth `display: none` to `display: block` entrance animations without JS overhead.
-
-### 4. Layout Mechanics & Spatial Math
-
-- **8px Grid System**: Every margin, padding, gap, and height MUST derive from an 8px grid (or 4px micro-grid).
-- **Asymmetrical Balance**: Avoid cookie-cutter centered layouts for SaaS apps. Use strong left-aligned structural axes with generous negative space.
-- **Container Queries**: Components adjust layout based on container size (`@container`), not viewport size (`@media`), making them context-agnostic.
-- **WCAG 2.2 AA Target Size (SC 2.5.8)**: All interactive targets MUST measure at least `24x24px` CSS pixels (min `44x44px` for touch).
+---
+name: impeccable
+description: "Use when Flagship design engineering skill for creating production-grade, anti-generic frontend interfaces with supreme craftsmanship, visual hierarchy, typography, spatial systems, and micro-interactions."
+version: 5.0.0
+last-updated: 2026-09-13
+skills:
+  - better-ui
+  - better-colors
+  - baseline-ui
+tools: Read, Grep, Glob, Bash, Edit, Write
+scripts-binding:
+  - .agent/scripts/lint_runner.js
+  - .agent/scripts/verify_all.js
+---
+
+# Impeccable — Production-Grade Frontend Craft
+
+---
+
+## 🛠️ Technical Architecture & Reference Recipes
+
+---
+
+---
+
+## Core Pillars of Impeccable UI
+
+### 1. Typography & Typographic Rhythm
+
+- **Optical Sizing & Tracking**: Large display headings (32px+) require tight letter-spacing (`letter-spacing: -0.03em`). Small caption text (12px) requires positive tracking (`letter-spacing: +0.01em`).
+- **Tabular Numbers**: Any numeric data that updates, increments, or displays in columns MUST use `font-variant-numeric: tabular-nums` or `font-feature-settings: "tnum"` to prevent visual jitter.
+- **Text Wrapping & Balance**: Headings MUST use `text-wrap: balance` to prevent typographic orphans. Body paragraphs MUST use `text-wrap: pretty` (where supported) or max `65ch` width.
+
+### 2. Color Systems & Gamut Precision
+
+- **OKLCH Color Space**: Prefer `oklch()` over `hsl()` or `hex` for smooth perceptual uniformity across hue and lightness shifts.
+- **Subtle Surface Steps**: Define surface colors with small perceptual lightness steps ($L \pm 2\%$) to create hierarchy without harsh dividers.
+- **Adaptive Contrast**: Text contrast MUST adapt automatically across light/dark themes with high legibility ratios ($\ge 7:1$ for primary, $\ge 4.5:1$ for secondary).
+
+### 3. Motion & Micro-Interactions
+
+- **Intentional Motion**: Animations exist ONLY to convey spatial continuity, provide press feedback, or indicate state changes.
+- **Duration Constraints**: Micro-interactions $\le 160\text{ms}$; dropdowns/popovers $\le 220\text{ms}$; page transitions $\le 300\text{ms}$.
+- **Physically Grounded Entrances**: Elements scale in from `scale(0.96)` and opacity `0`, anchored to their trigger origin.
+- **DOM Entry (@starting-style)**: Use `@starting-style` with `transition-behavior: allow-discrete` for smooth `display: none` to `display: block` entrance animations without JS overhead.
+
+### 4. Layout Mechanics & Spatial Math
+
+- **8px Grid System**: Every margin, padding, gap, and height MUST derive from an 8px grid (or 4px micro-grid).
+- **Asymmetrical Balance**: Avoid cookie-cutter centered layouts for SaaS apps. Use strong left-aligned structural axes with generous negative space.
+- **Container Queries**: Components adjust layout based on container size (`@container`), not viewport size (`@media`), making them context-agnostic.
+- **WCAG 2.2 AA Target Size (SC 2.5.8)**: All interactive targets MUST measure at least `24x24px` CSS pixels (min `44x44px` for touch).