m3-tokens

Material Design 3 Token System

When to Use This Skill

• Implementing semantic color tokens
• Setting up light/dark theme switching
• Understanding M3 color roles
• Referencing the project's actual color values

Source of Truth

All colors come from docs/material-theme.json, exported from Material Theme Builder.

Seed Color: #63A002 (Discourser/TastyMakers green)

Key Color Values

Light Theme (schemes.light)

{
  "primary": "#4C662B",
  "onPrimary": "#FFFFFF",
  "primaryContainer": "#CDEDA3",
  "onPrimaryContainer": "#354E16",
  
  "secondary": "#586249",
  "onSecondary": "#FFFFFF",
  "secondaryContainer": "#DCE7C8",
  "onSecondaryContainer": "#404A33",
  
  "tertiary": "#386663",
  "onTertiary": "#FFFFFF",
  "tertiaryContainer": "#BCECE7",
  "onTertiaryContainer": "#1F4E4B",
  
  "surface": "#F9FAEF",
  "onSurface": "#1A1C16",
  "surfaceVariant": "#E1E4D5",
  "onSurfaceVariant": "#44483D",
  
  "surfaceContainerLowest": "#FFFFFF",
  "surfaceContainerLow": "#F3F4E9",
  "surfaceContainer": "#EEEFE3",
  "surfaceContainerHigh": "#E8E9DE",
  "surfaceContainerHighest": "#E2E3D8",
  
  "outline": "#75796C",
  "outlineVariant": "#C5C8BA",
  
  "error": "#BA1A1A",
  "onError": "#FFFFFF",
  "errorContainer": "#FFDAD6",
  "onErrorContainer": "#93000A"
}

Dark Theme (schemes.dark)

{
  "primary": "#B1D18A",
  "onPrimary": "#1E3701",
  "primaryContainer": "#354E16",
  "onPrimaryContainer": "#CDEDA3",
  
  "secondary": "#BFCBAD",
  "onSecondary": "#29331D",
  "secondaryContainer": "#404A33",
  "onSecondaryContainer": "#DCE7C8",
  
  "tertiary": "#A0D0CB",
  "onTertiary": "#003734",
  "tertiaryContainer": "#1F4E4B",
  "onTertiaryContainer": "#BCECE7",
  
  "surface": "#12140E",
  "onSurface": "#E2E3D8",
  "surfaceVariant": "#44483D",
  "onSurfaceVariant": "#C5C8BA",
  
  "surfaceContainerLowest": "#0D0F09",
  "surfaceContainerLow": "#1A1C16",
  "surfaceContainer": "#1E201A",
  "surfaceContainerHigh": "#282B24",
  "surfaceContainerHighest": "#33362F",
  
  "outline": "#8F9285",
  "outlineVariant": "#44483D",
  
  "error": "#FFB4AB",
  "onError": "#690005",
  "errorContainer": "#93000A",
  "onErrorContainer": "#FFDAD6"
}

Semantic Token Pattern in Panda CSS

// In transform.ts or panda.config.ts

semanticTokens: {
  colors: {
    primary: {
      value: { base: '#4C662B', _dark: '#B1D18A' }
    },
    onPrimary: {
      value: { base: '#FFFFFF', _dark: '#1E3701' }
    },
    surface: {
      value: { base: '#F9FAEF', _dark: '#12140E' }
    },
    onSurface: {
      value: { base: '#1A1C16', _dark: '#E2E3D8' }
    },
    // ... all semantic colors
  }
}

Using Semantic Tokens in Recipes

// Always use semantic names, never raw hex values
buttonRecipe = defineRecipe({
  variants: {
    variant: {
      filled: {
        bg: 'primary',           // ✅ Semantic
        color: 'onPrimary',      // ✅ Semantic
        // bg: '#4C662B',        // ❌ Raw hex
      },
    },
  },
});

Dark Mode Activation

<!-- In HTML -->
<html data-theme="dark">

<!-- Or via class -->
<html class="dark">

// In panda.config.ts conditions
conditions: {
  light: '[data-theme=light] &, .light &',
  dark: '[data-theme=dark] &, .dark &'
}

M3 Color Role Usage Guide

Files to Reference

• docs/material-theme.json - Complete export with all palettes
• src/languages/material3.language.ts - Implementation (once created)