@lifeonlars/prime-yggdrasil 0.1.0

package/LICENSE

@@ -0,0 +1,30 @@
+MIT License
+
+Copyright (c) 2025 Lars Farstad
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+This design system provides CSS theming for PrimeReact components.
+PrimeReact is a separate library with its own license:
+
+PrimeReact - https://github.com/primefaces/primereact
+Copyright (c) 2024 PrimeTek Informatics
+Licensed under MIT License

package/README.md

@@ -0,0 +1,276 @@
+# 🌳 Yggdrasil Design System
+
+> **AI-agent-friendly PrimeReact design system for component-driven development**
+
+Yggdrasil is a comprehensive design system built on [PrimeReact](https://primereact.org/) that enforces consistency through semantic tokens, prevents bespoke component creation, and guides AI agents to use existing patterns.
+
+[![Storybook](https://img.shields.io/badge/Storybook-FF4785?logo=storybook&logoColor=white)](https://your-storybook-url.com)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## 🎯 Purpose
+
+**Problem**: AI agents often create custom components and hardcode styles, leading to inconsistent UIs and maintenance nightmares.
+
+**Solution**: Yggdrasil enforces component reuse and token-based styling through:
+- 📚 Comprehensive semantic token system (727+ tokens)
+- 🧩 PrimeReact component library integration
+- 🌓 Automatic light/dark mode support
+- 📏 4px grid system for consistent spacing
+- 🤖 AI-agent-specific documentation and guardrails
+
+## ✨ Features
+
+- **🎨 Semantic Token System** - 96% of styles use semantic tokens instead of hardcoded values
+- **🌗 Dark Mode Built-in** - Automatic theme switching with optimized dark mode shadows
+- **📦 Modular Architecture** - Split into 10 category files for easy maintenance
+- **🧩 Component-First** - Encourages PrimeReact usage over custom components
+- **📐 4px Grid System** - Consistent spacing and sizing across all components
+- **♿ WCAG 3.0 Compliant** - APCA contrast tested for accessibility
+- **📖 Storybook Integration** - Live component examples and documentation
+- **🤖 AI Agent Guides** - Purpose-built documentation for AI-driven development
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+npm install prime-yggdrasil primereact primeicons
+```
+
+### Usage
+
+```tsx
+// Import theme
+import 'prime-yggdrasil/yggdrasil-light.css';  // or yggdrasil-dark.css
+import 'primeicons/primeicons.css';
+
+// Use PrimeReact components
+import { Button } from 'primereact/button';
+import { DataTable } from 'primereact/datatable';
+
+function App() {
+  return (
+    <div style={{ color: 'var(--text-neutral-default)' }}>
+      <Button label="Click me" />
+    </div>
+  );
+}
+```
+
+## 📚 Documentation
+
+### For Developers
+- **[Getting Started](./docs/README.md)** - Overview and project structure
+- **[Theme Architecture](./src/theme/README.md)** - How the theme system works
+- **[Consumption Guide](./docs/CONSUMPTION-GUIDE.md)** - How to use in your project
+
+### For AI Agents
+- **[AI Agent Guide](./docs/AI-AGENT-GUIDE.md)** - Complete guide for AI-driven development
+- **[Component Selection](./docs/AI-AGENT-GUIDE.md#component-selection-guide)** - Decision tree for choosing components
+- **[Token Reference](./docs/AI-AGENT-GUIDE.md#quick-reference-for-common-tasks)** - Quick semantic token lookup
+
+### For Designers
+- **[Design Principles](./docs/README.md#design-principles)** - 4px grid, semantic tokens
+- **[Elevation System](./docs/ELEVATION-SYSTEM.md)** - Shadow hierarchy and usage
+- **[Contrast Report](./docs/contrast-report.md)** - Accessibility validation
+
+## 🎨 Design Tokens
+
+### Colors
+```css
+/* Text */
+--text-neutral-default       /* Main body text */
+--text-neutral-subdued       /* Secondary text */
+--text-state-interactive     /* Links, interactive elements */
+--text-onsurface-onbrand     /* Text on colored backgrounds */
+
+/* Surfaces */
+--surface-neutral-primary    /* Main backgrounds */
+--surface-neutral-secondary  /* Secondary backgrounds */
+--surface-brand-primary      /* Brand blue */
+--surface-state-hover        /* Hover states */
+
+/* Borders */
+--border-neutral-default     /* Standard borders */
+--border-state-interactive   /* Interactive borders */
+--border-state-focus         /* Focus rings */
+```
+
+### Spacing (4px Grid)
+```css
+0.5rem  /*  8px */
+1rem    /* 16px */
+1.5rem  /* 24px */
+2rem    /* 32px */
+```
+
+### Border Radius
+```css
+--radius-sm   /* 4px - Subtle */
+--radius-md   /* 8px - Standard */
+--radius-lg   /* 12px - Cards */
+--radius-full /* Pills, avatars */
+```
+
+## 🧩 Component Usage
+
+### ✅ Correct (Use PrimeReact)
+```tsx
+import { Button } from 'primereact/button';
+import { DataTable } from 'primereact/datatable';
+import { InputText } from 'primereact/inputtext';
+
+<Button label="Save" />
+<DataTable value={data} />
+<InputText placeholder="Enter text" />
+```
+
+### ❌ Incorrect (Don't Create Custom)
+```tsx
+// Don't do this!
+const CustomButton = ({ children }) => (
+  <button style={{ background: '#3B82F6', color: 'white' }}>
+    {children}
+  </button>
+);
+```
+
+## 🛠️ Development
+
+### Prerequisites
+- Node.js 18+
+- npm or pnpm
+
+### Local Development
+```bash
+# Install dependencies
+npm install
+
+# Start Storybook
+npm run dev
+
+# Run tests
+npm test
+
+# Build library
+npm run build
+```
+
+### Scripts
+```bash
+npm run dev                 # Start Storybook
+npm run build              # Build library
+npm run test:contrast      # Test color contrast
+npm run test:themes        # Validate theme structure
+npm run lint:css           # Lint CSS files
+```
+
+## 📊 Project Stats
+
+- **Semantic Tokens**: 727 color replacements (96% coverage)
+- **Components**: 69 PrimeReact components themed
+- **Files**: 10 modular CSS category files
+- **Contrast**: WCAG 3.0 (APCA) validated
+- **Dark Mode**: Optimized shadows with white rim strategy
+
+## 🤖 AI Agent Integration
+
+Yggdrasil is specifically designed to guide AI agents toward component-driven development:
+
+1. **Comprehensive Documentation** - AI agents can read [AI-AGENT-GUIDE.md](./docs/AI-AGENT-GUIDE.md)
+2. **Decision Trees** - Step-by-step component selection guidance
+3. **Token Reference** - Quick lookup for semantic tokens
+4. **Anti-Patterns** - Clear examples of what NOT to do
+5. **Validation Rules** - Optional ESLint/pre-commit hooks
+
+### Example AI Prompt
+```
+I'm building a React app with Yggdrasil design system.
+
+Before implementing UI:
+1. Read: node_modules/prime-yggdrasil/docs/AI-AGENT-GUIDE.md
+2. Check: Is there a PrimeReact component for this?
+3. Use: Semantic tokens only (no hardcoded colors)
+4. Follow: 4px grid for all spacing
+
+Create a user profile form with name, email, and submit button.
+```
+
+## 🏗️ Architecture
+
+```
+Yggdrasil
+├── Foundations (foundations.css)
+│   └── Raw color palette (Sky, Sea, Forest, etc.)
+│
+├── Border Radius (radius.css)
+│   └── Semantic radius tokens (sm, md, lg)
+│
+├── Semantic Tokens (semantic-light/dark.css)
+│   ├── Surfaces (backgrounds)
+│   ├── Text (typography colors)
+│   ├── Borders (borders, focus rings)
+│   ├── Icons (icon colors)
+│   └── Elevation (shadows)
+│
+└── Components (components/*.css)
+    ├── button.css (buttons, splitbutton)
+    ├── data.css (tables, trees, pagination)
+    ├── form.css (inputs, dropdowns, checkboxes)
+    ├── menu.css (navigation components)
+    └── ... (6 more category files)
+```
+
+## 📦 Package Contents
+
+When you install Yggdrasil, you get:
+
+```
+prime-yggdrasil/
+├── dist/
+│   ├── yggdrasil-light.css     # Light theme (import this)
+│   ├── yggdrasil-dark.css      # Dark theme (import this)
+│   ├── index.js                # Optional JS utilities
+│   └── index.d.ts              # TypeScript definitions
+│
+└── docs/
+    ├── AI-AGENT-GUIDE.md       # For AI agents
+    ├── CONSUMPTION-GUIDE.md    # Integration guide
+    ├── ELEVATION-SYSTEM.md     # Shadow system
+    └── contrast-report.md      # Accessibility report
+```
+
+## 🤝 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
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for details.
+
+## 📄 License
+
+MIT © Lars Farstad
+
+## 🙏 Credits
+
+Built with:
+- [PrimeReact](https://primereact.org/) - Component library
+- [PrimeIcons](https://primereact.org/icons) - Icon set
+- [Storybook](https://storybook.js.org/) - Component documentation
+- [APCA](https://github.com/Myndex/apca-w3) - Contrast testing
+
+## 📞 Support
+
+- 📖 [Documentation](./docs/README.md)
+- 🐛 [Issue Tracker](https://github.com/lifeonlars/prime-yggdrasil/issues)
+- 💬 [Discussions](https://github.com/lifeonlars/prime-yggdrasil/discussions)
+- 🎨 [Storybook](https://your-storybook-url.com)
+
+---
+
+**Made for AI agents, loved by developers** 🤖❤️👨‍💻

package/dist/foundations.css

@@ -0,0 +1,180 @@
+:root {
+
+  --foundation-sky-050: #F0F4F9;
+  --foundation-black: #000000;
+  --foundation-sky-100: #DDE0EA;
+  --foundation-white: #FFFFFF;
+  --foundation-sky-200: #BCCEE2;
+  --foundation-sky-300: #9DB7D6;
+  --foundation-sky-400: #648CC3;
+  --foundation-sky-500: #2E598F;
+  --foundation-sky-600: #183B60;
+  --foundation-sky-700: #001F4A;
+  --foundation-sky-800: #001129;
+  --foundation-sky-900: #000712;
+  --foundation-sky-950: #000409;
+  --foundation-sea-100: #D9E4E1;
+  --foundation-sea-200: #BEDCDD;
+  --foundation-sea-300: #98C5D3;
+  --foundation-sea-400: #7BB8D1;
+  --foundation-sea-500: #649EB3;
+  --foundation-sea-600: #477E92;
+  --foundation-sea-700: #336174;
+  --foundation-sea-800: #244655;
+  --foundation-sand-100: #EFE7DB;
+  --foundation-sand-200: #F4DAB8;
+  --foundation-sand-300: #F2C77F;
+  --foundation-sand-400: #E2AC5D;
+  --foundation-sand-500: #D39327;
+  --foundation-sand-600: #C17B16;
+  --foundation-sand-700: #AA6509;
+  --foundation-sand-800: #7B4E0F;
+  --foundation-forest-100: #DFE3D9;
+  --foundation-forest-200: #C7D3B2;
+  --foundation-forest-300: #B0C18E;
+  --foundation-forest-400: #9AB56B;
+  --foundation-forest-500: #7A9652;
+  --foundation-forest-600: #5D7235;
+  --foundation-forest-700: #485E1D;
+  --foundation-berries-100: #F4DFDF;
+  --foundation-berries-200: #F9BBC3;
+  --foundation-berries-300: #FCA4AB;
+  --foundation-berries-400: #FF8186;
+  --foundation-berries-500: #EA5E68;
+  --foundation-berries-600: #D64949;
+  --foundation-berries-700: #BC3939;
+  --foundation-rock-050: #F8F8F8;
+  --foundation-rock-100: #F2F1F2;
+  --foundation-rock-200: #E4E4E4;
+  --foundation-rock-300: #C4C2C5;
+  --foundation-rock-400: #A39FA7;
+  --foundation-rock-500: #8A858E;
+  --foundation-rock-600: #716C75;
+  --foundation-rock-700: #58525D;
+  --foundation-rock-800: #2E2734;
+  --foundation-rock-900: #201C25;
+  --foundation-rock-950: #131116;
+  --foundation-darker-050: #000F260C;
+  --foundation-darker-100: #000F2619;
+  --foundation-darker-150: #000F2626;
+  --foundation-darker-200: #000F2633;
+  --foundation-darker-250: #000F263F;
+  --foundation-darker-300: #000F264C;
+  --foundation-darker-400: #000F2666;
+  --foundation-darker-500: #000F267F;
+  --foundation-darker-600: #000F2699;
+  --foundation-darker-700: #000F26B2;
+  --foundation-darker-800: #000F26CC;
+  --foundation-darker-900: #000F26E5;
+  --foundation-darker-950: #000F26F2;
+  --foundation-lighter-050: #FFFFFF0C;
+  --foundation-lighter-100: #FFFFFF19;
+  --foundation-lighter-200: #FFFFFF33;
+  --foundation-lighter-300: #FFFFFF4C;
+  --foundation-lighter-400: #FFFFFF66;
+  --foundation-lighter-500: #FFFFFF7F;
+  --foundation-lighter-600: #FFFFFF99;
+  --foundation-lighter-700: #FFFFFFB2;
+  --foundation-lighter-800: #FFFFFFCC;
+  --foundation-lighter-900: #FFFFFFE5;
+  --foundation-lighter-950: #FFFFFFF2;
+  --charts-aquamarine-050: #B1E7E4;
+  --charts-aquamarine-100: #95DEDB;
+  --charts-aquamarine-200: #76D5D0;
+  --charts-aquamarine-300: #53CAC4;
+  --charts-aquamarine-400: #3ABCB5;
+  --charts-aquamarine-500: #34AAA4;
+  --charts-aquamarine-600: #2E958F;
+  --charts-aquamarine-700: #267B77;
+  --charts-aquamarine-800: #133F3C;
+  --charts-aquamarine-900: #0D2B2A;
+  --charts-aquamarine-950: #091D1C;
+  --charts-amber-050: #FFD79A;
+  --charts-amber-100: #FFC876;
+  --charts-amber-200: #FFB84D;
+  --charts-amber-300: #FFA41C;
+  --charts-amber-400: #F49300;
+  --charts-amber-500: #DD8500;
+  --charts-amber-600: #C27400;
+  --charts-amber-700: #A16000;
+  --charts-amber-800: #523100;
+  --charts-amber-900: #392200;
+  --charts-amber-950: #261700;
+  --charts-garnet-050: #F9D3E0;
+  --charts-garnet-100: #F7C4D6;
+  --charts-garnet-200: #F5B3CA;
+  --charts-garnet-300: #F3A0BD;
+  --charts-garnet-400: #F193B4;
+  --charts-garnet-500: #ED709C;
+  --charts-garnet-600: #E84C83;
+  --charts-garnet-700: #D71C5D;
+  --charts-garnet-800: #700E31;
+  --charts-garnet-900: #4F0A22;
+  --charts-garnet-950: #360717;
+  --charts-charoite-050: #DEDAEE;
+  --charts-charoite-100: #D4CEE9;
+  --charts-charoite-200: #C8C1E3;
+  --charts-charoite-300: #BCB3DC;
+  --charts-charoite-400: #AEA3D5;
+  --charts-charoite-500: #9E91CD;
+  --charts-charoite-600: #8B7CC3;
+  --charts-charoite-700: #7462B7;
+  --charts-charoite-800: #3B2F68;
+  --charts-charoite-900: #292147;
+  --charts-charoite-950: #1B162F;
+  --charts-sapphire-050: #D2EBF8;
+  --charts-sapphire-100: #A9D8F1;
+  --charts-sapphire-200: #92CDEE;
+  --charts-sapphire-300: #77C1E9;
+  --charts-sapphire-400: #58B3E4;
+  --charts-sapphire-500: #33A2DF;
+  --charts-sapphire-600: #208ECA;
+  --charts-sapphire-700: #1B76A8;
+  --charts-sapphire-800: #0E3C55;
+  --charts-sapphire-900: #092A3B;
+  --charts-sapphire-950: #061C27;
+  --charts-amethyst-050: #F1D4F2;
+  --charts-emerald-050: #CCF7D8;
+  --charts-emerald-100: #9CEFB3;
+  --charts-emerald-200: #76E896;
+  --charts-emerald-300: #45E070;
+  --charts-emerald-400: #20C34E;
+  --charts-emerald-500: #1DB146;
+  --charts-emerald-600: #199B3E;
+  --charts-emerald-700: #158133;
+  --charts-emerald-800: #0F5D25;
+  --charts-emerald-900: #0B421A;
+  --charts-emerald-950: #072D12;
+  --charts-topaz-050: #F8EDB3;
+  --charts-topaz-100: #F2DE6E;
+  --charts-topaz-200: #EDD138;
+  --charts-topaz-300: #E4C414;
+  --charts-topaz-400: #C4A912;
+  --charts-topaz-500: #B19810;
+  --charts-topaz-600: #9C860E;
+  --charts-topaz-700: #816F0C;
+  --charts-topaz-800: #604E08;
+  --charts-topaz-900: #443706;
+  --charts-topaz-950: #2F2604;
+  --charts-ruby-050: #FBE8E8;
+  --charts-ruby-100: #F8D4D4;
+  --charts-ruby-200: #F6C6C6;
+  --charts-ruby-300: #F4B6B6;
+  --charts-ruby-400: #EE9090;
+  --charts-ruby-500: #EA7777;
+  --charts-ruby-600: #E55656;
+  --charts-ruby-700: #D92121;
+  --charts-ruby-800: #9E1818;
+  --charts-ruby-900: #711111;
+  --charts-ruby-950: #500C0C;
+  --charts-amethyst-100: #ECC5EE;
+  --charts-amethyst-200: #E7B5E9;
+  --charts-amethyst-300: #E2A3E3;
+  --charts-amethyst-400: #DB8FDD;
+  --charts-amethyst-500: #D377D6;
+  --charts-amethyst-600: #CA59CD;
+  --charts-amethyst-700: #B437B8;
+  --charts-amethyst-800: #5D1D5F;
+  --charts-amethyst-900: #411442;
+  --charts-amethyst-950: #2B0D2C;
+}

package/dist/index.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e="0.1.0",o={name:"Yggdrasil",version:"0.1.0",tokens:727,coverage:"96%",modes:["light","dark"]};exports.theme=o;exports.version=e;

package/dist/index.js

@@ -0,0 +1,11 @@
+const e = "0.1.0", o = {
+  name: "Yggdrasil",
+  version: "0.1.0",
+  tokens: 727,
+  coverage: "96%",
+  modes: ["light", "dark"]
+};
+export {
+  o as theme,
+  e as version
+};

package/dist/vite.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" class="iconify iconify--logos" width="31.88" height="32" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 257"><defs><linearGradient id="IconifyId1813088fe1fbc01fb466" x1="-.828%" x2="57.636%" y1="7.652%" y2="78.411%"><stop offset="0%" stop-color="#41D1FF"></stop><stop offset="100%" stop-color="#BD34FE"></stop></linearGradient><linearGradient id="IconifyId1813088fe1fbc01fb467" x1="43.376%" x2="50.316%" y1="2.242%" y2="89.03%"><stop offset="0%" stop-color="#FFEA83"></stop><stop offset="8.333%" stop-color="#FFDD35"></stop><stop offset="100%" stop-color="#FFA800"></stop></linearGradient></defs><path fill="url(#IconifyId1813088fe1fbc01fb466)" d="M255.153 37.938L134.897 252.976c-2.483 4.44-8.862 4.466-11.382.048L.875 37.958c-2.746-4.814 1.371-10.646 6.827-9.67l120.385 21.517a6.537 6.537 0 0 0 2.322-.004l117.867-21.483c5.438-.991 9.574 4.796 6.877 9.62Z"></path><path fill="url(#IconifyId1813088fe1fbc01fb467)" d="M185.432.063L96.44 17.501a3.268 3.268 0 0 0-2.634 3.014l-5.474 92.456a3.268 3.268 0 0 0 3.997 3.378l24.777-5.718c2.318-.535 4.413 1.507 3.936 3.838l-7.361 36.047c-.495 2.426 1.782 4.5 4.151 3.78l15.304-4.649c2.372-.72 4.652 1.36 4.15 3.788l-11.698 56.621c-.732 3.542 3.979 5.473 5.943 2.437l1.313-2.028l72.516-144.72c1.215-2.423-.88-5.186-3.54-4.672l-25.505 4.922c-2.396.462-4.435-1.77-3.759-4.114l16.646-57.705c.677-2.35-1.37-4.583-3.769-4.113Z"></path></svg>

package/dist/yggdrasil-dark.css

@@ -0,0 +1,12 @@
+/**
+ * Yggdrasil Dark
+ *
+ * Legacy theme file for stylesheet swapping.
+ * For runtime switching, use yggdrasil-adaptive.css
+ */
+
+@import url('https://fonts.googleapis.com/css2?family=Roboto:ital,wght@0,100;0,300;0,400;0,500;0,700;0,900;1,100;1,300;1,400;1,500;1,700;1,900&display=swap');
+@import "./foundations.css";
+@import "./radius.css";
+@import "./semantic-dark.css";
+@import "./components.css";

package/dist/yggdrasil-light.css

@@ -0,0 +1,12 @@
+/**
+ * Yggdrasil Light
+ *
+ * Legacy theme file for stylesheet swapping.
+ * For runtime switching, use yggdrasil-adaptive.css
+ */
+
+@import url('https://fonts.googleapis.com/css2?family=Roboto:ital,wght@0,100;0,300;0,400;0,500;0,700;0,900;1,100;1,300;1,400;1,500;1,700;1,900&display=swap');
+@import "./foundations.css";
+@import "./radius.css";
+@import "./semantic-light.css";
+@import "./components.css";