@spaced-out/ui-design-system 0.5.21 → 0.5.22

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [0.5.22](https://github.com/spaced-out/ui-design-system/compare/v0.5.21...v0.5.22) (2025-11-12)
+
+
+### Bug Fixes
+
+* add context aware results and utils and types info ([#431](https://github.com/spaced-out/ui-design-system/issues/431)) ([743fecf](https://github.com/spaced-out/ui-design-system/commit/743fecf93625edd13800e345c408343eff773748))
+
 ### [0.5.21](https://github.com/spaced-out/ui-design-system/compare/v0.5.20...v0.5.21) (2025-11-12)
 
 

package/mcp/build-mcp-data.js

@@ -42,7 +42,34 @@ function getDirectories(path) {
 }
 
 /**
- * Extract all components with their files
+ * Get all files recursively in a directory
+ */
+function getAllFilesRecursively(dirPath, filesList = [], baseDir = dirPath) {
+  try {
+    const files = readdirSync(dirPath);
+    
+    files.forEach(file => {
+      if (file.startsWith('.')) return;
+      
+      const filePath = join(dirPath, file);
+      const stat = statSync(filePath);
+      
+      if (stat.isDirectory()) {
+        getAllFilesRecursively(filePath, filesList, baseDir);
+      } else {
+        const relativePath = filePath.replace(baseDir + '/', '');
+        filesList.push(relativePath);
+      }
+    });
+  } catch (error) {
+    // Ignore errors for non-existent directories
+  }
+  
+  return filesList;
+}
+
+/**
+ * Extract all components with their files (including sub-components)
  */
 function buildComponentsData() {
   console.log('📦 Extracting components...');
@@ -59,24 +86,58 @@ function buildComponentsData() {
   for (const componentName of componentDirs) {
     const componentDir = join(componentsPath, componentName);
     
+    // Get all files in the component directory
+    const allFiles = getAllFilesRecursively(componentDir);
+    
+    // Extract main component files
     const mainTsx = join(componentDir, `${componentName}.tsx`);
     const mainTs = join(componentDir, `${componentName}.ts`);
+    const mainContent = safeReadFile(mainTsx) || safeReadFile(mainTs);
     
+    // Extract story files
     const storyTsx = join(componentDir, `${componentName}.stories.tsx`);
     const storyTs = join(componentDir, `${componentName}.stories.ts`);
+    const storyContent = safeReadFile(storyTsx) || safeReadFile(storyTs);
     
+    // Extract CSS file
     const cssFile = join(componentDir, `${componentName}.module.css`);
+    const cssContent = safeReadFile(cssFile);
     
+    // Extract index file
     const indexFile = join(componentDir, 'index.ts');
-    
-    const mainContent = safeReadFile(mainTsx) || safeReadFile(mainTs);
-    const storyContent = safeReadFile(storyTsx) || safeReadFile(storyTs);
-    const cssContent = safeReadFile(cssFile);
     const indexContent = safeReadFile(indexFile);
     
-    const allFiles = existsSync(componentDir) 
-      ? readdirSync(componentDir).filter(f => !f.startsWith('.'))
-      : [];
+    // Extract all additional TypeScript/TSX files (sub-components)
+    const additionalFiles = {};
+    for (const file of allFiles) {
+      // Skip main files we already extracted
+      if (
+        file === `${componentName}.tsx` ||
+        file === `${componentName}.ts` ||
+        file === `${componentName}.stories.tsx` ||
+        file === `${componentName}.stories.ts` ||
+        file === `${componentName}.module.css` ||
+        file === 'index.ts' ||
+        file.endsWith('.module.css') ||
+        file.endsWith('.stories.tsx') ||
+        file.endsWith('.stories.ts') ||
+        file.endsWith('.stories.module.css')
+      ) {
+        continue;
+      }
+      
+      // Only include .tsx and .ts files (sub-components)
+      if (file.endsWith('.tsx') || file.endsWith('.ts')) {
+        const fullPath = join(componentDir, file);
+        const content = safeReadFile(fullPath);
+        if (content) {
+          additionalFiles[file] = {
+            path: file,
+            content: content
+          };
+        }
+      }
+    }
     
     components[componentName] = {
       name: componentName,
@@ -86,6 +147,7 @@ function buildComponentsData() {
         story: storyContent ? { path: `${componentName}.stories.tsx`, content: storyContent } : null,
         css: cssContent ? { path: `${componentName}.module.css`, content: cssContent } : null,
         index: indexContent ? { path: 'index.ts', content: indexContent } : null,
+        additional: additionalFiles,
       },
       allFiles,
     };
@@ -190,6 +252,94 @@ function buildTokensData() {
   return tokens;
 }
 
+/**
+ * Extract all utils
+ */
+function buildUtilsData() {
+  console.log('🔧 Extracting utils...');
+  const utilsPath = join(DESIGN_SYSTEM_PATH, 'src/utils');
+  const utils = {};
+  
+  if (!existsSync(utilsPath)) {
+    console.warn('⚠️  Utils path not found');
+    return utils;
+  }
+
+  const utilDirs = getDirectories(utilsPath);
+  
+  for (const utilName of utilDirs) {
+    const utilDir = join(utilsPath, utilName);
+    
+    // Get all files in the util directory
+    const allFiles = getAllFilesRecursively(utilDir);
+    
+    // Read all TypeScript files
+    const files = {};
+    for (const file of allFiles) {
+      if ((file.endsWith('.ts') || file.endsWith('.tsx')) && !file.endsWith('.d.ts')) {
+        const fullPath = join(utilDir, file);
+        const content = safeReadFile(fullPath);
+        if (content) {
+          files[file] = {
+            path: file,
+            content: content
+          };
+        }
+      }
+    }
+    
+    utils[utilName] = {
+      name: utilName,
+      path: `src/utils/${utilName}`,
+      files: files,
+      allFiles: allFiles,
+    };
+  }
+  
+  console.log(`   ✅ Extracted ${Object.keys(utils).length} util modules`);
+  return utils;
+}
+
+/**
+ * Extract all types
+ */
+function buildTypesData() {
+  console.log('📐 Extracting types...');
+  const typesPath = join(DESIGN_SYSTEM_PATH, 'src/types');
+  const types = {};
+  
+  if (!existsSync(typesPath)) {
+    console.warn('⚠️  Types path not found');
+    return types;
+  }
+
+  try {
+    const files = readdirSync(typesPath).filter(f => 
+      !f.startsWith('.') && 
+      (f.endsWith('.ts') || f.endsWith('.tsx')) &&
+      !f.endsWith('.d.ts')
+    );
+    
+    for (const file of files) {
+      const filePath = join(typesPath, file);
+      const content = safeReadFile(filePath);
+      if (content) {
+        const typeName = file.replace(/\.(ts|tsx)$/, '');
+        types[typeName] = {
+          name: typeName,
+          path: `src/types/${file}`,
+          content: content,
+        };
+      }
+    }
+  } catch (error) {
+    console.warn(`   ⚠️  Error reading types:`, error.message);
+  }
+  
+  console.log(`   ✅ Extracted ${Object.keys(types).length} type files`);
+  return types;
+}
+
 /**
  * Get package version
  */
@@ -217,6 +367,8 @@ function build() {
       components: buildComponentsData(),
       hooks: buildHooksData(),
       tokens: buildTokensData(),
+      utils: buildUtilsData(),
+      types: buildTypesData(),
     };
 
     // Create output directory if it doesn't exist
@@ -232,6 +384,8 @@ function build() {
     console.log(`   - Components: ${Object.keys(data.components).length}`);
     console.log(`   - Hooks: ${Object.keys(data.hooks).length}`);
     console.log(`   - Token categories: ${Object.keys(data.tokens).length}`);
+    console.log(`   - Utils: ${Object.keys(data.utils).length}`);
+    console.log(`   - Types: ${Object.keys(data.types).length}`);
     console.log(`   - Version: ${data.metadata.version}`);
     console.log(`   - Output: ${OUTPUT_FILE}`);
     console.log(`   - Size: ${(Buffer.byteLength(JSON.stringify(data)) / 1024 / 1024).toFixed(2)} MB\n`);

package/mcp/index.js

@@ -51,6 +51,8 @@ console.error('✅ Loaded Genesis design system data');
 console.error(`   Version: ${designSystemData.metadata.version}`);
 console.error(`   Components: ${Object.keys(designSystemData.components).length}`);
 console.error(`   Hooks: ${Object.keys(designSystemData.hooks).length}`);
+console.error(`   Utils: ${Object.keys(designSystemData.utils || {}).length}`);
+console.error(`   Types: ${Object.keys(designSystemData.types || {}).length}`);
 console.error(`   Built: ${designSystemData.metadata.buildDate}`);
 
 /**
@@ -67,6 +69,20 @@ function getAllHooks() {
   return Object.keys(designSystemData.hooks).sort();
 }
 
+/**
+ * Get all utils
+ */
+function getAllUtils() {
+  return Object.keys(designSystemData.utils || {}).sort();
+}
+
+/**
+ * Get all types
+ */
+function getAllTypes() {
+  return Object.keys(designSystemData.types || {}).sort();
+}
+
 /**
  * Get component details
  */
@@ -81,6 +97,20 @@ function getHookDetails(hookName) {
   return designSystemData.hooks[hookName] || null;
 }
 
+/**
+ * Get util details
+ */
+function getUtilDetails(utilName) {
+  return designSystemData.utils?.[utilName] || null;
+}
+
+/**
+ * Get type details
+ */
+function getTypeDetails(typeName) {
+  return designSystemData.types?.[typeName] || null;
+}
+
 /**
  * Get all design tokens
  */
@@ -126,8 +156,35 @@ function searchComponents(query) {
 function getCSSModuleGuidelines() {
   return {
     description: 'Comprehensive CSS Module guidelines and best practices for the Genesis Design System',
+    contextNote: {
+      critical: '⚠️ IMPORTANT: Patterns differ based on context',
+      insideDesignSystem: 'Use .module.css files with PascalCase naming and relative token imports',
+      usingDesignSystem: 'Use .css files (no .module) with kebab-case naming and @spaced-out/ui-design-system imports',
+      recommendation: 'Call get_css_module_import_patterns tool for detailed context-specific examples',
+    },
     typescriptRequirement: '⚠️ CRITICAL: Use pure TypeScript only. NO Flow types (Flow.AbstractComponent). Use React.forwardRef<HTMLElement, Props> pattern.',
+    cssModuleImportPattern: {
+      critical: '🚨 MANDATORY: ALWAYS import CSS Modules as a default import with "css" as the variable name',
+      insideDesignSystem: 'import css from \'./ComponentName.module.css\';',
+      usingDesignSystem: 'import css from \'./component-name.css\';',
+      incorrect: [
+        'import \'./ComponentName.module.css\'; // ❌ WRONG - No side-effect imports',
+        'import * as css from \'./ComponentName.module.css\'; // ❌ WRONG - No namespace imports',
+        'import styles from \'./ComponentName.module.css\'; // ❌ WRONG - Must use "css" as variable name',
+      ],
+      classNameUsage: {
+        correct: 'className={css.tableHeaderContent} // Use camelCase property access',
+        incorrect: [
+          'className="table-header-content" // ❌ WRONG - No string literals',
+          'className="tableHeaderContent" // ❌ WRONG - No string literals',
+          'className={\'table-header-content\'} // ❌ WRONG - No string literals in braces',
+        ],
+      },
+      explanation: 'CSS Modules require a default import to access class names as properties. The variable MUST be named "css" for consistency across the codebase. Class names are accessed as camelCase properties (css.myClass) not as string literals.',
+    },
     criticalRules: [
+      '🚨 MANDATORY: Import CSS Modules as: import css from \'./Component.module.css\'',
+      '🚨 MANDATORY: Use className={css.className} NOT className="class-name"',
       '⚠️ ALWAYS use design tokens instead of hardcoded values',
       '⚠️ Use BEM modifier pattern: .baseClass.modifier NOT .baseClass--modifier',
       '⚠️ Use descendant selectors for child element styling: .container .childClass NOT :global() selectors',
@@ -231,6 +288,20 @@ function getCSSModuleGuidelines() {
     },
     realWorldExample: {
       description: 'Complete example with state-based styling for multiple child elements',
+      importPattern: `// 🚨 MANDATORY: Import CSS Module as default with "css" variable name
+import css from './ComponentName.module.css';
+
+// Usage in JSX:
+<div className={css.wrapper}>
+  <div className={css.header}>
+    <span className={css.title}>Title</span>
+  </div>
+</div>
+
+// ❌ NEVER DO THIS:
+// import './ComponentName.module.css';
+// <div className="wrapper">
+// <div className={'wrapper'}>`,
       code: `@value (
   colorBorderPrimary,
   colorBackgroundTertiary,
@@ -295,6 +366,16 @@ function getCSSModuleGuidelines() {
 }`,
     },
     commonMistakes: [
+      {
+        mistake: '🚨 CRITICAL: Incorrect CSS Module import or usage',
+        wrong: `import './Component.module.css'; // Side-effect import
+import styles from './Component.module.css'; // Wrong variable name
+<div className="wrapper"> // String literal
+<div className={'wrapper'}> // String literal in braces`,
+        right: `import css from './Component.module.css'; // Default import with "css" variable
+<div className={css.wrapper}> // Property access with camelCase`,
+        explanation: 'CSS Modules MUST be imported as default with variable name "css" and used via property access, never as string literals.',
+      },
       {
         mistake: 'Using hardcoded pixel values',
         wrong: 'width: 58px; height: 78px; padding: 12px 16px;',
@@ -324,6 +405,346 @@ function getCSSModuleGuidelines() {
   };
 }
 
+/**
+ * Get CSS Module import and usage patterns
+ */
+function getCSSModuleImportPatterns() {
+  return {
+    title: '🚨 MANDATORY CSS Module Import and Usage Pattern',
+    critical: 'This pattern is REQUIRED but differs based on context: developing INSIDE the design system vs USING the design system in another app.',
+    
+    contextWarning: {
+      title: '⚠️ CRITICAL: Two Different Contexts',
+      description: 'The patterns differ significantly based on where you are developing',
+      contexts: {
+        insideDesignSystem: 'Building components IN the ui-design-system repository',
+        usingDesignSystem: 'Building features in an app that USES @spaced-out/ui-design-system',
+      },
+      howToKnow: 'Check package.json: If it has "name": "@spaced-out/ui-design-system", you are INSIDE. If it has "@spaced-out/ui-design-system" as a dependency, you are USING it.',
+    },
+    
+    insideDesignSystem: {
+      title: '📦 Context: Developing INSIDE the Design System Repository',
+      fileNaming: {
+        tsx: 'ComponentName.tsx (PascalCase)',
+        css: 'ComponentName.module.css (PascalCase + .module.css)',
+        examples: ['DataTable.tsx + DataTable.module.css', 'UserProfile.tsx + UserProfile.module.css'],
+      },
+      cssImport: {
+        pattern: "import css from './ComponentName.module.css';",
+        examples: [
+          "import css from './DataTable.module.css';",
+          "import css from './UserProfile.module.css';",
+        ],
+      },
+      tokenImports: {
+        pattern: "@value (tokenName) from '../../styles/variables/_category.css';",
+        explanation: 'Use RELATIVE paths to the styles directory',
+        examples: [
+          "@value (size480) from '../../styles/variables/_size.css';",
+          "@value (colorPrimary) from '../../styles/variables/_color.css';",
+          "@value (spaceMedium) from '../../styles/variables/_space.css';",
+        ],
+      },
+      componentImports: {
+        pattern: "from 'src/components/ComponentName';",
+        examples: [
+          "import {Button} from 'src/components/Button';",
+          "import {Table} from 'src/components/Table';",
+        ],
+      },
+      utilImports: {
+        pattern: "from 'src/utils/utilName';",
+        examples: [
+          "import classify from 'src/utils/classify';",
+          "import {generateTestId} from 'src/utils/qa';",
+        ],
+      },
+    },
+    
+    usingDesignSystem: {
+      title: '🏗️ Context: Using Design System in Another Application',
+      fileNaming: {
+        tsx: 'component-name.tsx (kebab-case)',
+        css: 'component-name.css (kebab-case, NO .module.css suffix)',
+        examples: ['data-table.tsx + data-table.css', 'user-profile.tsx + user-profile.css'],
+        critical: '🚨 File is .css NOT .module.css',
+      },
+      cssImport: {
+        pattern: "import css from './component-name.css';",
+        examples: [
+          "import css from './data-table.css';",
+          "import css from './user-profile.css';",
+        ],
+        note: 'Notice: NO .module.css suffix in the filename',
+      },
+      tokenImports: {
+        pattern: "@value (tokenName) from '@spaced-out/ui-design-system/lib/styles/variables/_category.css';",
+        explanation: 'Use NPM PACKAGE path, not relative paths',
+        examples: [
+          "@value (size480) from '@spaced-out/ui-design-system/lib/styles/variables/_size.css';",
+          "@value (colorPrimary) from '@spaced-out/ui-design-system/lib/styles/variables/_color.css';",
+          "@value (spaceMedium) from '@spaced-out/ui-design-system/lib/styles/variables/_space.css';",
+        ],
+        critical: '🚨 Must use @spaced-out/ui-design-system/lib/styles/... NOT relative paths',
+      },
+      componentImports: {
+        pattern: "from '@spaced-out/ui-design-system/lib/components/ComponentName';",
+        examples: [
+          "import {Button} from '@spaced-out/ui-design-system/lib/components/Button';",
+          "import {Table} from '@spaced-out/ui-design-system/lib/components/Table';",
+        ],
+      },
+      utilImports: {
+        pattern: "from '@spaced-out/ui-design-system/lib/utils/utilName';",
+        examples: [
+          "import classify from '@spaced-out/ui-design-system/lib/utils/classify';",
+          "import {generateTestId} from '@spaced-out/ui-design-system/lib/utils/qa';",
+        ],
+      },
+    },
+    
+    comparisonTable: {
+      title: 'Side-by-Side Comparison',
+      aspect: {
+        tsxFileName: {
+          insideDS: 'ComponentName.tsx (PascalCase)',
+          usingDS: 'component-name.tsx (kebab-case)',
+        },
+        cssFileName: {
+          insideDS: 'ComponentName.module.css',
+          usingDS: 'component-name.css (NO .module)',
+        },
+        cssImport: {
+          insideDS: "import css from './ComponentName.module.css';",
+          usingDS: "import css from './component-name.css';",
+        },
+        tokenImport: {
+          insideDS: "@value (size480) from '../../styles/variables/_size.css';",
+          usingDS: "@value (size480) from '@spaced-out/ui-design-system/lib/styles/variables/_size.css';",
+        },
+        componentImport: {
+          insideDS: "import {Button} from 'src/components/Button';",
+          usingDS: "import {Button} from '@spaced-out/ui-design-system/lib/components/Button';",
+        },
+      },
+    },
+    
+    correctImport: {
+      pattern: 'import css from \'./ComponentName.module.css\';',
+      explanation: 'CSS Modules MUST be imported as a default import with the variable name "css"',
+      examples: [
+        'import css from \'./DataTable.module.css\';',
+        'import css from \'./UserProfile.module.css\';',
+        'import css from \'./NavigationBar.module.css\';',
+      ],
+    },
+    
+    incorrectImports: {
+      sideEffect: {
+        code: 'import \'./ComponentName.module.css\';',
+        error: '❌ WRONG: Side-effect imports do not provide access to class names',
+        why: 'This imports the CSS but you cannot access the class names in your component',
+      },
+      namespace: {
+        code: 'import * as css from \'./ComponentName.module.css\';',
+        error: '❌ WRONG: Namespace imports are not supported for CSS Modules',
+        why: 'CSS Modules use default exports, not named exports',
+      },
+      wrongVariableName: {
+        code: 'import styles from \'./ComponentName.module.css\';',
+        error: '❌ WRONG: Variable name must be "css" not "styles" or any other name',
+        why: 'Consistency across the codebase requires using "css" as the variable name',
+      },
+    },
+    
+    correctUsage: {
+      pattern: 'className={css.className}',
+      explanation: 'Class names are accessed as camelCase properties of the css object',
+      examples: [
+        '<div className={css.wrapper}>',
+        '<div className={css.tableHeader}>',
+        '<button className={css.submitButton}>',
+        '<span className={css.errorMessage}>',
+      ],
+      withClassify: [
+        'className={classify(css.wrapper, css.active)}',
+        'className={classify(css.button, { [css.disabled]: isDisabled })}',
+        'className={classify(css.container, classNames?.wrapper)}',
+      ],
+    },
+    
+    incorrectUsage: {
+      stringLiteral: {
+        code: '<div className="wrapper">',
+        error: '❌ WRONG: Never use string literals for class names',
+        why: 'CSS Modules provide scoped class names that must be accessed via the css object',
+      },
+      stringInBraces: {
+        code: '<div className={\'wrapper\'}>',
+        error: '❌ WRONG: String literals in braces are still wrong',
+        why: 'You must use the css object property access: className={css.wrapper}',
+      },
+      kebabCase: {
+        code: '<div className={css[\'table-header\']}>',
+        error: '❌ WRONG: Use camelCase properties, not kebab-case strings',
+        why: 'CSS class names are automatically converted to camelCase properties',
+      },
+    },
+    
+    cssFileNaming: {
+      inDesignSystem: {
+        pattern: 'ComponentName.module.css',
+        examples: [
+          'DataTable.module.css',
+          'UserProfile.module.css',
+          'NavigationBar.module.css',
+        ],
+      },
+      inMainApp: {
+        pattern: 'component-name.module.css (kebab-case)',
+        examples: [
+          'data-table.module.css',
+          'user-profile.module.css',
+          'navigation-bar.module.css',
+        ],
+        note: 'The main application uses kebab-case for file names',
+      },
+    },
+    
+    cssSyntax: {
+      classDefinition: 'Use camelCase for class names in CSS files',
+      correct: [
+        '.wrapper { }',
+        '.tableHeader { }',
+        '.submitButton { }',
+        '.errorMessage { }',
+      ],
+      incorrect: [
+        '.table-header { } // ❌ Use .tableHeader instead',
+        '.submit_button { } // ❌ Use .submitButton instead',
+      ],
+    },
+    
+    completeExamples: {
+      insideDesignSystem: {
+        title: 'Complete Example: Building INSIDE Design System',
+        tsx: `// DataTable.tsx (in ui-design-system repo)
+import * as React from 'react';
+import classify from 'src/utils/classify';
+import {generateTestId} from 'src/utils/qa';
+import {Button} from 'src/components/Button';
+import {SearchInput} from 'src/components/SearchInput';
+
+// 📦 INSIDE DESIGN SYSTEM: Import with .module.css and relative path
+import css from './DataTable.module.css';
+
+export const DataTable = () => (
+  <div className={css.wrapper}>
+    <div className={css.header}>
+      <SearchInput className={css.search} />
+      <Button>Filter</Button>
+    </div>
+    <table className={css.table}>
+      <thead className={css.thead}>
+        <tr>
+          <th className={css.th}>Name</th>
+          <th className={css.th}>Status</th>
+        </tr>
+      </thead>
+    </table>
+  </div>
+);`,
+        css: `/* DataTable.module.css (in ui-design-system repo) */
+/* 📦 INSIDE DESIGN SYSTEM: Import tokens with RELATIVE paths */
+@value (
+  colorBorderPrimary,
+  colorBackgroundTertiary
+) from '../../styles/variables/_color.css';
+
+@value (
+  spaceSmall,
+  spaceMedium
+) from '../../styles/variables/_space.css';
+
+@value (size480) from '../../styles/variables/_size.css';
+
+.wrapper {
+  display: flex;
+  flex-direction: column;
+  width: size480;
+}
+
+.header {
+  padding: spaceMedium;
+  background: colorBackgroundTertiary;
+}
+
+.table {
+  border: 1px solid colorBorderPrimary;
+}`,
+      },
+      usingDesignSystem: {
+        title: 'Complete Example: USING Design System in Another App',
+        tsx: `// data-table.tsx (in your app repo, NOT in ui-design-system)
+import * as React from 'react';
+import classify from '@spaced-out/ui-design-system/lib/utils/classify';
+import {generateTestId} from '@spaced-out/ui-design-system/lib/utils/qa';
+import {Button} from '@spaced-out/ui-design-system/lib/components/Button';
+import {SearchInput} from '@spaced-out/ui-design-system/lib/components/SearchInput';
+
+// 🏗️ USING DESIGN SYSTEM: Import WITHOUT .module.css, kebab-case filename
+import css from './data-table.css';
+
+export const DataTable = () => (
+  <div className={css.wrapper}>
+    <div className={css.header}>
+      <SearchInput className={css.search} />
+      <Button>Filter</Button>
+    </div>
+    <table className={css.table}>
+      <thead className={css.thead}>
+        <tr>
+          <th className={css.th}>Name</th>
+          <th className={css.th}>Status</th>
+        </tr>
+      </thead>
+    </table>
+  </div>
+);`,
+        css: `/* data-table.css (in your app repo, NOT in ui-design-system) */
+/* 🏗️ USING DESIGN SYSTEM: Import tokens from NPM PACKAGE path */
+@value (
+  colorBorderPrimary,
+  colorBackgroundTertiary
+) from '@spaced-out/ui-design-system/lib/styles/variables/_color.css';
+
+@value (
+  spaceSmall,
+  spaceMedium
+) from '@spaced-out/ui-design-system/lib/styles/variables/_space.css';
+
+@value (size480) from '@spaced-out/ui-design-system/lib/styles/variables/_size.css';
+
+.wrapper {
+  display: flex;
+  flex-direction: column;
+  width: size480;
+}
+
+.header {
+  padding: spaceMedium;
+  background: colorBackgroundTertiary;
+}
+
+.table {
+  border: 1px solid colorBorderPrimary;
+}`,
+      },
+    },
+  };
+}
+
 /**
  * Get design token import guidelines
  */
@@ -483,12 +904,22 @@ function getComponentTemplate() {
 import classify from 'src/utils/classify';
 import {generateTestId} from 'src/utils/qa';
 
+// 🚨 CRITICAL: CSS Modules MUST be imported as default import with variable name "css"
+// ✅ Correct: import css from './ComponentName.module.css';
+// ❌ WRONG: import './ComponentName.module.css';
+// ❌ WRONG: import * as css from './ComponentName.module.css';
+// ❌ WRONG: import styles from './ComponentName.module.css';
 import css from 'src/components/ComponentName/ComponentName.module.css';
 
 // IMPORTANT: Use pure TypeScript - NO Flow types
 // ✅ Correct: React.forwardRef<HTMLDivElement, Props>
 // ❌ Wrong: Flow.AbstractComponent<Props, HTMLDivElement>
 
+// IMPORTANT: Use className with CSS Module property access
+// ✅ Correct: className={css.wrapper}
+// ❌ WRONG: className="wrapper"
+// ❌ WRONG: className={'wrapper'}
+
 type ClassNames = Readonly<{
   wrapper?: string;
 }>;
@@ -669,6 +1100,8 @@ const server = new Server(
 server.setRequestHandler(ListResourcesRequestSchema, async () => {
   const components = getAllComponents();
   const hooks = getAllHooks();
+  const utils = getAllUtils();
+  const types = getAllTypes();
   
   const resources = [
     {
@@ -689,6 +1122,18 @@ server.setRequestHandler(ListResourcesRequestSchema, async () => {
       mimeType: 'application/json',
       description: `List of all ${hooks.length} available hooks`,
     },
+    {
+      uri: 'genesis://utils',
+      name: 'All Utils',
+      mimeType: 'application/json',
+      description: `List of all ${utils.length} available utility modules`,
+    },
+    {
+      uri: 'genesis://types',
+      name: 'All Types',
+      mimeType: 'application/json',
+      description: `List of all ${types.length} available type definitions`,
+    },
     {
       uri: 'genesis://tokens',
       name: 'Design Tokens',
@@ -717,6 +1162,26 @@ server.setRequestHandler(ListResourcesRequestSchema, async () => {
     });
   });
 
+  // Add individual util resources
+  utils.forEach(util => {
+    resources.push({
+      uri: `genesis://util/${util}`,
+      name: `Util: ${util}`,
+      mimeType: 'text/markdown',
+      description: `Utility functions for ${util}`,
+    });
+  });
+
+  // Add individual type resources
+  types.forEach(type => {
+    resources.push({
+      uri: `genesis://type/${type}`,
+      name: `Type: ${type}`,
+      mimeType: 'text/markdown',
+      description: `Type definitions for ${type}`,
+    });
+  });
+
   return { resources };
 });
 
@@ -736,6 +1201,8 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
 
 - **Components:** ${Object.keys(designSystemData.components).length}
 - **Hooks:** ${Object.keys(designSystemData.hooks).length}
+- **Utils:** ${Object.keys(designSystemData.utils || {}).length}
+- **Types:** ${Object.keys(designSystemData.types || {}).length}
 - **Design Token Categories:** ${Object.keys(designSystemData.tokens).length}
 
 ## Available Components
@@ -746,6 +1213,14 @@ ${getAllComponents().map(c => `- ${c}`).join('\n')}
 
 ${getAllHooks().map(h => `- ${h}`).join('\n')}
 
+## Available Utils
+
+${getAllUtils().map(u => `- ${u}`).join('\n')}
+
+## Available Types
+
+${getAllTypes().map(t => `- ${t}`).join('\n')}
+
 ## Design Token Categories
 
 ${Object.keys(designSystemData.tokens).map(cat => `- **${cat}**: ${Object.keys(designSystemData.tokens[cat]).length} file(s)`).join('\n')}
@@ -788,6 +1263,32 @@ ${Object.keys(designSystemData.tokens).map(cat => `- **${cat}**: ${Object.keys(d
     };
   }
 
+  if (uri === 'genesis://utils') {
+    const utils = getAllUtils();
+    return {
+      contents: [
+        {
+          uri,
+          mimeType: 'application/json',
+          text: JSON.stringify(utils, null, 2),
+        },
+      ],
+    };
+  }
+
+  if (uri === 'genesis://types') {
+    const types = getAllTypes();
+    return {
+      contents: [
+        {
+          uri,
+          mimeType: 'application/json',
+          text: JSON.stringify(types, null, 2),
+        },
+      ],
+    };
+  }
+
   if (uri === 'genesis://tokens') {
     const tokens = getAllDesignTokens();
     return {
@@ -850,6 +1351,18 @@ ${Object.keys(designSystemData.tokens).map(cat => `- **${cat}**: ${Object.keys(d
       markdown += '\n```\n\n';
     }
 
+    // Display additional files (sub-components)
+    if (details.files.additional && Object.keys(details.files.additional).length > 0) {
+      markdown += `## Additional Files (Sub-components)\n\n`;
+      
+      for (const [fileName, fileData] of Object.entries(details.files.additional)) {
+        markdown += `### ${fileName}\n\n`;
+        markdown += '```typescript\n';
+        markdown += fileData.content;
+        markdown += '\n```\n\n';
+      }
+    }
+
     return {
       contents: [
         {
@@ -898,6 +1411,67 @@ ${Object.keys(designSystemData.tokens).map(cat => `- **${cat}**: ${Object.keys(d
     };
   }
 
+  if (uri.startsWith('genesis://util/')) {
+    const utilName = uri.replace('genesis://util/', '');
+    const details = getUtilDetails(utilName);
+    
+    if (!details) {
+      throw new Error(`Util ${utilName} not found`);
+    }
+
+    let markdown = `# ${utilName}\n\n`;
+    markdown += `**Path:** \`${details.path}\`\n\n`;
+    markdown += `**Files:** ${details.allFiles.join(', ')}\n\n`;
+
+    // Display all files in the util module
+    if (details.files && Object.keys(details.files).length > 0) {
+      markdown += `## Utility Files\n\n`;
+      
+      for (const [fileName, fileData] of Object.entries(details.files)) {
+        markdown += `### ${fileName}\n\n`;
+        markdown += '```typescript\n';
+        markdown += fileData.content;
+        markdown += '\n```\n\n';
+      }
+    }
+
+    return {
+      contents: [
+        {
+          uri,
+          mimeType: 'text/markdown',
+          text: markdown,
+        },
+      ],
+    };
+  }
+
+  if (uri.startsWith('genesis://type/')) {
+    const typeName = uri.replace('genesis://type/', '');
+    const details = getTypeDetails(typeName);
+    
+    if (!details) {
+      throw new Error(`Type ${typeName} not found`);
+    }
+
+    let markdown = `# ${typeName}\n\n`;
+    markdown += `**Path:** \`${details.path}\`\n\n`;
+    markdown += `## Type Definitions\n\n`;
+    markdown += '```typescript\n';
+    markdown += details.content;
+    markdown += '\n```\n\n';
+
+    return {
+      contents: [
+        {
+          uri,
+          mimeType: 'text/markdown',
+          text: markdown,
+        },
+      ],
+    };
+  }
+
   throw new Error(`Unknown resource: ${uri}`);
 });
 
@@ -965,6 +1539,50 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           required: ['name'],
         },
       },
+      {
+        name: 'list_utils',
+        description: 'List all available utility modules in the design system',
+        inputSchema: {
+          type: 'object',
+          properties: {},
+        },
+      },
+      {
+        name: 'get_util',
+        description: 'Get detailed information about a specific utility module including all its functions',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            name: {
+              type: 'string',
+              description: 'Name of the utility module (e.g., "classify", "qa", "dom")',
+            },
+          },
+          required: ['name'],
+        },
+      },
+      {
+        name: 'list_types',
+        description: 'List all available type definitions in the design system',
+        inputSchema: {
+          type: 'object',
+          properties: {},
+        },
+      },
+      {
+        name: 'get_type',
+        description: 'Get detailed information about a specific type definition file',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            name: {
+              type: 'string',
+              description: 'Name of the type file (e.g., "common", "typography", "charts")',
+            },
+          },
+          required: ['name'],
+        },
+      },
       {
         name: 'get_design_tokens',
         description: 'Get all design tokens including colors, spacing, typography, shadows, etc.',
@@ -986,6 +1604,14 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           properties: {},
         },
       },
+      {
+        name: 'get_css_module_import_patterns',
+        description: '🚨 MANDATORY: Get the required CSS Module import and usage pattern based on context. This tool shows TWO different patterns: (1) Building INSIDE ui-design-system repo: .module.css files, PascalCase, relative imports. (2) USING design system in another app: .css files, kebab-case, @spaced-out/ui-design-system imports. MUST be called FIRST before generating any component to understand context and use correct patterns. Failure to follow context-specific patterns will cause import errors.',
+        inputSchema: {
+          type: 'object',
+          properties: {},
+        },
+      },
       {
         name: 'get_design_token_import_guidelines',
         description: 'Get guidelines and best practices for importing design tokens in CSS Module files. This includes the correct import paths, available token files, and examples of correct vs incorrect imports. ALWAYS call this function before creating CSS Module files to ensure correct token imports.',
@@ -996,7 +1622,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: 'get_css_module_guidelines',
-        description: 'Get comprehensive CSS Module styling guidelines including class naming conventions, token usage, icon color patterns, and common mistakes to avoid. CRITICAL: Call this before creating or modifying any CSS Module files to ensure consistency with the design system patterns.',
+        description: 'Get comprehensive CSS Module styling guidelines including MANDATORY import pattern (import css from "./file.module.css"), class naming conventions, token usage, icon color patterns, and common mistakes to avoid. 🚨 CRITICAL: Call this BEFORE creating or modifying any component files to ensure correct CSS Module usage and design system patterns. This includes the mandatory pattern: import css from "./Component.module.css" and className={css.className}.',
         inputSchema: {
           type: 'object',
           properties: {},
@@ -1126,6 +1752,76 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         };
       }
 
+      case 'list_utils': {
+        const utils = getAllUtils();
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify(utils, null, 2),
+            },
+          ],
+        };
+      }
+
+      case 'get_util': {
+        const details = getUtilDetails(args.name);
+        if (!details) {
+          return {
+            content: [
+              {
+                type: 'text',
+                text: `Util "${args.name}" not found`,
+              },
+            ],
+            isError: true,
+          };
+        }
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify(details, null, 2),
+            },
+          ],
+        };
+      }
+
+      case 'list_types': {
+        const types = getAllTypes();
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify(types, null, 2),
+            },
+          ],
+        };
+      }
+
+      case 'get_type': {
+        const details = getTypeDetails(args.name);
+        if (!details) {
+          return {
+            content: [
+              {
+                type: 'text',
+                text: `Type "${args.name}" not found`,
+              },
+            ],
+            isError: true,
+          };
+        }
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify(details, null, 2),
+            },
+          ],
+        };
+      }
+
       case 'get_design_tokens': {
         const allTokens = getAllDesignTokens();
         const tokens = args.category ? { [args.category]: allTokens[args.category] } : allTokens;
@@ -1151,6 +1847,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         };
       }
 
+      case 'get_css_module_import_patterns': {
+        const patterns = getCSSModuleImportPatterns();
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify(patterns, null, 2),
+            },
+          ],
+        };
+      }
+
       case 'get_design_token_import_guidelines': {
         const guidelines = getDesignTokenImportGuidelines();
         return {

package/mcp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spaced-out/genesis-mcp-server",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "MCP server for Genesis UI Design System - provides AI assistants with access to components, hooks, and design tokens",
   "type": "module",
   "main": "index.js",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spaced-out/ui-design-system",
-  "version": "0.5.21",
+  "version": "0.5.22",
   "description": "Sense UI components library",
   "author": {
     "name": "Spaced Out"