npm - @discourser/design-system - Versions diffs - 0.22.2 → 0.22.4 - Mend

@discourser/design-system 0.22.2 → 0.22.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (75) hide show

package/dist/figma-codex.json +2 -2
package/docs/CSS_USAGE.md +235 -0
package/docs/FIGMA_MAKE_SETUP.md +339 -0
package/docs/GUIDELINES_REVIEW.md +728 -0
package/docs/MAINTAINER_CHECKLIST.md +265 -0
package/docs/TESTING_QUICK_REFERENCE.md +159 -0
package/docs/TESTING_TOKENS.md +340 -0
package/docs/active-stories/README.md +29 -0
package/docs/active-stories/STORY-006a-figma-translation-foundations.md +324 -0
package/docs/active-stories/STORY-006b-figma-translation-components.md +201 -0
package/docs/active-stories/STORY-006c-figma-translation-layout-extension.md +258 -0
package/docs/active-stories/STORY-008-kai-sidecar-fragments.md +137 -0
package/docs/active-stories/STORY-011-verify-translation-docs.md +182 -0
package/docs/archive/ARCHITECTURE-discourser-design-system.md +448 -0
package/docs/claude-feed-back/ARCHITECTURE_DIAGRAM.md +243 -0
package/docs/claude-feed-back/STYLING_VERIFICATION.md +89 -0
package/docs/claude-feed-back/TEST_RESULTS.md +182 -0
package/docs/context-share/ELEVATION_FIX_PLAN.md +903 -0
package/docs/context-share/STORY-001-VALIDATION-PASSED.md +192 -0
package/docs/context-share/STORY-002-IMPLEMENTATION-COMPLETE.md +161 -0
package/docs/context-share/STORYBOOK_MCP_STRATEGY.md +867 -0
package/docs/context-share/TESTING_GAPS_FILLED.md +353 -0
package/docs/context-share/TOKEN_TESTING_SUMMARY.md +388 -0
package/docs/context-share/code-connect-prompt.md +90 -0
package/docs/context-share/dds-autonomous-pipeline.md +765 -0
package/docs/context-share/fix-checkbox-radio-tokens.md +145 -0
package/docs/context-share/icon-component-prompt.md +154 -0
package/docs/context-share/icons/Audience.svg +3 -0
package/docs/context-share/icons/AudioSpeaker.svg +3 -0
package/docs/context-share/icons/BookmarkPlus.svg +3 -0
package/docs/context-share/icons/ClipBoard.svg +8 -0
package/docs/context-share/icons/DiscourserLogo.svg +4 -0
package/docs/context-share/icons/ExitStudio.svg +4 -0
package/docs/context-share/icons/Microphone.svg +5 -0
package/docs/context-share/icons/NotebookPen.svg +3 -0
package/docs/context-share/icons/PausePlay.svg +5 -0
package/docs/context-share/icons/Play.svg +4 -0
package/docs/context-share/icons/Record.svg +6 -0
package/docs/context-share/icons/RepeatQuestion.svg +3 -0
package/docs/context-share/icons/ScrollText.svg +3 -0
package/docs/context-share/icons/Sparkles.svg +3 -0
package/docs/context-share/icons/Speech.svg +3 -0
package/docs/context-share/icons/StopPlay.svg +4 -0
package/docs/context-share/icons/Timer.svg +3 -0
package/docs/context-share/icons/UserProfile.svg +3 -0
package/docs/context-share/m3-token-pipeline-audit.md +125 -0
package/docs/context-share/storybook-mcp-kai-agent-revised-summary.md +211 -0
package/docs/discourser-design-system-prd.md +3698 -0
package/docs/figma-captures/01-typography.png +0 -0
package/docs/figma-captures/02-button-iconbutton.png +0 -0
package/docs/figma-captures/03-form-inputs.png +0 -0
package/docs/figma-captures/04-form-controls.png +0 -0
package/docs/figma-captures/05-data-display.png +0 -0
package/docs/figma-captures/06-feedback.png +0 -0
package/docs/figma-captures/07-overlays.png +0 -0
package/docs/figma-captures/08-navigation-layout.png +0 -0
package/docs/figma-captures/09-custom-components.png +0 -0
package/docs/figma-captures/10-scenario-queue.png +0 -0
package/docs/figma-captures/11-icon-library.png +0 -0
package/docs/figma-make-docs/01-understanding-templates.md +235 -0
package/docs/figma-make-docs/02-prerequisites.md +266 -0
package/docs/figma-make-docs/03-creating-template.md +306 -0
package/docs/figma-make-docs/04-adding-guidelines.md +448 -0
package/docs/figma-make-docs/05-example-starter-code.md +590 -0
package/docs/figma-make-docs/06-publishing-template.md +417 -0
package/docs/figma-make-docs/07-maintenance.md +536 -0
package/docs/figma-make-docs/08-faq.md +490 -0
package/docs/figma-make-docs/README.md +95 -0
package/docs/material-theme.json +418 -0
package/docs/plans/2026-03-12-figma-token-export-rewrite.md +504 -0
package/docs/plans/2026-03-12-step7-panda-token-resolution-design.md +119 -0
package/docs/plans/2026-03-12-step7-panda-token-resolution.md +993 -0
package/docs/token-name-mapping.json +850 -0
package/docs/token-name-mapping.md +251 -0
package/package.json +3 -2

