@discourser/design-system 0.14.0 → 0.15.0

package/dist/chunk-F7LHARS4.js

@@ -1,6 +1,6 @@
 import { __export } from './chunk-WR5Z5QMQ.js';
 import { ark as ark$1 } from '@ark-ui/react/factory';
-import { createContext, mergeProps } from '@ark-ui/react/utils';
+import { mergeProps, createContext } from '@ark-ui/react/utils';
 import { forwardRef, useMemo, createContext as createContext$1, useContext } from 'react';
 import { styled, createStyleContext, Stack } from 'styled-system/jsx';
 import { group, absoluteCenter, spinner, button, input, inputAddon, inputGroup, textarea, heading, badge, toast, card, dialog, switchComponent, accordion, drawer, tabs, checkbox, radioGroup, select, slider, avatar, progress, skeleton, popover, tooltip, stepper } from 'styled-system/recipes';

package/dist/components/Checkbox.d.ts

@@ -177,18 +177,18 @@ export declare const Indicator: import("react").ForwardRefExoticComponent<Omit<{
     onFocusCapture?: import("react").FocusEventHandler<SVGSVGElement> | undefined;
     onBlur?: import("react").FocusEventHandler<SVGSVGElement> | undefined;
     onBlurCapture?: import("react").FocusEventHandler<SVGSVGElement> | undefined;
-    onChange?: import("react").FormEventHandler<SVGSVGElement> | undefined;
-    onChangeCapture?: import("react").FormEventHandler<SVGSVGElement> | undefined;
+    onChange?: import("react").ChangeEventHandler<SVGSVGElement, Element> | undefined;
+    onChangeCapture?: import("react").ChangeEventHandler<SVGSVGElement, Element> | undefined;
     onBeforeInput?: import("react").InputEventHandler<SVGSVGElement> | undefined;
-    onBeforeInputCapture?: import("react").FormEventHandler<SVGSVGElement> | undefined;
-    onInput?: import("react").FormEventHandler<SVGSVGElement> | undefined;
-    onInputCapture?: import("react").FormEventHandler<SVGSVGElement> | undefined;
-    onReset?: import("react").FormEventHandler<SVGSVGElement> | undefined;
-    onResetCapture?: import("react").FormEventHandler<SVGSVGElement> | undefined;
-    onSubmit?: import("react").FormEventHandler<SVGSVGElement> | undefined;
-    onSubmitCapture?: import("react").FormEventHandler<SVGSVGElement> | undefined;
-    onInvalid?: import("react").FormEventHandler<SVGSVGElement> | undefined;
-    onInvalidCapture?: import("react").FormEventHandler<SVGSVGElement> | undefined;
+    onBeforeInputCapture?: import("react").InputEventHandler<SVGSVGElement> | undefined;
+    onInput?: import("react").InputEventHandler<SVGSVGElement> | undefined;
+    onInputCapture?: import("react").InputEventHandler<SVGSVGElement> | undefined;
+    onReset?: import("react").ReactEventHandler<SVGSVGElement> | undefined;
+    onResetCapture?: import("react").ReactEventHandler<SVGSVGElement> | undefined;
+    onSubmit?: import("react").SubmitEventHandler<SVGSVGElement> | undefined;
+    onSubmitCapture?: import("react").SubmitEventHandler<SVGSVGElement> | undefined;
+    onInvalid?: import("react").ReactEventHandler<SVGSVGElement> | undefined;
+    onInvalidCapture?: import("react").ReactEventHandler<SVGSVGElement> | undefined;
     onLoad?: import("react").ReactEventHandler<SVGSVGElement> | undefined;
     onLoadCapture?: import("react").ReactEventHandler<SVGSVGElement> | undefined;
     onError?: import("react").ReactEventHandler<SVGSVGElement> | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@discourser/design-system",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Aesthetic-agnostic design system with Panda CSS and Ark UI",
   "type": "module",
   "publishConfig": {
@@ -193,50 +193,50 @@
     "react-dom": ">=19.0.0"
   },
   "dependencies": {
-    "@ark-ui/react": "^5.30.0",
+    "@ark-ui/react": "^5.31.0",
     "clsx": "^2.1.1"
   },
   "devDependencies": {
     "@changesets/changelog-github": "^0.5.2",
     "@changesets/cli": "^2.29.8",
-    "@eslint/js": "^9.0.0",
+    "@eslint/js": "^9.39.2",
     "@material/material-color-utilities": "^0.3.0",
-    "@pandacss/dev": "^1.8.0",
+    "@pandacss/dev": "^1.8.1",
     "@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/react": "^16.3.2",
     "@testing-library/user-event": "^14.6.1",
     "@types/inquirer": "^9.0.9",
-    "@types/node": "^22.0.0",
-    "@types/react": "^19.0.0",
-    "@types/react-dom": "^19.0.0",
-    "@typescript-eslint/eslint-plugin": "^8.0.0",
-    "@typescript-eslint/parser": "^8.0.0",
-    "@vitejs/plugin-react": "^4.3.0",
+    "@types/node": "^22.19.11",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@typescript-eslint/eslint-plugin": "^8.55.0",
+    "@typescript-eslint/parser": "^8.55.0",
+    "@vitejs/plugin-react": "^4.7.0",
     "@vitest/ui": "^2.1.9",
-    "axe-core": "^4.11.0",
-    "eslint": "^9.0.0",
-    "eslint-plugin-react": "^7.35.0",
-    "eslint-plugin-react-hooks": "^5.0.0",
+    "axe-core": "^4.11.1",
+    "eslint": "^9.39.2",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-react-hooks": "^5.2.0",
     "eslint-plugin-storybook": "10.2.8",
     "husky": "^9.1.7",
-    "inquirer": "^13.1.0",
+    "inquirer": "^13.2.2",
     "jest-axe": "^10.0.0",
     "jsdom": "^27.4.0",
     "lint-staged": "^16.2.7",
-    "prettier": "^3.3.1",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0",
+    "prettier": "^3.8.1",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
     "storybook": "^10.2.8",
-    "tsup": "^8.3.0",
-    "tsx": "^4.19.0",
-    "typescript": "^5.7.0",
-    "vite": "^6.0.0",
-    "vitest": "^2.1.0"
+    "tsup": "^8.5.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vite": "^6.4.1",
+    "vitest": "^2.1.9"
   },
   "keywords": [
     "design-system",

package/src/preset/__tests__/translation-component-completeness.test.ts

@@ -0,0 +1,349 @@
+/* eslint-disable no-undef */
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * Component Completeness Verification for Translation Documentation
+ *
+ * This test suite verifies that all exported components from src/components/index.ts
+ * are documented in the Figma Translation suite (05-Components.mdx).
+ *
+ * Prevents missing component documentation when new components are added.
+ */
+
+const COMPONENTS_EXPORT_PATH = join(process.cwd(), 'src/components/index.ts');
+const COMPONENTS_MDX_PATH = join(
+  process.cwd(),
+  'stories/documentation/figma-translation/05-Components.mdx',
+);
+
+/**
+ * Extract exported component names from src/components/index.ts
+ */
+function extractComponentExports(): string[] {
+  const content = readFileSync(COMPONENTS_EXPORT_PATH, 'utf-8');
+  const components: string[] = [];
+
+  // Match: export { ComponentName } from './ComponentName'
+  const exportPattern =
+    /export\s+\{\s*([A-Z][a-zA-Z0-9]+)(?:,\s*type\s+[A-Z][a-zA-Z0-9]+Props)?\s*\}\s+from\s+['"].\/([A-Z][a-zA-Z0-9]+)['"]/g;
+  let match;
+
+  while ((match = exportPattern.exec(content)) !== null) {
+    const componentName = match[1];
+    components.push(componentName);
+  }
+
+  // Match: export * as ComponentName from './ComponentName'
+  const namespacePattern =
+    /export\s+\*\s+as\s+([A-Z][a-zA-Z0-9]+)\s+from\s+['"].\/([A-Z][a-zA-Z0-9]+)['"]/g;
+
+  while ((match = namespacePattern.exec(content)) !== null) {
+    const componentName = match[1];
+    components.push(componentName);
+  }
+
+  // Match standalone exports like: export { toaster, Toaster } from './Toast'
+  const standalonePattern =
+    /export\s+\{\s*([a-zA-Z][a-zA-Z0-9]+)(?:,\s*([a-zA-Z][a-zA-Z0-9]+))?\s*\}\s+from\s+['"].\/[A-Z][a-zA-Z0-9]+['"]/g;
+
+  while ((match = standalonePattern.exec(content)) !== null) {
+    // Add first export (might be lowercase like 'toaster')
+    if (match[1] && match[1][0] === match[1][0].toUpperCase()) {
+      components.push(match[1]);
+    }
+    // Add second export if exists
+    if (match[2] && match[2][0] === match[2][0].toUpperCase()) {
+      components.push(match[2]);
+    }
+  }
+
+  return [...new Set(components)].sort();
+}
+
+/**
+ * Check if a component is documented in 05-Components.mdx
+ */
+function isComponentDocumented(
+  componentName: string,
+  mdxContent: string,
+): boolean {
+  // Check for heading: ### ComponentName
+  const headingPattern = new RegExp(`^###\\s+${componentName}(?:\\s|$)`, 'gm');
+
+  if (headingPattern.test(mdxContent)) {
+    return true;
+  }
+
+  // Special cases: some components may be documented under different names
+  // or as part of compound components
+
+  // InputGroup, InputAddon documented as part of Input section
+  if (['InputGroup', 'InputAddon'].includes(componentName)) {
+    return /^###\s+Input(?:Group|Addon)/gm.test(mdxContent);
+  }
+
+  // ButtonGroup documented as part of Button or Group section
+  if (componentName === 'ButtonGroup') {
+    return /^###\s+(?:Button|Group)/gm.test(mdxContent);
+  }
+
+  // Toaster is documented with Toast
+  if (componentName === 'Toaster') {
+    return /^###\s+Toast/gm.test(mdxContent);
+  }
+
+  // Icon, CloseButton, AbsoluteCenter, Group are utility components
+  // They may be in a "Utility" section
+  if (
+    ['Icon', 'CloseButton', 'AbsoluteCenter', 'Group'].includes(componentName)
+  ) {
+    const utilitySection = /^##\s+\d+\.\s+Utility/gm.test(mdxContent);
+    const hasHeading = new RegExp(`###\\s+${componentName}`, 'gm').test(
+      mdxContent,
+    );
+    return utilitySection && hasHeading;
+  }
+
+  return false;
+}
+
+/**
+ * Components that are not UI components (type exports, helpers, etc.)
+ * These are allowed to not be in the translation docs
+ */
+const UTILITY_EXPORTS_ALLOWLIST = [
+  // Type exports (if any appear in the export list)
+  'ButtonProps',
+  'CardProps',
+
+  // Internal utilities that aren't visual components
+  'toaster', // (lowercase - programmatic API, not a component)
+];
+
+/**
+ * Normalize component name for comparison
+ * Handles cases where config uses different naming than export
+ */
+function normalizeComponentName(name: string): string {
+  // switchComponent (in config) vs Switch (in export)
+  if (name === 'switchComponent') return 'Switch';
+  if (name === 'Switch') return 'Switch';
+
+  return name;
+}
+
+describe('Translation Documentation - Component Completeness', () => {
+  it('should document all exported components', () => {
+    const components = extractComponentExports();
+    const mdxContent = readFileSync(COMPONENTS_MDX_PATH, 'utf-8');
+
+    const undocumentedComponents: string[] = [];
+
+    components.forEach((componentName) => {
+      // Skip utility exports
+      if (UTILITY_EXPORTS_ALLOWLIST.includes(componentName)) {
+        return;
+      }
+
+      // Skip lowercase exports (like toaster) - they're programmatic APIs
+      if (componentName[0] === componentName[0].toLowerCase()) {
+        return;
+      }
+
+      const normalized = normalizeComponentName(componentName);
+
+      if (!isComponentDocumented(normalized, mdxContent)) {
+        undocumentedComponents.push(componentName);
+      }
+    });
+
+    if (undocumentedComponents.length > 0) {
+      const errorMessage =
+        `\n\nThe following components are exported from src/components/index.ts but NOT documented in 05-Components.mdx:\n\n` +
+        undocumentedComponents.map((name) => `  - ${name}`).join('\n') +
+        `\n\nAdd a "### ${undocumentedComponents[0]}" heading section to 05-Components.mdx with:\n` +
+        `  - Maps from: [Figma/Shadcn equivalent]\n` +
+        `  - Import: import { ${undocumentedComponents[0]} } from '@discourser/design-system'\n` +
+        `  - Type: Simple (recipe) or Compound (slot recipe)\n` +
+        `  - Props table with variants, sizes, etc.\n\n` +
+        `See 07-ExtensionGuide.mdx for the full template.\n`;
+
+      throw new Error(errorMessage);
+    }
+
+    expect(undocumentedComponents).toHaveLength(0);
+  });
+
+  it('should extract at least 15 component exports', () => {
+    // Sanity check: ensure we're actually finding component exports
+    const components = extractComponentExports();
+
+    expect(components.length).toBeGreaterThanOrEqual(15);
+  });
+
+  it('should find component headings in 05-Components.mdx', () => {
+    // Sanity check: ensure the MDX file has component sections
+    const mdxContent = readFileSync(COMPONENTS_MDX_PATH, 'utf-8');
+
+    // Count ### headings (component sections)
+    const headingPattern = /^###\s+[A-Z][a-zA-Z0-9]+/gm;
+    const headings = mdxContent.match(headingPattern) || [];
+
+    // Should have at least 20 component sections
+    expect(headings.length).toBeGreaterThanOrEqual(20);
+  });
+
+  it('05-Components.mdx should exist', () => {
+    expect(() => {
+      readFileSync(COMPONENTS_MDX_PATH, 'utf-8');
+    }).not.toThrow();
+  });
+});
+
+describe('Translation Documentation - Cross-Reference Integrity', () => {
+  const TRANSLATION_DOCS_PATH = join(
+    process.cwd(),
+    'stories/documentation/figma-translation',
+  );
+  const GUIDELINES_PATH = join(
+    process.cwd(),
+    'stories/documentation/guidelines',
+  );
+
+  const TRANSLATION_FILES = [
+    '00-FigmaTranslation.mdx',
+    '01-Colors.mdx',
+    '02-Typography.mdx',
+    '03-Spacing.mdx',
+    '04-Shadows-Radii.mdx',
+    '05-Components.mdx',
+    '06-Layout.mdx',
+    '07-ExtensionGuide.mdx',
+  ];
+
+  /**
+   * Extract cross-reference links from MDX content
+   * Matches: [Link Text](/docs/documentation-guidelines-99-component-name--docs)
+   */
+  function extractCrossReferences(
+    content: string,
+  ): Array<{ link: string; text: string; line: number }> {
+    const references: Array<{ link: string; text: string; line: number }> = [];
+    const lines = content.split('\n');
+
+    const linkPattern =
+      /\[([^\]]+)\]\(\/docs\/(documentation-(?:guidelines|figma-translation)-[^)]+)\)/g;
+
+    lines.forEach((line, lineIndex) => {
+      let match;
+      while ((match = linkPattern.exec(line)) !== null) {
+        references.push({
+          text: match[1],
+          link: match[2],
+          line: lineIndex + 1,
+        });
+      }
+    });
+
+    return references;
+  }
+
+  it('should have valid cross-references to Guidelines documentation', () => {
+    const brokenLinks: Array<{
+      file: string;
+      link: string;
+      text: string;
+      line: number;
+    }> = [];
+
+    TRANSLATION_FILES.forEach((filename) => {
+      const filePath = join(TRANSLATION_DOCS_PATH, filename);
+      const content = readFileSync(filePath, 'utf-8');
+      const references = extractCrossReferences(content);
+
+      references.forEach((ref) => {
+        // Check if it's a guidelines reference
+        if (ref.link.includes('documentation-guidelines')) {
+          // Extract the guideline file reference
+          // Example: documentation-guidelines-99-button--docs -> should check for button.mdx or 99-Button.mdx
+
+          const guidelineFilePattern = ref.link
+            .replace(/^documentation-guidelines-(?:99-)?/, '')
+            .replace(/--docs$/, '');
+
+          // Try common patterns
+          const possiblePaths = [
+            join(GUIDELINES_PATH, `${guidelineFilePattern}.mdx`),
+            join(GUIDELINES_PATH, `99-${guidelineFilePattern}.mdx`),
+            join(
+              GUIDELINES_PATH,
+              `99-${guidelineFilePattern.charAt(0).toUpperCase() + guidelineFilePattern.slice(1)}.mdx`,
+            ),
+            join(GUIDELINES_PATH, 'components', `${guidelineFilePattern}.mdx`),
+            join(
+              GUIDELINES_PATH,
+              'design-tokens',
+              `${guidelineFilePattern}.mdx`,
+            ),
+            join(
+              GUIDELINES_PATH,
+              `${guidelineFilePattern.replace(/-/g, '/')}.mdx`,
+            ),
+            join(GUIDELINES_PATH, `overview-patterns.mdx`), // Special case
+          ];
+
+          const exists = possiblePaths.some((path) => {
+            try {
+              readFileSync(path, 'utf-8');
+              return true;
+            } catch {
+              return false;
+            }
+          });
+
+          if (!exists) {
+            brokenLinks.push({
+              file: filename,
+              link: ref.link,
+              text: ref.text,
+              line: ref.line,
+            });
+          }
+        }
+      });
+    });
+
+    if (brokenLinks.length > 0) {
+      const errorMessage = brokenLinks
+        .map(
+          (ref) =>
+            `  ${ref.file}:${ref.line}\n    Link: [${ref.text}](/docs/${ref.link})\n    Target file not found in stories/documentation/guidelines/`,
+        )
+        .join('\n\n');
+
+      console.warn(
+        `\n\nWarning: Found ${brokenLinks.length} potentially broken cross-reference link(s):\n\n${errorMessage}\n\n` +
+          `This may be a false positive if the Guidelines file exists but wasn't detected.\n` +
+          `Verify manually if needed.\n`,
+      );
+    }
+
+    // This is a warning, not a hard failure, since file structure may vary
+    // Just log the count
+    expect(brokenLinks.length).toBeLessThanOrEqual(10);
+  });
+
+  it('should extract cross-references from translation files', () => {
+    // Sanity check: ensure we're finding cross-references
+    const allReferences = TRANSLATION_FILES.flatMap((filename) => {
+      const filePath = join(TRANSLATION_DOCS_PATH, filename);
+      const content = readFileSync(filePath, 'utf-8');
+      return extractCrossReferences(content);
+    });
+
+    // Should find at least 10 cross-reference links
+    expect(allReferences.length).toBeGreaterThanOrEqual(10);
+  });
+});

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

@@ -0,0 +1,349 @@
+/* eslint-disable no-undef */
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { discourserPandaPreset as preset } from '../index';
+
+/**
+ * Token Accuracy Verification for Translation Documentation
+ *
+ * This test suite verifies that all tokens referenced in the Figma Translation
+ * documentation (files 01-04) actually exist in the design system configuration.
+ *
+ * Prevents documentation drift where docs reference non-existent tokens.
+ */
+
+const TRANSLATION_DOCS_PATH = join(
+  process.cwd(),
+  'stories/documentation/figma-translation',
+);
+
+const TRANSLATION_FILES = [
+  '01-Colors.mdx',
+  '02-Typography.mdx',
+  '03-Spacing.mdx',
+  '04-Shadows-Radii.mdx',
+];
+
+/**
+ * Build a comprehensive list of valid tokens from the Panda preset
+ */
+function buildKnownTokenList(): Set<string> {
+  const tokens = new Set<string>();
+
+  // Semantic tokens from preset
+  const semanticColors = preset.theme?.extend?.semanticTokens?.colors || {};
+  const semanticShadows = preset.theme?.extend?.semanticTokens?.shadows || {};
+
+  // Add semantic color tokens (with nested structure)
+  Object.keys(semanticColors).forEach((key) => {
+    tokens.add(key);
+    // Handle nested tokens like fg.default, fg.muted, surface.container, etc.
+    const value = semanticColors[key];
+    if (typeof value === 'object' && value !== null && 'value' in value) {
+      tokens.add(key);
+    }
+  });
+
+  // Add semantic shadow tokens
+  Object.keys(semanticShadows).forEach((key) => {
+    tokens.add(key);
+  });
+
+  // Add semantic radii tokens
+  const semanticRadii = preset.theme?.extend?.semanticTokens?.radii || {};
+  Object.keys(semanticRadii).forEach((key) => {
+    tokens.add(key);
+  });
+
+  // Add textStyle tokens
+  const textStyles = preset.theme?.extend?.textStyles || {};
+  Object.keys(textStyles).forEach((key) => {
+    tokens.add(key);
+  });
+
+  // Add common Radix color scale patterns (primary.1-12, secondary.1-12, etc.)
+  const colorPalettes = [
+    'primary',
+    'secondary',
+    'tertiary',
+    'error',
+    'neutral',
+    'gray',
+    'red',
+  ];
+  colorPalettes.forEach((palette) => {
+    for (let i = 1; i <= 12; i++) {
+      tokens.add(`${palette}.${i}`);
+      tokens.add(`${palette}.a${i}`); // Alpha variants
+    }
+    tokens.add(`${palette}.contrast`); // Contrast token (if it exists)
+  });
+
+  // Add M3 explicit tokens
+  const m3Tokens = [
+    'm3Primary',
+    'm3Secondary',
+    'm3Tertiary',
+    'm3Primary.container',
+    'm3Secondary.container',
+    'm3Tertiary.container',
+    'onM3Primary',
+    'onM3Secondary',
+    'onM3Tertiary',
+    'onM3Primary.container',
+    'onM3Secondary.container',
+    'onM3Tertiary.container',
+  ];
+  m3Tokens.forEach((token) => tokens.add(token));
+
+  // Add surface tokens
+  const surfaceTokens = [
+    'surface',
+    'surface.dim',
+    'surface.bright',
+    'surface.container',
+    'surface.container.low',
+    'surface.container.lowest',
+    'surface.container.high',
+    'surface.container.highest',
+    'onSurface',
+    'onSurface.variant',
+    'outline',
+    'outline.variant',
+  ];
+  surfaceTokens.forEach((token) => tokens.add(token));
+
+  // Add common semantic tokens
+  const commonTokens = [
+    'canvas',
+    'border',
+    'fg.default',
+    'fg.muted',
+    'fg.subtle',
+  ];
+  commonTokens.forEach((token) => tokens.add(token));
+
+  // Add spacing tokens (numeric values are always valid in Panda)
+  // We'll handle these separately in validation
+
+  // Add font families
+  const fontFamilies = ['body', 'display', 'mono'];
+  fontFamilies.forEach((token) => tokens.add(token));
+
+  // Add font weights
+  const fontWeights = ['light', 'normal', 'medium', 'semibold', 'bold'];
+  fontWeights.forEach((token) => tokens.add(token));
+
+  // Add common border radius values
+  const radiiTokens = [
+    'l1',
+    'l2',
+    'l3',
+    'xs',
+    'sm',
+    'md',
+    'lg',
+    'xl',
+    '2xl',
+    '3xl',
+    'full',
+    'none',
+  ];
+  radiiTokens.forEach((token) => tokens.add(token));
+
+  return tokens;
+}
+
+/**
+ * Extract token references from MDX content
+ * Matches patterns like: bg="token", color="token", shadow="token", etc.
+ */
+function extractTokenReferences(
+  content: string,
+  _filename: string,
+): Array<{ token: string; line: number; context: string }> {
+  const references: Array<{ token: string; line: number; context: string }> =
+    [];
+  const lines = content.split('\n');
+
+  // Regex patterns for different token types
+  const patterns = [
+    // CSS props: bg="...", color="...", borderColor="...", etc.
+    /(?:bg|color|borderColor|shadow|rounded|textStyle|fontFamily|fontWeight|p|px|py|pt|pb|pl|pr|m|mx|my|mt|mb|ml|mr|gap|rowGap|columnGap|maxW|minH|h|w|display|flexDir|alignItems|justifyContent|gridTemplateColumns|borderRadius|borderTopRadius|borderBottomRadius|borderLeftRadius|borderRightRadius|borderTopLeftRadius|borderTopRightRadius|borderBottomLeftRadius|borderBottomRightRadius)="([^"]+)"/g,
+
+    // Semantic tokens in prose: `canvas`, `fg.default`, etc. (backtick wrapped)
+    /`((?:fg|bg|surface|outline|canvas|border|onSurface|onM3Primary|onM3Secondary|onM3Tertiary|m3Primary|m3Secondary|m3Tertiary)(?:\.[a-zA-Z0-9]+)*)`/g,
+
+    // Color palette references: primary.9, error.11, etc. (backtick wrapped)
+    /`((?:primary|secondary|tertiary|error|neutral|gray|red)\.(?:\d+|a\d+|contrast))`/g,
+  ];
+
+  lines.forEach((line, lineIndex) => {
+    patterns.forEach((pattern) => {
+      let match;
+      while ((match = pattern.exec(line)) !== null) {
+        const token = match[1];
+
+        // Skip empty matches, URLs, and obvious non-tokens
+        if (
+          !token ||
+          token.includes('http') ||
+          token.includes('//') ||
+          token.includes('.com') ||
+          token.includes('.mdx')
+        ) {
+          continue;
+        }
+
+        references.push({
+          token,
+          line: lineIndex + 1,
+          context: line.trim().substring(0, 80), // First 80 chars for context
+        });
+      }
+    });
+  });
+
+  return references;
+}
+
+/**
+ * Check if a token is valid
+ */
+function isValidToken(token: string, knownTokens: Set<string>): boolean {
+  // Direct match
+  if (knownTokens.has(token)) {
+    return true;
+  }
+
+  // Numeric spacing values are always valid (4, 6, 8, 16, etc.)
+  if (/^\d+(?:\.\d+)?$/.test(token)) {
+    return true;
+  }
+
+  // Percentage values
+  if (/^\d+%$/.test(token)) {
+    return true;
+  }
+
+  // Viewport units
+  if (/^(?:100vh|100vw|dvh|full|auto)$/.test(token)) {
+    return true;
+  }
+
+  // CSS keywords
+  const cssKeywords = [
+    'flex',
+    'grid',
+    'block',
+    'inline-block',
+    'none',
+    'inline',
+    'inline-flex',
+    'inline-grid',
+    'column',
+    'row',
+    'wrap',
+    'nowrap',
+    'flex-start',
+    'flex-end',
+    'center',
+    'space-between',
+    'space-around',
+    'space-evenly',
+    'stretch',
+    'baseline',
+    'transparent',
+    'white',
+    'black',
+    'inherit',
+    'currentColor',
+    'auto',
+    'hidden',
+    'visible',
+    'scroll',
+    'unset',
+    'initial',
+  ];
+  if (cssKeywords.includes(token)) {
+    return true;
+  }
+
+  // Breakpoint tokens (base, sm, md, lg, xl, 2xl)
+  if (/^(?:base|sm|md|lg|xl|2xl)$/.test(token)) {
+    return true;
+  }
+
+  // Grid template patterns: "1fr", "repeat(2, 1fr)", "200px 1fr"
+  if (/^(?:\d+fr|repeat\(|auto|minmax\(|\d+px)/.test(token)) {
+    return true;
+  }
+
+  // Specific max-width tokens
+  if (
+    /^breakpoint-/.test(token) ||
+    /^(?:xs|sm|md|lg|xl|2xl|3xl|4xl|5xl|6xl|7xl|full)$/.test(token)
+  ) {
+    return true;
+  }
+
+  return false;
+}
+
+describe('Translation Documentation - Token Accuracy', () => {
+  const knownTokens = buildKnownTokenList();
+
+  TRANSLATION_FILES.forEach((filename) => {
+    describe(`${filename}`, () => {
+      it('should only reference valid tokens', () => {
+        const filePath = join(TRANSLATION_DOCS_PATH, filename);
+        let content: string;
+
+        try {
+          content = readFileSync(filePath, 'utf-8');
+        } catch (error) {
+          throw new Error(`Failed to read ${filename}: ${error}`);
+        }
+
+        const references = extractTokenReferences(content, filename);
+        const invalidReferences: typeof references = [];
+
+        references.forEach((ref) => {
+          if (!isValidToken(ref.token, knownTokens)) {
+            invalidReferences.push(ref);
+          }
+        });
+
+        if (invalidReferences.length > 0) {
+          const errorMessage = invalidReferences
+            .map(
+              (ref) =>
+                `  Line ${ref.line}: Token "${ref.token}" does not exist\n    Context: ${ref.context}`,
+            )
+            .join('\n\n');
+
+          throw new Error(
+            `\n\nFound ${invalidReferences.length} invalid token(s) in ${filename}:\n\n${errorMessage}\n\n` +
+              `Tokens must exist in panda.config.ts, preset files, or be valid CSS values.`,
+          );
+        }
+
+        // If we get here, all tokens are valid
+        expect(invalidReferences).toHaveLength(0);
+      });
+    });
+  });
+
+  it('should have extracted tokens from all files', () => {
+    // Sanity check: ensure we're actually finding tokens
+    const allReferences = TRANSLATION_FILES.flatMap((filename) => {
+      const filePath = join(TRANSLATION_DOCS_PATH, filename);
+      const content = readFileSync(filePath, 'utf-8');
+      return extractTokenReferences(content, filename);
+    });
+
+    // We should find at least 50 token references across all files
+    expect(allReferences.length).toBeGreaterThan(50);
+  });
+});