@discourser/design-system 0.25.3 → 0.26.0

package/src/languages/material3.language.ts

@@ -6,6 +6,10 @@ import type { DesignLanguageContract } from '../contracts/design-language.contra
  * Source color: #63A002 (TastyMakers green)
  * Generated via Material Theme Builder plugin 2024-12-24
  */
+// ⚠️  After changing this file, run `pnpm figma:export` to:
+//     1. Regenerate tokens/export-to-figma/ files for Figma import
+//     2. Regenerate docs/token-name-mapping.json for AI agent resolution
+//     3. Update docs/token-name-mapping.md manually to match
 export const material3Language: DesignLanguageContract = {
   name: 'material3',
   version: '1.0.0',
@@ -200,119 +204,284 @@ export const material3Language: DesignLanguageContract = {
 
   typography: {
     fonts: {
-      display: '"Fraunces", Georgia, serif',
-      body: '"Poppins", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
-      mono: '"JetBrains Mono", "Fira Code", Consolas, monospace',
+      display: {
+        family: '"Fraunces", Georgia, serif',
+        figmaName: 'Fraunces',
+        weightMap: {
+          '100': 'Thin',
+          '300': 'Light',
+          '400': 'Regular',
+          '500': 'Medium',
+          '600': 'SemiBold',
+          '700': 'Bold',
+        },
+      },
+      body: {
+        family:
+          '"Poppins", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
+        figmaName: 'Poppins',
+        weightMap: {
+          '100': 'Thin',
+          '300': 'Light',
+          '400': 'Regular',
+          '500': 'Medium',
+          '600': 'SemiBold',
+          '700': 'Bold',
+        },
+      },
+      mono: {
+        family: '"JetBrains Mono", "Fira Code", Consolas, monospace',
+        figmaName: 'JetBrains Mono',
+        weightMap: {
+          '400': 'Regular',
+          '700': 'Bold',
+        },
+      },
     },
     scale: {
+      // ── Display ─────────────────────────────────────────────────────────────
+
       displayLarge: {
-        fontSize: '57px',
-        lineHeight: '64px',
-        fontWeight: '400',
-        letterSpacing: '-0.25px',
-        fontFamily: 'display',
-        fontVariationSettings: "'SOFT' 0, 'WONK' 1",
+        geometry: {
+          fontSize: '57px',
+          lineHeight: '64px',
+          letterSpacing: '-0.25px',
+          fontFamily: 'display',
+          fontVariationSettings: "'SOFT' 0, 'WONK' 1",
+        },
+        defaultWeight: 'regular',
+        weights: {
+          regular: { name: 'regular', fontWeight: '400' },
+          semiBold: { name: 'semiBold', fontWeight: '600' },
+        },
       },
+
       displayMedium: {
-        fontSize: '45px',
-        lineHeight: '52px',
-        fontWeight: '400',
-        letterSpacing: '0px',
-        fontFamily: 'display',
+        geometry: {
+          fontSize: '45px',
+          lineHeight: '52px',
+          letterSpacing: '0px',
+          fontFamily: 'display',
+        },
+        defaultWeight: 'regular',
+        weights: {
+          regular: { name: 'regular', fontWeight: '400' },
+          semiBold: { name: 'semiBold', fontWeight: '600' },
+        },
       },
+
       displaySmall: {
-        fontSize: '36px',
-        lineHeight: '44px',
-        fontWeight: '400',
-        letterSpacing: '0px',
-        fontFamily: 'display',
+        geometry: {
+          fontSize: '36px',
+          lineHeight: '44px',
+          letterSpacing: '0px',
+          fontFamily: 'display',
+        },
+        defaultWeight: 'regular',
+        weights: {
+          regular: { name: 'regular', fontWeight: '400' },
+          semiBold: { name: 'semiBold', fontWeight: '600' },
+        },
       },
+
+      // ── Headline ────────────────────────────────────────────────────────────
+
       headlineLarge: {
-        fontSize: '32px',
-        lineHeight: '40px',
-        fontWeight: '400',
-        letterSpacing: '0px',
-        fontFamily: 'display',
+        geometry: {
+          fontSize: '32px',
+          lineHeight: '40px',
+          letterSpacing: '0px',
+          fontFamily: 'display',
+        },
+        defaultWeight: 'regular',
+        weights: {
+          light: { name: 'light', fontWeight: '300' },
+          regular: { name: 'regular', fontWeight: '400' },
+          semiBold: { name: 'semiBold', fontWeight: '600' },
+        },
       },
+
       headlineMedium: {
-        fontSize: '28px',
-        lineHeight: '36px',
-        fontWeight: '400',
-        letterSpacing: '0px',
-        fontFamily: 'display',
-        fontVariationSettings: "'SOFT' 0, 'WONK' 1",
+        geometry: {
+          fontSize: '28px',
+          lineHeight: '36px',
+          letterSpacing: '0px',
+          fontFamily: 'display',
+          fontVariationSettings: "'SOFT' 0, 'WONK' 1",
+        },
+        defaultWeight: 'regular',
+        weights: {
+          light: { name: 'light', fontWeight: '300' },
+          regular: { name: 'regular', fontWeight: '400' },
+          semiBold: { name: 'semiBold', fontWeight: '600' },
+        },
       },
+
       headlineSmall: {
-        fontSize: '24px',
-        lineHeight: '32px',
-        fontWeight: '400',
-        letterSpacing: '0px',
-        fontFamily: 'display',
+        geometry: {
+          fontSize: '24px',
+          lineHeight: '32px',
+          letterSpacing: '0px',
+          fontFamily: 'display',
+        },
+        defaultWeight: 'regular',
+        weights: {
+          light: { name: 'light', fontWeight: '300' },
+          regular: { name: 'regular', fontWeight: '400' },
+          semiBold: { name: 'semiBold', fontWeight: '600' },
+        },
       },
+
+      // ── Title ────────────────────────────────────────────────────────────────
+
       titleLarge: {
-        fontSize: '22px',
-        lineHeight: '28px',
-        fontWeight: '500',
-        letterSpacing: '0px',
-        fontFamily: 'body',
+        geometry: {
+          fontSize: '22px',
+          lineHeight: '28px',
+          letterSpacing: '0px',
+          fontFamily: 'body',
+        },
+        defaultWeight: 'medium',
+        weights: {
+          regular: { name: 'regular', fontWeight: '400' },
+          medium: { name: 'medium', fontWeight: '500' },
+          semiBold: { name: 'semiBold', fontWeight: '600' },
+          bold: { name: 'bold', fontWeight: '700' },
+        },
       },
+
       titleMedium: {
-        fontSize: '16px',
-        lineHeight: '24px',
-        fontWeight: '500',
-        letterSpacing: '0.15px',
-        fontFamily: 'body',
+        geometry: {
+          fontSize: '16px',
+          lineHeight: '24px',
+          letterSpacing: '0.15px',
+          fontFamily: 'body',
+        },
+        defaultWeight: 'medium',
+        weights: {
+          regular: { name: 'regular', fontWeight: '400' },
+          medium: { name: 'medium', fontWeight: '500' },
+          semiBold: { name: 'semiBold', fontWeight: '600' },
+          bold: { name: 'bold', fontWeight: '700' },
+        },
       },
+
       titleSmall: {
-        fontSize: '14px',
-        lineHeight: '20px',
-        fontWeight: '500',
-        letterSpacing: '0.1px',
-        fontFamily: 'body',
+        geometry: {
+          fontSize: '14px',
+          lineHeight: '20px',
+          letterSpacing: '0.1px',
+          fontFamily: 'body',
+        },
+        defaultWeight: 'medium',
+        weights: {
+          regular: { name: 'regular', fontWeight: '400' },
+          medium: { name: 'medium', fontWeight: '500' },
+          semiBold: { name: 'semiBold', fontWeight: '600' },
+          bold: { name: 'bold', fontWeight: '700' },
+        },
       },
+
+      // ── Body ─────────────────────────────────────────────────────────────────
       // Custom override: bodyLarge bumped to 18px/28px (was M3 default 16px/24px)
       // Decision date: 2026-03-24
+
       bodyLarge: {
-        fontSize: '18px',
-        lineHeight: '28px',
-        fontWeight: '400',
-        letterSpacing: '0.5px',
-        fontFamily: 'body',
+        geometry: {
+          fontSize: '18px',
+          lineHeight: '28px',
+          letterSpacing: '0.5px',
+          fontFamily: 'body',
+        },
+        defaultWeight: 'regular',
+        weights: {
+          light: { name: 'light', fontWeight: '300' },
+          regular: { name: 'regular', fontWeight: '400' },
+          medium: { name: 'medium', fontWeight: '500' },
+          semiBold: { name: 'semiBold', fontWeight: '600' },
+        },
       },
+
       bodyMedium: {
-        fontSize: '14px',
-        lineHeight: '20px',
-        fontWeight: '400',
-        letterSpacing: '0.25px',
-        fontFamily: 'body',
+        geometry: {
+          fontSize: '14px',
+          lineHeight: '20px',
+          letterSpacing: '0.25px',
+          fontFamily: 'body',
+        },
+        defaultWeight: 'regular',
+        weights: {
+          light: { name: 'light', fontWeight: '300' },
+          regular: { name: 'regular', fontWeight: '400' },
+          medium: { name: 'medium', fontWeight: '500' },
+          semiBold: { name: 'semiBold', fontWeight: '600' },
+        },
       },
+
       bodySmall: {
-        fontSize: '12px',
-        lineHeight: '16px',
-        fontWeight: '400',
-        letterSpacing: '0.4px',
-        fontFamily: 'body',
+        geometry: {
+          fontSize: '12px',
+          lineHeight: '16px',
+          letterSpacing: '0.4px',
+          fontFamily: 'body',
+        },
+        defaultWeight: 'regular',
+        weights: {
+          light: { name: 'light', fontWeight: '300' },
+          regular: { name: 'regular', fontWeight: '400' },
+          medium: { name: 'medium', fontWeight: '500' },
+          semiBold: { name: 'semiBold', fontWeight: '600' },
+        },
       },
+
+      // ── Label ────────────────────────────────────────────────────────────────
+
       labelLarge: {
-        fontSize: '14px',
-        lineHeight: '20px',
-        fontWeight: '500',
-        letterSpacing: '0.1px',
-        fontFamily: 'body',
+        geometry: {
+          fontSize: '14px',
+          lineHeight: '20px',
+          letterSpacing: '0.1px',
+          fontFamily: 'body',
+        },
+        defaultWeight: 'medium',
+        weights: {
+          light: { name: 'light', fontWeight: '300' },
+          medium: { name: 'medium', fontWeight: '500' },
+          semiBold: { name: 'semiBold', fontWeight: '600' },
+          bold: { name: 'bold', fontWeight: '700' },
+        },
       },
+
       labelMedium: {
-        fontSize: '12px',
-        lineHeight: '16px',
-        fontWeight: '500',
-        letterSpacing: '0.5px',
-        fontFamily: 'body',
+        geometry: {
+          fontSize: '12px',
+          lineHeight: '16px',
+          letterSpacing: '0.5px',
+          fontFamily: 'body',
+        },
+        defaultWeight: 'medium',
+        weights: {
+          light: { name: 'light', fontWeight: '300' },
+          medium: { name: 'medium', fontWeight: '500' },
+          semiBold: { name: 'semiBold', fontWeight: '600' },
+          bold: { name: 'bold', fontWeight: '700' },
+        },
       },
+
       labelSmall: {
-        fontSize: '11px',
-        lineHeight: '16px',
-        fontWeight: '500',
-        letterSpacing: '0.5px',
-        fontFamily: 'body',
+        geometry: {
+          fontSize: '11px',
+          lineHeight: '16px',
+          letterSpacing: '0.5px',
+          fontFamily: 'body',
+        },
+        defaultWeight: 'medium',
+        weights: {
+          light: { name: 'light', fontWeight: '300' },
+          medium: { name: 'medium', fontWeight: '500' },
+          semiBold: { name: 'semiBold', fontWeight: '600' },
+          bold: { name: 'bold', fontWeight: '700' },
+        },
       },
     },
   },

package/src/languages/transform.ts

@@ -1,6 +1,7 @@
 import type {
   DesignLanguageContract,
   TonalPalette,
+  TypeScaleStep,
 } from '../contracts/design-language.contract';
 /**
  * Transforms a DesignLanguageContract into Panda CSS theme configuration
@@ -19,33 +20,21 @@ function transformTokens(language: DesignLanguageContract) {
       language.colors as unknown as Record<string, TonalPalette>,
     ),
     fonts: {
-      display: { value: language.typography.fonts.display },
-      body: { value: language.typography.fonts.body },
-      mono: { value: language.typography.fonts.mono },
+      display: { value: language.typography.fonts.display.family },
+      body: { value: language.typography.fonts.body.family },
+      mono: { value: language.typography.fonts.mono.family },
     },
     fontSizes: extractFontSizes(
-      language.typography.scale as unknown as Record<
-        string,
-        { fontSize: string }
-      >,
+      language.typography.scale as unknown as Record<string, TypeScaleStep>,
     ),
     lineHeights: extractLineHeights(
-      language.typography.scale as unknown as Record<
-        string,
-        { lineHeight: string }
-      >,
+      language.typography.scale as unknown as Record<string, TypeScaleStep>,
     ),
     fontWeights: extractFontWeights(
-      language.typography.scale as unknown as Record<
-        string,
-        { fontWeight: string }
-      >,
+      language.typography.scale as unknown as Record<string, TypeScaleStep>,
     ),
     letterSpacings: extractLetterSpacings(
-      language.typography.scale as unknown as Record<
-        string,
-        { letterSpacing: string }
-      >,
+      language.typography.scale as unknown as Record<string, TypeScaleStep>,
     ),
     spacing: objectToTokens(
       language.spacing as unknown as Record<string, string>,
@@ -77,24 +66,32 @@ function transformSemanticTokens(_language: DesignLanguageContract) {
 }
 
 function transformTextStyles(language: DesignLanguageContract) {
-  const scale = language.typography.scale;
+  const scale = language.typography.scale as unknown as Record<
+    string,
+    TypeScaleStep
+  >;
 
   return Object.fromEntries(
-    Object.entries(scale).map(([name, style]) => [
-      name,
-      {
-        value: {
-          fontFamily: `{fonts.${style.fontFamily || 'body'}}`,
-          fontSize: style.fontSize,
-          lineHeight: style.lineHeight,
-          fontWeight: style.fontWeight,
-          letterSpacing: style.letterSpacing,
-          ...(style.fontVariationSettings
-            ? { fontVariationSettings: style.fontVariationSettings }
-            : {}),
+    Object.entries(scale).map(([name, step]) => {
+      const s = step as TypeScaleStep;
+      const defaultVariant = s.weights[s.defaultWeight];
+      const fontWeight = defaultVariant?.fontWeight ?? '400';
+      return [
+        name,
+        {
+          value: {
+            fontFamily: `{fonts.${s.geometry.fontFamily}}`,
+            fontSize: s.geometry.fontSize,
+            lineHeight: s.geometry.lineHeight,
+            fontWeight,
+            letterSpacing: s.geometry.letterSpacing,
+            ...(s.geometry.fontVariationSettings
+              ? { fontVariationSettings: s.geometry.fontVariationSettings }
+              : {}),
+          },
         },
-      },
-    ]),
+      ];
+    }),
   );
 }
 
@@ -115,41 +112,41 @@ function objectToTokens<T extends Record<string, string>>(obj: T) {
   );
 }
 
-function extractFontSizes(scale: Record<string, { fontSize: string }>) {
+function extractFontSizes(scale: Record<string, TypeScaleStep>) {
   return Object.fromEntries(
-    Object.entries(scale).map(([name, style]) => [
+    Object.entries(scale).map(([name, step]) => [
       name,
-      { value: style.fontSize },
+      { value: step.geometry.fontSize },
     ]),
   );
 }
 
-function extractLineHeights(scale: Record<string, { lineHeight: string }>) {
+function extractLineHeights(scale: Record<string, TypeScaleStep>) {
   return Object.fromEntries(
-    Object.entries(scale).map(([name, style]) => [
+    Object.entries(scale).map(([name, step]) => [
       name,
-      { value: style.lineHeight },
+      { value: step.geometry.lineHeight },
     ]),
   );
 }
 
-function extractFontWeights(scale: Record<string, { fontWeight: string }>) {
+function extractFontWeights(scale: Record<string, TypeScaleStep>) {
   const weights = new Map<string, string>();
-  Object.values(scale).forEach((style) => {
-    weights.set(style.fontWeight, style.fontWeight);
+  Object.values(scale).forEach((step) => {
+    Object.values(step.weights).forEach((variant) => {
+      if (variant) weights.set(variant.fontWeight, variant.fontWeight);
+    });
   });
   return Object.fromEntries(
     Array.from(weights.entries()).map(([key, value]) => [key, { value }]),
   );
 }
 
-function extractLetterSpacings(
-  scale: Record<string, { letterSpacing: string }>,
-) {
+function extractLetterSpacings(scale: Record<string, TypeScaleStep>) {
   return Object.fromEntries(
-    Object.entries(scale).map(([name, style]) => [
+    Object.entries(scale).map(([name, step]) => [
       name,
-      { value: style.letterSpacing },
+      { value: step.geometry.letterSpacing },
     ]),
   );
 }

package/src/preset/__tests__/translation-token-accuracy.test.ts

@@ -114,6 +114,19 @@ function buildKnownTokenList(): Set<string> {
   ];
   surfaceTokens.forEach((token) => tokens.add(token));
 
+  // Add M3 role container tokens (nested dot-notation)
+  const containerTokens = [
+    'primary.container',
+    'onPrimary.container',
+    'secondary.container',
+    'onSecondary.container',
+    'tertiary.container',
+    'onTertiary.container',
+    'error.container',
+    'onError.container',
+  ];
+  containerTokens.forEach((token) => tokens.add(token));
+
   // Add common semantic tokens
   const commonTokens = [
     'canvas',

package/src/stories/foundations/Colors.mdx

@@ -185,6 +185,14 @@ M3 provides 5 surface container levels for creating subtle depth without elevati
     name="inversePrimary"
     description="Primary color on inverse surface"
   />
+  <SemanticSwatch
+    name="inverseSecondary"
+    description="Secondary color on inverse surface (light mode = dark palette value)"
+  />
+  <SemanticSwatch
+    name="inverseTertiary"
+    description="Tertiary color on inverse surface (light mode = dark palette value)"
+  />
 </div>
 
 ### Utility Colors
@@ -235,7 +243,7 @@ const buttonStyle = css({
   bg: 'primary',
   color: 'onPrimary',
   _hover: {
-    bg: 'primaryContainer'
+    bg: 'primary.container'
   }
 });
 

package/src/stories/foundations/Elevation.mdx

@@ -27,13 +27,19 @@ The middle layer maps design intent to base tokens:
 Components use semantic tokens for flexibility:
 ```tsx
 // ✅ Use semantic tokens in components
-boxShadow: 'sm'
-boxShadow: 'md'
-
-// ❌ Don't use base tokens directly
+boxShadow: 'xs'   // level1 — subtle cards
+boxShadow: 'sm'   // level2 — default cards
+boxShadow: 'md'   // level3 — dialogs, dropdowns
+boxShadow: 'lg'   // level4 — drawers, sheets
+boxShadow: 'xl'   // level5 — FABs, tooltips
+
+// ❌ Don't use base tokens directly — these are internal only
+boxShadow: 'level1'
 boxShadow: 'level2'
 ```
 
+**Shadow semantic token map:** `xs`=level1, `sm`=level2, `md`=level3, `lg`=level4, `xl`=level5.
+
 This architecture allows the design language to be swapped by changing which base tokens the semantic layer references, without touching component code.
 
 ## Elevation Scale
@@ -44,14 +50,14 @@ This architecture allows the design language to be swapped by changing which bas
 
 ## Elevation Reference
 
-| Level | Shadow Value | Use Case |
-|-------|--------------|----------|
-| **level0** | none | Flat elements, no elevation needed |
-| **level1** | `0px 1px 2px rgba(0,0,0,0.3), 0px 1px 3px 1px rgba(0,0,0,0.15)` | Cards at rest, contained buttons |
-| **level2** | `0px 1px 2px rgba(0,0,0,0.3), 0px 2px 6px 2px rgba(0,0,0,0.15)` | Cards on hover, raised buttons |
-| **level3** | `0px 4px 8px 3px rgba(0,0,0,0.15), 0px 1px 3px rgba(0,0,0,0.3)` | Dialogs, dropdowns, popovers |
-| **level4** | `0px 6px 10px 4px rgba(0,0,0,0.15), 0px 2px 3px rgba(0,0,0,0.3)` | Navigation drawer, modal sheets |
-| **level5** | `0px 8px 12px 6px rgba(0,0,0,0.15), 0px 4px 4px rgba(0,0,0,0.3)` | Floating action buttons, tooltips |
+| M3 Level | Semantic Token | Shadow Value | Use Case |
+|----------|---------------|--------------|----------|
+| **level0** | (no shadow) | none | Flat elements, no elevation needed |
+| **level1** | **`xs`** | `0px 1px 2px rgba(0,0,0,0.3), 0px 1px 3px 1px rgba(0,0,0,0.15)` | Cards at rest, contained buttons |
+| **level2** | **`sm`** | `0px 1px 2px rgba(0,0,0,0.3), 0px 2px 6px 2px rgba(0,0,0,0.15)` | Cards on hover, raised buttons |
+| **level3** | **`md`** | `0px 4px 8px 3px rgba(0,0,0,0.15), 0px 1px 3px rgba(0,0,0,0.3)` | Dialogs, dropdowns, popovers |
+| **level4** | **`lg`** | `0px 6px 10px 4px rgba(0,0,0,0.15), 0px 2px 3px rgba(0,0,0,0.3)` | Navigation drawer, modal sheets |
+| **level5** | **`xl`** | `0px 8px 12px 6px rgba(0,0,0,0.15), 0px 4px 4px rgba(0,0,0,0.3)` | Floating action buttons, tooltips |
 
 ---
 
@@ -212,8 +218,8 @@ Elevation works differently in dark themes:
 import { css } from 'styled-system/css';
 
 const cardStyle = css({
-  boxShadow: 'xs',
-  borderRadius: 'medium',
+  boxShadow: 'sm',   // level2 — default card elevation
+  borderRadius: 'l3',
   padding: 'lg'
 });
 ```
@@ -246,9 +252,9 @@ const modalStyle = css({
   top: '50%',
   left: '50%',
   transform: 'translate(-50%, -50%)',
-  boxShadow: 'md',
-  borderRadius: 'large',
-  backgroundColor: 'surface',
+  boxShadow: 'md',   // level3 — dialog elevation
+  borderRadius: 'l3',
+  backgroundColor: 'surface.container.high',
   padding: 'xl'
 });
 ```