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.

📚 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

1. Install

npm install @lifeonlars/prime-yggdrasil primereact

# Optional: PrimeIcons (for icon font support)
npm install primeicons

For custom SVG icons, see section 5.

2. Initialize AI Agents (Recommended)

npx @lifeonlars/prime-yggdrasil init

This copies 6 specialized AI agents to your project's .ai/yggdrasil/ directory, enabling design system compliance.

3. Import Theme

// 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'

4. Use Components

import { Button } from 'primereact/button';
import { DataTable } from 'primereact/datatable';
import { InputText } from 'primereact/inputtext';

function App() {
  return (
    <div style={{ color: 'var(--text-neutral-default)' }}>
      <Button label="Click me" />
    </div>
  );
}

5. SVG Icons (Optional)

Yggdrasil supports custom SVG icons without requiring PrimeIcons. Create a public/icons/ directory and add your SVG files:

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

// Option A: PrimeIcons (requires primeicons package)
<Icon name="pi pi-check" size="medium" />

// Option B: Custom SVG icons (place in public/icons/)
<Icon name="my-icon" size="large" />  // 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:

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 |

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

const sentiment = getSentimentPalette();
// sentiment.positive = '#AAECBC', sentiment.neutral = '#F2DE6E', sentiment.negative = '#F4B6B6'

<TimeSeriesLine
  data={data}
  encoding={{ x: 'date', y: 'mentions' }}
  title="Media Mentions"
  format={{ compact: true }}
/>

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

Documentation

For Developers

• Consumption Guide - Integration and setup
• Utilities Policy - Allowed utility classes
• FAQ & Troubleshooting - Common issues

For AI Agents

• AI Agent Guide - Complete AI integration guide
• Decision Matrix - Component selection for common scenarios
• Anti-Patterns - What NOT to do

Reference

• 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 |

Validate Your Code

# 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/.

Design Tokens

Common Tokens

/* 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

Correct (Use PrimeReact)

import { Button } from 'primereact/button';
import { DataTable } from 'primereact/datatable';

<Button label="Save" />
<DataTable value={data} />

Incorrect (Don't Create Custom)

// Don't do this!
const CustomButton = ({ children }) => (
  <button style={{ background: '#3B82F6' }}>{children}</button>
);

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:

Prerequisites

• Node.js 18+
• npm or pnpm

Local Development

npm install          # Install dependencies
npm run dev          # Start Storybook
npm test             # Run tests
npm run build        # Build library

Scripts

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

Testing

• 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