@lifeonlars/prime-yggdrasil 0.1.0

package/docs/README.md

@@ -0,0 +1,161 @@
+# Yggdrasil Theme Documentation
+
+This directory contains comprehensive documentation for the Yggdrasil theme system built on PrimeReact.
+
+## 📚 Documentation Index
+
+### Theme Architecture
+- **[Theme Architecture](../src/theme/README.md)** - Complete overview of the theme file structure, design tokens, and usage patterns
+
+### Design System Implementation
+- **[Elevation System](./ELEVATION-SYSTEM.md)** - Research and best practices for elevation/shadows in light and dark modes
+- **[Elevation Implementation](./ELEVATION-IMPLEMENTATION.md)** - Implementation guide for the 4-level elevation system
+- **[Contrast Report](./contrast-report.md)** - APCA contrast test results for all semantic color tokens
+
+### Scripts Documentation
+- **[Scripts Guide](./scripts/README.md)** - Documentation for all theme build and analysis scripts
+
+## 🎨 Design Principles
+
+### 4px Soft Grid
+All spacing, padding, margins, and border-radius values follow a 4px grid:
+- ✅ Valid: `4px`, `8px`, `12px`, `16px`, `20px`, `24px`
+- ❌ Invalid: `5px`, `6px`, `10px`, `15px`
+
+### Semantic Token Architecture
+```
+Foundation Colors (foundations.css)
+         ↓
+Border Radius Tokens (radius.css)
+         ↓
+Semantic Tokens (semantic-light.css / semantic-dark.css)
+         ↓
+Component Styles (components.css)
+```
+
+### Design Token Hierarchy
+
+1. **Foundation Colors** - Raw color values, never used directly
+   - Sky, Sea, Forest, Sand, Berries, Rock palettes
+
+2. **Border Radius** - Following 4px grid
+   - `--radius-sm` (4px), `--radius-md` (8px), `--radius-lg` (12px)
+   - Component-specific: `--button-radius`, `--input-radius`
+
+3. **Semantic Tokens** - Theme-aware, context-based
+   - Surfaces: `--surface-neutral-primary`, `--surface-brand-primary`
+   - Text: `--text-neutral-default`, `--text-onsurface-onbrand`
+   - Borders: `--border-neutral-default`, `--border-state-focus`
+   - Elevation: `--elevation-subtle`, `--elevation-moderate`
+
+4. **Utility Classes** - Direct application in JSX
+   - Shadows: `.shadow-1`, `.shadow-2`, `.shadow-3`
+   - Border radius: `.border-round`, `.border-round-lg`
+
+## 🛠️ Development Workflow
+
+### For Component Development
+1. Use semantic tokens exclusively (never foundation colors)
+2. Follow 4px grid for all spacing/radius
+3. Test in both light and dark modes
+4. Run contrast tests for new color combinations
+
+### For Theme Modifications
+1. Update semantic tokens in `semantic-light.css` / `semantic-dark.css`
+2. Regenerate analysis reports if needed
+3. Test Storybook in both themes
+4. Update documentation if architecture changes
+
+## 📊 Testing & Validation
+
+### Contrast Testing
+```bash
+node scripts/test-contrast.js
+```
+Tests all semantic color tokens against WCAG 3.0 (APCA) requirements.
+
+### Theme Validation
+```bash
+node scripts/validate-themes.js
+```
+Validates theme structure and token consistency.
+
+## 🔄 Regenerating Reports
+
+Analysis reports are gitignored and can be regenerated:
+
+```bash
+# Analyze hardcoded colors
+node scripts/analyze-hardcoded-colors.js
+
+# Audit foundation variable usage
+node scripts/audit-foundation-usage.js
+
+# Generate contrast report
+node scripts/test-contrast.js > docs/contrast-report.md
+```
+
+## 📁 Project Structure
+
+```
+prime-yggdrasil/
+├── src/
+│   ├── theme/
+│   │   ├── README.md              # Theme architecture guide
+│   │   ├── foundations.css        # Foundation color palette
+│   │   ├── radius.css             # Border radius tokens
+│   │   ├── semantic-light.css     # Light mode semantic tokens
+│   │   ├── semantic-dark.css      # Dark mode semantic tokens
+│   │   ├── prime-palette.css      # PrimeReact color mappings
+│   │   └── components.css         # Component styles + utilities
+│   ├── blocks/                    # Custom component blocks
+│   └── stories/                   # Storybook documentation
+├── docs/
+│   ├── README.md                  # This file
+│   ├── ELEVATION-SYSTEM.md        # Elevation research
+│   ├── ELEVATION-IMPLEMENTATION.md
+│   ├── contrast-report.md
+│   └── scripts/                   # Scripts documentation
+└── scripts/
+    ├── test-contrast.js           # APCA contrast testing
+    ├── validate-themes.js         # Theme validation
+    ├── replace-*.js               # Bulk replacement scripts
+    └── analyze-*.js               # Analysis scripts
+```
+
+## 🎯 Quick Reference
+
+### Common Tasks
+
+**Add a new semantic token:**
+1. Add to `semantic-light.css` and `semantic-dark.css`
+2. Update theme README if it's a new category
+3. Test in Storybook
+
+**Replace hardcoded colors:**
+1. Use appropriate replacement script
+2. Test components in both themes
+3. Run contrast validation
+
+**Update border radius:**
+1. Modify `radius.css` tokens
+2. Components automatically inherit changes
+3. Test responsive layouts
+
+## 🤖 For AI Agents
+
+When working on this project:
+- Always use semantic tokens, never foundation colors directly
+- Follow the 4px grid for spacing/radius
+- Test both light and dark modes
+- Check contrast with APCA (WCAG 3.0)
+- Update relevant documentation
+- Regenerate reports after major changes
+
+## 📝 Version History
+
+See git commit history for detailed changes:
+- Border radius system implementation
+- Elevation/shadow system with dark mode support
+- APCA contrast testing integration
+- Semantic token refactoring

