Yggdrasil Design System

> AI-agent-friendly PrimeReact design system for component-driven development

A comprehensive design system built on PrimeReact that enforces consistency through semantic tokens, prevents bespoke component creation, and guides AI agents to use existing patterns.

![npm version](https://www.npmjs.com/package/@lifeonlars/prime-yggdrasil)
![License: MIT](https://opensource.org/licenses/MIT)
![Storybook](https://lifeonlars.github.io/prime-yggdrasil/)

📚 View Live Storybook →

Why Yggdrasil?

Problem: AI agents often create custom components and hardcode styles, leading to inconsistent UIs and maintenance nightmares.

Solution: Yggdrasil provides guardrails that enforce component reuse and token-based styling through semantic tokens, AI agents, and validation tooling.

---

Quick Start

$3

bash

npm install @lifeonlars/prime-yggdrasil primereact



Optional: PrimeIcons (for icon font support)

npm install primeicons





For custom SVG icons, see section 5.



$3

bash

npx @lifeonlars/prime-yggdrasil init





This copies 6 specialized AI agents to your project's

.ai/yggdrasil/

 directory, enabling design system compliance.



$3

tsx

// src/main.tsx or src/App.tsx

import '@lifeonlars/prime-yggdrasil/theme.css';

import 'primeicons/primeicons.css'; // Optional



// Set theme on html element

document.documentElement.setAttribute('data-theme', 'light'); // or 'dark'

$3

tsx

import { Button } from 'primereact/button';

import { DataTable } from 'primereact/datatable';

import { InputText } from 'primereact/inputtext';



function App() {

  return (

    

      

  );

}





$3



Yggdrasil supports custom SVG icons without requiring PrimeIcons. Create a

public/icons/

 directory and add your SVG files:

tsx

import { Icon } from '@lifeonlars/prime-yggdrasil';



// Option A: PrimeIcons (requires primeicons package)





// Option B: Custom SVG icons (place in public/icons/)

  // loads public/icons/my-icon.svg





For full icon documentation including sizing and colors, see Consumption Guide - Icon System.



---



What's Included



| Feature                    | Description                                          |

| -------------------------- | ---------------------------------------------------- |

| Semantic Token System  | 336 design tokens with automatic light/dark mode     |

| PrimeReact Integration | 69 themed components ready to use                    |

| 6 AI Agents            | Prevent drift, guide composition, enforce compliance |

| CLI Validation         |

yggdrasil audit and yggdrasil validate

 commands  |

| 4px Grid System        | Consistent spacing across all components             |

| WCAG 3.0 Compliant     | APCA contrast tested for accessibility               |



---



Charts Package



For data visualization, install the companion charts package:

bash

npm install @lifeonlars/prime-yggdrasil-charts highcharts





The charts package provides Highcharts-based visualizations that automatically use Yggdrasil's design tokens:



| Chart Type       | Description                              |

| ---------------- | ---------------------------------------- |

| TimeSeriesLine | Line/spline charts with date X-axis    |

| Column         | Vertical bar charts                    |

| Bar            | Horizontal bar charts                  |

| StackedColumn  | Stacked vertical bars                  |

| Donut          | Pie chart with center hole             |

tsx

import { TimeSeriesLine, getSentimentPalette } from '@lifeonlars/prime-yggdrasil-charts';



const sentiment = getSentimentPalette();

// sentiment.positive = '#AAECBC', sentiment.neutral = '#F2DE6E', sentiment.negative = '#F4B6B6'



  data={data}

  encoding={{ x: 'date', y: 'mentions' }}

  title="Media Mentions"

  format={{ compact: true }}

/>





See @lifeonlars/prime-yggdrasil-charts for full documentation.



---



Documentation



$3



- Consumption Guide - Integration and setup

- Utilities Policy - Allowed utility classes

- FAQ & Troubleshooting - Common issues



$3



- AI Agent Guide - Complete AI integration guide

- Decision Matrix - Component selection for common scenarios

- Anti-Patterns - What NOT to do



$3



- Master Token Reference - All semantic tokens

- Component Index - Use-case to component mapping

- Aesthetics - Design principles



---



AI Agents



Yggdrasil includes 6 specialized agents that prevent drift and enforce design system compliance:



| Agent                     | Purpose                                                       |

| ------------------------- | ------------------------------------------------------------- |

| Block Composer        | Prevents bespoke components, suggests PrimeReact alternatives |

| Utilities Guard       | Enforces utilities for layout only (not design)               |

| Semantic Token Intent | Ensures correct token usage for all states                    |

| Drift Validator       | Catches violations via CLI and ESLint                         |

| Interaction Patterns  | Validates loading/error/empty state handling                  |

| Accessibility         | Enforces WCAG 2.1 AA compliance                               |



$3

bash

Report violations

npx @lifeonlars/prime-yggdrasil validate



Detailed audit with recommendations

npx @lifeonlars/prime-yggdrasil audit



Auto-fix safe violations

npx @lifeonlars/prime-yggdrasil audit --fix





For detailed agent documentation, see .ai/agents/.



---



AI Agent Integration



This package includes AI development skills for multiple coding platforms with automatic verification.



$3



- Claude Code - Automatic setup with task management (Ctrl+T)

- Antigravity CLI - Skills installed to .agents/skills/

- Gemini CLI - Skills installed to .agents/skills/

- Any SKILL.md-compatible platform



$3



Skills are automatically installed when you run:

bash

npm install @lifeonlars/prime-yggdrasil





This configures your project with:



- verification-before-completion - Enforces evidence-based completion

- frontend-design - Design system consistency checks

- vercel-react-best-practices - React performance best practices

- agent-browser - Automated UI verification



$3



Claude Code:

- Press Ctrl+T to view task list

- See CLAUDE.md for Claude Code workflows



Antigravity / Gemini CLI:

- Skills available in .agents/skills/

- See AGENTS.md for generic agent guide



$3



All platforms follow a verification workflow:



1. Implement feature/fix

2. Run build verification

3. Run lint verification

4. Run visual verification (for UI changes)

5. Capture evidence (command output, screenshots)

6. Mark task complete only after all verifications pass



See CONTRIBUTING.md for the complete development workflow and definition of done.



---



Design Tokens



$3

css

/ Text /

--text-neutral-default       / Main body text /

--text-neutral-subdued       / Secondary text /

--text-state-interactive     / Links, interactive elements /



/ Surfaces /

--surface-neutral-primary    / Main backgrounds /

--surface-neutral-secondary  / Secondary backgrounds /

--surface-brand-primary      / Brand color /



/ Borders /

--border-neutral-default     / Standard borders /

--border-state-focus         / Focus rings /



/ Spacing (4px grid) /

0.5rem (8px), 1rem (16px), 1.5rem (24px), 2rem (32px)



/ Border Radius /

--radius-sm (4px), --radius-md (8px), --radius-lg (12px)





For all 336 tokens, see Master Token Reference.



---



Component Usage



$3

tsx

import { Button } from 'primereact/button';

import { DataTable } from 'primereact/datatable';

);





See Anti-Patterns for more examples of what to avoid.



---



Architecture



@lifeonlars/prime-yggdrasil/

├── dist/                    # Built CSS and JS

│   ├── theme.css            # Single theme (light + dark)

│   ├── components/          # Category-specific CSS

│   └── index.js             # JS utilities + Icon component

│

├── docs/                    # Comprehensive documentation

│   ├── AI-AGENT-GUIDE.md

│   ├── CONSUMPTION-GUIDE.md

│   └── ...

│

├── cli/                     # Validation tools

│   ├── yggdrasil validate

│   └── yggdrasil audit

│

└── .ai/agents/              # 6 specialized AI agents





---



Development



For contributors working on Yggdrasil itself:



$3



- Node.js 18+

- npm or pnpm



$3

bash

npm install          # Install dependencies

npm run dev          # Start Storybook

npm test             # Run tests

npm run build        # Build library

$3

bash

npm run storybook       # Start Storybook dev server

npm run build           # Build library package

npm run test:contrast   # Test color contrast (APCA)

npm run test:themes     # Validate theme structure

npm run lint            # Lint TypeScript/JavaScript

npm run lint:css        # Lint CSS files





$3



- Play functions - Interactive tests in Storybook

- Accessibility tests -

@storybook/addon-a11y` integration
- Visual regression - Chromatic integration

---

Contributing

We welcome contributions! Please:

1. Follow existing semantic token patterns
2. Test in both light and dark modes
3. Run contrast tests for new colors
4. Update documentation
5. Add Storybook examples

---

License

MIT © Lars Farstad

Credits

Built with:

- PrimeReact - Component library
- PrimeIcons - Icon set
- Storybook - Component documentation

---

Made for AI agents, loved by developers