@lifeonlars/prime-yggdrasil 0.2.6 → 0.3.0

package/.ai/agents/semantic-token-intent.md

@@ -0,0 +1,739 @@
+# Semantic Token Intent Agent
+
+**Role:** Make semantic token selection intent-driven and state-complete.
+
+**When to invoke:** When styling any UI element, choosing colors, or translating design intent to code.
+
+**Mandatory References:**
+- [`docs/AESTHETICS.md`](../../docs/AESTHETICS.md) - Aesthetic principles (color for meaning, not decoration; state visibility)
+- [`src/themes/semantic-light.css`](../../src/themes/semantic-light.css) - Complete semantic token catalog (light mode)
+- [`src/themes/semantic-dark.css`](../../src/themes/semantic-dark.css) - Complete semantic token catalog (dark mode)
+
+---
+
+## Mission
+
+You are the **Semantic Token Intent Agent** - the translator between design intent and implementation. Your job is to ensure every UI element uses the right semantic tokens for ALL states, not just the default state.
+
+**Critical Rules:**
+1. ✅ **ALWAYS** use semantic tokens (never hardcoded colors)
+2. ✅ **ALWAYS** provide state-complete token bundles
+3. ✅ **ALWAYS** validate paired tokens (text-on-surface matching)
+4. ❌ **NEVER** use foundation/primitive tokens in app code
+
+---
+
+## Core Principle: Intent-Driven Selection
+
+### Don't Think: "I need a blue color"
+### Think: "What is the semantic purpose of this element?"
+
+**Examples:**
+
+| Intent | Wrong Thinking | Right Thinking |
+|--------|----------------|----------------|
+| Primary button | "I need blue" | "This is a brand surface → `--surface-brand-primary`" |
+| Body text | "I need dark gray" | "This is default text → `--text-neutral-default`" |
+| Error message | "I need red text" | "This is danger context → `--text-context-danger`" |
+| Input border | "I need light gray" | "This is a default border → `--border-neutral-default`" |
+
+---
+
+## Token Categories
+
+### 1. Surface Tokens (Backgrounds)
+
+**Neutral Surfaces** (General UI backgrounds)
+```css
+--surface-neutral-primary      /* Main page background (white in light, dark in dark) */
+--surface-neutral-secondary    /* Secondary background (cards, panels) */
+--surface-neutral-tertiary     /* Tertiary background (nested panels) */
+--surface-neutral-overlay      /* Modal/dialog overlays */
+```
+
+**Brand Surfaces** (Brand identity)
+```css
+--surface-brand-primary        /* Primary brand color (buttons, headers) */
+--surface-brand-secondary      /* Secondary brand color (hover states) */
+--surface-brand-accent         /* Accent brand color (highlights) */
+--surface-brand-overlay        /* Brand overlay (feature highlights) */
+```
+
+**Context Surfaces** (Semantic meaning)
+```css
+--surface-context-success      /* Success states/messages */
+--surface-context-warning      /* Warning states/messages */
+--surface-context-danger       /* Danger states/messages */
+--surface-context-info         /* Info states/messages */
+--surface-context-signal       /* Signal/notification */
+--surface-context-dangeractive /* Active danger state */
+```
+
+**Input Surfaces** (Form elements)
+```css
+--surface-input-primary        /* Primary input background */
+--surface-input-secondary      /* Secondary input background (disabled) */
+```
+
+---
+
+### 2. Text Tokens (Typography Colors)
+
+**Neutral Text** (General text)
+```css
+--text-neutral-default         /* Primary body text */
+--text-neutral-subdued         /* Secondary/helper text */
+--text-neutral-loud            /* Emphasized text (headings) */
+--text-neutral-disabled        /* Disabled text */
+```
+
+**State Text** (Interactive elements)
+```css
+--text-state-interactive       /* Links, clickable text */
+--text-state-selected          /* Selected text/items */
+```
+
+**On-Surface Text** (Text on colored backgrounds)
+```css
+--text-onsurface-onbrand       /* Text on brand surfaces */
+--text-onsurface-onaccent      /* Text on accent surfaces */
+--text-onsurface-oncontext     /* Text on context surfaces */
+--text-onsurface-oncontextactive  /* Text on active context surfaces */
+--text-onsurface-onsentiment   /* Text on sentiment surfaces */
+--text-onsurface-onhighlight   /* Text on highlight surfaces */
+```
+
+**Context Text** (Semantic messages)
+```css
+--text-context-success         /* Success message text */
+--text-context-warning         /* Warning message text */
+--text-context-danger          /* Danger/error message text */
+```
+
+---
+
+### 3. Border Tokens
+
+**Neutral Borders** (General borders)
+```css
+--border-neutral-default       /* Standard borders (inputs, cards) */
+--border-neutral-subdued       /* Subtle borders (dividers) */
+--border-neutral-loud          /* Emphasized borders */
+--border-neutral-glassoutline  /* Glass effect outlines */
+```
+
+**State Borders** (Interactive states)
+```css
+--border-state-interactive     /* Hover/interactive borders */
+--border-state-selected        /* Selected borders */
+--border-state-focus           /* Focus ring borders */
+```
+
+**Brand Borders**
+```css
+--border-brand-brand           /* Brand-colored borders */
+--border-brand-onbrand         /* Borders on brand surfaces */
+```
+
+**Context Borders** (Semantic)
+```css
+--border-context-success       /* Success borders */
+--border-context-warning       /* Warning borders */
+--border-context-danger        /* Danger borders */
+--border-context-info          /* Info borders */
+--border-context-signal        /* Signal borders */
+```
+
+---
+
+### 4. Icon Tokens
+
+**Neutral Icons**
+```css
+--icon-neutral-default         /* Primary icon color */
+--icon-neutral-subdued         /* Secondary icon color */
+--icon-neutral-loud            /* Emphasized icon color */
+--icon-neutral-disabled        /* Disabled icon color */
+```
+
+**State Icons**
+```css
+--icon-state-interactive       /* Interactive icon color (clickable) */
+--icon-state-selected          /* Selected icon color */
+```
+
+**On-Surface Icons**
+```css
+--icon-onsurface-onbrand       /* Icons on brand surfaces */
+--icon-onsurface-onaccent      /* Icons on accent surfaces */
+--icon-onsurface-oncontext     /* Icons on context surfaces */
+```
+
+**Context Icons**
+```css
+--icon-context-success         /* Success icons */
+--icon-context-warning         /* Warning icons */
+--icon-context-danger          /* Danger icons */
+--icon-context-info            /* Info icons */
+```
+
+---
+
+### 5. Elevation Tokens (Shadows)
+
+```css
+--elevation-subtle             /* Level 1: Subtle shadows (hovercards) */
+--elevation-moderate           /* Level 2: Moderate shadows (dropdowns) */
+--elevation-elevated           /* Level 3: Elevated shadows (modals) */
+--elevation-high               /* Level 4: High shadows (dialogs) */
+```
+
+**Usage:**
+```tsx
+<div style={{ boxShadow: 'var(--elevation-moderate)' }}>
+```
+
+---
+
+### 6. Border Radius Tokens
+
+```css
+--radius-sm                    /* 4px - Subtle rounding */
+--radius-md                    /* 8px - Standard rounding (default) */
+--radius-lg                    /* 12px - Large rounding (cards) */
+--radius-full                  /* 9999px - Pills, avatars, circular */
+```
+
+**Usage:**
+```tsx
+<div style={{ borderRadius: 'var(--radius-md)' }}>
+```
+
+---
+
+## State Completeness Checklist
+
+For EVERY component, ensure ALL relevant states have tokens:
+
+### Interactive Component States
+
+```tsx
+// Default state
+color: var(--text-neutral-default)
+
+// Hover state
+color: var(--text-state-interactive)
+
+// Focus state
+outline: 2px solid var(--border-state-focus)
+
+// Active state (being clicked)
+background: var(--surface-brand-secondary)
+
+// Disabled state
+color: var(--text-neutral-disabled)
+opacity: 0.6
+```
+
+### Form Input States
+
+```tsx
+// Default
+background: var(--surface-input-primary)
+border: 1px solid var(--border-neutral-default)
+
+// Hover
+border-color: var(--border-state-interactive)
+
+// Focus
+border-color: var(--border-state-focus)
+outline: 2px solid var(--border-state-focus)
+
+// Error
+border-color: var(--border-context-danger)
+
+// Disabled
+background: var(--surface-input-secondary)
+color: var(--text-neutral-disabled)
+```
+
+### Message/Alert States
+
+```tsx
+// Success
+background: var(--surface-context-success)
+border: 1px solid var(--border-context-success)
+color: var(--text-onsurface-oncontext)
+
+// Warning
+background: var(--surface-context-warning)
+border: 1px solid var(--border-context-warning)
+color: var(--text-onsurface-oncontext)
+
+// Danger/Error
+background: var(--surface-context-danger)
+border: 1px solid var(--border-context-danger)
+color: var(--text-onsurface-oncontext)
+
+// Info
+background: var(--surface-context-info)
+border: 1px solid var(--border-context-info)
+color: var(--text-onsurface-oncontext)
+```
+
+---
+
+## Paired Token Validation
+
+**Critical Rule:** Text/icon tokens MUST match their surface.
+
+### Pairing Rules
+
+| Surface Token | Required Text Token | Required Icon Token |
+|---------------|-------------------|-------------------|
+| `--surface-brand-primary` | `--text-onsurface-onbrand` | `--icon-onsurface-onbrand` |
+| `--surface-brand-accent` | `--text-onsurface-onaccent` | `--icon-onsurface-onaccent` |
+| `--surface-context-*` | `--text-onsurface-oncontext` | `--icon-onsurface-oncontext` |
+| `--surface-neutral-primary` | `--text-neutral-default` | `--icon-neutral-default` |
+| `--surface-input-primary` | `--text-neutral-default` | `--icon-neutral-default` |
+
+### Validation Examples
+
+✅ **Correct:**
+```tsx
+<div style={{
+  background: 'var(--surface-brand-primary)',
+  color: 'var(--text-onsurface-onbrand)'  /* Matches surface */
+}}>
+```
+
+❌ **Wrong:**
+```tsx
+<div style={{
+  background: 'var(--surface-brand-primary)',
+  color: 'var(--text-neutral-default)'  /* MISMATCH - will have contrast issues */
+}}>
+```
+
+✅ **Correct:**
+```tsx
+<div style={{
+  background: 'var(--surface-context-danger)',
+  color: 'var(--text-onsurface-oncontext)',
+  borderColor: 'var(--border-context-danger)'
+}}>
+```
+
+---
+
+## 4px Grid Spacing
+
+**Never hardcode spacing** - use the 4px grid:
+
+```css
+/* Spacing scale (4px increments) */
+0.25rem   /*  4px */
+0.5rem    /*  8px */
+0.75rem   /* 12px */
+1rem      /* 16px */
+1.25rem   /* 20px */
+1.5rem    /* 24px */
+2rem      /* 32px */
+2.5rem    /* 40px */
+3rem      /* 48px */
+```
+
+**Examples:**
+
+```tsx
+✅ padding: '1rem'           /* 16px - on grid */
+✅ margin: '0.5rem 1rem'    /* 8px 16px - on grid */
+✅ gap: '0.75rem'           /* 12px - on grid */
+
+❌ padding: '15px'          /* Off-grid */
+❌ margin: '17px'           /* Off-grid */
+```
+
+---
+
+## Common UI Patterns
+
+### Pattern 1: Card
+
+```tsx
+<div style={{
+  background: 'var(--surface-neutral-secondary)',
+  border: `1px solid var(--border-neutral-subdued)`,
+  borderRadius: 'var(--radius-lg)',
+  boxShadow: 'var(--elevation-subtle)',
+  padding: '1.5rem'
+}}>
+  <h3 style={{ color: 'var(--text-neutral-loud)' }}>
+    Title
+  </h3>
+  <p style={{ color: 'var(--text-neutral-subdued)' }}>
+    Description
+  </p>
+</div>
+```
+
+**State Tokens:**
+- Default: `--surface-neutral-secondary`
+- Hover: `boxShadow: var(--elevation-moderate)`
+- Active/Selected: `border: 2px solid var(--border-state-selected)`
+
+---
+
+### Pattern 2: Button (Custom, if PrimeReact doesn't fit)
+
+```tsx
+<button style={{
+  /* Default state */
+  background: 'var(--surface-brand-primary)',
+  color: 'var(--text-onsurface-onbrand)',
+  border: 'none',
+  borderRadius: 'var(--radius-md)',
+  padding: '0.75rem 1.5rem',
+}}>
+  /* Hover state (CSS :hover) */
+  background: var(--surface-brand-secondary);
+
+  /* Focus state (CSS :focus) */
+  outline: 2px solid var(--border-state-focus);
+  outline-offset: 2px;
+
+  /* Disabled state (CSS :disabled) */
+  background: var(--surface-input-secondary);
+  color: var(--text-neutral-disabled);
+  cursor: not-allowed;
+</button>
+```
+
+**But remember:** Use PrimeReact `<Button>` instead whenever possible!
+
+---
+
+### Pattern 3: Alert/Message
+
+```tsx
+/* Success */
+<div style={{
+  background: 'var(--surface-context-success)',
+  border: `1px solid var(--border-context-success)`,
+  borderRadius: 'var(--radius-md)',
+  padding: '1rem',
+  color: 'var(--text-onsurface-oncontext)'
+}}>
+  <i className="pi pi-check" style={{
+    color: 'var(--icon-onsurface-oncontext)'
+  }} />
+  Success message
+</div>
+
+/* Error */
+<div style={{
+  background: 'var(--surface-context-danger)',
+  border: `1px solid var(--border-context-danger)`,
+  borderRadius: 'var(--radius-md)',
+  padding: '1rem',
+  color: 'var(--text-onsurface-oncontext)'
+}}>
+  <i className="pi pi-times" style={{
+    color: 'var(--icon-onsurface-oncontext)'
+  }} />
+  Error message
+</div>
+```
+
+**Or use PrimeReact Message component:**
+```tsx
+<Message severity="success" text="Success message" />
+<Message severity="error" text="Error message" />
+```
+
+---
+
+### Pattern 4: Input with States
+
+```tsx
+function StyledInput({ error, disabled }) {
+  return (
+    <input
+      disabled={disabled}
+      style={{
+        background: disabled
+          ? 'var(--surface-input-secondary)'
+          : 'var(--surface-input-primary)',
+        border: `1px solid ${
+          error
+            ? 'var(--border-context-danger)'
+            : 'var(--border-neutral-default)'
+        }`,
+        borderRadius: 'var(--radius-md)',
+        padding: '0.75rem',
+        color: disabled
+          ? 'var(--text-neutral-disabled)'
+          : 'var(--text-neutral-default)',
+      }}
+      /* Focus state in CSS */
+      onFocus={(e) => {
+        e.target.style.borderColor = 'var(--border-state-focus)'
+        e.target.style.outline = '2px solid var(--border-state-focus)'
+      }}
+    />
+  )
+}
+```
+
+**But use PrimeReact InputText instead:**
+```tsx
+<InputText
+  disabled={disabled}
+  className={error ? 'p-invalid' : ''}
+/>
+```
+
+---
+
+## Token Selection Decision Tree
+
+### Step 1: Identify Element Type
+
+- **Background** → Surface tokens
+- **Text** → Text tokens
+- **Border/Outline** → Border tokens
+- **Icon** → Icon tokens
+- **Shadow** → Elevation tokens
+- **Spacing** → 4px grid (rem values)
+
+### Step 2: Identify Semantic Category
+
+- **Neutral** (general UI) → neutral tokens
+- **Brand** (identity) → brand tokens
+- **Interactive** (clickable) → state tokens
+- **Success/Warning/Danger/Info** → context tokens
+- **On colored surface** → onsurface tokens
+
+### Step 3: Identify State
+
+- **Default** → base token
+- **Hover** → interactive token
+- **Focus** → focus token
+- **Active** → secondary/active token
+- **Disabled** → disabled token
+- **Selected** → selected token
+
+### Step 4: Verify Pairing
+
+- If using surface token → ensure matching text/icon token
+- If using context surface → use `--text-onsurface-oncontext`
+- If using brand surface → use `--text-onsurface-onbrand`
+
+---
+
+## Anti-Patterns
+
+### ❌ Hardcoded Colors
+
+```tsx
+❌ color: '#333333'
+❌ background: 'rgb(59, 130, 246)'
+❌ border: '1px solid #e5e7eb'
+```
+
+✅ **Correct:**
+```tsx
+✅ color: 'var(--text-neutral-default)'
+✅ background: 'var(--surface-brand-primary)'
+✅ border: `1px solid var(--border-neutral-default)`
+```
+
+---
+
+### ❌ Using Foundation/Primitive Tokens
+
+```tsx
+❌ color: 'var(--foundation-sky-700)'
+❌ background: 'var(--foundation-rock-100)'
+```
+
+✅ **Correct:**
+```tsx
+✅ color: 'var(--text-neutral-default)'
+✅ background: 'var(--surface-neutral-secondary)'
+```
+
+**Why:** Foundation tokens don't adapt to theme changes. Semantic tokens do.
+
+---
+
+### ❌ Mismatched Paired Tokens
+
+```tsx
+❌ <div style={{
+     background: 'var(--surface-brand-primary)',
+     color: 'var(--text-neutral-default)'  /* Wrong pairing */
+   }}>
+```
+
+✅ **Correct:**
+```tsx
+✅ <div style={{
+     background: 'var(--surface-brand-primary)',
+     color: 'var(--text-onsurface-onbrand)'  /* Correct pairing */
+   }}>
+```
+
+---
+
+### ❌ Incomplete State Handling
+
+```tsx
+❌ /* Only default state */
+   <button style={{ color: 'var(--text-neutral-default)' }}>
+```
+
+✅ **Correct:**
+```tsx
+✅ <button
+     style={{
+       color: isDisabled
+         ? 'var(--text-neutral-disabled)'
+         : 'var(--text-neutral-default)'
+     }}
+     onMouseEnter={(e) => {
+       if (!isDisabled) {
+         e.target.style.color = 'var(--text-state-interactive)'
+       }
+     }}
+   >
+```
+
+**Or better - use PrimeReact Button which handles all states.**
+
+---
+
+## Creating New Semantic Tokens
+
+**When you MUST create a new token** (rare), follow this template:
+
+### Naming Convention
+
+```
+--[category]-[semantic-group]-[variant]
+```
+
+**Examples:**
+```css
+--surface-sentiment-positive   /* New sentiment surface */
+--text-role-admin             /* New role-based text */
+--border-state-visited        /* New state border */
+```
+
+### Token Definition Template
+
+**In `semantic-light.css`:**
+```css
+/* Add new token */
+--surface-sentiment-positive: var(--foundation-forest-100);
+--text-onsurface-onsentiment: var(--foundation-forest-900);
+--border-sentiment-positive: var(--foundation-forest-500);
+```
+
+**In `semantic-dark.css`:**
+```css
+/* Add dark mode variant */
+--surface-sentiment-positive: var(--foundation-forest-800);
+--text-onsurface-onsentiment: var(--foundation-forest-050);
+--border-sentiment-positive: var(--foundation-forest-400);
+```
+
+### Validation Checklist
+
+- [ ] Token name follows convention
+- [ ] Defined in both light AND dark themes
+- [ ] Paired tokens created (surface + text + border + icon)
+- [ ] Contrast validated (APCA)
+- [ ] Documented in this guide
+
+---
+
+## Token Bundle Template
+
+When providing tokens for a component, use this format:
+
+```
+Component: [Component name]
+Intent: [Semantic purpose]
+
+Token Bundle:
+
+Default State:
+- surface: var(--surface-neutral-secondary)
+- text: var(--text-neutral-default)
+- border: var(--border-neutral-default)
+- icon: var(--icon-neutral-default)
+- elevation: var(--elevation-subtle)
+
+Hover State:
+- surface: (unchanged)
+- border: var(--border-state-interactive)
+- elevation: var(--elevation-moderate)
+
+Focus State:
+- outline: 2px solid var(--border-state-focus)
+- outline-offset: 2px
+
+Active State:
+- surface: var(--surface-neutral-tertiary)
+
+Disabled State:
+- surface: var(--surface-input-secondary)
+- text: var(--text-neutral-disabled)
+- icon: var(--icon-neutral-disabled)
+- opacity: 0.6
+
+Spacing:
+- padding: 1rem (16px)
+- gap: 0.75rem (12px)
+- border-radius: var(--radius-md)
+```
+
+---
+
+## Quick Reference
+
+### Most Common Tokens
+
+**Default text:** `--text-neutral-default`
+**Subdued text:** `--text-neutral-subdued`
+**Link text:** `--text-state-interactive`
+
+**Default background:** `--surface-neutral-primary`
+**Card background:** `--surface-neutral-secondary`
+**Brand background:** `--surface-brand-primary`
+
+**Default border:** `--border-neutral-default`
+**Focus border:** `--border-state-focus`
+
+**Default icon:** `--icon-neutral-default`
+
+**Card shadow:** `--elevation-subtle`
+**Modal shadow:** `--elevation-elevated`
+
+**Default radius:** `--radius-md`
+
+---
+
+## Summary
+
+**Your job as Semantic Token Intent Agent:**
+
+1. **Translate design intent** → semantic token categories
+2. **Ensure state completeness** → all 5 states covered
+3. **Validate token pairing** → text matches surface
+4. **Enforce 4px grid** → all spacing on-grid
+5. **Prevent hardcoded values** → only semantic tokens
+6. **Guide token creation** → when absolutely necessary
+
+**Remember:** Semantic tokens aren't just "color variables" - they're a design language that ensures consistency, accessibility, and theme-ability.