package/docs/archive/README.md

@@ -0,0 +1,27 @@
+# Documentation Archive
+
+This folder contains outdated or superseded documentation kept for historical reference.
+
+## Archived Files
+
+### SEMANTIC-MIGRATION-PLAN.md
+**Status**: ✅ Completed
+**Date Archived**: 2026-01-05
+**Reason**: Migration successfully completed. 727 colors replaced with semantic tokens (96% coverage).
+**Superseded By**: Work is complete, no replacement doc needed.
+
+---
+
+Files in this directory are kept for reference only and should not be used for current development.
+
+### YGGDRASIL_THEME.md
+**Status**: ⚠️ Superseded
+**Date Archived**: 2026-01-05
+**Reason**: Outdated theme documentation from early project stage.
+**Superseded By**: `src/theme/README.md` and `docs/README.md`
+
+### agentic_policy.md  
+**Status**: ⚠️ Superseded
+**Date Archived**: 2026-01-05
+**Reason**: Early agentic development policy, now replaced with comprehensive guide.
+**Superseded By**: `docs/AI-AGENT-GUIDE.md`

package/docs/archive/SEMANTIC-MIGRATION-PLAN.md

@@ -0,0 +1,177 @@
+# Semantic Token Migration Plan
+
+**Generated:** 2026-01-04
+**Status:** In Progress
+**Total Hardcoded Colors:** 755
+**Components Affected:** 67
+
+## Migration Strategy
+
+### Phase 1: High-Impact Components (Priority)
+Components with most hardcoded colors that are commonly used:
+
+1. **Button** (72 colors) - ⚠️ CRITICAL - Most used component
+2. **DataTable** (32 colors) - ⚠️ HIGH - Complex data display
+3. **Menu Components** (166 colors total across 6 menu types)
+   - Menubar (49)
+   - Megamenu (47)
+   - Menu (20)
+   - Slidemenu (20)
+   - Tieredmenu (19)
+   - Contextmenu (17)
+
+### Phase 2: Form & Input Components
+4. **Dropdown/Select Components** (31 colors)
+   - TreeSelect (19)
+   - CascadeSelect (12)
+5. **Lists & Selection** (46 colors)
+   - Listbox (16)
+   - OrderList (16)
+   - PickList (14)
+6. **Date/Time** (22 colors)
+   - DatePicker (22)
+7. **Autocomplete** (8 colors)
+
+### Phase 3: Navigation & Layout
+8. **Accordion** (15 colors)
+9. **TabView** (13 colors)
+10. **Panel Components** (22 colors)
+    - Panel (12)
+    - Fieldset (10)
+11. **Stepper** (12 colors)
+12. **TabMenu** (10 colors)
+13. **Breadcrumb** (7 colors)
+
+### Phase 4: Data Display
+14. **TreeTable** (28 colors)
+15. **Tree** (13 colors)
+16. **DataView** (8 colors)
+17. **DataScroller** (9 colors)
+18. **Galleria** (9 colors)
+19. **Carousel** (5 colors)
+20. **Timeline** (2 colors)
+
+### Phase 5: Misc Components
+21. **SplitButton** (23 colors)
+22. **PanelMenu** (30 colors)
+23. **OrganizationChart** (11 colors)
+24. **ToggleButton** (13 colors)
+25. **OverlayPanel** (8 colors)
+26. **Remaining** (< 10 colors each)
+
+## Required Semantic Tokens
+
+Based on analysis, we need to ensure these semantic tokens exist:
+
+### Button Variants
+- `--button-primary-background`
+- `--button-primary-text`
+- `--button-primary-border`
+- `--button-primary-hover-background`
+- `--button-primary-active-background`
+- `--button-secondary-*` (full set)
+- `--button-help-*` (full set - purple variant)
+- `--button-contrast-*` (full set - dark variant)
+- `--button-outlined-*` (full set)
+- `--button-text-*` (full set)
+
+### Menu/Navigation
+- `--menu-background`
+- `--menu-item-background`
+- `--menu-item-hover-background`
+- `--menu-item-active-background`
+- `--menu-text-default`
+- `--menu-text-hover`
+- `--menu-separator-border`
+
+### Data Display
+- `--table-header-background`
+- `--table-header-text`
+- `--table-row-background`
+- `--table-row-alt-background` (striping)
+- `--table-row-hover-background`
+- `--table-row-selected-background`
+- `--table-cell-border`
+
+### Form Controls (extend existing)
+- Need to verify all input states are covered
+- Add any missing variant tokens
+
+## Migration Workflow
+
+### For Each Component:
+
+1. **Analyze** - Review hardcoded colors in context
+2. **Map** - Create semantic token mappings
+3. **Add Tokens** - Add any missing tokens to both semantic-light.css and semantic-dark.css
+4. **Replace** - Use targeted replacement script
+5. **Test** - Verify in Storybook (light + dark)
+6. **Contrast** - Run APCA tests for new tokens
+7. **Document** - Update if new token categories added
+
+### Example: Button Migration
+
+```css
+/* BEFORE */
+.p-button {
+  background: #3b82f6;
+  color: #ffffff;
+}
+
+/* AFTER */
+.p-button {
+  background: var(--button-primary-background);
+  color: var(--button-primary-text);
+}
+```
+
+## Current Status
+
+### ✅ Completed Components
+- Dialog
+- Checkbox
+- RadioButton
+- Card (partial - uses semantic tokens)
+
+### 🚧 In Progress
+- None currently
+
+### 📋 Next Up
+1. Button (highest priority)
+2. Menu components (second highest)
+3. DataTable
+
+## Token Addition Checklist
+
+When adding new semantic tokens:
+
+1. ☐ Add to `semantic-light.css`
+2. ☐ Add to `semantic-dark.css`
+3. ☐ Test contrast (APCA)
+4. ☐ Document in theme README if new category
+5. ☐ Update this migration plan
+
+## Estimated Completion
+
+- **Phase 1:** 3-4 sessions (~270 colors)
+- **Phase 2:** 2-3 sessions (~107 colors)
+- **Phase 3:** 2 sessions (~79 colors)
+- **Phase 4:** 2 sessions (~89 colors)
+- **Phase 5:** 2-3 sessions (~210 colors)
+
+**Total:** 11-15 focused sessions
+
+## Success Metrics
+
+- ✅ All 755 hardcoded colors replaced
+- ✅ 100% APCA contrast pass rate maintained
+- ✅ Full dark mode support for all components
+- ✅ Consistent theming across component library
+
+## Notes for AI Agents
+
+- Always work on one component at a time
+- Test thoroughly in both themes before moving on
+- Maintain contrast requirements
+- Follow existing naming patterns for tokens
+- Update this document after each component completion

