@discourser/design-system 0.13.0 → 0.14.0

package/dist/preset/semantic-tokens.d.ts

@@ -99,7 +99,7 @@ export declare const m3SemanticTokens: {
             };
         };
     };
-    secondary: {
+    m3Secondary: {
         DEFAULT: {
             value: {
                 base: string;
@@ -113,7 +113,7 @@ export declare const m3SemanticTokens: {
             };
         };
     };
-    onSecondary: {
+    onM3Secondary: {
         DEFAULT: {
             value: {
                 base: string;
@@ -127,7 +127,7 @@ export declare const m3SemanticTokens: {
             };
         };
     };
-    tertiary: {
+    m3Tertiary: {
         DEFAULT: {
             value: {
                 base: string;
@@ -141,7 +141,7 @@ export declare const m3SemanticTokens: {
             };
         };
     };
-    onTertiary: {
+    onM3Tertiary: {
         DEFAULT: {
             value: {
                 base: string;

package/dist/preset/shadows.d.ts

@@ -1,43 +1,29 @@
 /**
- * Shadow semantic tokens from Park UI
- * Adjusted to use 'base' instead of '_light' and neutral.a* instead of black.a*
+ * Shadow semantic tokens - chained to M3 base elevation tokens
+ *
+ * Three-layer architecture:
+ * 1. Base tokens (level0-5): M3 elevation values defined in transform.ts
+ * 2. Semantic tokens (xs-2xl): Reference base tokens for consistency
+ * 3. Components: Use semantic tokens for flexibility
  */
 export declare const shadows: {
     xs: {
-        value: {
-            base: string;
-            _dark: string;
-        };
+        value: string;
     };
     sm: {
-        value: {
-            base: string;
-            _dark: string;
-        };
+        value: string;
     };
     md: {
-        value: {
-            base: string;
-            _dark: string;
-        };
+        value: string;
     };
     lg: {
-        value: {
-            base: string;
-            _dark: string;
-        };
+        value: string;
     };
     xl: {
-        value: {
-            base: string;
-            _dark: string;
-        };
+        value: string;
     };
     '2xl': {
-        value: {
-            base: string;
-            _dark: string;
-        };
+        value: string;
     };
     inset: {
         value: {

package/dist/preset/shadows.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shadows.d.ts","sourceRoot":"","sources":["../../src/preset/shadows.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2ClB,CAAC"}
+{"version":3,"file":"shadows.d.ts","sourceRoot":"","sources":["../../src/preset/shadows.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;CAyBlB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@discourser/design-system",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Aesthetic-agnostic design system with Panda CSS and Ark UI",
   "type": "module",
   "publishConfig": {
@@ -202,11 +202,11 @@
     "@eslint/js": "^9.0.0",
     "@material/material-color-utilities": "^0.3.0",
     "@pandacss/dev": "^1.8.0",
-    "@storybook/addon-a11y": "^8.5.0",
-    "@storybook/addon-essentials": "^8.5.0",
-    "@storybook/addon-styling": "^1.3.7",
-    "@storybook/react": "^8.5.0",
-    "@storybook/react-vite": "^8.5.0",
+    "@storybook/addon-a11y": "^10.2.8",
+    "@storybook/addon-docs": "^10.2.8",
+    "@storybook/addon-mcp": "^0.2.2",
+    "@storybook/react": "^10.2.8",
+    "@storybook/react-vite": "^10.2.8",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.1",
     "@testing-library/user-event": "^14.6.1",
@@ -222,6 +222,7 @@
     "eslint": "^9.0.0",
     "eslint-plugin-react": "^7.35.0",
     "eslint-plugin-react-hooks": "^5.0.0",
+    "eslint-plugin-storybook": "10.2.8",
     "husky": "^9.1.7",
     "inquirer": "^13.1.0",
     "jest-axe": "^10.0.0",
@@ -230,7 +231,7 @@
     "prettier": "^3.3.1",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "storybook": "^8.5.0",
+    "storybook": "^10.2.8",
     "tsup": "^8.3.0",
     "tsx": "^4.19.0",
     "typescript": "^5.7.0",

package/src/components/Badge.tsx

@@ -13,7 +13,7 @@ export interface BadgeProps extends Omit<BaseBadgeProps, 'colorPalette'> {
    * The color palette to use for the badge.
    * @default "primary"
    */
-  colorPalette?: 'primary' | 'neutral' | 'error' | 'gray' | 'red' | undefined;
+  colorPalette?: 'primary' | 'secondary' | 'tertiary' | 'neutral' | 'error' | 'gray' | 'red' | undefined;
 }
 
 export const Badge = forwardRef<HTMLDivElement, BadgeProps>(

package/src/languages/__tests__/transform.test.ts

@@ -0,0 +1,100 @@
+import { describe, it, expect } from 'vitest';
+import { transformToPandaTheme } from '../transform';
+import { material3Language } from '../material3.language';
+
+describe('Design Language Transform', () => {
+  const pandaTheme = transformToPandaTheme(material3Language);
+
+  describe('Shadow base tokens', () => {
+    it('should transform elevation.levels to shadow tokens', () => {
+      expect(pandaTheme.tokens.shadows).toBeDefined();
+      expect(pandaTheme.tokens.shadows).toHaveProperty('level0');
+      expect(pandaTheme.tokens.shadows).toHaveProperty('level1');
+      expect(pandaTheme.tokens.shadows).toHaveProperty('level2');
+      expect(pandaTheme.tokens.shadows).toHaveProperty('level3');
+      expect(pandaTheme.tokens.shadows).toHaveProperty('level4');
+      expect(pandaTheme.tokens.shadows).toHaveProperty('level5');
+    });
+
+    it('should preserve M3 shadow values exactly', () => {
+      const expected = material3Language.elevation.levels;
+
+      expect(pandaTheme.tokens.shadows.level0.value).toBe(expected.level0);
+      expect(pandaTheme.tokens.shadows.level1.value).toBe(expected.level1);
+      expect(pandaTheme.tokens.shadows.level2.value).toBe(expected.level2);
+      expect(pandaTheme.tokens.shadows.level3.value).toBe(expected.level3);
+      expect(pandaTheme.tokens.shadows.level4.value).toBe(expected.level4);
+      expect(pandaTheme.tokens.shadows.level5.value).toBe(expected.level5);
+    });
+
+    it('level0 should be none (no shadow)', () => {
+      expect(pandaTheme.tokens.shadows.level0.value).toBe('none');
+    });
+
+    it('level1-5 should contain rgba shadow values', () => {
+      expect(pandaTheme.tokens.shadows.level1.value).toContain('rgba');
+      expect(pandaTheme.tokens.shadows.level2.value).toContain('rgba');
+      expect(pandaTheme.tokens.shadows.level3.value).toContain('rgba');
+      expect(pandaTheme.tokens.shadows.level4.value).toContain('rgba');
+      expect(pandaTheme.tokens.shadows.level5.value).toContain('rgba');
+    });
+
+    it('shadow values should follow M3 pattern (two shadows)', () => {
+      // M3 shadows typically have two parts: ambient and directional
+      const shadowLevels = [1, 2, 3, 4, 5];
+
+      shadowLevels.forEach(level => {
+        const shadowValue = pandaTheme.tokens.shadows[`level${level}`].value;
+        const shadowParts = shadowValue.split(',').length;
+
+        // Should have 2 parts (ambient + directional)
+        expect(shadowParts).toBeGreaterThanOrEqual(2);
+      });
+    });
+  });
+
+  describe('Elevation progression', () => {
+    it('should have increasing shadow complexity from level1 to level5', () => {
+      // Extract shadow strings and check they increase in complexity
+      // This is a heuristic test - higher levels should have larger offsets/blur
+
+      const levels = [1, 2, 3, 4, 5].map(
+        level => pandaTheme.tokens.shadows[`level${level}`].value
+      );
+
+      // Check that each level is different
+      const uniqueLevels = new Set(levels);
+      expect(uniqueLevels.size).toBe(5);
+
+      // Check that level1 is simpler than level5 (by string length as proxy)
+      expect(levels[0].length).toBeLessThan(levels[4].length);
+    });
+  });
+
+  describe('Transform function integrity', () => {
+    it('should not modify the original language object', () => {
+      const original = JSON.stringify(material3Language);
+      transformToPandaTheme(material3Language);
+      const after = JSON.stringify(material3Language);
+
+      expect(after).toBe(original);
+    });
+
+    it('should return theme with expected structure', () => {
+      expect(pandaTheme).toHaveProperty('tokens');
+      expect(pandaTheme).toHaveProperty('semanticTokens');
+      expect(pandaTheme).toHaveProperty('textStyles');
+    });
+
+    it('should transform all token categories', () => {
+      expect(pandaTheme.tokens).toHaveProperty('colors');
+      expect(pandaTheme.tokens).toHaveProperty('fonts');
+      expect(pandaTheme.tokens).toHaveProperty('fontSizes');
+      expect(pandaTheme.tokens).toHaveProperty('spacing');
+      expect(pandaTheme.tokens).toHaveProperty('radii');
+      expect(pandaTheme.tokens).toHaveProperty('shadows');
+      expect(pandaTheme.tokens).toHaveProperty('durations');
+      expect(pandaTheme.tokens).toHaveProperty('easings');
+    });
+  });
+});

package/src/preset/__tests__/shadows.test.ts

@@ -0,0 +1,83 @@
+import { describe, it, expect } from 'vitest';
+import { shadows } from '../shadows';
+
+describe('Shadow Token Architecture', () => {
+  describe('Semantic tokens chain to M3 base tokens', () => {
+    it('xs should reference shadows.level1', () => {
+      expect(shadows.xs.value).toBe('{shadows.level1}');
+    });
+
+    it('sm should reference shadows.level2', () => {
+      expect(shadows.sm.value).toBe('{shadows.level2}');
+    });
+
+    it('md should reference shadows.level3', () => {
+      expect(shadows.md.value).toBe('{shadows.level3}');
+    });
+
+    it('lg should reference shadows.level4', () => {
+      expect(shadows.lg.value).toBe('{shadows.level4}');
+    });
+
+    it('xl should reference shadows.level5', () => {
+      expect(shadows.xl.value).toBe('{shadows.level5}');
+    });
+
+    it('2xl should reference shadows.level5', () => {
+      expect(shadows['2xl'].value).toBe('{shadows.level5}');
+    });
+  });
+
+  describe('Utility tokens remain independent', () => {
+    it('inset should have base and _dark values (not reference base tokens)', () => {
+      expect(shadows.inset.value).toHaveProperty('base');
+      expect(shadows.inset.value).toHaveProperty('_dark');
+      expect(typeof shadows.inset.value.base).toBe('string');
+      expect(shadows.inset.value.base).toContain('inset');
+    });
+
+    it('inset should not reference a level token', () => {
+      expect(shadows.inset.value.base).not.toMatch(/\{shadows\.level\d\}/);
+    });
+  });
+
+  describe('Token coverage', () => {
+    it('should have all required semantic shadow tokens', () => {
+      const requiredTokens = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', 'inset'];
+      const definedTokens = Object.keys(shadows);
+
+      requiredTokens.forEach(token => {
+        expect(definedTokens).toContain(token);
+      });
+    });
+
+    it('should not have unexpected tokens', () => {
+      const allowedTokens = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', 'inset', 'focus-underline', 'inset-border'];
+      const definedTokens = Object.keys(shadows);
+
+      definedTokens.forEach(token => {
+        expect(allowedTokens).toContain(token);
+      });
+    });
+  });
+
+  describe('No hardcoded Park UI values', () => {
+    it('semantic elevation tokens should not contain hardcoded color references', () => {
+      const elevationTokens = ['xs', 'sm', 'md', 'lg', 'xl', '2xl'];
+
+      elevationTokens.forEach(token => {
+        const value = shadows[token as keyof typeof shadows].value;
+
+        // Should be a string reference, not an object with base/_dark
+        expect(typeof value).toBe('string');
+
+        // Should reference a level token
+        expect(value).toMatch(/^\{shadows\.level\d\}$/);
+
+        // Should NOT contain color references
+        expect(value).not.toContain('{colors.');
+        expect(value).not.toContain('rgba');
+      });
+    });
+  });
+});

package/src/preset/__tests__/token-resolution.test.ts

@@ -0,0 +1,247 @@
+import { describe, it, expect } from 'vitest';
+import { discourserPandaPreset as preset } from '../index';
+
+/**
+ * Integration tests for token resolution
+ * These tests verify that the full Panda config resolves tokens correctly
+ */
+describe('Token Resolution Integration', () => {
+
+  describe('Shadow token resolution', () => {
+    it('preset should include semantic shadow tokens', () => {
+      expect(preset.theme?.extend?.semanticTokens?.shadows).toBeDefined();
+
+      const shadows = preset.theme?.extend?.semanticTokens?.shadows;
+      expect(shadows).toHaveProperty('xs');
+      expect(shadows).toHaveProperty('sm');
+      expect(shadows).toHaveProperty('md');
+      expect(shadows).toHaveProperty('lg');
+      expect(shadows).toHaveProperty('xl');
+      expect(shadows).toHaveProperty('2xl');
+      expect(shadows).toHaveProperty('inset');
+    });
+
+    it('preset should include base shadow tokens from M3', () => {
+      expect(preset.theme?.extend?.tokens?.shadows).toBeDefined();
+
+      const shadows = preset.theme?.extend?.tokens?.shadows;
+      expect(shadows).toHaveProperty('level0');
+      expect(shadows).toHaveProperty('level1');
+      expect(shadows).toHaveProperty('level2');
+      expect(shadows).toHaveProperty('level3');
+      expect(shadows).toHaveProperty('level4');
+      expect(shadows).toHaveProperty('level5');
+    });
+
+    it('semantic tokens should reference base tokens using token syntax', () => {
+      const semanticShadows = preset.theme?.extend?.semanticTokens?.shadows;
+
+      expect(semanticShadows?.xs?.value).toBe('{shadows.level1}');
+      expect(semanticShadows?.sm?.value).toBe('{shadows.level2}');
+      expect(semanticShadows?.md?.value).toBe('{shadows.level3}');
+      expect(semanticShadows?.lg?.value).toBe('{shadows.level4}');
+      expect(semanticShadows?.xl?.value).toBe('{shadows.level5}');
+      expect(semanticShadows?.['2xl']?.value).toBe('{shadows.level5}');
+    });
+  });
+
+  describe('Recipe shadow usage', () => {
+    it('button recipe should be included in preset', () => {
+      const recipes = preset.theme?.extend?.recipes;
+      expect(recipes).toHaveProperty('button');
+    });
+
+    it('button recipe should use semantic shadow tokens', () => {
+      const button = preset.theme?.extend?.recipes?.button;
+      // Panda CSS conditional styles (_hover, _active) are not in SystemStyleObject type
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const elevated = button?.variants?.variant?.elevated as any;
+
+      expect(elevated?.boxShadow).toBe('sm');
+      expect(elevated?._hover?.boxShadow).toBe('md');
+      expect(elevated?._active?.boxShadow).toBe('xs');
+    });
+  });
+
+  describe('Preset structure', () => {
+    it('should have required theme extensions', () => {
+      expect(preset.theme?.extend).toBeDefined();
+      expect(preset.theme?.extend?.tokens).toBeDefined();
+      expect(preset.theme?.extend?.semanticTokens).toBeDefined();
+      expect(preset.theme?.extend?.recipes).toBeDefined();
+    });
+
+    it('should include color palette transformations', () => {
+      const colors = preset.theme?.extend?.tokens?.colors;
+
+      // M3 uses tonal palettes
+      expect(colors).toHaveProperty('primary');
+      expect(colors).toHaveProperty('secondary');
+      expect(colors).toHaveProperty('tertiary');
+      expect(colors).toHaveProperty('neutral');
+      expect(colors).toHaveProperty('error');
+    });
+  });
+
+  describe('Token reference integrity', () => {
+    it('semantic tokens should only reference existing base tokens', () => {
+      const baseShadows = preset.theme?.extend?.tokens?.shadows;
+      const semanticShadows = preset.theme?.extend?.semanticTokens?.shadows;
+
+      const baseTokenNames = Object.keys(baseShadows || {});
+
+      Object.entries(semanticShadows || {}).forEach(([_name, config]) => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const value = (config as any)?.value;
+
+        // If it's a token reference, verify the referenced token exists
+        if (typeof value === 'string' && value.match(/^\{shadows\./)) {
+          const referencedToken = value.replace(/^\{shadows\./, '').replace(/\}$/, '');
+
+          if (referencedToken.startsWith('level')) {
+            expect(baseTokenNames).toContain(referencedToken);
+          }
+        }
+      });
+    });
+
+    it('should not have circular token references', () => {
+      const semanticShadows = preset.theme?.extend?.semanticTokens?.shadows;
+
+      // Semantic tokens should reference base tokens, not each other
+      Object.entries(semanticShadows || {}).forEach(([_name, config]) => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const value = (config as any)?.value;
+
+        if (typeof value === 'string' && value.match(/^\{shadows\./)) {
+          const referencedToken = value.replace(/^\{shadows\./, '').replace(/\}$/, '');
+
+          // Should reference level tokens, not other semantic tokens
+          expect(referencedToken).toMatch(/^level\d$/);
+        }
+      });
+    });
+
+    it('inset token should remain independent (not chained to level tokens)', () => {
+      const semanticShadows = preset.theme?.extend?.semanticTokens?.shadows;
+      const insetToken = semanticShadows?.inset;
+
+      // STORY-002 acceptance criterion: inset must NOT reference base tokens
+      expect(insetToken?.value).toBeDefined();
+
+      // Should be an object with base/_dark, not a string reference
+      expect(typeof insetToken?.value).toBe('object');
+      expect(insetToken?.value).toHaveProperty('base');
+      expect(insetToken?.value).toHaveProperty('_dark');
+
+      // Should NOT contain token references
+      const insetString = JSON.stringify(insetToken);
+      expect(insetString).not.toMatch(/\{shadows\.level\d\}/);
+    });
+
+    it('utility tokens (focus-underline, inset-border) should remain independent', () => {
+      const semanticShadows = preset.theme?.extend?.semanticTokens?.shadows;
+
+      const focusUnderline = semanticShadows?.['focus-underline'];
+      const insetBorder = semanticShadows?.['inset-border'];
+
+      // TODO: STORY-003 will add these utility tokens
+      // For now, they should NOT be defined (current behavior)
+      expect(focusUnderline).toBeUndefined();
+      expect(insetBorder).toBeUndefined();
+    });
+  });
+
+  describe('Design system consistency', () => {
+    it('all shadow-using recipes should use semantic or custom values', () => {
+      const recipes = preset.theme?.extend?.recipes || {};
+      const slotRecipes = preset.theme?.extend?.slotRecipes || {};
+
+      // Name mapping for recipes registered under different names
+      const nameMapping: Record<string, string> = {
+        'switch': 'switchComponent',
+      };
+
+      const recipesWithShadows = [
+        'button',
+        'card',
+        'dialog',
+        'drawer',
+        'popover',
+        'select',
+        'slider',
+        'switch',
+        'toast',
+        'tooltip',
+      ];
+
+      recipesWithShadows.forEach(recipeName => {
+        // Try to find in recipes first, then slotRecipes, accounting for name mapping
+        const mappedName = nameMapping[recipeName] || recipeName;
+        const recipe = recipes[recipeName as keyof typeof recipes] ||
+                      slotRecipes[mappedName as keyof typeof slotRecipes];
+
+        if (!recipe) {
+          throw new Error(`Recipe ${recipeName} (mapped to ${mappedName}) not found in recipes or slotRecipes`);
+        }
+
+        const recipeString = JSON.stringify(recipe);
+
+        // Should NOT use base level tokens directly
+        expect(recipeString).not.toMatch(/['"]level[0-5]['"]/);
+      });
+    });
+
+    it('ALL recipes in preset should avoid direct base token usage (system-wide check)', () => {
+      const recipes = preset.theme?.extend?.recipes || {};
+      const slotRecipes = preset.theme?.extend?.slotRecipes || {};
+
+      // Check EVERY recipe in the preset (both simple recipes and slot recipes)
+      const allRecipes = { ...recipes, ...slotRecipes };
+
+      Object.entries(allRecipes).forEach(([recipeName, recipe]) => {
+        if (!recipe) return;
+
+        const recipeString = JSON.stringify(recipe);
+
+        // No recipe should use level0-5 directly
+        const hasBaseTokens = recipeString.match(/['"]level[0-5]['"]/);
+
+        if (hasBaseTokens) {
+          // Fail with clear message showing which recipe broke the rule
+          throw new Error(`Recipe ${recipeName} contains base token reference: ${hasBaseTokens[0]}`);
+        }
+
+        expect(recipeString).not.toMatch(/boxShadow['"]?\s*:\s*['"]level\d/);
+      });
+    });
+
+    it('utility shadow tokens should be used in appropriate recipes', () => {
+      const recipes = preset.theme?.extend?.recipes || {};
+
+      // TODO: STORY-003 will migrate to utility tokens (focus-underline, inset-border)
+      // For now, recipes use inline values (current behavior)
+
+      // Input currently uses inline '0 1px 0 0 var(--shadow-color)'
+      const input = recipes.input;
+      if (input) {
+        const inputString = JSON.stringify(input);
+        expect(inputString).toContain('0 1px 0 0 var(--shadow-color)');
+      }
+
+      // Textarea currently uses inline '0 1px 0 0 var(--shadow-color)'
+      const textarea = recipes.textarea;
+      if (textarea) {
+        const textareaString = JSON.stringify(textarea);
+        expect(textareaString).toContain('0 1px 0 0 var(--shadow-color)');
+      }
+
+      // RadioGroup currently uses inline 'inset 0 0 0 1px var(--shadow-color)'
+      const radioGroup = recipes.radioGroup || recipes['radio-group'];
+      if (radioGroup) {
+        const radioString = JSON.stringify(radioGroup);
+        expect(radioString).toContain('inset 0 0 0 1px var(--shadow-color)');
+      }
+    });
+  });
+});