package/dist/figma-codex.json CHANGED Viewed

@@ -1,8 +1,8 @@
 {
   "version": "1.0.0",
   "packageName": "@discourser/design-system",
-  "generatedAt": "2026-03-13T03:32:14.503Z",
-  "gitHash": "7c8d515d",
+  "generatedAt": "2026-03-14T18:14:13.010Z",
+  "gitHash": "50bebdde",
   "figmaFiles": {
     "GaHmFfmvO4loUzuZS4TgEz": {
       "fileKey": "GaHmFfmvO4loUzuZS4TgEz"

package/docs/CSS_USAGE.md ADDED Viewed

@@ -0,0 +1,235 @@
+# Using Pre-compiled CSS
+As of version 0.4.1, `@discourser/design-system` ships with pre-compiled CSS for easy integration with any project.
+## Quick Start
+### Installation
+```bash
+npm install @discourser/design-system react react-dom
+```
+### Basic Usage
+Simply import the pre-compiled CSS and start using components:
+```tsx
+// Import the pre-compiled CSS (do this once in your app entry point)
+import '@discourser/design-system/styles.css';
+// Import components
+import { Button, Card, Input } from '@discourser/design-system';
+function App() {
+  return (
+    <div>
+      <Card variant="elevated">
+        <h1>Welcome</h1>
+        <Input label="Email" type="email" />
+        <Button variant="filled">Submit</Button>
+      </Card>
+    </div>
+  );
+}
+```
+### Theme Support
+The pre-compiled CSS includes both light and dark theme support. Set the `data-theme` attribute on your HTML element:
+```tsx
+// Light theme (default)
+<html data-theme="light">
+  <body>
+    <App />
+  </body>
+</html>
+// Dark theme
+<html data-theme="dark">
+  <body>
+    <App />
+  </body>
+</html>
+```
+You can toggle themes dynamically:
+```tsx
+function ThemeToggle() {
+  const [theme, setTheme] = useState<'light' | 'dark'>('light');
+  useEffect(() => {
+    document.documentElement.setAttribute('data-theme', theme);
+  }, [theme]);
+  return (
+    <Button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
+      Toggle Theme
+    </Button>
+  );
+}
+```
+## What's Included
+The pre-compiled `styles.css` file (144KB) includes:
+- ✅ All semantic color tokens (primary, surface, onPrimary, etc.)
+- ✅ All typography tokens (displayLarge through labelSmall)
+- ✅ All spacing tokens (none through xxxl)
+- ✅ All component recipes (button, card, dialog, input, etc.)
+- ✅ Light and dark theme support via `[data-theme="light"]` and `[data-theme="dark"]`
+- ✅ CSS reset and base styles
+- ✅ Material Design 3 design tokens
+## Advanced Usage
+### Using Styled System (Advanced)
+For advanced styling needs, you can still import the Panda CSS styled system:
+```tsx
+import { css } from '@discourser/design-system/styled-system/css';
+import { Button } from '@discourser/design-system';
+const customStyle = css({
+  bg: 'primary',
+  color: 'onPrimary',
+  padding: 'lg',
+  borderRadius: 'md'
+});
+function CustomButton() {
+  return <Button className={customStyle}>Custom Styled Button</Button>;
+}
+```
+### Without Pre-compiled CSS
+If you prefer to use Panda CSS's runtime styles (for dynamic styling), you can skip importing `styles.css` and use the styled system directly. However, you'll need to set up Panda CSS in your project with `panda codegen`.
+## Integration Examples
+### Vite
+```tsx
+// main.tsx
+import '@discourser/design-system/styles.css';
+import { createRoot } from 'react-dom/client';
+import App from './App';
+createRoot(document.getElementById('root')!).render(<App />);
+```
+### Next.js (App Router)
+```tsx
+// app/layout.tsx
+import '@discourser/design-system/styles.css';
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en" data-theme="light">
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+### Next.js (Pages Router)
+```tsx
+// pages/_app.tsx
+import '@discourser/design-system/styles.css';
+import type { AppProps } from 'next/app';
+export default function App({ Component, pageProps }: AppProps) {
+  return <Component {...pageProps} />;
+}
+```
+## Figma Make Integration
+The pre-compiled CSS enables seamless integration with Figma Make. Simply install the package and it will automatically use the pre-compiled styles for AI-generated designs.
+## File Size
+The pre-compiled CSS file is optimized and includes only the styles you need:
+- **Size**: 144KB (uncompressed)
+- **Gzipped**: ~20-25KB (estimated)
+- **Includes**: All tokens, recipes, and theme styles
+## Migration from Runtime CSS
+If you were previously using runtime Panda CSS:
+**Before:**
+```tsx
+// Had to run panda codegen
+import { css } from '../styled-system/css';
+```
+**After:**
+```tsx
+// Just import the pre-compiled CSS
+import '@discourser/design-system/styles.css';
+import { Button } from '@discourser/design-system';
+```
+No more build step required!
+## Troubleshooting
+### Components don't have styles
+Make sure you've imported the CSS at the top of your application:
+```tsx
+import '@discourser/design-system/styles.css'; // Add this!
+```
+### Theme not working
+Ensure the `data-theme` attribute is set on your HTML element:
+```html
+<html data-theme="light"> <!-- or "dark" -->
+```
+### CSS conflicts with other libraries
+The design system uses CSS layers to prevent conflicts:
+```css
+@layer reset, base, tokens, recipes, utilities;
+```
+If you still have conflicts, you may need to adjust your CSS loading order.
+## Package Exports
+The package exports the following:
+```json
+{
+  ".": "./dist/index.js",
+  "./styles.css": "./dist/styles.css",
+  "./styled-system": "./styled-system/index.mjs",
+  "./styled-system/css": "./styled-system/css/index.mjs",
+  "./styled-system/tokens": "./styled-system/tokens/index.mjs",
+  "./styled-system/recipes": "./styled-system/recipes/index.mjs"
+}
+```
+## Questions?
+- **Documentation**: See the [guidelines folder](./guidelines/) for complete component documentation
+- **GitHub**: https://github.com/Tasty-Maker-Studio/Discourser-Design-System
+- **Issues**: https://github.com/Tasty-Maker-Studio/Discourser-Design-System/issues

package/docs/FIGMA_MAKE_SETUP.md ADDED Viewed

@@ -0,0 +1,339 @@
+# Figma Make Setup Guide
+This guide walks you through integrating the Discourser Design System with Figma Make for AI-powered design generation.
+## Overview
+Figma Make allows AI to generate designs using your design system package and guidelines. This integration enables you to:
+- Generate UI components following your design system patterns
+- Ensure AI-generated designs use proper tokens and components
+- Test design variations quickly
+- Maintain consistency across AI-generated designs
+## Prerequisites
+- Figma account with access to Figma Make
+- Node.js 18+ and npm/pnpm installed
+- Design system published to npm (v0.3.1+)
+## Step 1: Publish Updated Package
+The guidelines folder must be included in the npm package for Figma Make to access them.
+### 1.1 Verify Changes
+```bash
+cd /Users/willstreeter/WebstormProjects/vibe-coding/shifu-project/Discourser-Design-System
+# Verify guidelines are in package.json files array
+cat package.json | grep -A 3 '"files"'
+# Should show: "dist", "styled-system", "guidelines"
+# Verify changeset exists
+ls .changeset/*.md
+```
+### 1.2 Create Pull Request
+```bash
+# Stage changes
+git add package.json .changeset/add-guidelines-to-package.md
+# Commit changes
+git commit -m "$(cat <<'EOF'
+feat: add guidelines to npm package for Figma Make
+- Include guidelines folder in published package
+- Enable Figma Make integration with AI guidelines
+- Support AI-powered design generation
+Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
+EOF
+)"
+# Push to branch
+git push origin feat/figma-make-integration
+```
+### 1.3 Merge and Publish
+1. Create PR on GitHub
+2. Merge PR to main
+3. Release workflow will create version bump PR
+4. Merge version bump PR to trigger npm publish
+5. Verify package published with guidelines:
+   ```bash
+   npm view @discourser/design-system
+   # Check "files" list includes "guidelines"
+   ```
+## Step 2: Set Up in Figma Make
+### 2.1 Access Figma Make
+1. Open Figma Desktop or Web App
+2. Navigate to **File → Make**
+3. Select **Bring your design system**
+### 2.2 Connect NPM Package
+1. In the Figma Make interface:
+   - Click **Add npm package**
+   - Enter package name: `@discourser/design-system`
+   - Select version: `latest` (should be 0.3.1+)
+   - Click **Install**
+2. Wait for package installation (may take 1-2 minutes)
+3. Figma Make will automatically detect:
+   - `guidelines/Guidelines.md` as entry point
+   - Component documentation in `guidelines/components/`
+   - Token documentation in `guidelines/design-tokens/`
+### 2.3 Verify Installation
+Check that Figma Make shows:
+- ✅ Package installed: `@discourser/design-system@0.3.1`
+- ✅ Guidelines detected: `guidelines/Guidelines.md`
+- ✅ Components found: Button, Card, Dialog, Input, IconButton, Switch
+- ✅ Tokens found: Colors, Typography, Spacing, Elevation
+## Step 3: Test AI Generation
+### 3.1 Create Test File
+1. In Figma Make, create a new file
+2. The AI should now have access to your design system
+### 3.2 Test Prompts
+Try these prompts to test the integration:
+#### Basic Component Test
+```
+Create a login form using the Discourser design system with:
+- Email input field
+- Password input field
+- Submit button (filled variant)
+- "Forgot password?" link button (text variant)
+```
+Expected result:
+- Uses `<Input>` component with proper labels
+- Uses `<Button>` components with correct variants
+- Follows spacing guidelines
+- Uses semantic color tokens
+#### Color Token Test
+```
+Create a Card component with:
+- Primary color header
+- Surface container background
+- Elevated variant
+```
+Expected result:
+- Uses `<Card variant="elevated">`
+- Header uses `bg: 'primary'` and `color: 'onPrimary'`
+- Proper surface container elevation
+#### Complex Layout Test
+```
+Create a settings page with:
+- Page heading
+- Three sections using Cards
+- Each section has switches for toggle options
+- Save and Cancel buttons at bottom
+```
+Expected result:
+- Uses proper component hierarchy
+- Consistent spacing throughout
+- Correct button hierarchy (filled for Save, outlined for Cancel)
+- Switch components with proper labels
+### 3.3 Validation Checklist
+After each generation, verify:
+- [ ] Components imported from `@discourser/design-system`
+- [ ] No native HTML elements used (no `<button>`, `<input>`, etc.)
+- [ ] Color tokens are semantic (no hex values)
+- [ ] Proper variant selection (filled for primary, outlined for secondary)
+- [ ] Labels provided for all inputs
+- [ ] Spacing uses design tokens
+- [ ] Theme support works (data-theme attribute)
+## Step 4: Common Issues and Solutions
+### Issue: Guidelines Not Found
+**Symptom:** Figma Make shows "No guidelines detected"
+**Solutions:**
+1. Verify package version is 0.3.1+
+2. Check npm package contents:
+   ```bash
+   npm pack @discourser/design-system --dry-run
+   ```
+3. Reinstall package in Figma Make
+4. Try manually specifying guidelines path: `guidelines/Guidelines.md`
+### Issue: AI Not Following Guidelines
+**Symptom:** AI generates code with wrong patterns (native HTML, hex colors, etc.)
+**Solutions:**
+1. Be more explicit in prompts: "Use the Discourser design system components"
+2. Add constraints: "Do not use native HTML elements"
+3. Reference specific guideline sections: "Follow the button guidelines for variant selection"
+4. Check if Guidelines.md is being read by AI (ask it to summarize the guidelines)
+### Issue: Components Not Importing
+**Symptom:** Generated code has import errors
+**Solutions:**
+1. Verify React peer dependencies: `react>=19.0.0`, `react-dom>=19.0.0`
+2. Check package exports in package.json
+3. Ensure generated imports match export structure:
+   ```typescript
+   // Correct
+   import { Button } from '@discourser/design-system';
+   import { css } from '@discourser/design-system/styled-system/css';
+   ```
+### Issue: Wrong Semantic Tokens
+**Symptom:** AI uses wrong token names or hex values
+**Solutions:**
+1. Reference color guidelines: "Follow the color token guidelines"
+2. Be specific: "Use primary and onPrimary semantic tokens"
+3. Check if `design-tokens/colors.md` is accessible
+## Step 5: Advanced Usage
+### Creating Templates
+Once your design system works in Figma Make, create reusable templates:
+1. Generate a well-structured component
+2. Save as template in Figma Make
+3. Name clearly: "Login Form - Discourser DS"
+4. Add description with key patterns used
+5. Share with team
+### Iterating on Designs
+Use Figma Make's iteration features:
+1. Generate initial design
+2. Request variations: "Make it more compact"
+3. Refine: "Use tonal variant for secondary action"
+4. Export final code
+### Team Onboarding
+Use Figma Make as teaching tool:
+1. New team members can explore design system through AI
+2. Generate examples to understand patterns
+3. Learn proper component usage through generated code
+4. Build familiarity with token system
+## Guidelines Structure Reference
+Your guidelines are already optimally structured for Figma Make:
+```
+guidelines/
+├── Guidelines.md                    # Entry point (REQUIRED)
+├── overview-components.md           # Component overview
+├── design-tokens/                   # Token documentation
+│   ├── colors.md                   # Semantic color tokens
+│   ├── typography.md               # Text styles
+│   ├── spacing.md                  # Space scale
+│   └── elevation.md                # Elevation system
+└── components/                      # Component documentation
+    ├── button.md                   # Button component
+    ├── card.md                     # Card component
+    ├── dialog.md                   # Dialog component
+    ├── icon-button.md              # IconButton component
+    ├── input.md                    # Input component
+    └── switch.md                   # Switch component
+```
+## Best Practices
+### Writing Effective Prompts
+✅ **Good Prompts:**
+```
+Create a user profile card using Discourser design system:
+- Card with elevated variant
+- Avatar image (use placeholder)
+- Name as heading size md
+- Bio text with onSurfaceVariant color
+- Edit button with outlined variant
+```
+❌ **Poor Prompts:**
+```
+Make a profile card
+```
+### Monitoring AI Behavior
+Track how well AI follows guidelines:
+- Document patterns AI handles well
+- Note areas where AI deviates
+- Update guidelines to address gaps
+- Share findings with team
+### Continuous Improvement
+Improve integration over time:
+1. Collect examples of good/bad AI generations
+2. Identify guideline gaps
+3. Enhance component documentation
+4. Add more DO/DON'T examples
+5. Republish package with improvements
+## Resources
+- Figma Make Documentation: https://developers.figma.com/docs/code
+- Package on npm: https://www.npmjs.com/package/@discourser/design-system
+- Repository: https://github.com/Tasty-Maker-Studio/Discourser-Design-System
+- Storybook: https://discourser-design-system.netlify.app/
+## Support
+For issues or questions:
+1. Check guidelines in `/guidelines` directory
+2. Review Figma Make documentation
+3. Open issue on GitHub
+4. Contact maintainers
+---
+**Last Updated:** 2026-01-12
+**Package Version:** 0.3.1
+**Figma Make Support:** Yes