@discourser/design-system 0.7.0 → 0.9.0

package/guidelines/Guidelines.md

@@ -78,6 +78,83 @@ BEFORE using ANY component, you MUST read its guidelines file first:
 
 **DO NOT write code using a component until you have read its specific guidelines.**
 
+## CRITICAL: Working with Figma Designs
+
+**When building from a Figma frame, DO NOT pixel-match or extract values from the design.**
+
+Instead, follow these rules:
+
+### NEVER Do This:
+
+- ❌ Extract hex colors from the Figma design (e.g., `#4A4A4A`, `#f5f1eb`)
+- ❌ Copy exact pixel values for spacing (e.g., `padding: '20px 10px'`)
+- ❌ Copy exact font sizes (e.g., `fontSize: '16px'`)
+- ❌ Copy exact border radius values (e.g., `borderRadius: '13px'`)
+- ❌ Create inline SVGs for logos or icons
+- ❌ Override component styles with `className={css({...})}` containing hardcoded values
+- ❌ Use `<span>` or `<div>` when a design system component exists
+
+### ALWAYS Do This:
+
+- ✅ Map visual colors to semantic tokens (green → `primary`, light bg → `surface`)
+- ✅ Use spacing tokens (`sm`, `md`, `lg`) not pixel values
+- ✅ Use typography tokens (`bodyMedium`, `titleLarge`) not font sizes
+- ✅ Use radius tokens (`small`, `medium`, `large`) not pixel values
+- ✅ Use placeholder elements or icon components for logos/icons
+- ✅ Use component variants (`variant="filled"`) not style overrides
+- ✅ Use `<Badge>` component, not styled spans
+- ✅ Use `<Button>` component, not styled divs
+
+### Color Mapping Guide
+
+When you see these colors in a Figma design, use these tokens:
+
+| Figma Color          | Semantic Token                  | Usage                       |
+| -------------------- | ------------------------------- | --------------------------- |
+| Green/olive tones    | `primary`                       | Brand color, CTAs           |
+| Light cream/beige    | `surface` or `surfaceContainer` | Backgrounds                 |
+| Dark gray/black text | `onSurface`                     | Primary text                |
+| Medium gray text     | `onSurfaceVariant`              | Secondary text              |
+| White                | `onPrimary`                     | Text on primary backgrounds |
+| Borders/dividers     | `outline` or `outlineVariant`   | Borders                     |
+| Error/red tones      | `error`                         | Error states                |
+
+### Component Override Rules
+
+**Acceptable overrides:**
+
+```tsx
+// ✅ OK - Layout positioning only
+<Card.Root className={css({ width: '100%', maxWidth: '400px' })}>
+```
+
+**Unacceptable overrides:**
+
+```tsx
+// ❌ WRONG - Overriding colors, fonts, spacing
+<Card.Root className={css({ bg: '#f5f1eb', borderRadius: '13px', padding: '20px' })}>
+```
+
+### Logo and Icon Handling
+
+- **Logos**: Use a placeholder `<div>` with text or import from an assets folder. NEVER create inline SVGs.
+- **Icons**: Use Lucide React icons or a placeholder. NEVER create custom SVG icon components.
+
+```tsx
+// ✅ OK - Placeholder for logo
+<div className={css({ display: 'flex', alignItems: 'center', gap: 'sm' })}>
+  <span>🎯</span>
+  <span>Discourser</span>
+</div>;
+
+// ❌ WRONG - Inline SVG
+function Logo() {
+  return <svg>...</svg>; // Never do this
+}
+```
+
+---
+
 ## Core Principles
 
 - **Always prefer design system components** over native HTML elements
@@ -87,6 +164,7 @@ BEFORE using ANY component, you MUST read its guidelines file first:
 - **Never use inline styles** with raw color values
 - **Read component guidelines** before using any component
 - **Follow common patterns** documented in overview-patterns.md