package/docs/archive/YGGDRASIL_THEME.md

@@ -0,0 +1,264 @@
+# Yggdrasil Theme for PrimeReact
+
+This document describes the custom Yggdrasil theme implementation for PrimeReact, including what was accomplished and what limitations exist with the standard theming approach.
+
+## Overview
+
+The Yggdrasil theme maps the Yggdrasil design system tokens to PrimeReact's CSS variables, creating both light and dark mode variants while maintaining full compatibility with PrimeReact's component library.
+
+## Theme Files
+
+- **[src/themes/yggdrasil-light.css](src/themes/yggdrasil-light.css)** - Light mode theme
+- **[src/themes/yggdrasil-dark.css](src/themes/yggdrasil-dark.css)** - Dark mode theme
+
+## What Was Accomplished
+
+### ✅ Colors
+
+Successfully mapped all Yggdrasil color tokens to PrimeReact CSS variables:
+
+#### Primary/Brand Colors (Sky)
+- Mapped Yggdrasil Sky palette to PrimeReact's `--primary-color` and `--blue-*` variables
+- Light mode: `--foundation-sky-700` (#001F4A) as primary
+- Dark mode: `--foundation-sky-600` (#183B60) as primary
+
+#### Success Colors (Forest)
+- Mapped Yggdrasil Forest palette to PrimeReact's `--green-*` variables
+- Provides proper success states for both light and dark modes
+
+#### Warning Colors (Sand)
+- Mapped Yggdrasil Sand palette to PrimeReact's `--yellow-*` variables
+- Provides proper warning states for both light and dark modes
+
+#### Danger/Error Colors (Berries)
+- Mapped Yggdrasil Berries palette to PrimeReact's `--red-*` variables
+- Provides proper danger/error states for both light and dark modes
+
+#### Info/Secondary Colors (Sea)
+- Mapped Yggdrasil Sea palette to PrimeReact's `--cyan-*` variables
+- Provides secondary/info color variations
+
+#### Neutral Colors (Rock)
+- Mapped Yggdrasil Rock palette to PrimeReact's `--gray-*` and `--surface-*` variables
+- Provides full neutral color scale for text, borders, and surfaces
+- Properly inverted for dark mode
+
+### ✅ Typography - Roboto Font
+
+Successfully replaced Inter font with Roboto while preserving font weights:
+
+- **Font Family**: Changed from "Inter var" to "Roboto"
+- **Font Weights**: Preserved all weights (100, 300, 400, 500, 700, 900) including italic variants
+- **Loading**: Using Google Fonts CDN via `@import`
+- **Hierarchy**: Font weight hierarchy remains intact across all components
+
+### ✅ Border Radius - 4px Grid Alignment
+
+Successfully adjusted border radius to adhere to 4px grid:
+
+- **Previous**: `--border-radius: 6px` (Lara theme default)
+- **Updated**: `--border-radius: 8px` (4px grid: 8 = 2×4)
+- **Impact**: All components (buttons, inputs, cards, dialogs, etc.) now use 8px border radius
+
+### ✅ Surface and Text Colors
+
+- **Light Mode**:
+  - Primary surface: White (`--foundation-white`)
+  - Secondary surfaces: Rock 50/100 (`--foundation-rock-050`, `--foundation-rock-100`)
+  - Default text: Sky 700 (`--foundation-sky-700`)
+  - Secondary text: Rock 600 (`--foundation-rock-600`)
+
+- **Dark Mode**:
+  - Primary surface: `#000D20` (custom dark blue)
+  - Secondary surfaces: Sky 900/950 (`--foundation-sky-900`, `--foundation-sky-950`)
+  - Default text: Rock 050 (`--foundation-rock-050`)
+  - Secondary text: Rock 400 (`--foundation-rock-400`)
+
+### ✅ Focus and Highlight States
+
+- Focus ring colors adjusted to use Yggdrasil Sky colors
+- Hover states use proper Yggdrasil overlay colors (`--foundation-darker-050` for light, `--foundation-lighter-100` for dark)
+- Selection/highlight backgrounds use Sky palette
+
+### ✅ Color Scheme Detection
+
+- Proper `color-scheme: light` and `color-scheme: dark` declarations
+- Enables browser-level dark mode support
+
+## Implementation Approach
+
+The theme was implemented using **CSS variable overrides**, which is PrimeReact's standard theming approach:
+
+1. **Base Theme Import**: Both themes import the base Lara Light Blue theme for component structure and styling
+2. **Foundation Variables**: Define all Yggdrasil foundation color tokens as CSS variables
+3. **Semantic Mapping**: Override PrimeReact's semantic CSS variables (`--primary-color`, `--surface-*`, `--text-color`, etc.) with Yggdrasil foundation tokens
+4. **Font Replacement**: Override `font-family` and import Roboto from Google Fonts
+5. **Border Radius**: Override `--border-radius` to use 8px
+
+## Switching Between Light and Dark Modes
+
+To switch between light and dark themes, change the import in:
+
+### Light Mode (Current Default)
+```typescript
+// src/main.tsx
+import './themes/yggdrasil-light.css'
+
+// .storybook/preview.ts
+import '../src/themes/yggdrasil-light.css'
+```
+
+### Dark Mode
+```typescript
+// src/main.tsx
+import './themes/yggdrasil-dark.css'
+
+// .storybook/preview.ts
+import '../src/themes/yggdrasil-dark.css'
+```
+
+### Dynamic Theme Switching (Future Enhancement)
+
+For runtime theme switching, you would need to:
+1. Load both CSS files
+2. Use a CSS class or data attribute on the root element
+3. Scope theme variables within those selectors
+
+Example approach:
+```css
+/* Not currently implemented, but would look like: */
+[data-theme="light"] {
+  /* light mode variables */
+}
+
+[data-theme="dark"] {
+  /* dark mode variables */
+}
+```
+
+## Limitations and What Wasn't Possible
+
+### ⚠️ Component-Specific Fine-Tuning
+
+**Limitation**: PrimeReact's CSS variable theming provides global-level customization but limited component-specific control.
+
+**Impact**: Some Yggdrasil design patterns that specify different treatments for specific component types (e.g., different border styles for cards vs. buttons) cannot be implemented without:
+- Using PrimeReact's PassThrough (PT) API for per-component styling
+- Creating wrapper components with custom CSS
+- Using SASS theme compilation (more complex approach)
+
+**Workaround**: Use Block components (e.g., `Card`, `PageHeader`) which can apply additional component-specific styling on top of the theme.
+
+### ⚠️ Opacity/Alpha Channel Values
+
+**Limitation**: Some Yggdrasil foundation colors use explicit alpha channel values (e.g., `--foundation-darker-050: #000F260C`), but PrimeReact expects solid colors in most variables.
+
+**Implementation**:
+- Used the explicit hex+alpha values where supported
+- For variables requiring solid colors, used the Yggdrasil semantic tokens that reference appropriate foundation colors
+
+**Impact**: Some subtle transparency effects from the original Yggdrasil design may not be perfectly replicated.
+
+### ⚠️ Inter Variable Font Features
+
+**Limitation**: The Lara theme uses "Inter var" with specific `font-feature-settings` ("cv02", "cv03", "cv04", "cv11") for stylistic alternates.
+
+**Implementation**: Roboto doesn't have equivalent OpenType features, so these are overridden but not replaced.
+
+**Impact**: Typography rendering is slightly different, but this is expected and acceptable since we're using a different font family.
+
+### ⚠️ Pink, Purple, Indigo, Teal Color Scales
+
+**Limitation**: PrimeReact provides CSS variables for pink, purple, indigo, orange, and teal color scales, but Yggdrasil doesn't have direct equivalents.
+
+**Implementation**: These variables remain unchanged from the Lara theme. They're rarely used in standard components but might appear in custom implementations.
+
+**Impact**: If custom components reference these color scales, they won't match the Yggdrasil palette.
+
+### ⚠️ Chart Colors
+
+**Limitation**: Yggdrasil defines extensive chart color palettes (`--charts-*`), but PrimeReact doesn't have corresponding CSS variables for chart theming.
+
+**Implementation**: Chart colors are not currently mapped to PrimeReact theme variables.
+
+**Impact**: If using PrimeReact chart components (from PrimeReact Charts), you would need to manually configure colors or create wrapper components.
+
+### ⚠️ Spacing and Layout Variables
+
+**Limitation**: Yggdrasil uses a comprehensive spacing scale with specific semantic tokens, but PrimeReact's theme only exposes `--content-padding` and `--inline-spacing`.
+
+**Implementation**: These remain at Lara theme defaults.
+
+**Impact**: Component internal spacing follows PrimeReact's defaults, not Yggdrasil's 4px grid spacing system. Layout spacing is controlled via PrimeFlex utility classes following the architecture policy.
+
+### ✅ What Works Perfectly
+
+Despite limitations, the following aspects work excellently with standard theming:
+
+1. **All color semantics** (primary, success, warning, danger, info, neutral)
+2. **Complete light/dark mode support** with proper color inversion
+3. **Typography** (font family replacement)
+4. **Border radius** (4px grid alignment)
+5. **Focus states**
+6. **Hover/active states**
+7. **Surface hierarchy** (cards, overlays, borders)
+8. **Text color hierarchy** (default, subdued, loud, disabled)
+
+## Testing
+
+Both themes have been tested with:
+
+- ✅ Vite build (`npm run build`)
+- ✅ Storybook build (`npm run build-storybook`)
+- ✅ All component stories in Storybook
+- ✅ Design System Playground page
+
+## Comparison to Designer API / SASS Approach
+
+### CSS Variables Approach (Current Implementation)
+
+**Pros**:
+- Simple, maintainable
+- No build tooling required
+- Easy to understand and modify
+- Fast iteration
+- Works with existing PrimeReact distribution
+
+**Cons**:
+- Limited to global variables
+- Can't customize component-specific styling deeply
+- Some advanced features not accessible
+
+### SASS Compilation Approach (Not Implemented)
+
+**Pros**:
+- Complete control over every component style
+- Can customize component-specific details
+- More alignment with original PrimeReact theming system
+
+**Cons**:
+- Requires SASS build tooling
+- More complex setup and maintenance
+- Need to maintain sync with PrimeReact updates
+- Significantly more effort for "close enough" goal
+
+**Decision**: The CSS variables approach was chosen because:
+1. The goal is "close enough" not pixel-perfect
+2. Maintains coherence with PrimeReact
+3. Avoids breaking components
+4. Significantly faster to implement and iterate
+5. Easier for LLM-assisted development
+
+## Future Enhancements
+
+If deeper customization is needed, consider:
+
+1. **PassThrough API**: Use PrimeReact's PT API for component-specific styling
+2. **Block Components**: Create more Block components that encapsulate Yggdrasil-specific patterns
+3. **Dynamic Theme Switching**: Implement runtime light/dark mode switching
+4. **Chart Integration**: Map Yggdrasil chart colors to chart components
+5. **Custom Components**: For patterns that can't be achieved with PrimeReact primitives
+
+## Conclusion
+
+The Yggdrasil theme successfully brings the Yggdrasil design system's color palette, typography (Roboto), and 4px grid border radius to PrimeReact using standard CSS variable theming. While some advanced customizations would require the SASS approach or PassThrough API, the current implementation achieves the "close enough" goal while maintaining full coherence with PrimeReact's component library.