@launch77-shared/lib-design-system 0.1.0

package/README.md

@@ -0,0 +1,120 @@
+# @launch77-shared/lib-design-system
+
+Token-driven design system providing a theming foundation for Launch77 applications. Built for seamless integration with shadcn/ui component libraries.
+
+## Installation
+
+**Recommended:** Install via Launch77 plugin (handles all configuration automatically):
+
+```bash
+launch77 plugin:install design-system
+```
+
+**Manual installation** (not recommended):
+
+```bash
+npm install @launch77-shared/lib-design-system
+```
+
+> **Note:** Manual installation requires configuring Tailwind preset and CSS imports yourself. The plugin automates this setup.
+
+## Features
+
+- 🎨 **Semantic Token System** - CSS custom properties in HSL format with alpha channel support
+- 🌗 **Dark Mode** - Complete dark mode support via `.dark` class
+- ⚡ **Tailwind Preset** - Ready-to-use Tailwind configuration with theme extensions
+- ♿ **Accessibility First** - Auto-injected base styles with focus rings and reduced motion support
+- 🎬 **Animations** - 8 built-in keyframe animations (accordion, fade, slide)
+- 🎯 **Brand Customization** - Simple CSS cascade for per-app theming
+- 🔧 **shadcn Compatible** - Follows shadcn/ui token architecture
+
+## What's Included
+
+### Semantic Color Tokens
+
+```css
+/* Available in light and dark modes */
+--color-background / --color-foreground
+--color-primary / --color-primary-foreground
+--color-secondary / --color-secondary-foreground
+--color-accent / --color-accent-foreground
+--color-muted / --color-muted-foreground
+--color-destructive / --color-destructive-foreground
+--color-card / --color-card-foreground
+--color-border
+--color-input
+--color-ring
+```
+
+### Tailwind Utilities
+
+All semantic colors available as Tailwind utilities with alpha channel support:
+
+```tsx
+<div className="bg-primary/20 text-foreground border-input" />
+```
+
+### Animations
+
+8 pre-built animations: fade-in/out, slide-in (4 directions), accordion-up/down.
+
+All animations automatically respect `prefers-reduced-motion` preferences.
+
+## Documentation
+
+- **[Complete Documentation](./docs/README.md)** - Comprehensive guide with:
+  - Design system concepts and philosophy
+  - How to build components with tokens
+  - Token system reference
+  - Architecture overview
+  - Dark mode implementation details
+  - TypeScript API reference
+
+- **Plugin README** - For installation and usage instructions:
+  - Quick start guide
+  - Usage examples (buttons, cards, forms)
+  - Brand customization
+  - Troubleshooting
+
+## Quick Reference
+
+### Using with Tailwind (if manually installed)
+
+```js
+// tailwind.config.js
+const preset = require('@launch77-shared/lib-design-system/preset')
+
+module.exports = {
+  presets: [preset],
+  content: ['./src/**/*.{ts,tsx}'],
+}
+```
+
+### Importing Tokens (if manually installed)
+
+```css
+/* globals.css */
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@import '@launch77-shared/lib-design-system/tokens.css';
+```
+
+### HSL Color Format
+
+Colors use HSL format for flexibility:
+
+```css
+--color-primary: 222 47% 11%; /* Hue Saturation% Lightness% */
+```
+
+Benefits: Alpha channel support (`bg-primary/20`), easy to adjust, color picker compatible.
+
+## TypeScript Support
+
+Full TypeScript definitions included for Tailwind configuration.
+
+## License
+
+UNLICENSED - Internal Launch77 use only.

package/docs/README.md