+- **Map Figma designs to tokens** — never extract exact values
 
 ## Quick Start
 

package/guidelines/exp/context/Gem-Smry-1-15-10_45.md

@@ -0,0 +1,57 @@
+Overall Goal
+The primary objective is to successfully integrate your local
+@discourser/design-system with Figma Make by creating a set of "guidelines"
+that allows Figma's AI to generate accurate, production-ready code based on
+your design system.
+
+The Core Problem
+Your initial attempt at providing guidelines was unsuccessful because their
+total size was massive (~839 KB across 33 files). This far exceeds the context
+window that Figma Make's AI can effectively handle, leading to it ignoring the
+rules, hallucinating incorrect code (like using Tailwind CSS), or failing
+entirely.
+
+The Solution: "Minimal Guidelines" (exp/v1)
+The core strategy you and Claude developed was to abandon the comprehensive
+documentation approach and instead create a hyper-efficient, minimal set of
+guidelines focused on fixing the most common failure modes.
+
+This new version, stored in guidelines/exp/v1/, has the following
+characteristics:
+
+- Drastic Size Reduction: The guidelines were shrunk by 99.2%, from ~839 KB
+  down to just ~6.9 KB.
+- Fewer Files: The structure was simplified from 33 files to just 2 core
+  instruction files and a testing log:
+  - Guidelines.md (1.3 KB): The main entry point containing only the most
+    critical, non-negotiable rules.
+  - quick-ref.md (5.6 KB): A "cheat sheet" containing decision trees,
+    correct import patterns, and barebones examples for key components,
+    prioritizing structure over prose.
+  - TESTING-LOG.md (6.7 KB): A pre-made template to systematically log the
+    results of your tests.
+- Focus on Critical Failures: The new guidelines prioritize telling the AI
+  how to avoid common mistakes, specifically:
+  1. How to correctly use compound components (e.g., always use
+     `<Card.Root>`).
+  2. How to correctly apply the `colorPalette` prop to buttons.
+  3. To use the design system's styling functions, not Tailwind CSS.
+
+The Action Plan: Structured Testing
+A clear, scientific testing plan was established to validate the new minimal
+guidelines.
+
+1. Test A (Experimental): Use the new, minimal exp/v1 guidelines.
+2. Test B (Control): Use a small subset of the original, large guidelines to
+   prove they are less effective.
+3. Standardized Prompts: Run a set of specific, repeatable prompts for both
+   tests, such as:
+   - "Create a Card with a title and a primary button"
+   - "Create a login form with email, password inputs and submit button"
+4. Success Metrics: Use the TESTING-LOG.md template to track pass/fail
+   criteria for each prompt, noting:
+   - Were the imports correct?
+   - Was .Root used for compound components?
+   - Was colorPalette used correctly?
+   - Was Tailwind CSS avoided?
+   - How long did it take?

package/guidelines/exp/v1/01-V1-Minimal.md

@@ -0,0 +1,66 @@
+# Discourser Design System
+
+Package: `@discourser/design-system`
+
+## CRITICAL RULES
+
+1. **ALWAYS** import from `@discourser/design-system`
+2. **NEVER** use Tailwind classes or raw CSS values
+3. **NEVER** create custom components when design system components exist
+4. **ALWAYS** use `.Root` for compound components (Card, Dialog, Switch, etc.)
+
+## Two Component Types
+
+### Simple Components (use directly)
+
+```tsx
+<Button variant="solid" colorPalette="primary">Click</Button>
+<Heading as="h1" size="2xl">Title</Heading>
+<Input label="Email" />
+```
+
+### Compound Components (MUST use .Root)
+
+```tsx
+<Card.Root>...</Card.Root>
+<Dialog.Root>...</Dialog.Root>
+<Switch.Root>...</Switch.Root>
+```
+
+⚠️ `<Card>Content</Card>` = RUNTIME ERROR. Must be `<Card.Root>Content</Card.Root>`
+
+## Import Pattern
+
+```tsx
+import {
+  Button,
+  Heading,
+  Input,
+  Textarea,
+  Badge,
+  Spinner,
+  Card,
+  Dialog,
+  Switch,
+  Checkbox,
+  Select,
+  Tabs,
+  Avatar,
+} from '@discourser/design-system';
+import { css } from '@discourser/design-system/styled-system/css';
+```
+
+## Styling
+
+```tsx
+// ✅ CORRECT - semantic tokens
+css({ bg: 'surface', color: 'onSurface', p: 'lg', gap: 'md' });
+
+// ❌ WRONG - raw values
+css({ bg: '#fff', padding: '24px' });
+className = 'bg-white p-6';
+```
+
+## Quick Reference Tables
+
+See: [quick-ref.md](quick-ref.md) for component selection and variants.

