@discourser/design-system 0.22.2 → 0.22.3

package/docs/claude-feed-back/ARCHITECTURE_DIAGRAM.md

@@ -0,0 +1,243 @@
+# Design System Architecture: Current vs. Correct
+
+## Current (Broken) Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ @discourser/design-system (Published Package)               │
+│                                                             │
+│  ┌──────────────┐   ┌─────────────────┐   ┌──────────────┐│
+│  │ src/preset/  │   │ src/components/ │   │ styled-      ││
+│  │ index.ts     │───│ Button.tsx      │   │ system/      ││
+│  │              │   │                 │   │              ││
+│  │ (defines     │   │ import { button}│──▶│ (GENERATED   ││
+│  │  tokens,     │   │ from 'styled-   │   │  during build││
+│  │  recipes)    │   │ system/recipes' │   │  published   ││
+│  └──────────────┘   └─────────────────┘   │  to npm) ❌  ││
+│                                            └──────────────┘│
+└─────────────────────────────────────────────────────────────┘
+                         │
+                         │ npm install
+                         ▼
+┌─────────────────────────────────────────────────────────────┐
+│ Consumer App (discourser.ai)                                │
+│                                                             │
+│  ┌────────────────────┐   ┌──────────────────────────────┐ │
+│  │ panda.config.ts    │   │ node_modules/                │ │
+│  │                    │   │ @discourser/                 │ │
+│  │ presets: [         │   │   design-system/             │ │
+│  │   discourserPanda  │───│     styled-system/ ❌        │ │
+│  │   Preset           │   │     (outdated, wrong tokens) │ │
+│  │ ]                  │   │                              │ │
+│  └────────────────────┘   └──────────────────────────────┘ │
+│                                                             │
+│  ❌ PROBLEM: Consumer tries to import from                 │
+│     @discourser/design-system/styled-system/*               │
+│     but that was generated for the design system's build,   │
+│     not the consumer's app                                  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Why This Fails:**
+1. Components in design system import from `styled-system/recipes`
+2. That `styled-system/` folder is built for the design system project
+3. Published to npm alongside components
+4. Consumer imports components, which reference a `styled-system/` that doesn't match their app
+5. Token references break, recipes don't align with consumer's configuration
+
+---
+
+## Correct Architecture: Preset-Only
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ @discourser/design-system (Published Package)               │
+│                                                             │
+│  ┌──────────────────────────────────────────────────────┐  │
+│  │ dist/preset/index.js                                 │  │
+│  │                                                      │  │
+│  │ export const discourserPandaPreset = {               │  │
+│  │   name: 'discourser-material3-preset',               │  │
+│  │   theme: {                                           │  │
+│  │     extend: {                                        │  │
+│  │       tokens: {                                      │  │
+│  │         colors: { /* M3 palettes */ },               │  │
+│  │         spacing: { /* M3 spacing */ },               │  │
+│  │         // ... all token definitions                 │  │
+│  │       },                                             │  │
+│  │       recipes: {                                     │  │
+│  │         button: { /* button recipe */ },             │  │
+│  │         input: { /* input recipe */ },               │  │
+│  │         // ... all recipe definitions                │  │
+│  │       }                                              │  │
+│  │     }                                                │  │
+│  │   }                                                  │  │
+│  │ }                                                    │  │
+│  └──────────────────────────────────────────────────────┘  │
+│                                                             │
+│  ✅ NO styled-system/ folder published                     │
+│  ✅ NO components published (or see Alternative below)     │
+│  ✅ Only preset configuration as JavaScript/TypeScript     │
+└─────────────────────────────────────────────────────────────┘
+                         │
+                         │ npm install
+                         ▼
+┌─────────────────────────────────────────────────────────────┐
+│ Consumer App (discourser.ai)                                │
+│                                                             │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │ panda.config.ts                                     │   │
+│  │                                                     │   │
+│  │ import { discourserPandaPreset }                    │   │
+│  │   from '@discourser/design-system/preset'           │   │
+│  │                                                     │   │
+│  │ export default defineConfig({                       │   │
+│  │   presets: [discourserPandaPreset],                 │   │
+│  │   include: ['./src/**/*.{ts,tsx}'],                 │   │
+│  │   outdir: 'styled-system' ────────────┐             │   │
+│  │ })                                    │             │   │
+│  └───────────────────────────────────────┼─────────────┘   │
+│                                          │                 │
+│                                          ▼                 │
+│  ┌───────────────────────────────────────────────────┐    │
+│  │ pnpm panda codegen                                │    │
+│  │                                                   │    │
+│  │ Generates styled-system/ in consumer's project:   │    │
+│  │                                                   │    │
+│  │ styled-system/                                    │    │
+│  │ ├── css/          ← CSS utility functions         │    │
+│  │ ├── tokens/       ← M3 tokens from preset         │    │
+│  │ ├── recipes/      ← Button, input recipes         │    │
+│  │ └── patterns/     ← Layout patterns               │    │
+│  │                                                   │    │
+│  │ ✅ Generated locally for THIS app                 │    │
+│  │ ✅ Uses tokens/recipes from preset                │    │
+│  │ ✅ Can add app-specific overrides                 │    │
+│  └───────────────────────────────────────────────────┘    │
+│                                          │                 │
+│                                          ▼                 │
+│  ┌───────────────────────────────────────────────────┐    │
+│  │ Consumer builds their own components              │    │
+│  │                                                   │    │
+│  │ import { button } from 'styled-system/recipes'    │    │
+│  │                                                   │    │
+│  │ export function Button({ variant, ...props }) {   │    │
+│  │   return (                                        │    │
+│  │     <button                                       │    │
+│  │       className={button({ variant })}             │    │
+│  │       {...props}                                  │    │
+│  │     />                                            │    │
+│  │   )                                               │    │
+│  │ }                                                 │    │
+│  │                                                   │    │
+│  │ ✅ Uses THEIR styled-system/ (local)              │    │
+│  │ ✅ Full control over components                   │    │
+│  │ ✅ Can customize as needed                        │    │
+│  └───────────────────────────────────────────────────┘    │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Alternative: Preset + Component Examples
+
+If you want to help consumers with pre-built components:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ @discourser/design-system (Published Package)               │
+│                                                             │
+│  ┌──────────────────┐   ┌──────────────────────────────┐   │
+│  │ dist/preset/     │   │ examples/ (in published pkg) │   │
+│  │ index.js         │   │                              │   │
+│  │                  │   │ Button.example.tsx           │   │
+│  │ (preset config)  │   │ Input.example.tsx            │   │
+│  │                  │   │ Card.example.tsx             │   │
+│  │ ✅ Build-time    │   │                              │   │
+│  │    configuration │   │ ✅ Reference implementations │   │
+│  └──────────────────┘   │ ✅ Copy-paste ready          │   │
+│                         │ ✅ Use consumer's            │   │
+│                         │    styled-system/            │   │
+│                         └──────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────┘
+                         │
+                         │ npm install
+                         ▼
+┌─────────────────────────────────────────────────────────────┐
+│ Consumer App                                                │
+│                                                             │
+│  1. Import preset in panda.config.ts                        │
+│  2. Run panda codegen                                       │
+│  3. Copy examples from node_modules/.../examples/           │
+│  4. Customize as needed                                     │
+│                                                             │
+│  ✅ Full flexibility                                        │
+│  ✅ No dependency hell                                      │
+│  ✅ Examples as documentation                               │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Key Principles
+
+### ✅ Correct Approach
+
+1. **Preset = Configuration Only**
+   - Token definitions (colors, spacing, typography)
+   - Recipe definitions (button variants, input styles)
+   - Semantic tokens (surface, primary, onPrimary)
+   - Theme extensions
+   - NO generated code
+   - NO styled-system/
+
+2. **Consumer Generates styled-system/**
+   - Runs `panda codegen` with your preset
+   - Gets their own `styled-system/` folder
+   - Matches their app configuration
+   - Can add overrides/extensions
+
+3. **Components Are Consumer Responsibility**
+   - OR provide as examples to copy
+   - OR publish separately as static CSS components
+   - Never mix runtime components with Panda preset
+
+### ❌ What NOT to Do
+
+1. **Don't Publish styled-system/**
+   - It's generated for YOUR project
+   - Won't work in consumer projects
+   - Creates conflicts and confusion
+
+2. **Don't Import styled-system/ in Published Components**
+   - If components are published, they can't reference styled-system/
+   - Must use static CSS or CSS modules instead
+
+3. **Don't Make @pandacss/dev a Regular Dependency**
+   - Must be peerDependency
+   - Prevents version conflicts
+   - Allows consumers to control Panda version
+
+---
+
+## Migration Summary
+
+### Remove from Published Package
+- ❌ `styled-system/` folder
+- ❌ Components that import from `styled-system/*`
+- ❌ tsup plugin that rewrites styled-system imports
+
+### Keep in Published Package
+- ✅ Preset configuration (`dist/preset/index.js`)
+- ✅ Type definitions (`DesignLanguageContract`)
+- ✅ Language utilities (for advanced users)
+
+### Update package.json
+- ✅ Move `@pandacss/dev` to peerDependencies
+- ✅ Remove `styled-system` from files array
+- ✅ Export only `dist/` folder
+
+### Documentation
+- ✅ README with usage examples
+- ✅ Example components consumers can copy
+- ✅ Migration guide from 0.9.x to 1.0.0

package/docs/claude-feed-back/STYLING_VERIFICATION.md

@@ -0,0 +1,89 @@
+# Button Styling Verification - Material 3 Design System
+
+## Issue Resolution Summary
+
+The buttons in the Next.js app (localhost:3000) are now rendering correctly with Material 3 styling from the @discourser/design-system package.
+
+## Root Cause
+
+The initial styling issue was caused by:
+1. Incorrect preset import path in `panda.config.ts` (importing from main export instead of `/preset`)
+2. Wrong `include` paths scanning `dist/` instead of `src/` files
+3. Stale `styled-system/` directory needed regeneration
+
+## Fix Applied
+
+Updated `/Users/willstreeter/WebstormProjects/vibe-coding/shifu-project/discourser.ai/panda.config.ts`:
+
+```typescript
+// Before
+import { discourserPandaPreset } from '@discourser/design-system';
+include: ['./node_modules/@discourser/design-system/dist/**/*.{js,cjs}']
+
+// After
+import { discourserPandaPreset } from '@discourser/design-system/preset';
+include: ['./node_modules/@discourser/design-system/src/**/*.{ts,tsx}']
+```
+
+Then regenerated: `pnpm panda codegen`
+
+## Verification Results
+
+### Button Styles Applied Correctly
+
+**Logout Button** (variant="outline"):
+- CSS Classes: `button button--variant_outline button--size_md color-palette_primary`
+- Background: `rgba(63, 105, 0, 0.094)` (translucent olive)
+- Border: `1px solid rgba(63, 105, 0, 0.392)` (olive border)
+- Text Color: `rgba(63, 105, 0, 0.8)` (olive text)
+- Border Radius: `6px`
+- Font: `Poppins, "Poppins Fallback"`
+
+**Log In Button** (variant="solid"):
+- CSS Classes: `button button--variant_solid button--size_md color-palette_primary`
+- Background: `rgb(63, 105, 0)` (solid olive/Material 3 primary)
+- Text Color: `rgb(255, 255, 255)` (white)
+- Border: `0px` (no border for solid)
+- Border Radius: `6px`
+- Font: `Poppins, "Poppins Fallback"`
+
+**Sign Up Button** (variant="outline"):
+- Same styling as Logout button (outline variant)
+
+### Material 3 Primary Color
+
+The olive/green color `rgb(63, 105, 0)` is the Material 3 primary color from the design system's token configuration, correctly applied across all variants.
+
+## Component Code
+
+### page.tsx (localhost:3000)
+```tsx
+<Button variant="solid">Log In</Button>
+<Button variant="outline">Sign Up</Button>
+```
+
+### LogoutButton.tsx
+```tsx
+<Button variant="outline" colorPalette="primary" loading={isLoading}>
+  {isLoading ? 'Logging out...' : 'Logout'}
+</Button>
+```
+
+## CSS Loading Chain
+
+1. `/Users/willstreeter/.../discourser.ai/src/app/layout.tsx` imports `./globals.css`
+2. `globals.css` imports `@discourser/design-system/styles.css`
+3. Design system styles.css contains all Panda CSS generated styles
+4. Consumer app's `styled-system/` contains locally generated styles from preset
+
+## Comparison: Storybook vs Next.js App
+
+Both environments now display identical Material 3 button styling:
+- ✅ Solid variant: Olive background with white text
+- ✅ Outline variant: Olive border and text with transparent background
+- ✅ Proper border radius, padding, and typography
+- ✅ Color palette correctly applied
+
+## Status: ✅ RESOLVED
+
+The design system is now working correctly in the consuming Next.js application. All buttons render with proper Material 3 styling using the olive color palette defined in the design system's tokens.

package/docs/claude-feed-back/TEST_RESULTS.md

@@ -0,0 +1,182 @@
+# Test Implementation Results
+
+## ✅ Build & Deployment Complete
+
+### What Was Done
+
+1. **✅ Built Design System**
+   - Panda codegen → styled-system/
+   - tsup → dist/ (ESM + CJS)
+   - TypeScript types → dist/**/*.d.ts
+   - CSS generation → dist/styles.css
+
+2. **✅ Updated Consumer Imports (31 files)**
+   - Changed from `import { Button } from '@discourser/design-system'`
+   - To `import { Button } from '@discourser/design-system/Button'`
+   - 59 imports across 31 files updated
+
+3. **✅ Copied to Consumer App**
+   - dist/ → node_modules/@discourser/design-system/dist/ (209 files)
+   - styled-system/ → node_modules/@discourser/design-system/styled-system/ (185 files)
+   - src/components/ → node_modules/@discourser/design-system/src/components/
+
+### Files Deployed
+
+**Total size:** ~3.1 MB
+- dist/ (1.3 MB) - Compiled JavaScript + TypeScript definitions
+- styled-system/ (1.8 MB) - Panda CSS generated code
+
+### Next Steps: Testing
+
+#### 1. Verify Imports Work
+
+Try importing a component in discourser.ai:
+
+```typescript
+// discourser.ai/src/test.tsx
+import { Button } from '@discourser/design-system/Button'
+import * as Card from '@discourser/design-system/Card'
+
+export function TestPage() {
+  return (
+    <div>
+      <Button variant="filled" size="md">Test Button</Button>
+      <Card.Root>
+        <Card.Body>
+          <Card.Title>Test Card</Card.Title>
+        </Card.Body>
+      </Card.Root>
+    </div>
+  )
+}
+```
+
+#### 2. Start Dev Server
+
+```bash
+cd /Users/willstreeter/WebstormProjects/vibe-coding/shifu-project/discourser.ai
+pnpm dev
+```
+
+#### 3. Check for Errors
+
+Look for:
+- ✅ No import resolution errors
+- ✅ Components render correctly
+- ✅ Styles are applied
+- ✅ Ark UI behaviors work (dialogs, tooltips, etc.)
+
+#### 4. Verify Deep Imports
+
+Test that tree-shaking works:
+
+```typescript
+// Only imports Button code, not the entire library
+import { Button } from '@discourser/design-system/Button'
+```
+
+#### 5. Test Namespace Components
+
+Components exported as namespaces:
+
+```typescript
+import * as Card from '@discourser/design-system/Card'
+import * as Dialog from '@discourser/design-system/Dialog'
+import * as RadioGroup from '@discourser/design-system/RadioGroup'
+import * as Switch from '@discourser/design-system/Switch'
+import * as Select from '@discourser/design-system/Select'
+import * as Slider from '@discourser/design-system/Slider'
+import * as Checkbox from '@discourser/design-system/Checkbox'
+import * as Avatar from '@discourser/design-system/Avatar'
+import * as Progress from '@discourser/design-system/Progress'
+import * as Skeleton from '@discourser/design-system/Skeleton'
+import * as Popover from '@discourser/design-system/Popover'
+import * as Tooltip from '@discourser/design-system/Tooltip'
+import * as Tabs from '@discourser/design-system/Tabs'
+import * as Accordion from '@discourser/design-system/Accordion'
+import * as Drawer from '@discourser/design-system/Drawer'
+```
+
+### Expected Behavior
+
+**✅ Working:**
+- Components import without errors
+- TypeScript autocomplete works
+- Components render with correct styles
+- Ark UI interactions work (dialogs open/close, tooltips show, etc.)
+- Dark mode toggle works
+- All Material 3 colors are applied
+
+**❌ If You See Errors:**
+
+1. **"Cannot find module '@discourser/design-system/Button'"**
+   - Check package.json exports are correct
+   - Verify src/components/Button.tsx exists in node_modules
+
+2. **"Cannot find module '@discourser/design-system/styled-system/css'"**
+   - Verify styled-system/ folder was copied
+   - Check styled-system/css/index.mjs exists
+
+3. **Components render but no styles**
+   - Import the CSS: `import '@discourser/design-system/styles.css'`
+   - Or ensure Panda CSS is processing the components
+
+4. **TypeScript errors in components**
+   - Check @ark-ui/react is installed in consumer app
+   - Verify React 19+ is installed
+
+### Troubleshooting Commands
+
+```bash
+# Verify files exist
+ls -la /Users/willstreeter/WebstormProjects/vibe-coding/shifu-project/discourser.ai/node_modules/@discourser/design-system/
+
+# Check dist exists
+ls /Users/willstreeter/WebstormProjects/vibe-coding/shifu-project/discourser.ai/node_modules/@discourser/design-system/dist/
+
+# Check styled-system exists
+ls /Users/willstreeter/WebstormProjects/vibe-coding/shifu-project/discourser.ai/node_modules/@discourser/design-system/styled-system/
+
+# Check components exist
+ls /Users/willstreeter/WebstormProjects/vibe-coding/shifu-project/discourser.ai/node_modules/@discourser/design-system/src/components/
+```
+
+### What Changed in Consumer App
+
+**Files Modified:** 31 files in discourser.ai/src/
+
+**Import Pattern Changes:**
+
+Before:
+```typescript
+import { Button, Card, Header } from '@discourser/design-system';
+```
+
+After:
+```typescript
+import { Button } from '@discourser/design-system/Button';
+import * as Card from '@discourser/design-system/Card';
+import { Header } from '@discourser/design-system/Header';
+```
+
+### Success Criteria
+
+- [ ] Dev server starts without errors
+- [ ] Components import successfully
+- [ ] Components render visually
+- [ ] Styles are applied (Material 3 colors)
+- [ ] Interactive components work (buttons click, dialogs open, etc.)
+- [ ] TypeScript types work (autocomplete, type checking)
+- [ ] Dark mode works
+- [ ] No console errors
+
+### If Everything Works
+
+The implementation is successful! You can now:
+1. Continue development with the new import pattern
+2. Publish the design system to npm
+3. Use across Next.js, Electron, React Native Web
+
+### If There Are Issues
+
+Report back what errors you see and I'll help debug!