@@ -0,0 +1,883 @@
+# Launch77 Design System - Complete Guide
+
+This design system provides a token-driven theming foundation for Launch77 applications and shared component libraries. It enables consistent, accessible, and brand-customizable user interfaces through semantic design tokens and Tailwind CSS integration.
+
+> **Installation:** Use the Launch77 plugin for automatic setup: `launch77 plugin:install design-system`
+
+## Table of Contents
+
+### Conceptual Guide
+
+1. [What is a Design System?](#what-is-a-design-system)
+2. [How to Build Components](#how-to-build-components)
+3. [Token Philosophy](#token-philosophy)
+4. [Common Patterns](#common-patterns)
+5. [When to Use Tokens](#when-to-use-tokens-vs-hardcoded-values)
+
+### Technical Reference
+
+6. [Architecture Overview](#architecture-overview)
+7. [Token System](#token-system)
+8. [Tailwind Preset](#tailwind-preset)
+9. [Dark Mode](#dark-mode)
+10. [Animations](#animations)
+11. [Accessibility Features](#accessibility-features)
+
+---
+
+## Conceptual Guide
+
+### What is a Design System?
+
+A design system is a **theming foundation** that separates visual decisions (colors, spacing) from component structure (buttons, cards). Think of it as a contract between designers and developers:
+
+- **Designers** define what "primary" means (your brand color)
+- **Developers** build components that reference "primary" (not hardcoded blue)
+- **Result**: Change the brand color once, and all components update automatically
+
+#### Why Use Semantic Tokens?
+
+Instead of naming colors by their appearance (`blue-500`, `red-600`), we name them by their **meaning**:
+
+```tsx
+// ❌ BAD: Hardcoded appearance
+<button className="bg-blue-500 text-white">Submit</button>
+
+// ✅ GOOD: Semantic meaning
+<button className="bg-primary text-primary-foreground">Submit</button>
+```
+
+**Benefits:**
+
+- **Rebrand easily**: Change `--color-primary` once, all buttons update
+- **Dark mode**: Tokens adapt automatically (no component changes needed)
+- **Consistency**: All "primary" buttons look identical across the app
+- **Maintainability**: Designers control colors, not component code
+
+#### Real-World Example
+
+Your company rebrands from blue to green:
+
+```css
+/* Old brand */
+--color-primary: 220 60% 50%; /* Blue */
+
+/* New brand */
+--color-primary: 150 60% 50%; /* Green */
+```
+
+All buttons, links, and primary elements update instantly - **no component code changes required**.
+
+---
+
+### How to Build Components
+
+When building components with this design system, follow these rules:
+
+#### Rule #1: Always Use Semantic Tokens
+
+**Every color in your component should use a semantic token:**
+
+```tsx
+// ✅ CORRECT
+function Button() {
+  return <button className="bg-primary text-primary-foreground hover:bg-primary/90">Click me</button>
+}
+
+// ❌ WRONG
+function Button() {
+  return <button className="bg-blue-500 text-white hover:bg-blue-600">Click me</button>
+}
+```
+
+#### Rule #2: Never Hardcode Colors
+
+**Don't use Tailwind's default color palette:**
+
+- ❌ Never: `bg-blue-500`, `text-gray-600`, `border-red-400`
+- ✅ Always: `bg-primary`, `text-muted-foreground`, `border-destructive`
+
+#### Rule #3: Use Semantic Utilities for Meaning
+
+**Match the token to the component's purpose:**
+
+```tsx
+// Primary action → bg-primary
+<button className="bg-primary text-primary-foreground">Save</button>
+
+// Destructive action → bg-destructive
+<button className="bg-destructive text-destructive-foreground">Delete</button>
+
+// Secondary action → bg-secondary
+<button className="bg-secondary text-secondary-foreground">Cancel</button>
+
+// Error message → text-destructive
+<p className="text-destructive">Error: Invalid input</p>
+
+// Subtle hint → text-muted-foreground
+<p className="text-muted-foreground">Optional field</p>
+```
+
+#### Simple Decision Tree
+
+When building a component, ask yourself:
+
+1. **What is this component's purpose?**
+   - Primary action? → Use `bg-primary`
+   - Secondary action? → Use `bg-secondary`
+   - Destructive action? → Use `bg-destructive`
+   - Neutral container? → Use `bg-card`
+   - Emphasis/highlight? → Use `bg-accent`
+
+2. **What is this text's role?**
+   - Main content? → Use `text-foreground`
+   - Subtle/helper text? → Use `text-muted-foreground`
+   - On colored background? → Use `text-primary-foreground` (matches the background)
+
+3. **What are these borders/inputs?**
+   - Standard border? → Use `border-border`
+   - Form input? → Use `border-input`
+   - Focus ring? → Use `ring-ring`
+
+---
+
+### Token Philosophy
+
+#### Tokens = Design Decisions
+
+Design tokens represent **design decisions**, not specific colors:
+
+- `--color-primary` = "What color represents our brand?"
+- `--color-destructive` = "What color means danger/error?"
+- `--color-muted` = "What color is subtle but visible?"
+
+These decisions can change (rebrand, dark mode, A/B tests), but the component code stays the same.
+
+#### Components = Structure
+
+Components define **structure and behavior**, not appearance:
+
+```tsx
+// This component is "themeable" - it adapts to any theme
+function Card({ children }) {
+  return <div className="bg-card text-card-foreground border border-border rounded-lg p-6">{children}</div>
+}
+```
+
+The card works with:
+
+- Any brand color (tokens define primary/accent)
+- Light or dark mode (tokens adapt automatically)
+- Any app's brand identity (each app overrides tokens)
+
+#### The Power of Separation
+
+By separating tokens (design) from components (structure), you get:
+
+```tsx
+// Component code (never changes)
+<button className="bg-primary text-primary-foreground">Save</button>
+
+// Theme 1: Blue brand
+--color-primary: 220 60% 50%;
+
+// Theme 2: Green brand
+--color-primary: 150 60% 50%;
+
+// Theme 3: Dark mode blue
+--color-primary: 220 70% 60%;
+```
+
+Same component, different visual appearance - **zero code changes**.
+
+---
+
+### Common Patterns
+
+Here's a quick reference for which tokens to use with common component types:
+
+| Component Type         | Recommended Tokens                                 | Example              |
+| ---------------------- | -------------------------------------------------- | -------------------- |
+| **Primary Button**     | `bg-primary` `text-primary-foreground`             | Save, Submit, Create |
+| **Secondary Button**   | `bg-secondary` `text-secondary-foreground`         | Cancel, Back         |
+| **Destructive Button** | `bg-destructive` `text-destructive-foreground`     | Delete, Remove       |
+| **Outline Button**     | `border-input` `text-foreground` `hover:bg-accent` | Optional actions     |
+| **Ghost Button**       | `hover:bg-accent` `text-foreground`                | Icon buttons         |
+| **Card Container**     | `bg-card` `text-card-foreground` `border-border`   | Content cards        |
+| **Main Content**       | `bg-background` `text-foreground`                  | Page layout          |
+| **Muted Container**    | `bg-muted` `text-muted-foreground`                 | Subtle backgrounds   |
+| **Error Message**      | `text-destructive` `border-destructive`            | Validation errors    |
+| **Success Message**    | `text-primary` `border-primary`                    | Success states       |
+| **Helper Text**        | `text-muted-foreground`                            | Labels, hints        |
+| **Form Input**         | `border-input` `bg-background` `ring-ring`         | Text inputs          |
+| **Hover States**       | `hover:bg-primary/90` (use alpha)                  | Interactive elements |
+
+#### Real Component Examples
+
+**Button Component with Variants:**
+
+```tsx
+import { cva } from 'class-variance-authority'
+
+const button = cva(
+  // Base styles (always applied)
+  'inline-flex items-center justify-center rounded-lg px-4 py-2 font-medium transition-colors',
+  {
+    variants: {
+      variant: {
+        primary: 'bg-primary text-primary-foreground hover:bg-primary/90',
+        secondary: 'bg-secondary text-secondary-foreground hover:bg-secondary/80',
+        destructive: 'bg-destructive text-destructive-foreground hover:bg-destructive/90',
+        outline: 'border border-input bg-background hover:bg-accent text-foreground',
+        ghost: 'hover:bg-accent hover:text-accent-foreground',
+      },
+    },
+  }
+)
+```
+
+**Card Component:**
+
+```tsx
+function Card({ children, className = '' }) {
+  return <div className={`bg-card text-card-foreground border border-border rounded-lg p-6 ${className}`}>{children}</div>
+}
+```
+
+**Form Input:**
+
+```tsx
+function Input({ className = '', ...props }) {
+  return <input className={`w-full px-3 py-2 bg-background text-foreground border border-input rounded-md focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 ${className}`} {...props} />
+}
+```
+
+**Alert Component:**
+
+```tsx
+function Alert({ variant = 'default', children }) {
+  const styles = {
+    default: 'bg-card text-card-foreground border-border',
+    destructive: 'bg-destructive/10 text-destructive border-destructive',
+    success: 'bg-primary/10 text-primary border-primary',
+  }
+
+  return <div className={`border rounded-lg p-4 ${styles[variant]}`}>{children}</div>
+}
+```
+
+---
+
+### When to Use Tokens vs Hardcoded Values
+
+#### ✅ Use Tokens When...
+
+**Colors should adapt to theme or brand:**
+
+```tsx
+// ✅ Button color should match brand
+<button className="bg-primary text-primary-foreground">Submit</button>
+
+// ✅ Text should adapt to light/dark mode
+<p className="text-foreground">Main content</p>
+
+// ✅ Card backgrounds should match theme
+<div className="bg-card border-border">...</div>
+
+// ✅ Interactive states should use theme colors
+<button className="hover:bg-primary/90">Hover me</button>
+```
+
+**Components that will be reused:**
+
+- Buttons, cards, inputs, navigation, etc.
+- Any UI element users interact with
+- Layout containers
+- Text content
+
+#### ❌ Don't Use Tokens For...
+
+**Decorative elements that shouldn't change:**
+
+```tsx
+// ❌ Company logo color is part of brand identity
+<svg className="fill-[#FF5816]">Logo</svg>
+
+// ❌ Specific illustrations have fixed colors
+<img src="/hero-illustration.svg" alt="Hero" />
+
+// ❌ Chart colors need to be distinct (not theme-dependent)
+<Bar data={data} colors={['#ff0000', '#00ff00', '#0000ff']} />
+
+// ❌ Code syntax highlighting (needs specific colors)
+<code className="language-js">...</code>
+```
+
+**One-off decorative flourishes:**
+
+- Gradients in marketing headers
+- Specific icons with fixed colors
+- Photography and illustrations
+- Data visualizations that need precise colors
+- Third-party embedded content
+
+#### Simple Rule of Thumb
+
+**Ask yourself: "If the user switches to dark mode or we rebrand, should this change color?"**
+
+- **Yes** → Use a semantic token
+- **No** → Use a hardcoded value
+
+#### Examples in Context
+
+```tsx
+function ProductCard({ product }) {
+  return (
+    {/* ✅ Card uses theme tokens (adapts to theme) */}
+    <div className="bg-card text-card-foreground border border-border rounded-lg p-4">
+
+      {/* ❌ Product image doesn't change with theme */}
+      <img src={product.image} alt={product.name} />
+
+      {/* ✅ Text uses theme tokens (adapts to light/dark) */}
+      <h3 className="text-foreground font-bold">{product.name}</h3>
+      <p className="text-muted-foreground">{product.description}</p>
+
+      {/* ❌ Product category badge has fixed brand color */}
+      <span className="bg-[#FF5816] text-white px-2 py-1 rounded">
+        {product.category}
+      </span>
+
+      {/* ✅ Action button uses theme tokens */}
+      <button className="bg-primary text-primary-foreground hover:bg-primary/90">
+        Add to Cart
+      </button>
+    </div>
+  )
+}
+```
+
+---
+
+## Technical Reference
+
+### Architecture Overview
+
+The design system consists of three layers:
+
+#### 1. CSS Tokens (`tokens.css`)
+
+Pure semantic CSS custom properties with no framework dependencies. These define the visual language of your application:
+
+```css
+:root {
+  --color-background: 0 0% 100%;
+  --color-foreground: 222 47% 11%;
+  --color-primary: 222 47% 11%;
+  /* ... more tokens */
+}
+
+.dark {
+  --color-background: 222 47% 11%;
+  --color-foreground: 210 40% 98%;
+  --color-primary: 217 91% 60%;
+  /* ... dark mode overrides */
+}
+```
+
+**Benefits:**
+
+- Framework-agnostic (works with any CSS)
+- Cascades naturally (easy to override)
+- No build step required
+
+#### 2. Tailwind Preset (`preset.js`)
+
+Maps Tailwind utilities to the CSS tokens and includes a plugin that auto-injects base styles:
+
+```js
+module.exports = {
+  theme: {
+    extend: {
+      colors: {
+        background: 'hsl(var(--color-background) / <alpha-value>)',
+        foreground: 'hsl(var(--color-foreground) / <alpha-value>)',
+        primary: {
+          DEFAULT: 'hsl(var(--color-primary) / <alpha-value>)',
+          foreground: 'hsl(var(--color-primary-foreground) / <alpha-value>)',
+        },
+        // ... more mappings
+      },
+    },
+  },
+  plugins: [
+    /* Auto-inject base styles */
+  ],
+}
+```
+
+**Benefits:**
+
+- Tailwind utilities automatically use tokens
+- Alpha channel support (`bg-primary/20`)
+- No manual configuration needed
+
+#### 3. App-Level Customization
+
+Each app can override tokens via its own `brand.css` file without touching shared components:
+
+```css
+/* app/brand.css */
+:root {
+  --color-primary: 158 64% 52%; /* Override with brand color */
+  --color-accent: 156 72% 72%;
+}
+
+.dark {
+  --color-primary: 158 64% 52%; /* Dark mode override */
+}
+```
+
+**Result:** Components stay neutral and reusable, while each app maintains its unique brand identity.
+
+---
+
+### Token System
+
+#### Understanding HSL Format
+
+All color tokens use HSL (Hue, Saturation, Lightness) format without the `hsl()` wrapper:
+
+```css
+--color-primary: 222 47% 11%;
+/*               ^^^  ^^  ^^
+                 H    S   L   */
+```
+
+**Why no `hsl()` wrapper?**
+
+This format enables Tailwind's alpha channel syntax:
+
+```tsx
+{/* Tailwind adds hsl() and alpha automatically */}
+<div className="bg-primary/20">  {/* → hsl(222 47% 11% / 0.2) */}
+```
+
+**HSL Benefits:**
+
+- **Alpha Channel**: Use `/` for opacity (e.g., `bg-primary/20` = 20% opacity)
+- **Human-Readable**: Easy to understand and adjust
+- **Design Tool Compatible**: Most color pickers support HSL
+- **shadcn Standard**: Matches shadcn/ui architecture
+
+**Converting from other formats:**
+
+```
+Hex #3730A3 → HSL 243 58% 41%
+RGB 55 48 163 → HSL 243 58% 41%
+
+Use online tools: hslpicker.com or browser DevTools color picker
+```
+
+#### Complete Token Reference
+
+##### Base Colors
+
+```css
+--color-background      /* Main app background (usually white/black) */
+--color-foreground      /* Main text color (usually black/white) */
+```
+
+**When to use:**
+
+- `bg-background` - Page layout, main containers
+- `text-foreground` - Primary text content
+
+##### Card
+
+```css
+--color-card            /* Card background (slightly elevated) */
+--color-card-foreground /* Card text color */
+```
+
+**When to use:**
+
+- `bg-card` - Content cards, modals, dropdown menus
+- `text-card-foreground` - Text inside cards
+
+##### Primary (Brand Color)
+
+```css
+--color-primary           /* Main brand color */
+--color-primary-foreground /* Text on primary background */
+```
+
+**When to use:**
+
+- `bg-primary` - Primary action buttons, active states, brand elements
+- `text-primary` - Links, highlighted text
+- `text-primary-foreground` - Text on primary backgrounds
+
+##### Secondary
+
+```css
+--color-secondary           /* Secondary actions/elements */
+--color-secondary-foreground /* Text on secondary background */
+```
+
+**When to use:**
+
+- `bg-secondary` - Secondary buttons, less important actions
+- `text-secondary-foreground` - Text on secondary backgrounds
+
+##### Accent
+
+```css
+--color-accent           /* Accent color for highlights */
+--color-accent-foreground /* Text on accent background */
+```
+
+**When to use:**
+
+- `bg-accent` - Hover states, highlights, badges
+- `hover:bg-accent` - Interactive element hover states
+
+##### Muted
+
+```css
+--color-muted           /* Subtle backgrounds */
+--color-muted-foreground /* Subtle text color */
+```
+
+**When to use:**
+
+- `bg-muted` - Disabled states, subtle containers
+- `text-muted-foreground` - Helper text, labels, secondary info
+
+##### Destructive
+
+```css
+--color-destructive           /* Destructive actions (delete, error) */
+--color-destructive-foreground /* Text on destructive background */
+```
+
+**When to use:**
+
+- `bg-destructive` - Delete buttons, error alerts
+- `text-destructive` - Error messages, validation failures
+- `border-destructive` - Error input borders
+
+##### Form Elements
+
+```css
+--color-border  /* Standard border color */
+--color-input   /* Input border color (slightly darker) */
+--color-ring    /* Focus ring color (usually primary) */
+```
+
+**When to use:**
+
+- `border-border` - Card borders, dividers
+- `border-input` - Form input borders
+- `ring-ring` - Focus rings on interactive elements
+
+##### Border Radius
+
+```css
+--radius: 1rem /* Base border radius (16px) */;
+```
+
+**Tailwind utilities automatically use this:**
+
+- `rounded-lg` → `var(--radius)` (16px)
+- `rounded-md` → `calc(var(--radius) - 2px)` (14px)
+- `rounded-sm` → `calc(var(--radius) - 4px)` (12px)
+
+---
+
+### Tailwind Preset
+
+#### What the Preset Provides
+
+The `preset.js` file exports a Tailwind configuration object that:
+
+1. **Maps all tokens to Tailwind utilities**
+2. **Enables alpha channel support** (`/` syntax)
+3. **Auto-injects base styles** via plugin
+4. **Configures border radius** utilities
+5. **Adds animation keyframes**
+
+#### Configuration API
+
+```js
+// tailwind.config.js
+const preset = require('@launch77-shared/lib-design-system/preset')
+
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  presets: [preset],
+  content: ['./src/**/*.{ts,tsx,js,jsx}', './app/**/*.{ts,tsx,js,jsx}'],
+}
+```
+
+#### Alpha Channel Support
+
+All color tokens support Tailwind's alpha channel syntax:
+
+```tsx
+<div className="bg-primary/10">10% opacity</div>
+<div className="bg-primary/20">20% opacity</div>
+<div className="bg-primary/50">50% opacity</div>
+<div className="bg-primary/90">90% opacity</div>
+
+<button className="bg-primary/90 hover:bg-primary">
+  Hover to full opacity
+</button>
+```
+
+**How it works:**
+
+The preset maps tokens like this:
+
+```js
+colors: {
+  primary: 'hsl(var(--color-primary) / <alpha-value>)',
+  //                                   ^^^^^^^^^^^^^^
+  //                                   Tailwind replaces this
+}
+```
+
+When you write `bg-primary/20`, Tailwind generates:
+
+```css
+.bg-primary\/20 {
+  background-color: hsl(var(--color-primary) / 0.2);
+}
+```
+
+#### Auto-Injected Base Styles
+
+The preset's plugin automatically adds these base styles (no manual copying needed):
+
+```css
+* {
+  border-color: hsl(var(--color-border));
+}
+
+html {
+  scroll-behavior: smooth;
+}
+
+body {
+  background-color: hsl(var(--color-background));
+  color: hsl(var(--color-foreground));
+}
+
+/* Plus: selection styles, focus rings, tap targets, reduced motion */
+```
+
+---
+
+### Dark Mode
+
+#### Implementation Strategy
+
+Dark mode uses **class-based toggling** on the `<html>` element:
+
+```html
+<!-- Light mode (default) -->
+<html>
+  ...
+</html>
+
+<!-- Dark mode (add .dark class) -->
+<html class="dark">
+  ...
+</html>
+```
+
+#### How It Works
+
+Tokens are defined twice - once in `:root` (light mode), once in `.dark` (dark mode):
+
+```css
+/* tokens.css */
+:root {
+  --color-background: 0 0% 100%; /* White */
+  --color-foreground: 222 47% 11%; /* Dark gray */
+  --color-primary: 222 47% 11%; /* Dark blue */
+}
+
+.dark {
+  --color-background: 222 47% 11%; /* Dark gray */
+  --color-foreground: 210 40% 98%; /* Off-white */
+  --color-primary: 217 91% 60%; /* Light blue */
+}
+```
+
+When `.dark` is added to `<html>`, the CSS cascade applies dark mode values. Components don't change - they still use `bg-background`, `text-foreground`, etc.
+
+#### Technical Details
+
+**Why class-based instead of `prefers-color-scheme`?**
+
+- User can override system preference
+- Easy to persist in localStorage
+- Simple to toggle programmatically
+- Works in all browsers
+
+**Why on `<html>` instead of `<body>`?**
+
+- Tailwind's dark mode selector targets `:root.dark`
+- Ensures all elements inherit correct mode
+- Fixes edge cases with portals and modals
+
+---
+
+### Animations
+
+#### Available Keyframes
+
+The preset provides 8 animation keyframes:
+
+```css
+@keyframes fadeIn
+@keyframes fadeOut
+@keyframes slideInFromTop
+@keyframes slideInFromBottom
+@keyframes slideInFromLeft
+@keyframes slideInFromRight
+@keyframes accordionDown
+@keyframes accordionUp;
+```
+
+#### Tailwind Utilities
+
+```tsx
+{/* Fade animations */}
+<div className="animate-fade-in">Fades in</div>
+<div className="animate-fade-out">Fades out</div>
+
+{/* Slide animations */}
+<div className="animate-slide-in-from-top">Slides from top</div>
+<div className="animate-slide-in-from-bottom">Slides from bottom</div>
+<div className="animate-slide-in-from-left">Slides from left</div>
+<div className="animate-slide-in-from-right">Slides from right</div>
+
+{/* Accordion animations (for Radix UI) */}
+<div className="animate-accordion-down">Expands</div>
+<div className="animate-accordion-up">Collapses</div>
+```
+
+#### Accessibility
+
+All animations automatically respect `prefers-reduced-motion`:
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+  }
+}
+```
+
+Users who have enabled reduced motion in their OS settings will see instant state changes instead of animations.
+
+---
+
+### Accessibility Features
+
+The preset auto-injects several accessibility features:
+
+#### Focus Rings
+
+```css
+/* Automatically applied to all interactive elements */
+*:focus-visible {
+  outline: none;
+  box-shadow: 0 0 0 2px hsl(var(--color-ring));
+}
+```
+
+Override per-component if needed:
+
+```tsx
+<button className="focus-visible:ring-2 focus-visible:ring-offset-2">Custom focus ring</button>
+```
+
+#### Minimum Tap Targets
+
+```css
+/* Interactive elements are at least 44x44px */
+button,
+[role='button'],
+input,
+select,
+textarea,
+a {
+  min-height: 44px;
+  min-width: 44px;
+}
+```
+
+#### Reduced Motion
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  /* Disables animations for users who prefer reduced motion */
+  animation-duration: 0.01ms !important;
+  transition-duration: 0.01ms !important;
+}
+```
+
+#### Smooth Scrolling
+
+```css
+html {
+  scroll-behavior: smooth;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  html {
+    scroll-behavior: auto;
+  }
+}
+```
+
+---
+
+## Additional Resources
+
+### Related Documentation
+
+- **Plugin README**: Installation and usage guide (in plugin package)
+- **Module README**: Per-app customization guide (installed by plugin)
+- **Test Page**: Visual demonstration of all features (`/design-system-test` route)
+
+### External Resources
+
+- [Tailwind CSS Documentation](https://tailwindcss.com)
+- [shadcn/ui Components](https://ui.shadcn.com)
+- [HSL Color Picker](https://hslpicker.com)
+- [WebAIM: Color Contrast](https://webaim.org/articles/contrast/)
+
+### TypeScript Support
+
+The library includes full TypeScript definitions:
+
+```ts
+import type { Config } from 'tailwindcss'
+import preset from '@launch77-shared/lib-design-system/preset'
+
+const config: Config = {
+  presets: [preset],
+  // TypeScript knows about all preset options
+}
+```
+
+---
+
+**Need help?** Check the plugin README for troubleshooting, or ask in the Launch77 community.

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@launch77-shared/lib-design-system",
+  "version": "0.1.0",
+  "description": "Launch77 Design System - Token-driven theming foundation for shadcn-based component libraries",
+  "license": "UNLICENSED",
+  "main": "./src/preset.js",
+  "exports": {
+    ".": {
+      "default": "./src/preset.js"
+    },
+    "./tokens.css": "./src/tokens.css",
+    "./preset": "./src/preset.js"
+  },
+  "files": [
+    "src/preset.js",
+    "src/tokens.css",
+    "src/index.js",
+    "src/index.d.ts",
+    "docs/"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "echo 'No build required for design system package'",
+    "typecheck": "tsc --noEmit",
+    "test": "echo 'Tests not yet implemented'",
+    "release:connect": "launch77-release-connect",
+    "release:verify": "launch77-release-verify"
+  },
+  "peerDependencies": {
+    "tailwindcss": "^3.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tailwindcss": "^3.4.17",
+    "typescript": "^5.3.0"
+  },
+  "launch77": {
+    "installedPlugins": {
+      "release": {
+        "package": "release",
+        "version": "1.0.0",
+        "installedAt": "2026-01-22T17:33:45.971Z",
+        "source": "local"
+      }
+    }
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,3 @@
+import type { Config } from 'tailwindcss'
+
+export const preset: Config

package/src/index.js

@@ -0,0 +1,3 @@
+module.exports = {
+  preset: require('./preset'),
+}

package/src/preset.js

@@ -0,0 +1,139 @@
+const plugin = require('tailwindcss/plugin')
+
+// Base styles plugin - automatically injects base styles without requiring CSS imports
+const baseStylesPlugin = plugin(function ({ addBase }) {
+  addBase({
+    '*': {
+      borderColor: 'hsl(var(--color-border))',
+    },
+    html: {
+      scrollBehavior: 'smooth',
+    },
+    body: {
+      backgroundColor: 'hsl(var(--color-background))',
+      color: 'hsl(var(--color-foreground))',
+      WebkitFontSmoothing: 'antialiased',
+      MozOsxFontSmoothing: 'grayscale',
+    },
+    '::selection': {
+      backgroundColor: 'hsl(var(--color-primary) / 0.2)',
+      color: 'hsl(var(--color-primary))',
+    },
+    ':focus-visible': {
+      outline: 'none',
+      boxShadow: '0 0 0 2px hsl(var(--color-background)), 0 0 0 4px hsl(var(--color-ring))',
+    },
+    'button, a, input, select, textarea': {
+      minHeight: '44px',
+      minWidth: '44px',
+    },
+    '@media (prefers-reduced-motion: reduce)': {
+      '*, *::before, *::after': {
+        animationDuration: '0.01ms !important',
+        animationIterationCount: '1 !important',
+        transitionDuration: '0.01ms !important',
+        scrollBehavior: 'auto !important',
+      },
+    },
+  })
+})
+
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  darkMode: ['class'],
+  theme: {
+    container: {
+      center: true,
+      padding: '2rem',
+      screens: {
+        '2xl': '1400px',
+      },
+    },
+    extend: {
+      colors: {
+        border: 'hsl(var(--color-border))',
+        input: 'hsl(var(--color-input))',
+        ring: 'hsl(var(--color-ring))',
+        background: 'hsl(var(--color-background))',
+        foreground: 'hsl(var(--color-foreground))',
+        primary: {
+          DEFAULT: 'hsl(var(--color-primary) / <alpha-value>)',
+          foreground: 'hsl(var(--color-primary-foreground))',
+        },
+        secondary: {
+          DEFAULT: 'hsl(var(--color-secondary) / <alpha-value>)',
+          foreground: 'hsl(var(--color-secondary-foreground))',
+        },
+        destructive: {
+          DEFAULT: 'hsl(var(--color-destructive) / <alpha-value>)',
+          foreground: 'hsl(var(--color-destructive-foreground))',
+        },
+        muted: {
+          DEFAULT: 'hsl(var(--color-muted) / <alpha-value>)',
+          foreground: 'hsl(var(--color-muted-foreground))',
+        },
+        accent: {
+          DEFAULT: 'hsl(var(--color-accent) / <alpha-value>)',
+          foreground: 'hsl(var(--color-accent-foreground))',
+        },
+        card: {
+          DEFAULT: 'hsl(var(--color-card))',
+          foreground: 'hsl(var(--color-card-foreground))',
+        },
+      },
+      borderRadius: {
+        lg: 'var(--radius)',
+        md: 'calc(var(--radius) - 2px)',
+        sm: 'calc(var(--radius) - 4px)',
+      },
+      keyframes: {
+        'accordion-down': {
+          from: { height: '0' },
+          to: { height: 'var(--radix-accordion-content-height)' },
+        },
+        'accordion-up': {
+          from: { height: 'var(--radix-accordion-content-height)' },
+          to: { height: '0' },
+        },
+        'fade-in': {
+          from: { opacity: '0' },
+          to: { opacity: '1' },
+        },
+        'fade-out': {
+          from: { opacity: '1' },
+          to: { opacity: '0' },
+        },
+        'slide-in-from-top': {
+          from: { transform: 'translateY(-100%)' },
+          to: { transform: 'translateY(0)' },
+        },
+        'slide-in-from-bottom': {
+          from: { transform: 'translateY(100%)' },
+          to: { transform: 'translateY(0)' },
+        },
+        'slide-in-from-left': {
+          from: { transform: 'translateX(-100%)' },
+          to: { transform: 'translateX(0)' },
+        },
+        'slide-in-from-right': {
+          from: { transform: 'translateX(100%)' },
+          to: { transform: 'translateX(0)' },
+        },
+      },
+      animation: {
+        'accordion-down': 'accordion-down 0.2s ease-out',
+        'accordion-up': 'accordion-up 0.2s ease-out',
+        'fade-in': 'fade-in 0.2s ease-out',
+        'fade-out': 'fade-out 0.2s ease-out',
+        'slide-in-from-top': 'slide-in-from-top 0.25s ease-out',
+        'slide-in-from-bottom': 'slide-in-from-bottom 0.25s ease-out',
+        'slide-in-from-left': 'slide-in-from-left 0.25s ease-out',
+        'slide-in-from-right': 'slide-in-from-right 0.25s ease-out',
+      },
+    },
+  },
+  plugins: [baseStylesPlugin],
+  future: {
+    hoverOnlyWhenSupported: true,
+  },
+}

package/src/tokens.css

@@ -0,0 +1,66 @@
+/* Pure CSS tokens - no Tailwind dependencies */
+
+:root {
+  /* Base colors */
+  --color-background: 0 0% 100%; /* white */
+  --color-foreground: 222 47% 11%; /* slate-900 */
+
+  /* Card */
+  --color-card: 0 0% 100%; /* white */
+  --color-card-foreground: 222 47% 11%; /* slate-900 */
+
+  /* Primary - Default neutral theme */
+  --color-primary: 222 47% 11%; /* slate-900 */
+  --color-primary-foreground: 0 0% 100%; /* white */
+
+  /* Secondary */
+  --color-secondary: 210 40% 96%; /* slate-100 */
+  --color-secondary-foreground: 222 47% 11%; /* slate-900 */
+
+  /* Muted */
+  --color-muted: 210 40% 96%; /* slate-100 */
+  --color-muted-foreground: 215 16% 47%; /* slate-500 */
+
+  /* Accent */
+  --color-accent: 210 40% 96%; /* slate-100 */
+  --color-accent-foreground: 222 47% 11%; /* slate-900 */
+
+  /* Destructive */
+  --color-destructive: 0 84% 60%; /* red-500 */
+  --color-destructive-foreground: 0 0% 98%; /* white */
+
+  /* Border */
+  --color-border: 214 32% 91%; /* slate-200 */
+  --color-input: 214 32% 91%; /* slate-200 */
+  --color-ring: 222 47% 11%; /* slate-900 */
+
+  /* Radius */
+  --radius: 1rem; /* rounded-2xl equivalent */
+}
+
+.dark {
+  --color-background: 222 47% 11%; /* slate-900 */
+  --color-foreground: 210 40% 98%; /* slate-50 */
+
+  --color-card: 222 47% 11%; /* slate-900 */
+  --color-card-foreground: 210 40% 98%; /* slate-50 */
+
+  --color-primary: 210 40% 98%; /* slate-50 for dark mode */
+  --color-primary-foreground: 222 47% 11%; /* slate-900 */
+
+  --color-secondary: 217 33% 17%; /* slate-800 */
+  --color-secondary-foreground: 210 40% 98%; /* slate-50 */
+
+  --color-muted: 217 33% 17%; /* slate-800 */
+  --color-muted-foreground: 215 20% 65%; /* slate-400 */
+
+  --color-accent: 217 33% 17%; /* slate-800 */
+  --color-accent-foreground: 210 40% 98%; /* slate-50 */
+
+  --color-destructive: 0 63% 31%; /* dark red */
+  --color-destructive-foreground: 210 40% 98%; /* slate-50 */
+
+  --color-border: 217 33% 17%; /* slate-800 */
+  --color-input: 217 33% 17%; /* slate-800 */
+  --color-ring: 210 40% 98%; /* slate-50 */
+}