package/guidelines/exp/v1/TESTING-LOG.md

@@ -0,0 +1,307 @@
+# Figma Make Testing Session Log
+
+**Date:** 2025-01-16
+**Package:** `@discourser/design-system@0.2.2`
+**Tester:** Will Streeter
+
+---
+
+## Session Overview
+
+| Test | Guidelines Version                                   | Total Size | Result     |
+| ---- | ---------------------------------------------------- | ---------- | ---------- |
+| A    | exp/v1                                               | 6.9 KB     | ⬜ Pending |
+| B    | Current subset (Guidelines.md + overview-imports.md) | ~16 KB     | ⬜ Pending |
+| C    | No guidelines (baseline)                             | 0 KB       | ⬜ Pending |
+
+---
+
+## Test A: Minimal Guidelines (exp/v1)
+
+**Setup:**
+
+- [ ] Created new Figma Make file
+- [ ] Installed `@discourser/design-system`
+- [ ] Added `guidelines/Guidelines.md` from exp/v1
+- [ ] Added `guidelines/quick-ref.md` from exp/v1
+
+### Prompt 1: Card with Button
+
+**Prompt:** "Create a Card with a title and a primary button"
+
+| Criteria                            | Pass | Fail | Notes |
+| ----------------------------------- | ---- | ---- | ----- |
+| Correct import path                 | ⬜   | ⬜   |       |
+| Used `Card.Root` (not `<Card>`)     | ⬜   | ⬜   |       |
+| Used `Card.Title` or `Card.Header`  | ⬜   | ⬜   |       |
+| Button has `colorPalette="primary"` | ⬜   | ⬜   |       |
+| Button has valid variant            | ⬜   | ⬜   |       |
+| No Tailwind classes                 | ⬜   | ⬜   |       |
+| Uses `css()` with semantic tokens   | ⬜   | ⬜   |       |
+
+**Time to complete:** \_\_\_ seconds / ⬜ Timeout
+
+**Actual output (paste key snippet):**
+
+```tsx
+
+```
+
+**Notes:**
+
+---
+
+### Prompt 2: Login Form
+
+**Prompt:** "Create a login form with email and password inputs and a submit button"
+
+| Criteria                          | Pass | Fail | Notes |
+| --------------------------------- | ---- | ---- | ----- |
+| Correct import path               | ⬜   | ⬜   |       |
+| Used `<Input>` component (simple) | ⬜   | ⬜   |       |
+| Input has `label` prop            | ⬜   | ⬜   |       |
+| Button has `colorPalette`         | ⬜   | ⬜   |       |
+| Button has `type="submit"`        | ⬜   | ⬜   |       |
+| No Tailwind classes               | ⬜   | ⬜   |       |
+| Uses `css()` with semantic tokens | ⬜   | ⬜   |       |
+
+**Time to complete:** \_\_\_ seconds / ⬜ Timeout
+
+**Actual output (paste key snippet):**
+
+```tsx
+
+```
+
+**Notes:**
+
+---
+
+### Prompt 3: Delete Confirmation Dialog
+
+**Prompt:** "Create a dialog for confirming a delete action"
+
+| Criteria                                             | Pass | Fail | Notes |
+| ---------------------------------------------------- | ---- | ---- | ----- |
+| Correct import path                                  | ⬜   | ⬜   |       |
+| Used `Dialog.Root` (not `<Dialog>`)                  | ⬜   | ⬜   |       |
+| Used `Dialog.Trigger`                                | ⬜   | ⬜   |       |
+| Used `Dialog.Content`                                | ⬜   | ⬜   |       |
+| Used `Dialog.Title`                                  | ⬜   | ⬜   |       |
+| Cancel button: `variant="outline"` or `"plain"`      | ⬜   | ⬜   |       |
+| Delete button: `colorPalette="error"` or `"primary"` | ⬜   | ⬜   |       |
+| No Tailwind classes                                  | ⬜   | ⬜   |       |
+
+**Time to complete:** \_\_\_ seconds / ⬜ Timeout
+
+**Actual output (paste key snippet):**
+
+```tsx
+
+```
+
+**Notes:**
+
+---
+
+### Test A Summary
+
+| Prompt           | Pass Rate | Critical Failures |
+| ---------------- | --------- | ----------------- |
+| Card with Button | /7        |                   |
+| Login Form       | /7        |                   |
+| Delete Dialog    | /8        |                   |
+| **Total**        | /22       |                   |
+
+**Overall Assessment:** ⬜ Usable / ⬜ Needs Work / ⬜ Failed
+
+**Key Observations:**
+
+---
+
+## Test B: Current Guidelines Subset
+
+**Setup:**
+
+- [ ] Created new Figma Make file
+- [ ] Installed `@discourser/design-system`
+- [ ] Added `guidelines/Guidelines.md` (current ~5.8KB)
+- [ ] Added `guidelines/overview-imports.md` (current ~10.4KB)
+
+### Prompt 1: Card with Button
+
+**Prompt:** "Create a Card with a title and a primary button"
+
+| Criteria                            | Pass | Fail | Notes |
+| ----------------------------------- | ---- | ---- | ----- |
+| Correct import path                 | ⬜   | ⬜   |       |
+| Used `Card.Root` (not `<Card>`)     | ⬜   | ⬜   |       |
+| Used `Card.Title` or `Card.Header`  | ⬜   | ⬜   |       |
+| Button has `colorPalette="primary"` | ⬜   | ⬜   |       |
+| Button has valid variant            | ⬜   | ⬜   |       |
+| No Tailwind classes                 | ⬜   | ⬜   |       |
+| Uses `css()` with semantic tokens   | ⬜   | ⬜   |       |
+
+**Time to complete:** \_\_\_ seconds / ⬜ Timeout
+
+**Actual output (paste key snippet):**
+
+```tsx
+
+```
+
+**Notes:**
+
+---
+
+### Prompt 2: Login Form
+
+**Prompt:** "Create a login form with email and password inputs and a submit button"
+
+| Criteria                          | Pass | Fail | Notes |
+| --------------------------------- | ---- | ---- | ----- |
+| Correct import path               | ⬜   | ⬜   |       |
+| Used `<Input>` component (simple) | ⬜   | ⬜   |       |
+| Input has `label` prop            | ⬜   | ⬜   |       |
+| Button has `colorPalette`         | ⬜   | ⬜   |       |
+| Button has `type="submit"`        | ⬜   | ⬜   |       |
+| No Tailwind classes               | ⬜   | ⬜   |       |
+| Uses `css()` with semantic tokens | ⬜   | ⬜   |       |
+
+**Time to complete:** \_\_\_ seconds / ⬜ Timeout
+
+**Actual output (paste key snippet):**
+
+```tsx
+
+```
+
+**Notes:**
+
+---
+
+### Prompt 3: Delete Confirmation Dialog
+
+**Prompt:** "Create a dialog for confirming a delete action"
+
+| Criteria                                             | Pass | Fail | Notes |
+| ---------------------------------------------------- | ---- | ---- | ----- |
+| Correct import path                                  | ⬜   | ⬜   |       |
+| Used `Dialog.Root` (not `<Dialog>`)                  | ⬜   | ⬜   |       |
+| Used `Dialog.Trigger`                                | ⬜   | ⬜   |       |
+| Used `Dialog.Content`                                | ⬜   | ⬜   |       |
+| Used `Dialog.Title`                                  | ⬜   | ⬜   |       |
+| Cancel button: `variant="outline"` or `"plain"`      | ⬜   | ⬜   |       |
+| Delete button: `colorPalette="error"` or `"primary"` | ⬜   | ⬜   |       |
+| No Tailwind classes                                  | ⬜   | ⬜   |       |
+
+**Time to complete:** \_\_\_ seconds / ⬜ Timeout
+
+**Actual output (paste key snippet):**
+
+```tsx
+
+```
+
+**Notes:**
+
+---
+
+### Test B Summary
+
+| Prompt           | Pass Rate | Critical Failures |
+| ---------------- | --------- | ----------------- |
+| Card with Button | /7        |                   |
+| Login Form       | /7        |                   |
+| Delete Dialog    | /8        |                   |
+| **Total**        | /22       |                   |
+
+**Overall Assessment:** ⬜ Usable / ⬜ Needs Work / ⬜ Failed
+
+**Key Observations:**
+
+---
+
+## Test C: No Guidelines (Baseline)
+
+**Setup:**
+
+- [ ] Created new Figma Make file
+- [ ] Installed `@discourser/design-system`
+- [ ] NO guidelines folder added
+
+### Prompt 1: Card with Button
+
+**Prompt:** "Create a Card with a title and a primary button using @discourser/design-system"
+
+| Criteria                           | Pass | Fail | Notes |
+| ---------------------------------- | ---- | ---- | ----- |
+| Correct import path                | ⬜   | ⬜   |       |
+| Used `Card.Root` (not `<Card>`)    | ⬜   | ⬜   |       |
+| Used `Card.Title` or `Card.Header` | ⬜   | ⬜   |       |
+| Button has `colorPalette`          | ⬜   | ⬜   |       |
+| Button has valid variant           | ⬜   | ⬜   |       |
+| No Tailwind classes                | ⬜   | ⬜   |       |
+
+**Time to complete:** \_\_\_ seconds / ⬜ Timeout
+
+**Actual output (paste key snippet):**
+
+```tsx
+
+```
+
+**Notes:**
+
+---
+
+### Test C Summary
+
+| Prompt           | Pass Rate | Critical Failures |
+| ---------------- | --------- | ----------------- |
+| Card with Button | /6        |                   |
+| **Total**        | /6        |                   |
+
+**Overall Assessment:** ⬜ Usable / ⬜ Needs Work / ⬜ Failed
+
+**Key Observations:**
+
+---
+
+## Comparison Summary
+
+| Test               | Guidelines Size | Pass Rate | Timeouts | Best For |
+| ------------------ | --------------- | --------- | -------- | -------- |
+| A (exp/v1)         | 6.9 KB          | /22       |          |          |
+| B (Current subset) | ~16 KB          | /22       |          |          |
+| C (No guidelines)  | 0 KB            | /6        |          |          |
+
+---
+
+## Key Findings
+
+### What Worked
+
+### What Failed
+
+### Recommendations for exp/v2
+
+---
+
+## Iteration Notes
+
+Use this section to track specific fixes needed:
+
+| Issue | Guideline Fix | Priority |
+| ----- | ------------- | -------- |
+|       |               |          |
+|       |               |          |
+|       |               |          |
+
+---
+
+## Next Steps
+
+- [ ]
+- [ ]
+- [ ]