@discourser/design-system 0.22.1 → 0.22.3

package/docs/discourser-design-system-prd.md

@@ -0,0 +1,3698 @@
+# Design System Repository Setup PRD
+## Project Overview
+
+Create a design system repository called `@discourser/design-system` using **Panda CSS** and **Ark UI**. This system uses an aesthetic-agnostic architecture where design languages (like Material Design 3) can be swapped by changing a single import.
+
+## Technical Stack
+
+- **Panda CSS** - Zero-runtime CSS-in-JS with token-first architecture
+- **Ark UI** - Headless, accessible components built on Zag.js state machines
+- **TypeScript** - Strict mode, full type safety
+- **tsup** - Build tool for ESM/CJS output
+- **Storybook** - Component documentation and testing
+- **Vitest** - Unit testing
+- **@material/material-color-utilities** - M3 color palette generation
+- **pnpm** - Package manager
+
+## Architecture: Three-Layer System
+
+```
+Layer 1: Infrastructure (Unchanging)
+├── Token pipeline
+├── Build system (tsup, Storybook)
+├── Component logic (Ark UI)
+└── Type contracts
+
+Layer 2: Design Language (Swappable)
+├── Token values (colors, spacing, radii)
+├── Semantic mappings
+└── Motion patterns
+
+Layer 3: Component Recipes (Derived)
+├── Visual styling via Panda recipes
+└── Variant definitions
+```
+
+## Repository Structure
+
+Create this exact folder structure:
+
+```
+design-system/
+├── .github/
+│   └── workflows/
+│       ├── ci.yml
+│       └── release.yml
+├── .storybook/
+│   ├── main.ts
+│   ├── preview.ts
+│   └── manager.ts
+├── scripts/
+│   ├── generate-palette.ts
+│   ├── sync-tokens.ts
+│   └── build.ts
+├── src/
+│   ├── contracts/
+│   │   └── design-language.contract.ts
+│   ├── languages/
+│   │   ├── material3.language.ts
+│   │   ├── transform.ts
+│   │   └── index.ts
+│   ├── tokens/
+│   │   ├── typography.ts
+│   │   ├── shadows.ts
+│   │   ├── motion.ts
+│   │   └── index.ts
+│   ├── recipes/
+│   │   ├── button.recipe.ts
+│   │   ├── card.recipe.ts
+│   │   ├── icon-button.recipe.ts
+│   │   ├── input.recipe.ts
+│   │   ├── dialog.recipe.ts
+│   │   └── index.ts
+│   ├── components/
+│   │   ├── Button/
+│   │   │   ├── Button.tsx
+│   │   │   ├── Button.stories.tsx
+│   │   │   └── index.ts
+│   │   ├── Card/
+│   │   │   ├── Card.tsx
+│   │   │   ├── Card.stories.tsx
+│   │   │   └── index.ts
+│   │   ├── Dialog/
+│   │   │   ├── Dialog.tsx
+│   │   │   ├── Dialog.stories.tsx
+│   │   │   └── index.ts
+│   │   └── index.ts
+│   ├── utils/
+│   │   └── cn.ts
+│   └── index.ts
+├── tokens/
+│   └── figma-export.json (placeholder)
+├── styled-system/           # Generated by Panda (gitignore)
+├── dist/                    # Build output (gitignore)
+├── panda.config.ts
+├── tsconfig.json
+├── tsup.config.ts
+├── vitest.config.ts
+├── package.json
+├── .gitignore
+├── .npmrc
+└── README.md
+```
+
+## File Contents
+
+### package.json
+
+```json
+{
+  "name": "@discourser/design-system",
+  "version": "0.1.0",
+  "description": "Aesthetic-agnostic design system with Panda CSS and Ark UI",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    },
+    "./styled-system": {
+      "import": "./styled-system/index.mjs",
+      "require": "./styled-system/index.js"
+    },
+    "./styled-system/css": {
+      "import": "./styled-system/css/index.mjs",
+      "require": "./styled-system/css/index.js"
+    },
+    "./styled-system/tokens": {
+      "import": "./styled-system/tokens/index.mjs",
+      "require": "./styled-system/tokens/index.js"
+    },
+    "./styled-system/recipes": {
+      "import": "./styled-system/recipes/index.mjs",
+      "require": "./styled-system/recipes/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "styled-system"
+  ],
+  "scripts": {
+    "dev": "storybook dev -p 6006",
+    "build": "pnpm build:panda && pnpm build:lib",
+    "build:panda": "panda codegen",
+    "build:lib": "tsup",
+    "build:storybook": "storybook build",
+    "prepare": "panda codegen",
+    "lint": "eslint src --ext .ts,.tsx",
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "tokens:generate": "tsx scripts/generate-palette.ts",
+    "tokens:sync": "tsx scripts/sync-tokens.ts",
+    "tokens:full": "pnpm tokens:generate && pnpm build:panda",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "react": ">=19.0.0",
+    "react-dom": ">=19.0.0"
+  },
+  "dependencies": {
+    "@ark-ui/react": "^4.4.0",
+    "clsx": "^2.1.1"
+  },
+  "devDependencies": {
+    "@material/material-color-utilities": "^0.3.0",
+    "@pandacss/dev": "^0.52.0",
+    "@storybook/addon-a11y": "^8.5.0",
+    "@storybook/addon-essentials": "^8.5.0",
+    "@storybook/react": "^8.5.0",
+    "@storybook/react-vite": "^8.5.0",
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^4.3.0",
+    "eslint": "^9.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "storybook": "^8.5.0",
+    "tsup": "^8.3.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "vite": "^6.0.0",
+    "vitest": "^2.1.0"
+  },
+  "keywords": [
+    "design-system",
+    "panda-css",
+    "ark-ui",
+    "material-design-3",
+    "react",
+    "components"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Tasty-Maker-Studio/Discourser-Design-System.git"
+  }
+}
+```
+
+### tsconfig.json
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "dist",
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"],
+      "styled-system/*": ["./styled-system/*"]
+    },
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true
+  },
+  "include": ["src/**/*", "scripts/**/*", "panda.config.ts"],
+  "exclude": ["node_modules", "dist", "styled-system", "storybook-static"]
+}
+```
+
+### tsup.config.ts
+
+```typescript
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'],
+  dts: true,
+  splitting: true,
+  sourcemap: true,
+  clean: true,
+  external: ['react', 'react-dom'],
+  esbuildOptions(options) {
+    options.banner = {
+      js: '"use client"',
+    };
+  },
+});
+```
+
+### panda.config.ts
+
+```typescript
+import { defineConfig } from '@pandacss/dev';
+import { activeLanguage, transformToPandaTheme } from './src/languages';
+import { buttonRecipe, cardRecipe, iconButtonRecipe } from './src/recipes';
+
+const theme = transformToPandaTheme(activeLanguage);
+
+export default defineConfig({
+  preflight: true,
+
+  include: [
+    './src/**/*.{js,jsx,ts,tsx}',
+    './stories/**/*.{js,jsx,ts,tsx}'
+  ],
+
+  exclude: [],
+
+  outdir: 'styled-system',
+
+  jsxFramework: 'react',
+
+  layers: {
+    reset: 'reset',
+    base: 'base',
+    tokens: 'tokens',
+    recipes: 'recipes',
+    utilities: 'utilities'
+  },
+
+  theme: {
+    tokens: theme.tokens,
+    semanticTokens: theme.semanticTokens,
+    textStyles: theme.textStyles,
+    extend: {
+      recipes: {
+        button: buttonRecipe,
+        card: cardRecipe,
+        iconButton: iconButtonRecipe,
+      }
+    }
+  },
+
+  conditions: {
+    light: '[data-theme=light] &, .light &',
+    dark: '[data-theme=dark] &, .dark &'
+  },
+
+  globalCss: {
+    html: {
+      colorScheme: 'light dark'
+    },
+    body: {
+      fontFamily: 'body',
+      bg: 'surface',
+      color: 'onSurface',
+      textStyle: 'bodyMedium'
+    }
+  }
+});
+```
+
+### src/contracts/design-language.contract.ts
+
+```typescript
+/**
+ * Design Language Contract
+ *
+ * Any aesthetic (M3, Carbon, Fluent, custom) must implement this interface.
+ * This enables swapping aesthetics by changing one import.
+ */
+
+export interface DesignLanguageContract {
+  name: string;
+  version: string;
+  colors: ColorPalettes;
+  semantic: SemanticColors;
+  semanticDark?: SemanticColors; // Optional dark theme overrides
+  typography: TypographyConfig;
+  spacing: SpacingScale;
+  shape: ShapeConfig;
+  elevation: ElevationConfig;
+  motion: MotionConfig;
+}
+
+// Color Types
+export interface ColorPalettes {
+  primary: TonalPalette;
+  secondary: TonalPalette;
+  tertiary: TonalPalette;
+  neutral: TonalPalette;
+  neutralVariant: TonalPalette;
+  error: TonalPalette;
+}
+
+export interface TonalPalette {
+  0: string;
+  10: string;
+  20: string;
+  30: string;
+  40: string;
+  50: string;
+  60: string;
+  70: string;
+  80: string;
+  90: string;
+  95: string;
+  99: string;
+  100: string;
+}
+
+export interface SemanticColors {
+  primary: string;
+  onPrimary: string;
+  primaryContainer: string;
+  onPrimaryContainer: string;
+  secondary: string;
+  onSecondary: string;
+  secondaryContainer: string;
+  onSecondaryContainer: string;
+  tertiary: string;
+  onTertiary: string;
+  tertiaryContainer: string;
+  onTertiaryContainer: string;
+  error: string;
+  onError: string;
+  errorContainer: string;
+  onErrorContainer: string;
+  surface: string;
+  onSurface: string;
+  surfaceVariant: string;
+  onSurfaceVariant: string;
+  surfaceContainerLowest: string;
+  surfaceContainerLow: string;
+  surfaceContainer: string;
+  surfaceContainerHigh: string;
+  surfaceContainerHighest: string;
+  outline: string;
+  outlineVariant: string;
+  inverseSurface: string;
+  inverseOnSurface: string;
+  inversePrimary: string;
+  background: string;
+  onBackground: string;
+  scrim: string;
+  shadow: string;
+}
+
+// Typography Types
+export interface TypographyConfig {
+  fonts: {
+    display: string;
+    body: string;
+    mono: string;
+  };
+  scale: TypographyScale;
+}
+
+export interface TypographyScale {
+  displayLarge: TypeStyle;
+  displayMedium: TypeStyle;
+  displaySmall: TypeStyle;
+  headlineLarge: TypeStyle;
+  headlineMedium: TypeStyle;
+  headlineSmall: TypeStyle;
+  titleLarge: TypeStyle;
+  titleMedium: TypeStyle;
+  titleSmall: TypeStyle;
+  bodyLarge: TypeStyle;
+  bodyMedium: TypeStyle;
+  bodySmall: TypeStyle;
+  labelLarge: TypeStyle;
+  labelMedium: TypeStyle;
+  labelSmall: TypeStyle;
+}
+
+export interface TypeStyle {
+  fontSize: string;
+  lineHeight: string;
+  fontWeight: string;
+  letterSpacing: string;
+  fontFamily?: 'display' | 'body' | 'mono';
+}
+
+// Spacing Types
+export interface SpacingScale {
+  none: string;
+  xxs: string;
+  xs: string;
+  sm: string;
+  md: string;
+  lg: string;
+  xl: string;
+  xxl: string;
+  xxxl: string;
+}
+
+// Shape Types
+export interface ShapeConfig {
+  radii: RadiiScale;
+  style: 'sharp' | 'rounded' | 'soft' | 'organic';
+}
+
+export interface RadiiScale {
+  none: string;
+  extraSmall: string;
+  small: string;
+  medium: string;
+  large: string;
+  extraLarge: string;
+  full: string;
+}
+
+// Elevation Types
+export interface ElevationConfig {
+  levels: ElevationScale;
+  style: 'shadow' | 'border' | 'blur' | 'flat';
+}
+
+export interface ElevationScale {
+  level0: string;
+  level1: string;
+  level2: string;
+  level3: string;
+  level4: string;
+  level5: string;
+}
+
+// Motion Types
+export interface MotionConfig {
+  durations: DurationScale;
+  easings: EasingScale;
+  style: 'expressive' | 'productive' | 'minimal';
+}
+
+export interface DurationScale {
+  instant: string;
+  fast: string;
+  normal: string;
+  slow: string;
+  slower: string;
+}
+
+export interface EasingScale {
+  standard: string;
+  standardDecelerate: string;
+  standardAccelerate: string;
+  emphasized: string;
+  emphasizedDecelerate: string;
+  emphasizedAccelerate: string;
+}
+```
+
+### src/languages/transform.ts
+
+```typescript
+import type { DesignLanguageContract, TonalPalette, SemanticColors } from '../contracts/design-language.contract';
+
+/**
+ * Transforms a DesignLanguageContract into Panda CSS theme configuration
+ */
+export function transformToPandaTheme(language: DesignLanguageContract) {
+  return {
+    tokens: transformTokens(language),
+    semanticTokens: transformSemanticTokens(language),
+    textStyles: transformTextStyles(language)
+  };
+}
+
+function transformTokens(language: DesignLanguageContract) {
+  return {
+    colors: transformColorPalettes(language.colors),
+    fonts: {
+      display: { value: language.typography.fonts.display },
+      body: { value: language.typography.fonts.body },
+      mono: { value: language.typography.fonts.mono }
+    },
+    fontSizes: extractFontSizes(language.typography.scale),
+    lineHeights: extractLineHeights(language.typography.scale),
+    fontWeights: extractFontWeights(language.typography.scale),
+    letterSpacings: extractLetterSpacings(language.typography.scale),
+    spacing: objectToTokens(language.spacing),
+    radii: objectToTokens(language.shape.radii),
+    shadows: objectToTokens(language.elevation.levels),
+    durations: objectToTokens(language.motion.durations),
+    easings: objectToTokens(language.motion.easings)
+  };
+}
+
+function transformSemanticTokens(language: DesignLanguageContract) {
+  const light = language.semantic;
+  const dark = language.semanticDark || light; // Fallback to light if no dark
+
+  return {
+    colors: Object.fromEntries(
+      Object.entries(light).map(([key, lightValue]) => [
+        key,
+        {
+          value: {
+            base: lightValue,
+            _dark: dark[key as keyof SemanticColors] || lightValue
+          }
+        }
+      ])
+    )
+  };
+}
+
+function transformTextStyles(language: DesignLanguageContract) {
+  const scale = language.typography.scale;
+
+  return Object.fromEntries(
+    Object.entries(scale).map(([name, style]) => [
+      name,
+      {
+        value: {
+          fontFamily: style.fontFamily || 'body',
+          fontSize: style.fontSize,
+          lineHeight: style.lineHeight,
+          fontWeight: style.fontWeight,
+          letterSpacing: style.letterSpacing
+        }
+      }
+    ])
+  );
+}
+
+function transformColorPalettes(palettes: Record<string, TonalPalette>) {
+  return Object.fromEntries(
+    Object.entries(palettes).map(([name, palette]) => [
+      name,
+      Object.fromEntries(
+        Object.entries(palette).map(([tone, value]) => [
+          tone,
+          { value }
+        ])
+      )
+    ])
+  );
+}
+
+function objectToTokens<T extends Record<string, string>>(obj: T) {
+  return Object.fromEntries(
+    Object.entries(obj).map(([key, value]) => [key, { value }])
+  );
+}
+
+function extractFontSizes(scale: Record<string, { fontSize: string }>) {
+  return Object.fromEntries(
+    Object.entries(scale).map(([name, style]) => [
+      name,
+      { value: style.fontSize }
+    ])
+  );
+}
+
+function extractLineHeights(scale: Record<string, { lineHeight: string }>) {
+  return Object.fromEntries(
+    Object.entries(scale).map(([name, style]) => [
+      name,
+      { value: style.lineHeight }
+    ])
+  );
+}
+
+function extractFontWeights(scale: Record<string, { fontWeight: string }>) {
+  const weights = new Map<string, string>();
+  Object.values(scale).forEach(style => {
+    weights.set(style.fontWeight, style.fontWeight);
+  });
+  return Object.fromEntries(
+    Array.from(weights.entries()).map(([key, value]) => [
+      key,
+      { value }
+    ])
+  );
+}
+
+function extractLetterSpacings(scale: Record<string, { letterSpacing: string }>) {
+  return Object.fromEntries(
+    Object.entries(scale).map(([name, style]) => [
+      name,
+      { value: style.letterSpacing }
+    ])
+  );
+}
+```
+
+### src/languages/material3.language.ts
+
+```typescript
+import type { DesignLanguageContract } from '../contracts/design-language.contract';
+
+/**
+ * Material Design 3 Language Implementation
+ * 
+ * Source color: #63A002 (TastyMakers green)
+ * Generated via Material Theme Builder plugin 2024-12-24
+ */
+export const material3Language: DesignLanguageContract = {
+  name: 'material3',
+  version: '1.0.0',
+  
+  colors: {
+    // From Material Theme Builder export
+    primary: {
+      0: '#000000',
+      10: '#102000',
+      20: '#1F3700',
+      30: '#2F4F00',
+      40: '#3F6900',
+      50: '#518500',
+      60: '#64A104',
+      70: '#7DBD2A',
+      80: '#97D945',
+      90: '#B2F65F',
+      95: '#D2FF9B',
+      99: '#F9FFE9',
+      100: '#FFFFFF'
+    },
+    secondary: {
+      0: '#000000',
+      10: '#121F04',
+      20: '#263515',
+      30: '#3C4C2A',
+      40: '#54643F',
+      50: '#6C7D56',
+      60: '#85976E',
+      70: '#A0B187',
+      80: '#BBCDA1',
+      90: '#D7E9BB',
+      95: '#E5F7C9',
+      99: '#F9FFE9',
+      100: '#FFFFFF'
+    },
+    tertiary: {
+      0: '#000000',
+      10: '#00201E',
+      20: '#003735',
+      30: '#00504C',
+      40: '#046A66',
+      50: '#30837F',
+      60: '#4D9D98',
+      70: '#69B8B3',
+      80: '#85D4CF',
+      90: '#A1F1EB',
+      95: '#B0FFF9',
+      99: '#F2FFFD',
+      100: '#FFFFFF'
+    },
+    neutral: {
+      0: '#000000',
+      10: '#1B1C18',
+      20: '#30312C',
+      30: '#464742',
+      40: '#5E5F59',
+      50: '#777771',
+      60: '#91918B',
+      70: '#ABACA5',
+      80: '#C7C7C0',
+      90: '#E3E3DB',
+      95: '#F2F1E9',
+      99: '#FDFCF5',
+      100: '#FFFFFF'
+    },
+    neutralVariant: {
+      0: '#000000',
+      10: '#191D14',
+      20: '#2E3228',
+      30: '#44483D',
+      40: '#5C6054',
+      50: '#75796C',
+      60: '#8F9285',
+      70: '#A9AD9F',
+      80: '#C5C8BA',
+      90: '#E1E4D5',
+      95: '#EFF2E3',
+      99: '#FBFEEE',
+      100: '#FFFFFF'
+    },
+    error: {
+      0: '#000000',
+      10: '#410E0B',
+      20: '#601410',
+      30: '#8C1D18',
+      40: '#B3261E',
+      50: '#DC362E',
+      60: '#E46962',
+      70: '#EC928E',
+      80: '#F2B8B5',
+      90: '#F9DEDC',
+      95: '#FCEEEE',
+      99: '#FFFBF9',
+      100: '#FFFFFF'
+    }
+  },
+  
+  semantic: {
+    // Light theme from Material Theme Builder
+    primary: '#4C662B',
+    onPrimary: '#FFFFFF',
+    primaryContainer: '#CDEDA3',
+    onPrimaryContainer: '#354E16',
+    
+    secondary: '#586249',
+    onSecondary: '#FFFFFF',
+    secondaryContainer: '#DCE7C8',
+    onSecondaryContainer: '#404A33',
+    
+    tertiary: '#386663',
+    onTertiary: '#FFFFFF',
+    tertiaryContainer: '#BCECE7',
+    onTertiaryContainer: '#1F4E4B',
+    
+    error: '#BA1A1A',
+    onError: '#FFFFFF',
+    errorContainer: '#FFDAD6',
+    onErrorContainer: '#93000A',
+    
+    surface: '#F9FAEF',
+    onSurface: '#1A1C16',
+    surfaceVariant: '#E1E4D5',
+    onSurfaceVariant: '#44483D',
+    
+    surfaceContainerLowest: '#FFFFFF',
+    surfaceContainerLow: '#F3F4E9',
+    surfaceContainer: '#EEEFE3',
+    surfaceContainerHigh: '#E8E9DE',
+    surfaceContainerHighest: '#E2E3D8',
+    
+    outline: '#75796C',
+    outlineVariant: '#C5C8BA',
+    
+    inverseSurface: '#2F312A',
+    inverseOnSurface: '#F1F2E6',
+    inversePrimary: '#B1D18A',
+    
+    background: '#F9FAEF',
+    onBackground: '#1A1C16',
+    
+    scrim: '#000000',
+    shadow: '#000000'
+  },
+  
+  // Dark theme semantic colors (for reference/dark mode implementation)
+  semanticDark: {
+    primary: '#B1D18A',
+    onPrimary: '#1F3701',
+    primaryContainer: '#354E16',
+    onPrimaryContainer: '#CDEDA3',
+    
+    secondary: '#BFCBAD',
+    onSecondary: '#2A331E',
+    secondaryContainer: '#404A33',
+    onSecondaryContainer: '#DCE7C8',
+    
+    tertiary: '#A0D0CB',
+    onTertiary: '#003735',
+    tertiaryContainer: '#1F4E4B',
+    onTertiaryContainer: '#BCECE7',
+    
+    error: '#FFB4AB',
+    onError: '#690005',
+    errorContainer: '#93000A',
+    onErrorContainer: '#FFDAD6',
+    
+    surface: '#12140E',
+    onSurface: '#E2E3D8',
+    surfaceVariant: '#44483D',
+    onSurfaceVariant: '#C5C8BA',
+    
+    surfaceContainerLowest: '#0C0F09',
+    surfaceContainerLow: '#1A1C16',
+    surfaceContainer: '#1E201A',
+    surfaceContainerHigh: '#282B24',
+    surfaceContainerHighest: '#33362E',
+    
+    outline: '#8F9285',
+    outlineVariant: '#44483D',
+    
+    inverseSurface: '#E2E3D8',
+    inverseOnSurface: '#2F312A',
+    inversePrimary: '#4C662B',
+    
+    background: '#12140E',
+    onBackground: '#E2E3D8',
+    
+    scrim: '#000000',
+    shadow: '#000000'
+  },
+  
+  typography: {
+    fonts: {
+      display: 'Georgia, "Times New Roman", serif',
+      body: 'Inter, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
+      mono: '"JetBrains Mono", "Fira Code", Consolas, monospace'
+    },
+    scale: {
+      displayLarge: {
+        fontSize: '57px',
+        lineHeight: '64px',
+        fontWeight: '400',
+        letterSpacing: '-0.25px',
+        fontFamily: 'display'
+      },
+      displayMedium: {
+        fontSize: '45px',
+        lineHeight: '52px',
+        fontWeight: '400',
+        letterSpacing: '0px',
+        fontFamily: 'display'
+      },
+      displaySmall: {
+        fontSize: '36px',
+        lineHeight: '44px',
+        fontWeight: '400',
+        letterSpacing: '0px',
+        fontFamily: 'display'
+      },
+      headlineLarge: {
+        fontSize: '32px',
+        lineHeight: '40px',
+        fontWeight: '400',
+        letterSpacing: '0px',
+        fontFamily: 'display'
+      },
+      headlineMedium: {
+        fontSize: '28px',
+        lineHeight: '36px',
+        fontWeight: '400',
+        letterSpacing: '0px',
+        fontFamily: 'display'
+      },
+      headlineSmall: {
+        fontSize: '24px',
+        lineHeight: '32px',
+        fontWeight: '400',
+        letterSpacing: '0px',
+        fontFamily: 'display'
+      },
+      titleLarge: {
+        fontSize: '22px',
+        lineHeight: '28px',
+        fontWeight: '500',
+        letterSpacing: '0px',
+        fontFamily: 'body'
+      },
+      titleMedium: {
+        fontSize: '16px',
+        lineHeight: '24px',
+        fontWeight: '500',
+        letterSpacing: '0.15px',
+        fontFamily: 'body'
+      },
+      titleSmall: {
+        fontSize: '14px',
+        lineHeight: '20px',
+        fontWeight: '500',
+        letterSpacing: '0.1px',
+        fontFamily: 'body'
+      },
+      bodyLarge: {
+        fontSize: '16px',
+        lineHeight: '24px',
+        fontWeight: '400',
+        letterSpacing: '0.5px',
+        fontFamily: 'body'
+      },
+      bodyMedium: {
+        fontSize: '14px',
+        lineHeight: '20px',
+        fontWeight: '400',
+        letterSpacing: '0.25px',
+        fontFamily: 'body'
+      },
+      bodySmall: {
+        fontSize: '12px',
+        lineHeight: '16px',
+        fontWeight: '400',
+        letterSpacing: '0.4px',
+        fontFamily: 'body'
+      },
+      labelLarge: {
+        fontSize: '14px',
+        lineHeight: '20px',
+        fontWeight: '500',
+        letterSpacing: '0.1px',
+        fontFamily: 'body'
+      },
+      labelMedium: {
+        fontSize: '12px',
+        lineHeight: '16px',
+        fontWeight: '500',
+        letterSpacing: '0.5px',
+        fontFamily: 'body'
+      },
+      labelSmall: {
+        fontSize: '11px',
+        lineHeight: '16px',
+        fontWeight: '500',
+        letterSpacing: '0.5px',
+        fontFamily: 'body'
+      }
+    }
+  },
+  
+  spacing: {
+    none: '0px',
+    xxs: '2px',
+    xs: '4px',
+    sm: '8px',
+    md: '16px',
+    lg: '24px',
+    xl: '32px',
+    xxl: '48px',
+    xxxl: '64px'
+  },
+  
+  shape: {
+    radii: {
+      none: '0px',
+      extraSmall: '4px',
+      small: '8px',
+      medium: '12px',
+      large: '16px',
+      extraLarge: '28px',
+      full: '9999px'
+    },
+    style: 'rounded'
+  },
+  
+  elevation: {
+    levels: {
+      level0: 'none',
+      level1: '0px 1px 2px rgba(0, 0, 0, 0.3), 0px 1px 3px 1px rgba(0, 0, 0, 0.15)',
+      level2: '0px 1px 2px rgba(0, 0, 0, 0.3), 0px 2px 6px 2px rgba(0, 0, 0, 0.15)',
+      level3: '0px 4px 8px 3px rgba(0, 0, 0, 0.15), 0px 1px 3px rgba(0, 0, 0, 0.3)',
+      level4: '0px 6px 10px 4px rgba(0, 0, 0, 0.15), 0px 2px 3px rgba(0, 0, 0, 0.3)',
+      level5: '0px 8px 12px 6px rgba(0, 0, 0, 0.15), 0px 4px 4px rgba(0, 0, 0, 0.3)'
+    },
+    style: 'shadow'
+  },
+  
+  motion: {
+    durations: {
+      instant: '0ms',
+      fast: '100ms',
+      normal: '200ms',
+      slow: '300ms',
+      slower: '500ms'
+    },
+    easings: {
+      standard: 'cubic-bezier(0.2, 0, 0, 1)',
+      standardDecelerate: 'cubic-bezier(0, 0, 0, 1)',
+      standardAccelerate: 'cubic-bezier(0.3, 0, 1, 1)',
+      emphasized: 'cubic-bezier(0.2, 0, 0, 1)',
+      emphasizedDecelerate: 'cubic-bezier(0.05, 0.7, 0.1, 1)',
+      emphasizedAccelerate: 'cubic-bezier(0.3, 0, 0.8, 0.15)'
+    },
+    style: 'expressive'
+  }
+};
+```
+
+### src/languages/index.ts
+
+```typescript
+// Export the active language
+// Change this import to switch aesthetics
+export { material3Language as activeLanguage } from './material3.language';
+
+// Re-export transformer
+export { transformToPandaTheme } from './transform';
+
+// Re-export types
+export type { DesignLanguageContract } from '../contracts/design-language.contract';
+```
+
+### src/recipes/button.recipe.ts
+
+```typescript
+import { defineRecipe } from '@pandacss/dev';
+
+export const buttonRecipe = defineRecipe({
+  className: 'button',
+  description: 'Material Design 3 button component',
+  base: {
+    display: 'inline-flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    gap: 'sm',
+    fontFamily: 'body',
+    fontWeight: '500',
+    borderRadius: 'full',
+    cursor: 'pointer',
+    transition: 'all',
+    transitionDuration: 'fast',
+    transitionTimingFunction: 'standard',
+    outline: 'none',
+    border: 'none',
+    textDecoration: 'none',
+    _disabled: {
+      opacity: 0.38,
+      cursor: 'not-allowed',
+      pointerEvents: 'none'
+    },
+    _focusVisible: {
+      outline: '2px solid',
+      outlineColor: 'primary',
+      outlineOffset: '2px'
+    }
+  },
+  variants: {
+    variant: {
+      filled: {
+        bg: 'primary',
+        color: 'onPrimary',
+        _hover: {
+          opacity: 0.92,
+          shadow: 'level1'
+        },
+        _active: {
+          opacity: 0.88
+        }
+      },
+      outlined: {
+        bg: 'transparent',
+        color: 'primary',
+        borderWidth: '1px',
+        borderStyle: 'solid',
+        borderColor: 'outline',
+        _hover: {
+          bg: 'primary',
+          bgOpacity: 0.08
+        },
+        _active: {
+          bg: 'primary',
+          bgOpacity: 0.12
+        }
+      },
+      text: {
+        bg: 'transparent',
+        color: 'primary',
+        _hover: {
+          bg: 'primary',
+          bgOpacity: 0.08
+        },
+        _active: {
+          bg: 'primary',
+          bgOpacity: 0.12
+        }
+      },
+      elevated: {
+        bg: 'surfaceContainerLow',
+        color: 'primary',
+        shadow: 'level1',
+        _hover: {
+          shadow: 'level2',
+          bg: 'surfaceContainerLow'
+        },
+        _active: {
+          shadow: 'level1'
+        }
+      },
+      tonal: {
+        bg: 'secondaryContainer',
+        color: 'onSecondaryContainer',
+        _hover: {
+          shadow: 'level1'
+        },
+        _active: {
+          shadow: 'none'
+        }
+      }
+    },
+    size: {
+      sm: {
+        height: '32px',
+        px: 'md',
+        fontSize: 'labelMedium',
+        lineHeight: 'labelMedium'
+      },
+      md: {
+        height: '40px',
+        px: 'lg',
+        fontSize: 'labelLarge',
+        lineHeight: 'labelLarge'
+      },
+      lg: {
+        height: '48px',
+        px: 'xl',
+        fontSize: 'labelLarge',
+        lineHeight: 'labelLarge'
+      }
+    }
+  },
+  defaultVariants: {
+    variant: 'filled',
+    size: 'md'
+  }
+});
+```
+
+### src/recipes/card.recipe.ts
+
+```typescript
+import { defineRecipe } from '@pandacss/dev';
+
+export const cardRecipe = defineRecipe({
+  className: 'card',
+  description: 'Material Design 3 card component',
+  base: {
+    display: 'flex',
+    flexDirection: 'column',
+    borderRadius: 'medium',
+    overflow: 'hidden',
+    transition: 'all',
+    transitionDuration: 'fast',
+    transitionTimingFunction: 'standard'
+  },
+  variants: {
+    variant: {
+      elevated: {
+        bg: 'surfaceContainerLow',
+        shadow: 'level1',
+        _hover: {
+          shadow: 'level2'
+        }
+      },
+      filled: {
+        bg: 'surfaceContainerHighest'
+      },
+      outlined: {
+        bg: 'surface',
+        borderWidth: '1px',
+        borderStyle: 'solid',
+        borderColor: 'outlineVariant'
+      }
+    },
+    interactive: {
+      true: {
+        cursor: 'pointer',
+        _hover: {
+          opacity: 0.96
+        },
+        _active: {
+          opacity: 0.92
+        }
+      }
+    }
+  },
+  defaultVariants: {
+    variant: 'elevated',
+    interactive: false
+  }
+});
+```
+
+### src/recipes/icon-button.recipe.ts
+
+```typescript
+import { defineRecipe } from '@pandacss/dev';
+
+export const iconButtonRecipe = defineRecipe({
+  className: 'icon-button',
+  description: 'Material Design 3 icon button component',
+  base: {
+    display: 'inline-flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    borderRadius: 'full',
+    cursor: 'pointer',
+    transition: 'all',
+    transitionDuration: 'fast',
+    transitionTimingFunction: 'standard',
+    outline: 'none',
+    border: 'none',
+    p: '0',
+    _disabled: {
+      opacity: 0.38,
+      cursor: 'not-allowed',
+      pointerEvents: 'none'
+    },
+    _focusVisible: {
+      outline: '2px solid',
+      outlineColor: 'primary',
+      outlineOffset: '2px'
+    }
+  },
+  variants: {
+    variant: {
+      standard: {
+        bg: 'transparent',
+        color: 'onSurfaceVariant',
+        _hover: {
+          bg: 'onSurfaceVariant',
+          bgOpacity: 0.08
+        }
+      },
+      filled: {
+        bg: 'primary',
+        color: 'onPrimary',
+        _hover: {
+          opacity: 0.92
+        }
+      },
+      tonal: {
+        bg: 'secondaryContainer',
+        color: 'onSecondaryContainer',
+        _hover: {
+          opacity: 0.92
+        }
+      },
+      outlined: {
+        bg: 'transparent',
+        color: 'onSurfaceVariant',
+        borderWidth: '1px',
+        borderStyle: 'solid',
+        borderColor: 'outline',
+        _hover: {
+          bg: 'onSurfaceVariant',
+          bgOpacity: 0.08
+        }
+      }
+    },
+    size: {
+      sm: {
+        width: '32px',
+        height: '32px',
+        '& svg': {
+          width: '18px',
+          height: '18px'
+        }
+      },
+      md: {
+        width: '40px',
+        height: '40px',
+        '& svg': {
+          width: '24px',
+          height: '24px'
+        }
+      },
+      lg: {
+        width: '48px',
+        height: '48px',
+        '& svg': {
+          width: '24px',
+          height: '24px'
+        }
+      }
+    }
+  },
+  defaultVariants: {
+    variant: 'standard',
+    size: 'md'
+  }
+});
+```
+
+### src/recipes/index.ts
+
+```typescript
+export { buttonRecipe } from './button.recipe';
+export { cardRecipe } from './card.recipe';
+export { iconButtonRecipe } from './icon-button.recipe';
+```
+
+### src/utils/cn.ts
+
+```typescript
+import { clsx, type ClassValue } from 'clsx';
+
+/**
+ * Utility function to merge class names
+ */
+export function cn(...inputs: ClassValue[]) {
+  return clsx(inputs);
+}
+```
+
+### src/components/Button/Button.tsx
+
+```typescript
+import { forwardRef, type ButtonHTMLAttributes, type ReactNode } from 'react';
+import { button, type ButtonVariantProps } from 'styled-system/recipes';
+import { cn } from '../../utils/cn';
+
+export interface ButtonProps
+  extends ButtonHTMLAttributes<HTMLButtonElement>,
+    ButtonVariantProps {
+  children: ReactNode;
+  leftIcon?: ReactNode;
+  rightIcon?: ReactNode;
+}
+
+export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
+  (
+    { children, variant, size, leftIcon, rightIcon, className, ...props },
+    ref
+  ) => {
+    return (
+      <button
+        ref={ref}
+        className={cn(button({ variant, size }), className)}
+        {...props}
+      >
+        {leftIcon}
+        {children}
+        {rightIcon}
+      </button>
+    );
+  }
+);
+
+Button.displayName = 'Button';
+```
+
+### src/components/Button/Button.stories.tsx
+
+```typescript
+import type { Meta, StoryObj } from '@storybook/react';
+import { Button } from './Button';
+
+const meta: Meta<typeof Button> = {
+  title: 'Components/Button',
+  component: Button,
+  parameters: {
+    layout: 'centered',
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    variant: {
+      control: 'select',
+      options: ['filled', 'outlined', 'text', 'elevated', 'tonal'],
+    },
+    size: {
+      control: 'select',
+      options: ['sm', 'md', 'lg'],
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Filled: Story = {
+  args: {
+    children: 'Filled Button',
+    variant: 'filled',
+  },
+};
+
+export const Outlined: Story = {
+  args: {
+    children: 'Outlined Button',
+    variant: 'outlined',
+  },
+};
+
+export const Text: Story = {
+  args: {
+    children: 'Text Button',
+    variant: 'text',
+  },
+};
+
+export const Elevated: Story = {
+  args: {
+    children: 'Elevated Button',
+    variant: 'elevated',
+  },
+};
+
+export const Tonal: Story = {
+  args: {
+    children: 'Tonal Button',
+    variant: 'tonal',
+  },
+};
+
+export const Sizes: Story = {
+  render: () => (
+    <div style={{ display: 'flex', gap: '16px', alignItems: 'center' }}>
+      <Button size="sm">Small</Button>
+      <Button size="md">Medium</Button>
+      <Button size="lg">Large</Button>
+    </div>
+  ),
+};
+
+export const Disabled: Story = {
+  args: {
+    children: 'Disabled Button',
+    disabled: true,
+  },
+};
+```
+
+### src/components/Button/index.ts
+
+```typescript
+export { Button, type ButtonProps } from './Button';
+```
+
+### src/components/index.ts
+
+```typescript
+export * from './Button';
+// export * from './Card';
+// export * from './Dialog';
+```
+
+### src/index.ts
+
+```typescript
+// Components
+export * from './components';
+
+// Recipes (for direct usage)
+export * from './recipes';
+
+// Language system
+export * from './languages';
+
+// Contracts
+export type * from './contracts/design-language.contract';
+
+// Utilities
+export { cn } from './utils/cn';
+```
+
+### scripts/generate-palette.ts
+
+```typescript
+import {
+  argbFromHex,
+  hexFromArgb,
+  TonalPalette,
+  Hct,
+  themeFromSourceColor
+} from '@material/material-color-utilities';
+import fs from 'fs';
+import path from 'path';
+
+// TastyMakers source color from Material Theme Builder
+const SOURCE_COLOR = '#63A002';
+
+function generatePalette() {
+  const theme = themeFromSourceColor(argbFromHex(SOURCE_COLOR));
+  
+  const tones = [0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 95, 99, 100];
+  
+  const palettes = {
+    primary: extractTones(theme.palettes.primary, tones),
+    secondary: extractTones(theme.palettes.secondary, tones),
+    tertiary: extractTones(theme.palettes.tertiary, tones),
+    neutral: extractTones(theme.palettes.neutral, tones),
+    neutralVariant: extractTones(theme.palettes.neutralVariant, tones),
+    error: extractTones(theme.palettes.error, tones),
+  };
+  
+  const schemes = {
+    light: formatScheme(theme.schemes.light),
+    dark: formatScheme(theme.schemes.dark),
+  };
+  
+  const output = {
+    sourceColor: SOURCE_COLOR,
+    palettes,
+    schemes,
+  };
+  
+  const outputPath = path.join(process.cwd(), 'tokens/generated-palette.json');
+  fs.writeFileSync(outputPath, JSON.stringify(output, null, 2));
+  
+  console.log('✅ Palette generated!');
+  console.log(`   Source: ${SOURCE_COLOR}`);
+  console.log(`   Output: ${outputPath}`);
+  console.log('');
+  console.log('🎨 Primary tones:');
+  Object.entries(palettes.primary).forEach(([tone, hex]) => {
+    console.log(`   ${tone}: ${hex}`);
+  });
+}
+
+function extractTones(palette: TonalPalette, tones: number[]) {
+  return Object.fromEntries(
+    tones.map(tone => [tone.toString(), hexFromArgb(palette.tone(tone))])
+  );
+}
+
+function formatScheme(scheme: any) {
+  const result: Record<string, string> = {};
+  for (const [key, value] of Object.entries(scheme)) {
+    if (typeof value === 'number') {
+      result[key] = hexFromArgb(value);
+    }
+  }
+  return result;
+}
+
+generatePalette();
+```
+
+### .storybook/main.ts
+
+```typescript
+import type { StorybookConfig } from '@storybook/react-vite';
+
+const config: StorybookConfig = {
+  stories: ['../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
+  addons: [
+    '@storybook/addon-essentials',
+    '@storybook/addon-a11y',
+  ],
+  framework: {
+    name: '@storybook/react-vite',
+    options: {},
+  },
+  docs: {
+    autodocs: 'tag',
+  },
+};
+
+export default config;
+```
+
+### .storybook/preview.ts
+
+```typescript
+import type { Preview } from '@storybook/react';
+import '../styled-system/styles.css';
+
+const preview: Preview = {
+  parameters: {
+    actions: { argTypesRegex: '^on[A-Z].*' },
+    controls: {
+      matchers: {
+        color: /(background|color)$/i,
+        date: /Date$/i,
+      },
+    },
+    backgrounds: {
+      default: 'surface',
+      values: [
+        { name: 'surface', value: '#F9FAEF' },
+        { name: 'dark', value: '#12140E' },
+      ],
+    },
+  },
+};
+
+export default preview;
+```
+
+### .npmrc
+
+```
+auto-install-peers=true
+strict-peer-dependencies=false
+```
+
+### .gitignore
+
+```
+# Dependencies
+node_modules/
+
+# Build outputs
+dist/
+styled-system/
+storybook-static/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+npm-debug.log*
+pnpm-debug.log*
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# Testing
+coverage/
+
+# Misc
+*.tgz
+```
+
+### vitest.config.ts
+
+```typescript
+import { defineConfig } from 'vitest/config';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+  test: {
+    environment: 'jsdom',
+    globals: true,
+    setupFiles: ['./src/test/setup.ts'],
+  },
+  resolve: {
+    alias: {
+      '@': './src',
+      'styled-system': './styled-system',
+    },
+  },
+});
+```
+
+### README.md
+
+```markdown
+# @discourser/design-system
+
+An aesthetic-agnostic design system built with Panda CSS and Ark UI.
+
+## Features
+
+- 🎨 **Swappable aesthetics** - Change the entire look by swapping one import
+- 🎯 **Zero runtime CSS** - SSR-safe with Panda CSS
+- ♿ **Accessible** - WAI-ARIA compliant via Ark UI
+- 📦 **Tree-shakeable** - Only import what you need
+- 🌙 **Dark mode** - Built-in light/dark theme support
+- 🎭 **Material Design 3** - M3 Expressive as default aesthetic
+
+## Installation
+
+\`\`\`bash
+pnpm add @discourser/design-system
+\`\`\`
+
+## Quick Start
+
+\`\`\`tsx
+import { Button } from '@discourser/design-system';
+import '@discourser/design-system/styled-system/styles.css';
+
+function App() {
+  return (
+    <Button variant="filled" size="md">
+      Click me
+    </Button>
+  );
+}
+\`\`\`
+
+## Development
+
+\`\`\`bash
+# Install dependencies
+pnpm install
+
+# Start Storybook
+pnpm dev
+
+# Build
+pnpm build
+
+# Generate color palette from source color
+pnpm tokens:generate
+
+# Run tests
+pnpm test
+\`\`\`
+
+## Architecture
+
+This design system uses a three-layer architecture:
+
+1. **Infrastructure** - Token pipeline, build system, component logic
+2. **Design Language** - Swappable aesthetic (colors, typography, spacing)
+3. **Component Recipes** - Visual styling derived from the language
+
+To change the aesthetic, edit `src/languages/index.ts` and point to a different language file.
+
+## License
+
+MIT
+```
+
+## Post-Setup Commands
+
+After Copilot creates all files, run:
+
+```bash
+# Install dependencies
+pnpm install
+
+# Generate Panda CSS output
+pnpm build:panda
+
+# Generate M3 palette from source color (optional - values already in language file)
+pnpm tokens:generate
+
+# Start Storybook to verify everything works
+pnpm dev
+```
+
+## Success Criteria
+
+1. ✅ `pnpm install` completes without errors
+2. ✅ `pnpm build:panda` generates `styled-system/` folder
+3. ✅ `pnpm dev` launches Storybook
+4. ✅ Button component renders with M3 styling
+5. ✅ All 5 button variants visible in Storybook
+6. ✅ `pnpm build` creates `dist/` with ESM/CJS outputs
+
+## Notes
+
+- The color values in `material3.language.ts` are placeholders based on chartreuse (#CDDC39)
+- Run `pnpm tokens:generate` to create accurate M3 tonal palettes
+- Typography uses Georgia (display) and Inter (body) - ensure fonts are loaded in consuming apps
+
+---
+
+## Implementation Phases
+
+This section outlines the phased approach to implementing the design system. Each phase builds on the previous one and includes validation gates.
+
+### Phase 0: Context Engineering Foundation
+
+**Goal:** Set up Claude Code Skills and CLAUDE.md for efficient AI-assisted development.
+
+**Deliverables:**
+```
+.claude/
+├── commands/
+│   ├── fix-foundation.md       # Phase 1 automation
+│   ├── implement-architecture.md # Phase 2 automation  
+│   └── new-component.md        # Component scaffolding
+└── skills/
+    ├── design-language/
+    │   └── SKILL.md            # Contract architecture knowledge
+    ├── panda-recipes/
+    │   └── SKILL.md            # Recipe patterns with M3
+    ├── m3-tokens/
+    │   └── SKILL.md            # M3 color values reference
+    └── component-patterns/
+        └── SKILL.md            # forwardRef, Ark UI patterns
+
+CLAUDE.md                       # Slim (<300 lines), pointer-based project context
+```
+
+**Validation:**
+- [ ] `/fix-foundation` command recognized in Claude Code
+- [ ] Skills auto-load when relevant tasks are requested
+
+---
+
+### Phase 1: Fix Foundation
+
+**Goal:** Establish correct dependencies, configuration, and build pipeline.
+
+**Tasks:**
+1. Update `package.json` with correct versions:
+    - `@ark-ui/react` ^4.4.0
+    - `@pandacss/dev` ^0.52.0
+    - `@material/material-color-utilities` ^0.3.0
+    - React 19, Storybook 8.5, Vitest 2.x
+2. Update `tsconfig.json` with path aliases
+3. Update `.gitignore` (add `styled-system/`, `storybook-static/`)
+4. Update `.npmrc` for peer dependency handling
+
+**Validation:**
+```bash
+pnpm install           # ✅ No errors
+pnpm build:panda       # ✅ Generates styled-system/
+pnpm dev               # ✅ Storybook starts
+```
+
+---
+
+### Phase 2: Architecture Implementation
+
+**Goal:** Implement the three-layer Contract → Language → Transform architecture.
+
+**Tasks:**
+1. Create `src/contracts/design-language.contract.ts`
+    - Full `DesignLanguageContract` interface
+    - All supporting types (ColorPalettes, SemanticColors, Typography, etc.)
+
+2. Create `src/languages/material3.language.ts`
+    - Implement `DesignLanguageContract`
+    - Use values from `docs/material-theme.json`
+    - Include `semantic` (light) and `semanticDark` (dark)
+
+3. Create `src/languages/transform.ts`
+    - `transformToPandaTheme(language)` function
+    - Returns `{ tokens, semanticTokens, textStyles }`
+
+4. Create `src/languages/index.ts`
+    - Export `material3Language as activeLanguage`
+    - Re-export transformer
+
+5. Update `panda.config.ts` to use the transform
+
+**Validation:**
+```bash
+pnpm build:panda       # ✅ No errors
+# Check styled-system/tokens/ contains M3 semantic colors
+```
+
+---
+
+### Phase 3: M3 Token Integration
+
+**Goal:** Integrate full M3 token set from Material Theme Builder export.
+
+**Tasks:**
+1. Verify `docs/material-theme.json` contains complete export
+2. Ensure all tonal palettes (primary, secondary, tertiary, neutral, neutralVariant, error) are in language file
+3. Ensure all semantic tokens are mapped for both light and dark
+4. Add typography scale (display, headline, title, body, label)
+5. Add spacing, shape (radii), elevation (shadows), motion (durations, easings)
+
+**Validation:**
+```bash
+pnpm build:panda
+# Verify in Storybook:
+# - Colors render correctly
+# - Typography scale works
+# - Dark mode toggles properly (data-theme="dark")
+```
+
+---
+
+### Phase 4: Complete Recipe Coverage + Testing
+
+**Goal:** Ensure all components use the recipe pattern with full M3 variant support and comprehensive test coverage.
+
+**Tasks:**
+
+#### 4.1 Input Recipe & Component
+```typescript
+// src/recipes/input.recipe.ts
+import { defineRecipe } from '@pandacss/dev';
+
+export const inputRecipe = defineRecipe({
+  className: 'input',
+  description: 'Material Design 3 text field component',
+  base: {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: 'xs',
+  },
+  variants: {
+    variant: {
+      filled: {
+        // M3 filled text field styling
+      },
+      outlined: {
+        // M3 outlined text field styling
+      },
+    },
+    size: {
+      sm: { /* ... */ },
+      md: { /* ... */ },
+    },
+    state: {
+      error: { /* ... */ },
+      disabled: { /* ... */ },
+    },
+  },
+  defaultVariants: {
+    variant: 'outlined',
+    size: 'md',
+  },
+});
+```
+
+```typescript
+// src/components/Input/Input.tsx
+import { forwardRef } from 'react';
+import { Field } from '@ark-ui/react';
+import { input, type InputVariantProps } from 'styled-system/recipes';
+import { cn } from '../../utils/cn';
+
+export interface InputProps
+  extends React.InputHTMLAttributes<HTMLInputElement>,
+    InputVariantProps {
+  label?: string;
+  helperText?: string;
+  errorText?: string;
+}
+
+export const Input = forwardRef<HTMLInputElement, InputProps>(
+  ({ label, helperText, errorText, variant, size, state, className, ...props }, ref) => {
+    const hasError = !!errorText || state === 'error';
+    
+    return (
+      <Field.Root invalid={hasError}>
+        {label && <Field.Label>{label}</Field.Label>}
+        <Field.Input
+          ref={ref}
+          className={cn(input({ variant, size, state: hasError ? 'error' : state }), className)}
+          {...props}
+        />
+        {helperText && !hasError && <Field.HelperText>{helperText}</Field.HelperText>}
+        {errorText && <Field.ErrorText>{errorText}</Field.ErrorText>}
+      </Field.Root>
+    );
+  }
+);
+
+Input.displayName = 'Input';
+```
+
+#### 4.2 Dialog Recipe & Component (Compound Pattern)
+```typescript
+// src/recipes/dialog.recipe.ts
+import { defineSlotRecipe } from '@pandacss/dev';
+
+export const dialogRecipe = defineSlotRecipe({
+  className: 'dialog',
+  description: 'Material Design 3 dialog component',
+  slots: ['backdrop', 'positioner', 'content', 'title', 'description', 'closeTrigger'],
+  base: {
+    backdrop: {
+      position: 'fixed',
+      inset: 0,
+      bg: 'scrim',
+      opacity: 0.32,
+      zIndex: 'modal',
+    },
+    positioner: {
+      position: 'fixed',
+      inset: 0,
+      display: 'flex',
+      alignItems: 'center',
+      justifyContent: 'center',
+      zIndex: 'modal',
+    },
+    content: {
+      bg: 'surfaceContainerHigh',
+      borderRadius: 'extraLarge',
+      p: 'lg',
+      shadow: 'level3',
+      maxWidth: '560px',
+      minWidth: '280px',
+    },
+    title: {
+      textStyle: 'headlineSmall',
+      color: 'onSurface',
+      mb: 'md',
+    },
+    description: {
+      textStyle: 'bodyMedium',
+      color: 'onSurfaceVariant',
+    },
+    closeTrigger: {
+      position: 'absolute',
+      top: 'md',
+      right: 'md',
+    },
+  },
+  variants: {
+    size: {
+      sm: {
+        content: { maxWidth: '400px' },
+      },
+      md: {
+        content: { maxWidth: '560px' },
+      },
+      lg: {
+        content: { maxWidth: '720px' },
+      },
+      fullscreen: {
+        content: {
+          maxWidth: '100vw',
+          maxHeight: '100vh',
+          borderRadius: 'none',
+          m: 0,
+        },
+      },
+    },
+  },
+  defaultVariants: {
+    size: 'md',
+  },
+});
+```
+
+```typescript
+// src/components/Dialog/Dialog.tsx
+import { forwardRef } from 'react';
+import { Dialog as ArkDialog } from '@ark-ui/react';
+import { dialog, type DialogVariantProps } from 'styled-system/recipes';
+import { cn } from '../../utils/cn';
+
+const styles = dialog();
+
+export interface DialogProps extends ArkDialog.RootProps, DialogVariantProps {}
+
+const DialogRoot = (props: DialogProps) => <ArkDialog.Root {...props} />;
+
+const DialogTrigger = forwardRef<HTMLButtonElement, ArkDialog.TriggerProps>(
+  ({ className, ...props }, ref) => (
+    <ArkDialog.Trigger ref={ref} className={className} {...props} />
+  )
+);
+DialogTrigger.displayName = 'DialogTrigger';
+
+const DialogBackdrop = forwardRef<HTMLDivElement, ArkDialog.BackdropProps>(
+  ({ className, ...props }, ref) => (
+    <ArkDialog.Backdrop ref={ref} className={cn(styles.backdrop, className)} {...props} />
+  )
+);
+DialogBackdrop.displayName = 'DialogBackdrop';
+
+const DialogPositioner = forwardRef<HTMLDivElement, ArkDialog.PositionerProps>(
+  ({ className, ...props }, ref) => (
+    <ArkDialog.Positioner ref={ref} className={cn(styles.positioner, className)} {...props} />
+  )
+);
+DialogPositioner.displayName = 'DialogPositioner';
+
+const DialogContent = forwardRef<HTMLDivElement, ArkDialog.ContentProps>(
+  ({ className, ...props }, ref) => (
+    <ArkDialog.Content ref={ref} className={cn(styles.content, className)} {...props} />
+  )
+);
+DialogContent.displayName = 'DialogContent';
+
+const DialogTitle = forwardRef<HTMLHeadingElement, ArkDialog.TitleProps>(
+  ({ className, ...props }, ref) => (
+    <ArkDialog.Title ref={ref} className={cn(styles.title, className)} {...props} />
+  )
+);
+DialogTitle.displayName = 'DialogTitle';
+
+const DialogDescription = forwardRef<HTMLParagraphElement, ArkDialog.DescriptionProps>(
+  ({ className, ...props }, ref) => (
+    <ArkDialog.Description ref={ref} className={cn(styles.description, className)} {...props} />
+  )
+);
+DialogDescription.displayName = 'DialogDescription';
+
+const DialogCloseTrigger = forwardRef<HTMLButtonElement, ArkDialog.CloseTriggerProps>(
+  ({ className, ...props }, ref) => (
+    <ArkDialog.CloseTrigger ref={ref} className={cn(styles.closeTrigger, className)} {...props} />
+  )
+);
+DialogCloseTrigger.displayName = 'DialogCloseTrigger';
+
+export const Dialog = {
+  Root: DialogRoot,
+  Trigger: DialogTrigger,
+  Backdrop: DialogBackdrop,
+  Positioner: DialogPositioner,
+  Content: DialogContent,
+  Title: DialogTitle,
+  Description: DialogDescription,
+  CloseTrigger: DialogCloseTrigger,
+};
+```
+
+#### 4.3 Register All Recipes
+```typescript
+// panda.config.ts - update theme.extend.recipes
+recipes: {
+  button: buttonRecipe,
+  card: cardRecipe,
+  iconButton: iconButtonRecipe,
+  input: inputRecipe,
+},
+slotRecipes: {
+  dialog: dialogRecipe,
+},
+```
+
+#### 4.4 Component Testing Requirements
+
+Every component MUST have accompanying tests. Create test files alongside components.
+
+**Install test dependencies:**
+```bash
+pnpm add -D @testing-library/react @testing-library/jest-dom @testing-library/user-event jest-axe
+```
+
+**Test Setup:**
+```typescript
+// src/test/setup.ts
+import '@testing-library/jest-dom';
+import { vi } from 'vitest';
+
+// Mock matchMedia for components that use media queries
+Object.defineProperty(window, 'matchMedia', {
+  writable: true,
+  value: vi.fn().mockImplementation(query => ({
+    matches: false,
+    media: query,
+    onchange: null,
+    addListener: vi.fn(),
+    removeListener: vi.fn(),
+    addEventListener: vi.fn(),
+    removeEventListener: vi.fn(),
+    dispatchEvent: vi.fn(),
+  })),
+});
+```
+
+**Input Component Tests:**
+```typescript
+// src/components/Input/Input.test.tsx
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { describe, it, expect, vi } from 'vitest';
+import { Input } from './Input';
+
+describe('Input', () => {
+  it('renders with label', () => {
+    render(<Input label="Email" />);
+    expect(screen.getByLabelText('Email')).toBeInTheDocument();
+  });
+
+  it('shows error state', () => {
+    render(<Input label="Email" errorText="Invalid email" />);
+    expect(screen.getByText('Invalid email')).toBeInTheDocument();
+  });
+
+  it('calls onChange when typing', async () => {
+    const user = userEvent.setup();
+    const handleChange = vi.fn();
+    render(<Input label="Email" onChange={handleChange} />);
+    
+    await user.type(screen.getByLabelText('Email'), 'test@example.com');
+    expect(handleChange).toHaveBeenCalled();
+  });
+
+  it('renders all variants', () => {
+    const { rerender } = render(<Input variant="outlined" label="Test" />);
+    expect(screen.getByLabelText('Test')).toBeInTheDocument();
+    
+    rerender(<Input variant="filled" label="Test" />);
+    expect(screen.getByLabelText('Test')).toBeInTheDocument();
+  });
+
+  it('is disabled when disabled prop is true', () => {
+    render(<Input label="Email" disabled />);
+    expect(screen.getByLabelText('Email')).toBeDisabled();
+  });
+});
+```
+
+**Dialog Component Tests:**
+```typescript
+// src/components/Dialog/Dialog.test.tsx
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { describe, it, expect } from 'vitest';
+import { Dialog } from './Dialog';
+import { Button } from '../Button';
+
+describe('Dialog', () => {
+  it('opens when trigger is clicked', async () => {
+    const user = userEvent.setup();
+    render(
+      <Dialog.Root>
+        <Dialog.Trigger asChild>
+          <Button>Open</Button>
+        </Dialog.Trigger>
+        <Dialog.Backdrop />
+        <Dialog.Positioner>
+          <Dialog.Content>
+            <Dialog.Title>Test Dialog</Dialog.Title>
+            <Dialog.Description>Test content</Dialog.Description>
+          </Dialog.Content>
+        </Dialog.Positioner>
+      </Dialog.Root>
+    );
+
+    await user.click(screen.getByText('Open'));
+    await waitFor(() => {
+      expect(screen.getByText('Test Dialog')).toBeInTheDocument();
+    });
+  });
+
+  it('closes when close trigger is clicked', async () => {
+    const user = userEvent.setup();
+    render(
+      <Dialog.Root defaultOpen>
+        <Dialog.Backdrop />
+        <Dialog.Positioner>
+          <Dialog.Content>
+            <Dialog.Title>Test Dialog</Dialog.Title>
+            <Dialog.CloseTrigger>Close</Dialog.CloseTrigger>
+          </Dialog.Content>
+        </Dialog.Positioner>
+      </Dialog.Root>
+    );
+
+    await user.click(screen.getByText('Close'));
+    await waitFor(() => {
+      expect(screen.queryByText('Test Dialog')).not.toBeInTheDocument();
+    });
+  });
+
+  it('traps focus within dialog', async () => {
+    const user = userEvent.setup();
+    render(
+      <Dialog.Root defaultOpen>
+        <Dialog.Backdrop />
+        <Dialog.Positioner>
+          <Dialog.Content>
+            <Dialog.Title>Test Dialog</Dialog.Title>
+            <Button>First</Button>
+            <Button>Second</Button>
+            <Dialog.CloseTrigger>Close</Dialog.CloseTrigger>
+          </Dialog.Content>
+        </Dialog.Positioner>
+      </Dialog.Root>
+    );
+
+    await user.tab();
+    expect(screen.getByText('First')).toHaveFocus();
+    
+    await user.tab();
+    expect(screen.getByText('Second')).toHaveFocus();
+  });
+});
+```
+
+**Validation:**
+```bash
+pnpm build:panda       # ✅ All recipes generate
+pnpm dev               # ✅ All components render in Storybook
+pnpm test              # ✅ All component tests pass
+```
+
+---
+
+### Phase 5: Ark UI Integration + Accessibility Testing
+
+**Goal:** Ensure all components properly leverage Ark UI for accessibility and state management, with comprehensive accessibility tests.
+
+**Tasks:**
+
+#### 5.1 Audit Current Components
+Review each component and ensure it uses Ark UI primitives where applicable:
+
+| Component | Current | Target |
+|-----------|---------|--------|
+| Button | `<button>` | `<Ark.Button>` or keep native (simple) |
+| Card | `<div>` | Keep native (no interaction state) |
+| IconButton | `<button>` | `<Ark.Button>` |
+| Input | Native | `<Field.Root>`, `<Field.Input>`, etc. |
+| Dialog | N/A | Full Ark Dialog compound |
+
+#### 5.2 Implement Missing Ark UI Patterns
+
+**Button with Ark UI:**
+```typescript
+// src/components/Button/Button.tsx
+import { Button as ArkButton } from '@ark-ui/react';
+
+export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
+  ({ children, variant, size, leftIcon, rightIcon, className, ...props }, ref) => {
+    return (
+      <ArkButton
+        ref={ref}
+        className={cn(button({ variant, size }), className)}
+        {...props}
+      >
+        {leftIcon}
+        {children}
+        {rightIcon}
+      </ArkButton>
+    );
+  }
+);
+```
+
+#### 5.3 Add Additional Ark UI Components
+
+Consider adding these M3 components using Ark UI:
+- **Menu** - `@ark-ui/react` Menu
+- **Tabs** - `@ark-ui/react` Tabs
+- **Tooltip** - `@ark-ui/react` Tooltip
+- **Switch** - `@ark-ui/react` Switch
+- **Checkbox** - `@ark-ui/react` Checkbox
+- **Select** - `@ark-ui/react` Select
+
+#### 5.4 Accessibility Testing
+
+Every component MUST include accessibility tests using jest-axe:
+
+```typescript
+// src/components/Button/Button.a11y.test.tsx
+import { axe, toHaveNoViolations } from 'jest-axe';
+import { render } from '@testing-library/react';
+import { Button } from './Button';
+
+expect.extend(toHaveNoViolations);
+
+describe('Button accessibility', () => {
+  it('has no accessibility violations', async () => {
+    const { container } = render(<Button>Click me</Button>);
+    const results = await axe(container);
+    expect(results).toHaveNoViolations();
+  });
+
+  it('has no violations when disabled', async () => {
+    const { container } = render(<Button disabled>Disabled</Button>);
+    const results = await axe(container);
+    expect(results).toHaveNoViolations();
+  });
+
+  it('has no violations for all variants', async () => {
+    const variants = ['filled', 'outlined', 'text', 'elevated', 'tonal'] as const;
+    
+    for (const variant of variants) {
+      const { container } = render(<Button variant={variant}>Test</Button>);
+      const results = await axe(container);
+      expect(results).toHaveNoViolations();
+    }
+  });
+});
+```
+
+```typescript
+// src/components/Dialog/Dialog.a11y.test.tsx
+import { axe, toHaveNoViolations } from 'jest-axe';
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { Dialog } from './Dialog';
+import { Button } from '../Button';
+
+expect.extend(toHaveNoViolations);
+
+describe('Dialog accessibility', () => {
+  it('has no accessibility violations when open', async () => {
+    const { container } = render(
+      <Dialog.Root defaultOpen>
+        <Dialog.Backdrop />
+        <Dialog.Positioner>
+          <Dialog.Content>
+            <Dialog.Title>Accessible Dialog</Dialog.Title>
+            <Dialog.Description>This dialog should be accessible.</Dialog.Description>
+            <Dialog.CloseTrigger>Close</Dialog.CloseTrigger>
+          </Dialog.Content>
+        </Dialog.Positioner>
+      </Dialog.Root>
+    );
+    
+    const results = await axe(container);
+    expect(results).toHaveNoViolations();
+  });
+
+  it('has proper aria attributes', async () => {
+    render(
+      <Dialog.Root defaultOpen>
+        <Dialog.Backdrop />
+        <Dialog.Positioner>
+          <Dialog.Content>
+            <Dialog.Title>Test Title</Dialog.Title>
+            <Dialog.Description>Test Description</Dialog.Description>
+          </Dialog.Content>
+        </Dialog.Positioner>
+      </Dialog.Root>
+    );
+
+    const dialog = screen.getByRole('dialog');
+    expect(dialog).toHaveAttribute('aria-labelledby');
+    expect(dialog).toHaveAttribute('aria-describedby');
+  });
+});
+```
+
+**Validation:**
+```bash
+pnpm dev               # ✅ Components work correctly
+# Test keyboard navigation in Storybook
+# Test screen reader announcements
+pnpm test              # ✅ All tests pass (unit + a11y)
+```
+
+---
+
+### Phase 6: Build & Package (Figma Make Compatible)
+
+**Goal:** Create a publishable npm package compatible with Figma Make (Vite-based) with proper exports, types, and documentation.
+
+**Requirements from Figma Make (https://developers.figma.com/docs/code/bring-your-design-system-package/):**
+- ✅ React 18+ (we use React 19)
+- ✅ Compatible with Vite
+- ✅ Published as npm package (public or private)
+
+**Tasks:**
+
+#### 6.1 Verify Vite Compatibility
+
+Figma Make uses Vite as its build system. Test package compatibility:
+
+```bash
+# Create a test Vite project
+npm create vite@latest make-test-app -- --template react-ts
+cd make-test-app
+
+# Install your local package
+pnpm add ../path/to/tastymakers-design-system-0.1.0.tgz
+
+# Test the import
+cat > src/App.tsx << 'EOF'
+import { Button, Card } from '@discourser/design-system';
+import '@discourser/design-system/styles.css';
+
+function App() {
+  return (
+    <Card>
+      <Button variant="filled">Test Button</Button>
+    </Card>
+  );
+}
+export default App;
+EOF
+
+# Build - must succeed for Figma Make compatibility
+pnpm build
+```
+
+#### 6.2 Verify tsup Configuration
+```typescript
+// tsup.config.ts
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'],
+  dts: true,
+  splitting: true,
+  sourcemap: true,
+  clean: true,
+  external: ['react', 'react-dom'],
+  esbuildOptions(options) {
+    options.banner = {
+      js: '"use client"',
+    };
+  },
+});
+```
+
+#### 6.3 Verify Package Exports
+```json
+// package.json exports field
+{
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    },
+    "./styles.css": "./styled-system/styles.css",
+    "./styled-system": {
+      "import": "./styled-system/index.mjs",
+      "require": "./styled-system/index.js"
+    },
+    "./styled-system/css": {
+      "import": "./styled-system/css/index.mjs",
+      "require": "./styled-system/css/index.js"
+    },
+    "./styled-system/tokens": {
+      "import": "./styled-system/tokens/index.mjs",
+      "require": "./styled-system/tokens/index.js"
+    },
+    "./styled-system/recipes": {
+      "import": "./styled-system/recipes/index.mjs",
+      "require": "./styled-system/recipes/index.js"
+    }
+  }
+}
+```
+
+#### 6.4 Add CI/CD Workflows
+
+```yaml
+# .github/workflows/ci.yml
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v2
+        with:
+          version: 8
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'pnpm'
+      - run: pnpm install
+      - run: pnpm typecheck
+      - run: pnpm build:panda
+      - run: pnpm build
+      - run: pnpm test
+
+  vite-compatibility:
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v2
+        with:
+          version: 8
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'pnpm'
+      - run: pnpm install
+      - run: pnpm build
+      - run: pnpm pack
+      - name: Test Vite Compatibility
+        run: |
+          npm create vite@latest test-app -- --template react-ts
+          cd test-app
+          npm install ../tastymakers-design-system-*.tgz
+          npm run build
+```
+
+```yaml
+# .github/workflows/publish.yml
+name: Publish
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v2
+        with:
+          version: 8
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: 'https://registry.npmjs.org'
+      - run: pnpm install
+      - run: pnpm build
+      - run: pnpm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.
+             }}
+```
+
+#### 6.5 Create npm Organization
+
+Before publishing, create the `@discourser` npm organization:
+
+1. Go to https://www.npmjs.com/org/create
+2. Create organization with name `discourser`
+3. Choose "Unlimited public packages" (free tier)
+4. Verify organization exists at https://www.npmjs.com/org/discourser
+
+**Note:** npm allows multiple organizations per user account.
+
+#### 6.6 Configure npm Authentication Locally
+
+```bash
+# Login to npm (if not already)
+npm login
+
+# Verify you can publish to the org
+npm access ls-packages @discourser
+```
+
+#### 6.7 Install & Configure Changesets
+
+Changesets provides automated versioning and changelog generation.
+
+**Install dependencies:**
+```bash
+pnpm add -D @changesets/cli @changesets/changelog-github
+pnpm changeset init
+```
+
+**Configure `.changeset/config.json`:**
+```json
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.0.0/schema.json",
+  "changelog": [
+    "@changesets/changelog-github",
+    { "repo": "Tasty-Maker-Studio/Discourser-Design-System" }
+  ],
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}
+```
+
+**Create `.changeset/README.md`:**
+```markdown
+# Changesets
+
+Hello and welcome! This folder has been automatically generated by `@changesets/cli`.
+
+## How to add a changeset
+
+1. Run `pnpm changeset`
+2. Select the type of change (patch/minor/major)
+3. Write a summary of the change
+4. Commit the generated changeset file
+
+Changesets are automatically consumed when the "Version Packages" PR is merged.
+```
+
+**Create `CHANGELOG.md` (root):**
+```markdown
+# @discourser/design-system
+
+## Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+```
+
+**Update `package.json`:**
+```json
+{
+  "name": "@discourser/design-system",
+  "version": "0.0.0",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Tasty-Maker-Studio/Discourser-Design-System.git"
+  },
+  "scripts": {
+    "changeset": "changeset",
+    "version": "changeset version",
+    "release": "pnpm build && changeset publish"
+  }
+}
+```
+
+**Validation:**
+```bash
+pnpm changeset          # ✅ Interactive prompt works
+pnpm changeset status   # ✅ Shows no changesets (or lists pending)
+```
+
+#### 6.8 Create CI Workflow
+
+Create `.github/workflows/ci.yml`:
+
+```yaml
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build & Test
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v2
+        with:
+          version: 9
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Typecheck
+        run: pnpm typecheck
+
+      - name: Build Panda CSS
+        run: pnpm build:panda
+
+      - name: Build library
+        run: pnpm build:lib
+
+      - name: Run tests
+        run: pnpm test
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: build-output
+          path: |
+            dist/
+            styled-system/
+          retention-days: 1
+
+  vite-compatibility:
+    name: Vite Compatibility
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v2
+        with:
+          version: 9
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build package
+        run: pnpm build
+
+      - name: Create tarball
+        run: pnpm pack
+
+      - name: Test Vite compatibility
+        run: |
+          # Create test Vite app
+          npm create vite@latest test-app -- --template react-ts
+          cd test-app
+          
+          # Install the local package
+          npm install ../discourser-design-system-*.tgz
+          
+          # Create test file
+          cat > src/App.tsx << 'EOF'
+          import { Button } from '@discourser/design-system';
+          import '@discourser/design-system/styles.css';
+          
+          function App() {
+            return <Button variant="filled">Test</Button>;
+          }
+          export default App;
+          EOF
+          
+          # Build must succeed
+          npm run build
+```
+
+#### 6.9 Create Release Workflow
+
+Create `.github/workflows/release.yml`:
+
+```yaml
+name: Release
+
+on:
+  push:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v2
+        with:
+          version: 9
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'pnpm'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build
+        run: pnpm build
+
+      - name: Create Release Pull Request or Publish
+        id: changesets
+        uses: changesets/action@v1
+        with:
+          version: pnpm changeset version
+          publish: pnpm release
+          commit: "chore: version packages"
+          title: "chore: version packages"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Create Git Tag
+        if: steps.changesets.outputs.published == 'true'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          
+          # Get the version from package.json
+          VERSION=$(node -p "require('./package.json').version")
+          
+          # Create and push tag
+          git tag -a "v$VERSION" -m "Release v$VERSION"
+          git push origin "v$VERSION"
+```
+
+#### 6.10 Configure GitHub Secrets & Permissions (MANUAL)
+
+This step requires manual configuration in the GitHub repository settings.
+
+**Step 1: Generate npm Token**
+
+1. Go to https://www.npmjs.com/settings/YOUR_USERNAME/tokens
+2. Click "Generate New Token" → "Classic Token"
+3. Select "Automation" type
+4. Copy the generated token (starts with `npm_`)
+
+**Step 2: Add Secret to GitHub**
+
+1. Go to repository: https://github.com/Tasty-Maker-Studio/Discourser-Design-System
+2. Navigate to Settings → Secrets and variables → Actions
+3. Click "New repository secret"
+4. Name: `NPM_TOKEN`
+5. Value: Paste the npm token
+6. Click "Add secret"
+
+**Step 3: Configure Workflow Permissions**
+
+1. Go to Settings → Actions → General
+2. Scroll to "Workflow permissions"
+3. Select "Read and write permissions"
+4. Check "Allow GitHub Actions to create and approve pull requests"
+5. Click "Save"
+
+**Validation Checklist:**
+- [ ] NPM_TOKEN secret is configured
+- [ ] Workflow permissions allow write access
+- [ ] Workflow permissions allow PR creation
+
+#### 6.11 Validate Full Release Pipeline
+
+Test the complete release workflow end-to-end.
+
+**Step 1: Create a Test Changeset**
+```bash
+pnpm changeset
+
+# Select: patch
+# Summary: "Initial release - Button, Card, IconButton components"
+# This creates a file in .changeset/ like `funny-dogs-dance.md`
+```
+
+**Step 2: Commit and Push**
+```bash
+git add .
+git commit -m "chore: add changeset for initial release"
+git push origin main
+```
+
+**Step 3: Verify CI Workflow**
+1. Go to https://github.com/Tasty-Maker-Studio/Discourser-Design-System/actions
+2. Verify "CI" workflow passes (build, test, vite-compatibility)
+
+**Step 4: Verify Release Workflow**
+1. After CI passes, "Release" workflow should run
+2. It should create a PR titled "chore: version packages"
+
+**Step 5: Review Version Packages PR**
+The PR should contain:
+- `package.json`: version bumped from `0.0.0` to `0.0.1`
+- `CHANGELOG.md`: Updated with changeset content
+- Changeset file deleted from `.changeset/`
+
+**Step 6: Merge and Publish**
+1. Review the PR
+2. Merge to main
+3. Release workflow runs again and publishes to npm
+
+**Step 7: Verify npm Publication**
+```bash
+# Check package exists
+npm view @discourser/design-system
+
+# Or visit
+# https://www.npmjs.com/package/@discourser/design-system
+```
+
+**Complete Release Flow Diagram:**
+```
+Developer: pnpm changeset → Creates .changeset/*.md
+     ↓
+Git push to main
+     ↓
+CI Workflow: Build, Test, Vite Compatibility
+     ↓
+Release Workflow: Detects changesets → Creates "Version Packages" PR
+     ↓
+Human: Reviews and merges PR
+     ↓
+Release Workflow: Runs again → Publishes to npm + Creates git tag
+     ↓
+Package available at npmjs.com
+```
+
+**Validation:**
+```bash
+# After full pipeline test:
+npm view @discourser/design-system          # ✅ Package exists
+npm view @discourser/design-system versions # ✅ Shows 0.0.1
+```
+
+#### 6.12 Test Local Package (Manual Verification)
+
+For local testing before committing:
+
+```bash
+# Build the package
+pnpm build
+
+# Create a tarball
+pnpm pack
+
+# In a separate test Vite project
+npm create vite@latest make-test-app -- --template react-ts
+cd make-test-app
+pnpm add ../path/to/discourser-design-system-0.0.1.tgz
+pnpm build  # Must succeed for Figma Make compatibility
+```
+
+**Phase 6 Validation Summary:**
+```bash
+pnpm build             # ✅ Creates dist/ with ESM, CJS, and .d.ts
+pnpm pack              # ✅ Creates tarball
+pnpm test              # ✅ All tests pass
+pnpm changeset         # ✅ Interactive prompt works
+# CI workflow passes    # ✅ Build + Test + Vite compatibility
+# Release workflow      # ✅ Creates Version Packages PR
+# npm publish           # ✅ Package available on npmjs.com
+```
+
+---
+
+### Phase 7: Figma Make Guidelines
+
+**Goal:** Create guidelines that teach Figma Make how to use the design system package, following the [Figma documentation](https://developers.figma.com/docs/code/write-design-system-guidelines/).
+
+**Background:** Figma Make's AI can inspect your package but works best with explicit guidelines. This is similar to documentation you'd give a new engineer.
+
+**Tasks:**
+
+#### 7.1 Create Guidelines Structure
+
+```
+guidelines/
+├── Guidelines.md              # Top-level entry point (ALWAYS read first)
+├── overview-components.md     # Component catalog and usage patterns
+├── overview-icons.md          # Icon usage (if applicable)
+├── design-tokens/
+│   ├── colors.md              # Semantic color tokens
+│   ├── typography.md          # Typography scale
+│   ├── spacing.md             # Spacing tokens
+│   └── elevation.md           # Shadow/elevation tokens
+└── components/
+    ├── button.md
+    ├── card.md
+    ├── icon-button.md
+    ├── input.md
+    ├── dialog.md
+    └── [additional components].md
+```
+
+#### 7.2 Create Guidelines.md (Entry Point)
+
+```markdown
+<!-- guidelines/Guidelines.md -->
+# TastyMakers Design System Guidelines
+
+This project uses the `@discourser/design-system` package, a Material Design 3 implementation built with Panda CSS and Ark UI.
+
+## IMPORTANT: Always Read These First
+
+Before writing any code, follow these steps IN ORDER:
+
+### Step 1: Read Overview Files (REQUIRED)
+Read ALL files with a name that starts with "overview-":
+- `overview-components.md` - Available components and usage patterns
+- `overview-icons.md` - Icon usage (if applicable)
+
+### Step 2: Read Design Token Files (REQUIRED)
+Read ALL files in the `design-tokens/` folder:
+- `design-tokens/colors.md`
+- `design-tokens/typography.md`
+- `design-tokens/spacing.md`
+- `design-tokens/elevation.md`
+
+### Step 3: Plan Components Needed (REQUIRED)
+Identify which components you need to use.
+
+### Step 4: Read Component Guidelines BEFORE Using Components (REQUIRED)
+BEFORE using ANY component, you MUST read its guidelines file first:
+- Using Button? → Read `components/button.md` FIRST
+- Using Dialog? → Read `components/dialog.md` FIRST
+- Using Input? → Read `components/input.md` FIRST
+- Using Card? → Read `components/card.md` FIRST
+
+DO NOT write code using a component until you have read its specific guidelines.
+
+## Core Principles
+
+- **Always prefer design system components** over native HTML elements
+- **Use semantic tokens** (e.g., `primary`, `onPrimary`) not raw colors
+- **Follow M3 patterns** for variants, sizing, and state layers
+- **Do not override styles** unless absolutely necessary
+
+## Package Imports
+
+\`\`\`typescript
+// Components
+import { Button, Card, Dialog, Input, IconButton } from '@discourser/design-system';
+
+// Styles (REQUIRED - must be imported)
+import '@discourser/design-system/styles.css';
+\`\`\`
+
+## Quick Reference
+
+| Component | Variants | Sizes | Guidelines |
+|-----------|----------|-------|------------|
+| Button | filled, outlined, text, elevated, tonal | sm, md, lg | `components/button.md` |
+| Card | elevated, filled, outlined | - | `components/card.md` |
+| IconButton | standard, filled, tonal, outlined | sm, md, lg | `components/icon-button.md` |
+| Input | filled, outlined | sm, md | `components/input.md` |
+| Dialog | - | sm, md, lg, fullscreen | `components/dialog.md` |
+```
+
+#### 7.3 Create overview-components.md
+
+```markdown
+<!-- guidelines/overview-components.md -->
+# Components Overview
+
+Always prefer components from `@discourser/design-system` if available. Do not use native HTML elements when a design system component exists.
+
+## Available Components
+
+| Component | Purpose | Guidelines |
+|-----------|---------|------------|
+| Button | Primary interactive element for actions | [button.md](components/button.md) |
+| Card | Container for related content | [card.md](components/card.md) |
+| IconButton | Icon-only interactive element | [icon-button.md](components/icon-button.md) |
+| Input | Text input with label and validation | [input.md](components/input.md) |
+| Dialog | Modal overlay for focused tasks | [dialog.md](components/dialog.md) |
+
+## Common Props
+
+Most components accept:
+- `variant` - Visual style variant (e.g., filled, outlined)
+- `size` - Size variant (sm, md, lg)
+- `disabled` - Disable interaction
+- `className` - Additional CSS classes (use sparingly)
+
+## Styling Guidelines
+
+**✅ DO:**
+\`\`\`typescript
+<Button variant="filled" size="md">Submit</Button>
+<Card variant="elevated">Content</Card>
+<Input variant="outlined" label="Email" />
+\`\`\`
+
+**❌ DO NOT:**
+\`\`\`typescript
+// Don't override styles with inline styles
+<Button style={{ backgroundColor: 'blue' }}>Submit</Button>
+
+// Don't use raw HTML when components exist
+<button className="...">Submit</button>
+<input type="text" />
+
+// Don't use raw color values
+<div style={{ backgroundColor: '#4C662B' }}>...</div>
+\`\`\`
+
+## Controlled vs Uncontrolled
+
+- **Controlled**: Component receives `value` and `onChange` props
+- **Uncontrolled**: Component manages own state, use `defaultValue`
+- Prefer controlled for form components
+```
+
+#### 7.4 Create Design Token Guidelines
+
+```markdown
+<!-- guidelines/design-tokens/colors.md -->
+# Color Tokens
+
+The design system uses Material Design 3 semantic color tokens. Always use semantic tokens, never raw hex values.
+
+## Semantic Colors (Light Theme)
+
+### Primary
+| Token | Usage | Example Value |
+|-------|-------|---------------|
+| `primary` | Primary actions, buttons, links | #4C662B |
+| `onPrimary` | Text/icons on primary backgrounds | #FFFFFF |
+| `primaryContainer` | Primary container backgrounds | #CDEDA3 |
+| `onPrimaryContainer` | Text/icons on primary container | #354E16 |
+
+### Secondary
+| Token | Usage |
+|-------|-------|
+| `secondary` | Secondary actions |
+| `onSecondary` | Text/icons on secondary |
+| `secondaryContainer` | Secondary container backgrounds |
+| `onSecondaryContainer` | Text/icons on secondary container |
+
+### Surface
+| Token | Usage |
+|-------|-------|
+| `surface` | Default background |
+| `onSurface` | Default text color |
+| `surfaceVariant` | Alternate surface |
+| `onSurfaceVariant` | Text on variant surfaces |
+| `surfaceContainerLowest` | Lowest elevation |
+| `surfaceContainerLow` | Low elevation (cards) |
+| `surfaceContainer` | Default containers |
+| `surfaceContainerHigh` | Dialogs, elevated content |
+| `surfaceContainerHighest` | Highest elevation |
+
+### Error
+| Token | Usage |
+|-------|-------|
+| `error` | Error states |
+| `onError` | Text/icons on error |
+| `errorContainer` | Error container backgrounds |
+| `onErrorContainer` | Text/icons on error container |
+
+### Other
+| Token | Usage |
+|-------|-------|
+| `outline` | Borders, dividers |
+| `outlineVariant` | Subtle borders |
+| `scrim` | Modal overlays |
+| `shadow` | Shadow color |
+
+## Usage in Components
+
+Colors are applied automatically through component variants:
+
+\`\`\`typescript
+// ✅ Correct - uses semantic tokens internally
+<Button variant="filled">Primary Action</Button>
+
+// ❌ Wrong - don't apply colors directly
+<Button style={{ backgroundColor: '#4C662B' }}>Primary</Button>
+\`\`\`
+
+## Dark Mode
+
+The design system supports dark mode via `data-theme="dark"` on a parent element. Semantic tokens automatically adjust.
+```
+
+```markdown
+<!-- guidelines/design-tokens/typography.md -->
+# Typography Tokens
+
+The design system uses M3 typography scale with semantic naming.
+
+## Font Families
+
+| Token | Font | Usage |
+|-------|------|-------|
+| `display` | Georgia, serif | Display text, headings |
+| `body` | Inter, sans-serif | Body text, UI elements |
+| `mono` | JetBrains Mono | Code snippets |
+
+## Type Scale
+
+### Display (for hero sections, large text)
+- `displayLarge` - 57px
+- `displayMedium` - 45px
+- `displaySmall` - 36px
+
+### Headline (for page/section headers)
+- `headlineLarge` - 32px
+- `headlineMedium` - 28px
+- `headlineSmall` - 24px
+
+### Title (for card titles, dialogs)
+- `titleLarge` - 22px
+- `titleMedium` - 16px
+- `titleSmall` - 14px
+
+### Body (for content)
+- `bodyLarge` - 16px (primary body text)
+- `bodyMedium` - 14px (default body text)
+- `bodySmall` - 12px (secondary text)
+
+### Label (for buttons, form labels)
+- `labelLarge` - 14px (button text)
+- `labelMedium` - 12px (form labels)
+- `labelSmall` - 11px (badges)
+
+## Usage
+
+Typography is applied through `textStyle` in Panda CSS:
+
+\`\`\`typescript
+import { css } from 'styled-system/css';
+
+const heading = css({ textStyle: 'headlineMedium' });
+const body = css({ textStyle: 'bodyMedium' });
+\`\`\`
+```
+
+#### 7.5 Create Component Guidelines
+
+```markdown
+<!-- guidelines/components/button.md -->
+# Button
+
+**Purpose:** Primary interactive element for user actions.
+
+## Import
+
+\`\`\`typescript
+import { Button } from '@discourser/design-system';
+\`\`\`
+
+## Variants
+
+| Variant | Usage | When to Use |
+|---------|-------|-------------|
+| `filled` | Primary actions | Submit, Confirm, Main CTA |
+| `outlined` | Secondary actions | Cancel, Back, Alternative options |
+| `text` | Tertiary actions | Links, Less prominent actions |
+| `elevated` | Floating actions | FAB-like buttons |
+| `tonal` | Medium emphasis | Secondary CTA, Soft highlight |
+
+## Sizes
+
+| Size | Height | Usage |
+|------|--------|-------|
+| `sm` | 32px | Compact UI, dense layouts |
+| `md` | 40px | Default, most use cases |
+| `lg` | 48px | Touch targets, mobile emphasis |
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `'filled' \| 'outlined' \| 'text' \| 'elevated' \| 'tonal'` | `'filled'` | Visual style |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Button size |
+| `disabled` | `boolean` | `false` | Disable button |
+| `leftIcon` | `ReactNode` | - | Icon before text |
+| `rightIcon` | `ReactNode` | - | Icon after text |
+
+## Examples
+
+\`\`\`typescript
+// Primary action
+<Button variant="filled">Submit</Button>
+
+// Secondary action
+<Button variant="outlined">Cancel</Button>
+
+// With icon
+<Button variant="filled" leftIcon={<PlusIcon />}>Add Item</Button>
+
+// Disabled
+<Button variant="filled" disabled>Unavailable</Button>
+
+// Different sizes
+<Button size="sm">Small</Button>
+<Button size="md">Medium</Button>
+<Button size="lg">Large</Button>
+\`\`\`
+
+## DO NOT
+
+\`\`\`typescript
+// ❌ Don't use native button when Button component exists
+<button>Submit</button>
+
+// ❌ Don't override button colors with inline styles
+<Button style={{ backgroundColor: 'red' }}>Delete</Button>
+
+// ❌ Don't combine conflicting sizes
+<Button size="lg" style={{ height: '24px' }}>Small</Button>
+
+// ❌ Don't add className to override core styles
+<Button className="bg-blue-500">Custom</Button>
+\`\`\`
+```
+
+```markdown
+<!-- guidelines/components/dialog.md -->
+# Dialog
+
+**Purpose:** Modal overlay for focused tasks requiring user attention.
+
+## Import
+
+\`\`\`typescript
+import { Dialog } from '@discourser/design-system';
+\`\`\`
+
+## Structure
+
+Dialog uses a compound component pattern. All parts are required for proper accessibility:
+
+\`\`\`typescript
+<Dialog.Root>
+  <Dialog.Trigger asChild>
+    <Button>Open Dialog</Button>
+  </Dialog.Trigger>
+  <Dialog.Backdrop />
+  <Dialog.Positioner>
+    <Dialog.Content>
+      <Dialog.Title>Dialog Title</Dialog.Title>
+      <Dialog.Description>Dialog content goes here.</Dialog.Description>
+      <Dialog.CloseTrigger asChild>
+        <Button variant="text">Close</Button>
+      </Dialog.CloseTrigger>
+    </Dialog.Content>
+  </Dialog.Positioner>
+</Dialog.Root>
+\`\`\`
+
+## Parts
+
+| Part | Required | Description |
+|------|----------|-------------|
+| `Dialog.Root` | Yes | Container, manages open/close state |
+| `Dialog.Trigger` | No | Opens dialog when clicked |
+| `Dialog.Backdrop` | Yes | Semi-transparent overlay behind dialog |
+| `Dialog.Positioner` | Yes | Centers the content |
+| `Dialog.Content` | Yes | The dialog panel |
+| `Dialog.Title` | Yes | Accessible title (required for a11y) |
+| `Dialog.Description` | No | Supporting text |
+| `Dialog.CloseTrigger` | No | Closes dialog when clicked |
+
+## Sizes
+
+| Size | Max Width | Usage |
+|------|-----------|-------|
+| `sm` | 400px | Confirmations, simple prompts |
+| `md` | 560px | Default, forms |
+| `lg` | 720px | Complex content, tables |
+| `fullscreen` | 100vw | Mobile, immersive experiences |
+
+## Accessibility
+
+- Focus is automatically trapped within dialog when open
+- ESC key closes dialog
+- Title is announced to screen readers
+- Background content is marked as inert
+
+## Examples
+
+\`\`\`typescript
+// Confirmation dialog
+<Dialog.Root>
+  <Dialog.Trigger asChild>
+    <Button variant="outlined">Delete Item</Button>
+  </Dialog.Trigger>
+  <Dialog.Backdrop />
+  <Dialog.Positioner>
+    <Dialog.Content size="sm">
+      <Dialog.Title>Delete Item?</Dialog.Title>
+      <Dialog.Description>
+        This action cannot be undone. The item will be permanently deleted.
+      </Dialog.Description>
+      <div style={{ display: 'flex', gap: '8px', justifyContent: 'flex-end', marginTop: '24px' }}>
+        <Dialog.CloseTrigger asChild>
+          <Button variant="text">Cancel</Button>
+        </Dialog.CloseTrigger>
+        <Button variant="filled">Delete</Button>
+      </div>
+    </Dialog.Content>
+  </Dialog.Positioner>
+</Dialog.Root>
+
+// Controlled dialog
+function ControlledDialog() {
+  const [open, setOpen] = useState(false);
+  
+  return (
+    <Dialog.Root open={open} onOpenChange={({ open }) => setOpen(open)}>
+      <Dialog.Trigger asChild>
+        <Button>Open</Button>
+      </Dialog.Trigger>
+      <Dialog.Backdrop />
+      <Dialog.Positioner>
+        <Dialog.Content>
+          <Dialog.Title>Controlled Dialog</Dialog.Title>
+          <Dialog.Description>State is managed externally.</Dialog.Description>
+        </Dialog.Content>
+      </Dialog.Positioner>
+    </Dialog.Root>
+  );
+}
+\`\`\`
+
+## DO NOT
+
+\`\`\`typescript
+// ❌ Don't omit required parts
+<Dialog.Root>
+  <Dialog.Content>  {/* Missing Backdrop, Positioner, Title */}
+    Content here
+  </Dialog.Content>
+</Dialog.Root>
+
+// ❌ Don't omit Title (accessibility violation)
+<Dialog.Root>
+  <Dialog.Backdrop />
+  <Dialog.Positioner>
+    <Dialog.Content>
+      <Dialog.Description>No title!</Dialog.Description>
+    </Dialog.Content>
+  </Dialog.Positioner>
+</Dialog.Root>
+
+// ❌ Don't use native modal elements
+<dialog open>
+  <p>Native dialog</p>
+</dialog>
+\`\`\`
+```
+
+```markdown
+<!-- guidelines/components/input.md -->
+# Input
+
+**Purpose:** Text input field with label, helper text, and validation.
+
+## Import
+
+\`\`\`typescript
+import { Input } from '@discourser/design-system';
+\`\`\`
+
+## Variants
+
+| Variant | Usage |
+|---------|-------|
+| `outlined` | Default, most use cases |
+| `filled` | Alternative style, denser layouts |
+
+## Sizes
+
+| Size | Height | Usage |
+|------|--------|-------|
+| `sm` | 40px | Compact forms |
+| `md` | 56px | Default |
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `'outlined' \| 'filled'` | `'outlined'` | Visual style |
+| `size` | `'sm' \| 'md'` | `'md'` | Input size |
+| `label` | `string` | - | Field label |
+| `helperText` | `string` | - | Helper text below input |
+| `errorText` | `string` | - | Error message (shows error state) |
+| `disabled` | `boolean` | `false` | Disable input |
+
+## Examples
+
+\`\`\`typescript
+// Basic input with label
+<Input label="Email" placeholder="you@example.com" />
+
+// With helper text
+<Input 
+  label="Password" 
+  type="password"
+  helperText="Must be at least 8 characters"
+/>
+
+// Error state
+<Input 
+  label="Email" 
+  errorText="Please enter a valid email address"
+/>
+
+// Disabled
+<Input label="Username" disabled value="johndoe" />
+
+// Controlled
+const [email, setEmail] = useState('');
+<Input 
+  label="Email" 
+  value={email}
+  onChange={(e) => setEmail(e.target.value)}
+/>
+\`\`\`
+
+## DO NOT
+
+\`\`\`typescript
+// ❌ Don't use native input without the component
+<input type="text" />
+
+// ❌ Don't omit label (accessibility)
+<Input placeholder="Enter email" />  // Missing label!
+
+// ❌ Don't override input styles
+<Input label="Email" style={{ border: '2px solid red' }} />
+\`\`\`
+```
+
+#### 7.6 Publish Package to npm
+
+**Public Package:**
+```bash
+# Ensure logged into npm
+npm login
+
+# Publish
+pnpm publish --access public
+```
+
+**Private Package (for Figma organization):**
+1. In Figma Make, go to ⚙️ Make settings → Figma npm registry
+2. Click "Get started" and enter organization scope (e.g., `@discourser`)
+3. Click "Generate key" (requires org admin)
+4. Add to `.npmrc`:
+```
+@discourser:registry=https://npm.figma.com/
+//npm.figma.com/:_authToken=YOUR_TOKEN
+```
+5. Publish: `npm publish`
+
+#### 7.7 Create Figma Make Template (Optional)
+
+After publishing, create a Make template for your team:
+1. Create new Figma Make file
+2. Install package: "Install @discourser/design-system"
+3. Add guidelines folder with all markdown files from 7.1-7.5
+4. Publish as template for team use
+
+**Validation:**
+```bash
+# In Figma Make file:
+# 1. Install package
+# 2. Ask: "Create a form with Button and Input components"
+# 3. Verify Make uses design system components correctly
+# 4. Verify semantic tokens are applied
+# 5. Ask: "Create a confirmation dialog"
+# 6. Verify Dialog compound pattern is used correctly
+```
+
+---
+
+### Phase Summary
+
+| Phase | Description | Status |
+|-------|-------------|--------|
+| 0 | Context Engineering (Skills, CLAUDE.md) | ✅ Complete |
+| 1 | Fix Foundation (deps, config) | ✅ Complete |
+| 2 | Architecture (Contract/Language/Transform) | ✅ Complete |
+| 3 | M3 Token Integration | ✅ Complete |
+| 4 | Complete Recipe Coverage + Testing | 🔄 In Progress |
+| 5 | Ark UI Integration + A11y Testing | ⬜ Not Started |
+| 6 | Build & Package (Figma Make compatible) | ⬜ Not Started |
+| 7 | Figma Make Guidelines | ⬜ Not Started |
+
+---
+
+### Slash Commands Reference
+
+These commands are available in Claude Code when working in this repository:
+
+```bash
+/fix-foundation          # Run Phase 1 tasks
+/implement-architecture  # Run Phase 2 tasks
+/new-component <name>    # Scaffold a new component with recipe + stories + tests
+```
+
+### Skills Reference
+
+These skills auto-load when relevant:
+
+| Skill | Triggers On |
+|-------|-------------|
+| `design-language` | Contract, language, transform work |
+| `panda-recipes` | Recipe creation, variant patterns |
+| `m3-tokens` | Color values, semantic tokens |
+| `component-patterns` | Component creation, forwardRef, Ark UI |