grg-kit-cli 0.6.7 → 0.6.9

package/bin/grg.js

@@ -21,7 +21,7 @@ program
   .option('-t, --theme <name>', 'Theme to install (grg-theme, claude, clean-slate, modern-minimal, amber-minimal, mocks)', 'grg-theme')
   .action(init);
 
-// Add command with block subcommand
+// Add command with block and component subcommands
 const addCommand = program.command('add').description('Add resources to your project');
 
 addCommand
@@ -31,6 +31,16 @@ addCommand
   .option('-o, --output <path>', 'Custom output directory')
   .action(add);
 
+addCommand
+  .command('component [componentName]')
+  .description('Add GRG components to your project (e.g., grg add component file-upload)')
+  .option('--all', 'Add all components')
+  .option('-o, --output <path>', 'Custom output directory')
+  .action(async (componentName, options) => {
+    const { addComponent } = require('../commands/add');
+    await addComponent(componentName, options);
+  });
+
 // List command
 program
   .command('list [category]')

package/commands/add.js

@@ -196,4 +196,100 @@ function showUsage(RESOURCES) {
   console.log(chalk.gray('\nRun'), chalk.cyan('grg list blocks'), chalk.gray('for more details'));
 }
 
-module.exports = { add };
+/**
+ * Add component command - downloads GRG components
+ * Format: grg add component <componentName>
+ * Examples:
+ *   grg add component file-upload      # Download file-upload component
+ *   grg add component --all            # All components
+ */
+async function addComponent(componentName, options) {
+  // Fetch catalog dynamically (with caching)
+  const spinner = ora('Fetching catalog...').start();
+  const RESOURCES = await fetchCatalog({ silent: true });
+  spinner.stop();
+
+  // Handle --all flag (download all components)
+  if (options.all) {
+    console.log(chalk.bold.cyan(`\n📦 Adding all components\n`));
+    
+    for (const component of RESOURCES.components) {
+      await downloadComponent(component, options.output);
+    }
+    
+    console.log(chalk.bold.green('✨ Done!'));
+    return;
+  }
+
+  // Validate component name
+  if (!componentName) {
+    showComponentUsage(RESOURCES);
+    process.exit(1);
+  }
+
+  const component = RESOURCES.components.find(c => c.name === componentName);
+  if (!component) {
+    console.error(chalk.red(`\nError: Component "${componentName}" not found`));
+    console.log(chalk.yellow('\nAvailable components:'));
+    RESOURCES.components.forEach(c => {
+      console.log(chalk.cyan(`  ${c.name}`), chalk.gray(`- ${c.description}`));
+    });
+    process.exit(1);
+  }
+
+  await downloadComponent(component, options.output);
+  console.log(chalk.bold.green('✨ Done!'));
+}
+
+/**
+ * Download a component
+ */
+async function downloadComponent(component, customOutput) {
+  const downloadSpinner = ora();
+  const outputPath = customOutput 
+    ? `${customOutput}/${component.name}` 
+    : component.defaultOutput;
+
+  downloadSpinner.start(`Downloading ${component.title}...`);
+
+  try {
+    const emitter = degit(`${REPO}/${component.path}`, {
+      cache: false,
+      force: true,
+      verbose: false,
+    });
+
+    await emitter.clone(outputPath);
+
+    downloadSpinner.succeed(chalk.green(`✓ ${component.title} added`));
+    console.log(chalk.gray(`  Location: ${outputPath}`));
+    
+    if (component.dependencies && component.dependencies.length > 0) {
+      console.log(chalk.gray(`  Dependencies: ${component.dependencies.join(', ')}`));
+    }
+    console.log();
+
+  } catch (error) {
+    downloadSpinner.fail(chalk.red(`Failed to download ${component.title}`));
+    console.error(chalk.red(error.message));
+  }
+}
+
+/**
+ * Show component usage help
+ */
+function showComponentUsage(RESOURCES) {
+  console.log(chalk.yellow('\nUsage: grg add component <componentName>\n'));
+  console.log(chalk.bold('Examples:'));
+  console.log(chalk.cyan('  grg add component file-upload'), chalk.gray('  # Download file-upload'));
+  console.log(chalk.cyan('  grg add component --all'), chalk.gray('        # All components'));
+  
+  console.log(chalk.bold('\nAvailable components:'));
+  RESOURCES.components.forEach(c => {
+    console.log(chalk.cyan(`  ${c.name}`), chalk.gray(`- ${c.description}`));
+  });
+  
+  console.log(chalk.gray('\nRun'), chalk.cyan('grg list components'), chalk.gray('for more details'));
+}
+
+module.exports = { add, addComponent };

package/commands/init.js

@@ -48,10 +48,12 @@ async function init(options) {
   // Step 1: Install Tailwind CSS v4
   spinner.start('Installing Tailwind CSS v4...');
   try {
-    await execAsync('npm install tailwindcss @tailwindcss/postcss postcss', { stdio: 'pipe' });
+    await execAsync('npm install tailwindcss @tailwindcss/postcss postcss');
     spinner.succeed(chalk.green('✓ Tailwind CSS v4 installed'));
   } catch (error) {
-    spinner.warn(chalk.yellow('Tailwind CSS installation skipped (may already be installed)'));
+    spinner.fail(chalk.red('Failed to install Tailwind CSS v4'));
+    console.error(chalk.gray(error.message));
+    process.exit(1);
   }
 
   // Step 3: Create .postcssrc.json
@@ -71,10 +73,12 @@ async function init(options) {
   // Step 4: Install Spartan-NG CLI
   spinner.start('Installing Spartan-NG CLI...');
   try {
-    await execAsync('npm install -D @spartan-ng/cli', { stdio: 'pipe' });
+    await execAsync('npm install -D @spartan-ng/cli');
     spinner.succeed(chalk.green('✓ Spartan-NG CLI installed'));
   } catch (error) {
-    spinner.warn(chalk.yellow('Spartan-NG CLI installation skipped'));
+    spinner.fail(chalk.red('Failed to install Spartan-NG CLI'));
+    console.error(chalk.gray(error.message));
+    process.exit(1);
   }
 
   // Step 5: Create components.json config file
@@ -97,9 +101,14 @@ async function init(options) {
     let tsconfigContent = await fs.readFile(tsconfigPath, 'utf-8');
     
     // Strip comments from tsconfig (Angular generates tsconfig with comments)
+    // Be careful not to strip // inside strings (like URLs)
     tsconfigContent = tsconfigContent
       .replace(/\/\*[\s\S]*?\*\//g, '') // Remove block comments
-      .replace(/\/\/.*/g, '');          // Remove line comments
+      .replace(/^\s*\/\/.*/gm, '');     // Remove line comments (only at start of line after whitespace)
+    
+    // Remove trailing commas (common in tsconfig files)
+    tsconfigContent = tsconfigContent
+      .replace(/,(\s*[}\]])/g, '$1');
     
     const tsconfig = JSON.parse(tsconfigContent);
     
@@ -123,9 +132,12 @@ async function init(options) {
   try {
     const { spawn } = require('child_process');
     await new Promise((resolve, reject) => {
-      const child = spawn('npx', ['ng', 'g', '@spartan-ng/cli:ui'], {
+      // Use 'ng' directly (works with global @angular/cli) instead of 'npx ng'
+      // Exit code 127 occurs when npx can't find the command
+      const child = spawn('ng', ['g', '@spartan-ng/cli:ui'], {
         stdio: ['pipe', 'pipe', 'pipe'],
-        shell: true
+        shell: true,
+        env: { ...process.env }  // Inherit PATH to find global ng
       });
 
       let output = '';
@@ -156,7 +168,9 @@ async function init(options) {
         }
       });
 
+      let stderrOutput = '';
       child.stderr.on('data', (data) => {
+        stderrOutput += data.toString();
         // Spartan CLI outputs progress to stderr
         const text = data.toString();
         if (text.includes('CREATE') || text.includes('UPDATE')) {
@@ -168,14 +182,24 @@ async function init(options) {
       child.on('close', (code) => {
         console.log(); // New line after progress dots
         if (code === 0) resolve();
-        else reject(new Error(`Process exited with code ${code}`));
+        else reject(new Error(`Process exited with code ${code}${stderrOutput ? '\n' + stderrOutput : ''}`));
+      });
+      child.on('error', (err) => {
+        if (err.code === 'ENOENT') {
+          reject(new Error('Angular CLI (ng) not found. Please install it: npm install -g @angular/cli'));
+        } else {
+          reject(err);
+        }
       });
-      child.on('error', reject);
     });
     spinner.succeed(chalk.green('✓ All Spartan-NG UI components installed'));
   } catch (error) {
     spinner.fail(chalk.red('Failed to run Spartan-NG UI generator'));
     console.error(chalk.red(error.message));
+    console.log(chalk.yellow('\nTroubleshooting:'));
+    console.log(chalk.gray('  1. Ensure Angular CLI is installed:'), chalk.cyan('npm install -g @angular/cli'));
+    console.log(chalk.gray('  2. Ensure @spartan-ng/cli is installed:'), chalk.cyan('npm install -D @spartan-ng/cli'));
+    console.log(chalk.gray('  3. Try running manually:'), chalk.cyan('ng g @spartan-ng/cli:ui'));
     process.exit(1);
   }
 

package/commands/list.js

@@ -3,7 +3,7 @@ const ora = require('ora');
 const { fetchCatalog } = require('../config/catalog-fetcher');
 
 /**
- * List command - displays available blocks and themes
+ * List command - displays available blocks, components, and themes
  * Usage: grg list [category]
  */
 async function list(category) {
@@ -17,16 +17,17 @@ async function list(category) {
     console.log(chalk.bold.cyan('\n📦 GRG Kit Resources\n'));
     
     console.log(chalk.bold('Blocks') + chalk.gray(` (${RESOURCES.blocks.length} available)`));
-    console.log(chalk.gray('  Add with: grg add block --<name>'));
+    console.log(chalk.gray('  Add with: grg add block <name>'));
     console.log(chalk.gray('  Run: grg list blocks\n'));
     
+    console.log(chalk.bold('Components') + chalk.gray(` (${RESOURCES.components.length} available)`));
+    console.log(chalk.gray('  Add with: grg add component <name>'));
+    console.log(chalk.gray('  Run: grg list components\n'));
+    
     console.log(chalk.bold('Themes') + chalk.gray(` (${RESOURCES.themes.length} available)`));
     console.log(chalk.gray('  Set with: grg init --theme <name>'));
     console.log(chalk.gray('  Run: grg list themes\n'));
     
-    console.log(chalk.gray('Components and spartan-ng examples are installed automatically with'), chalk.cyan('grg init'));
-    console.log();
-    
     return;
   }
 
@@ -36,7 +37,10 @@ async function list(category) {
       RESOURCES.blocks.forEach(block => {
         console.log(chalk.bold(`  ${block.name}`));
         console.log(chalk.gray(`    ${block.description}`));
-        console.log(chalk.yellow(`    grg add block --${block.name}`));
+        console.log(chalk.yellow(`    grg add block ${block.name}`));
+        if (block.files && block.files.length > 0) {
+          console.log(chalk.gray(`    Files: ${block.files.map(f => f.id).join(', ')}`));
+        }
         if (block.tags && block.tags.length > 0) {
           console.log(chalk.gray(`    Tags: ${block.tags.join(', ')}`));
         }
@@ -44,6 +48,23 @@ async function list(category) {
       });
       break;
 
+    case 'components':
+      console.log(chalk.bold.cyan('\n🧩 Available Components\n'));
+      console.log(chalk.gray('  Use with: grg add component <name>\n'));
+      RESOURCES.components.forEach(component => {
+        console.log(chalk.bold(`  ${component.name}`));
+        console.log(chalk.gray(`    ${component.description}`));
+        console.log(chalk.yellow(`    grg add component ${component.name}`));
+        if (component.dependencies && component.dependencies.length > 0) {
+          console.log(chalk.gray(`    Dependencies: ${component.dependencies.join(', ')}`));
+        }
+        if (component.tags && component.tags.length > 0) {
+          console.log(chalk.gray(`    Tags: ${component.tags.join(', ')}`));
+        }
+        console.log();
+      });
+      break;
+
     case 'themes':
       console.log(chalk.bold.cyan('\n🎨 Available Themes\n'));
       console.log(chalk.gray('  Use with: grg init --theme <name>\n'));
@@ -60,7 +81,7 @@ async function list(category) {
 
     default:
       console.error(chalk.red(`Error: Unknown category "${category}"`));
-      console.log(chalk.yellow('Valid categories: blocks, themes'));
+      console.log(chalk.yellow('Valid categories: blocks, components, themes'));
       process.exit(1);
   }
 }

package/commands/llm-setup.js

@@ -183,7 +183,7 @@ This project uses **GRG Kit**, a comprehensive Angular UI toolkit built on top o
 **GRG Kit Components** (in \`libs/grg-ui/\`):
 - Use \`grg-\` prefix for selectors
 - Import via \`GrgComponentImports\`
-- Example: \`GrgStepperImports\`
+- Example: \`GrgFileUploadImports\`
 - Path alias: \`@grg-kit/ui/component-name\`
 
 ### 3. Import Patterns
@@ -213,14 +213,14 @@ import { HlmDialogImports } from '@spartan-ng/helm/dialog';
 
 #### GRG Kit Components
 \`\`\`typescript
-import { GrgStepperImports } from '@grg-kit/ui/stepper';
+import { GrgFileUploadImports } from '@grg-kit/ui/file-upload';
 
 @Component({
-  imports: [GrgStepperImports],
+  imports: [GrgFileUploadImports],
   template: \`
-    <grg-stepper>
-      <grg-step>...</grg-step>
-    </grg-stepper>
+    <grg-file-upload>
+      <grg-file-upload-trigger>Drop files here</grg-file-upload-trigger>
+    </grg-file-upload>
   \`
 })
 \`\`\`
@@ -343,6 +343,178 @@ class="flex flex-col justify-between gap-4 py-4 sm:flex-row sm:items-center"
 [attr.data-state]="row.getIsSelected() && 'selected'"
 \`\`\`
 
+## TailwindCSS Best Practices (CRITICAL)
+
+### NEVER Use Raw Color Classes
+
+**FORBIDDEN - Do NOT use these patterns:**
+\`\`\`typescript
+// ❌ WRONG - Raw Tailwind colors
+class="text-green-600 bg-green-100"     // No raw green
+class="text-red-500 bg-red-50"          // No raw red
+class="text-yellow-600 bg-yellow-100"   // No raw yellow
+class="text-blue-500 bg-blue-100"       // No raw blue
+class="border-gray-200"                 // No raw gray
+class="text-slate-700"                  // No raw slate
+\`\`\`
+
+**REQUIRED - Use semantic color tokens:**
+\`\`\`typescript
+// ✅ CORRECT - Semantic colors from design system
+class="text-foreground"                 // Primary text
+class="text-muted-foreground"           // Secondary/muted text
+class="bg-background"                   // Page background
+class="bg-card"                         // Card background
+class="bg-muted"                        // Muted/subtle background
+class="bg-primary text-primary-foreground"  // Primary actions
+class="bg-secondary text-secondary-foreground"  // Secondary elements
+class="bg-destructive text-destructive-foreground"  // Errors/danger
+class="bg-accent text-accent-foreground"  // Accents/highlights
+class="border-border"                   // Standard borders
+class="border-input"                    // Input borders
+\`\`\`
+
+### Available Semantic Colors
+
+These are the ONLY colors you should use (defined in \`styles.css\` and theme files):
+
+| Token | Usage |
+|-------|-------|
+| \`background\` / \`foreground\` | Page background and primary text |
+| \`card\` / \`card-foreground\` | Card containers |
+| \`popover\` / \`popover-foreground\` | Popovers, dropdowns |
+| \`primary\` / \`primary-foreground\` | Primary buttons, links |
+| \`secondary\` / \`secondary-foreground\` | Secondary actions |
+| \`muted\` / \`muted-foreground\` | Subtle backgrounds, secondary text |
+| \`accent\` / \`accent-foreground\` | Highlights, hover states |
+| \`destructive\` / \`destructive-foreground\` | Errors, delete actions |
+| \`border\` | Standard borders |
+| \`input\` | Form input borders |
+| \`ring\` | Focus rings |
+| \`chart-1\` through \`chart-5\` | Chart/data visualization colors |
+| \`sidebar-*\` | Sidebar-specific colors |
+
+### Adding New Semantic Colors
+
+If you need a color that doesn't exist (e.g., success, warning, info):
+
+**Step 1: Add CSS variables to \`src/styles.css\`:**
+\`\`\`css
+:root {
+  /* Existing variables... */
+  
+  /* Add new semantic color with BOTH light and dark values */
+  --success: oklch(0.72 0.19 142);           /* Green for light mode */
+  --success-foreground: oklch(1 0 0);        /* White text */
+  
+  --warning: oklch(0.75 0.18 85);            /* Amber for light mode */
+  --warning-foreground: oklch(0.2 0 0);      /* Dark text */
+  
+  --info: oklch(0.65 0.15 250);              /* Blue for light mode */
+  --info-foreground: oklch(1 0 0);           /* White text */
+}
+
+.dark {
+  /* Dark mode equivalents */
+  --success: oklch(0.65 0.17 142);
+  --success-foreground: oklch(1 0 0);
+  
+  --warning: oklch(0.70 0.16 85);
+  --warning-foreground: oklch(0.15 0 0);
+  
+  --info: oklch(0.60 0.14 250);
+  --info-foreground: oklch(1 0 0);
+}
+\`\`\`
+
+**Step 2: Register in \`@theme inline\` block (in theme file):**
+\`\`\`css
+@theme inline {
+  --color-success: var(--success);
+  --color-success-foreground: var(--success-foreground);
+  --color-warning: var(--warning);
+  --color-warning-foreground: var(--warning-foreground);
+  --color-info: var(--info);
+  --color-info-foreground: var(--info-foreground);
+}
+\`\`\`
+
+**Step 3: Now use in templates:**
+\`\`\`typescript
+class="bg-success text-success-foreground"  // Success states
+class="bg-warning text-warning-foreground"  // Warning states
+class="bg-info text-info-foreground"        // Info states
+\`\`\`
+
+### Typography Best Practices
+
+**NEVER use arbitrary font sizes:**
+\`\`\`typescript
+// ❌ WRONG - Arbitrary sizes
+class="text-[13px]"     // No arbitrary values
+class="text-[1.1rem]"   // No arbitrary values
+\`\`\`
+
+**USE the Tailwind typography scale:**
+\`\`\`typescript
+// ✅ CORRECT - Standard typography scale
+class="text-xs"    // 0.75rem (12px)
+class="text-sm"    // 0.875rem (14px)
+class="text-base"  // 1rem (16px) - default body
+class="text-lg"    // 1.125rem (18px)
+class="text-xl"    // 1.25rem (20px)
+class="text-2xl"   // 1.5rem (24px)
+class="text-3xl"   // 1.875rem (30px)
+class="text-4xl"   // 2.25rem (36px)
+\`\`\`
+
+**Font weights:**
+\`\`\`typescript
+class="font-normal"    // 400
+class="font-medium"    // 500
+class="font-semibold"  // 600
+class="font-bold"      // 700
+\`\`\`
+
+**Font families (from theme):**
+\`\`\`typescript
+class="font-sans"   // System UI font stack
+class="font-mono"   // Monospace for code
+class="font-serif"  // Serif for special cases
+\`\`\`
+
+### Spacing Best Practices
+
+**USE the standard spacing scale:**
+\`\`\`typescript
+// ✅ CORRECT - Standard spacing
+class="p-4"      // 1rem
+class="gap-2"    // 0.5rem
+class="mt-6"     // 1.5rem
+class="space-y-4" // 1rem between children
+\`\`\`
+
+**AVOID arbitrary spacing unless absolutely necessary:**
+\`\`\`typescript
+// ❌ AVOID - Arbitrary spacing
+class="p-[13px]"  // Use p-3 or p-4 instead
+\`\`\`
+
+### Dark Mode Support
+
+All semantic colors automatically support dark mode. The theme system handles this via:
+- \`:root\` for light mode values
+- \`.dark\` or \`[data-theme="theme-name"].dark\` for dark mode values
+
+**You do NOT need to add \`dark:\` prefixes** when using semantic colors:
+\`\`\`typescript
+// ✅ CORRECT - Semantic colors auto-adapt
+class="bg-background text-foreground"  // Works in both light and dark
+
+// ❌ WRONG - Manual dark mode with raw colors
+class="bg-white dark:bg-gray-900"  // Don't do this
+\`\`\`
+
 ### Component Variants
 Components support multiple variants through the \`variant\` attribute:
 
@@ -504,7 +676,7 @@ export class FormComponent {
 - **Slider**: Range input controls
 
 ### GRG Kit Custom Components
-- **Stepper**: Multi-step form wizard component
+- **File Upload**: Drag and drop file upload component
 
 ## Package Manager
 
@@ -568,7 +740,7 @@ After adding, restart your IDE for the MCP server to be available.
 Use the MCP server for:
 1. **Themes** - Install different color themes
 2. **Blocks** - Pre-built page layouts (auth, shell, settings)
-3. **GRG Kit Components** - Custom components like stepper, file-upload
+3. **GRG Kit Components** - Custom components like file-upload
 
 **Do NOT use MCP for:**
 - Spartan-NG components (button, card, dialog, etc.) - already installed
@@ -592,7 +764,7 @@ mcp2_search_ui_resources({
 **When to use:**
 - User needs a page layout or block
 - Looking for a theme
-- Need a GRG Kit component (stepper, file-upload)
+- Need a GRG Kit component (file-upload)
 
 ### 2. mcp2_suggest_resources
 
@@ -698,14 +870,14 @@ AI Workflow:
 ### Example 4: User Wants a Form Component
 
 \`\`\`
-User: "I need a multi-step form"
+User: "I need a file upload"
 
 AI Workflow:
-1. mcp2_search_ui_resources({ query: "stepper form" })
-   → Finds: component:stepper
+1. mcp2_search_ui_resources({ query: "file upload" })
+   → Finds: component:file-upload
    
 2. Components are included automatically with grg init
-   → Just import and use: import { GrgStepperImports } from '@grg-kit/ui/stepper';
+   → Just import and use: import { GrgFileUploadImports } from '@grg-kit/ui/file-upload';
    
 3. Use with Spartan-NG form components (from design-system.md)
 \`\`\`
@@ -735,7 +907,7 @@ User request:
 ├─ Need a theme?
 │  └─ Use MCP: mcp2_list_available_resources({ category: "themes" })
 │
-└─ Need stepper, file-upload, or other GRG Kit component?
+└─ Need file-upload or other GRG Kit component?
    └─ Use MCP: mcp2_search_ui_resources({ query: "..." })
 \`\`\`
 
@@ -789,7 +961,7 @@ import { HlmDialogImports } from '@spartan-ng/helm/dialog';
 
 **GRG Kit (grg- prefix):**
 \`\`\`typescript
-import { GrgStepperImports } from '@grg-kit/ui/stepper';
+import { GrgFileUploadImports } from '@grg-kit/ui/file-upload';
 \`\`\`
 
 ### Common Patterns
@@ -849,15 +1021,56 @@ import { lucideCheck, lucideX } from '@ng-icons/lucide';
 Use MCP only for:
 - **Blocks** (auth, shell, settings) - \`mcp2_search_ui_resources({ query: "auth" })\`
 - **Themes** - \`mcp2_list_available_resources({ category: "themes" })\`
-- **GRG Kit components** (stepper, file-upload) - \`mcp2_search_ui_resources({ query: "stepper" })\`
+- **GRG Kit components** (file-upload) - \`mcp2_search_ui_resources({ query: "file-upload" })\`
 
 **Do NOT use MCP for Spartan-NG components** - they are already installed!
 
+## TailwindCSS Rules (CRITICAL)
+
+### NEVER use raw Tailwind colors:
+\`\`\`html
+<!-- ❌ FORBIDDEN -->
+<div class="text-green-600 bg-green-100">Success</div>
+<div class="text-red-500">Error</div>
+<div class="bg-yellow-50 border-yellow-200">Warning</div>
+\`\`\`
+
+### ALWAYS use semantic color tokens:
+\`\`\`html
+<!-- ✅ CORRECT -->
+<div class="bg-primary text-primary-foreground">Primary</div>
+<div class="bg-destructive text-destructive-foreground">Error</div>
+<div class="text-muted-foreground">Secondary text</div>
+<div class="bg-muted">Subtle background</div>
+<div class="border-border">Standard border</div>
+\`\`\`
+
+### Available semantic colors:
+\`background\`, \`foreground\`, \`card\`, \`card-foreground\`, \`popover\`, \`popover-foreground\`,
+\`primary\`, \`primary-foreground\`, \`secondary\`, \`secondary-foreground\`, \`muted\`, \`muted-foreground\`,
+\`accent\`, \`accent-foreground\`, \`destructive\`, \`destructive-foreground\`, \`border\`, \`input\`, \`ring\`
+
+### Need a new color (e.g., success, warning)?
+1. Add CSS variable to \`src/styles.css\` with light AND dark mode values
+2. Register in \`@theme inline\` block
+3. Then use: \`bg-success text-success-foreground\`
+
+### Typography - use standard scale:
+\`\`\`html
+<!-- ✅ CORRECT -->
+<p class="text-sm">Small</p>
+<p class="text-base">Body</p>
+<h2 class="text-xl font-semibold">Heading</h2>
+
+<!-- ❌ WRONG - arbitrary sizes -->
+<p class="text-[13px]">Don't do this</p>
+\`\`\`
+
 ## Remember
 - Spartan-NG components are pre-installed - just import and use
 - Follow existing patterns in the codebase
-- Use TailwindCSS v4 for styling
-- Prefer signals for state management
+- Use TailwindCSS v4 for styling with SEMANTIC colors only
+- NEVER use raw colors like text-green-600, bg-yellow-100, etc.
 `;
 }
 
@@ -900,7 +1113,7 @@ import { HlmDialogImports } from '@spartan-ng/helm/dialog';
 
 **GRG Kit:**
 \`\`\`typescript
-import { GrgStepperImports } from '@grg-kit/ui/stepper';
+import { GrgFileUploadImports } from '@grg-kit/ui/file-upload';
 \`\`\`
 
 ## Common Components
@@ -982,7 +1195,7 @@ ${blocksList}
 - Need button, card, dialog, form field, table? → Use Spartan-NG (already installed)
 - Need page layout (dashboard, auth, settings)? → Use MCP: \`mcp2_search_ui_resources\`
 - Need theme? → Use MCP: \`mcp2_list_available_resources({ category: "themes" })\`
-- Need stepper, file-upload? → Use MCP: \`mcp2_search_ui_resources\`
+- Need file-upload? → Use MCP: \`mcp2_search_ui_resources\`
 
 ## Package Manager
 
@@ -991,6 +1204,91 @@ Use npm for package management.
 ## Styling
 
 Use TailwindCSS v4 for all styling. Prefer signals for state management.
+
+## TailwindCSS Best Practices (CRITICAL)
+
+### NEVER use raw Tailwind colors:
+\`\`\`html
+<!-- ❌ FORBIDDEN - These break theming and dark mode -->
+<div class="text-green-600 bg-green-100">Success</div>
+<div class="text-red-500">Error</div>
+<div class="bg-yellow-50">Warning</div>
+<div class="border-gray-200">Border</div>
+\`\`\`
+
+### ALWAYS use semantic color tokens:
+\`\`\`html
+<!-- ✅ CORRECT - These respect theming and dark mode -->
+<div class="bg-primary text-primary-foreground">Primary action</div>
+<div class="bg-destructive text-destructive-foreground">Error/Delete</div>
+<div class="text-muted-foreground">Secondary text</div>
+<div class="bg-muted">Subtle background</div>
+<div class="bg-accent text-accent-foreground">Highlighted</div>
+<div class="border-border">Standard border</div>
+\`\`\`
+
+### Available semantic colors:
+| Token | Usage |
+|-------|-------|
+| \`background\` / \`foreground\` | Page background, primary text |
+| \`card\` / \`card-foreground\` | Card containers |
+| \`primary\` / \`primary-foreground\` | Primary buttons, CTAs |
+| \`secondary\` / \`secondary-foreground\` | Secondary actions |
+| \`muted\` / \`muted-foreground\` | Subtle backgrounds, secondary text |
+| \`accent\` / \`accent-foreground\` | Highlights, hover states |
+| \`destructive\` / \`destructive-foreground\` | Errors, delete actions |
+| \`border\` | Standard borders |
+| \`input\` | Form input borders |
+
+### Adding new semantic colors (e.g., success, warning, info):
+
+**Step 1:** Add to \`src/styles.css\` with BOTH light and dark values:
+\`\`\`css
+:root {
+  --success: oklch(0.72 0.19 142);
+  --success-foreground: oklch(1 0 0);
+}
+.dark {
+  --success: oklch(0.65 0.17 142);
+  --success-foreground: oklch(1 0 0);
+}
+\`\`\`
+
+**Step 2:** Register in \`@theme inline\` block in theme file:
+\`\`\`css
+@theme inline {
+  --color-success: var(--success);
+  --color-success-foreground: var(--success-foreground);
+}
+\`\`\`
+
+**Step 3:** Use in templates:
+\`\`\`html
+<div class="bg-success text-success-foreground">Success!</div>
+\`\`\`
+
+### Typography - use standard scale only:
+\`\`\`html
+<!-- ✅ CORRECT -->
+<p class="text-sm">Small (14px)</p>
+<p class="text-base">Body (16px)</p>
+<h2 class="text-xl font-semibold">Heading</h2>
+
+<!-- ❌ WRONG - arbitrary sizes -->
+<p class="text-[13px]">Avoid arbitrary values</p>
+\`\`\`
+
+Standard scale: \`text-xs\` (12px), \`text-sm\` (14px), \`text-base\` (16px), \`text-lg\` (18px), \`text-xl\` (20px), \`text-2xl\` (24px), \`text-3xl\` (30px), \`text-4xl\` (36px)
+
+### Dark mode is automatic:
+Semantic colors automatically adapt to dark mode. Do NOT use \`dark:\` prefix with raw colors.
+\`\`\`html
+<!-- ✅ Auto-adapts to dark mode -->
+<div class="bg-background text-foreground">Content</div>
+
+<!-- ❌ Don't do this -->
+<div class="bg-white dark:bg-gray-900">Content</div>
+\`\`\`
 `;
 }
 

package/config/resources.js

@@ -145,23 +145,6 @@ const RESOURCES = {
       "dependencies": [
         "@spartan-ng/helm/button"
       ]
-    },
-    {
-      "name": "stepper",
-      "title": "Stepper Component",
-      "description": "Multi-step form component with progress indicator",
-      "path": "templates/ui/components/stepper",
-      "defaultOutput": "src/app/components/stepper",
-      "tags": [
-        "form",
-        "wizard",
-        "multi-step",
-        "progress"
-      ],
-      "dependencies": [
-        "@spartan-ng/helm/button",
-        "@spartan-ng/helm/card"
-      ]
     }
   ],
   "blocks": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grg-kit-cli",
-  "version": "0.6.7",
+  "version": "0.6.9",
   "description": "CLI tool for pulling GRG Kit resources into your Angular project",
   "main": "index.js",
   "bin": {

package/scripts/README.md

@@ -187,7 +187,6 @@ grg-kit/
 │   │       ├── meta.json               ← All themes metadata
 │   │       └── *.css
 │   ├── libs/grg-ui/
-│   │   ├── stepper/meta.json
 │   │   └── file-upload/meta.json
 │   └── scripts/
 │       └── generate-sources.js         ← Stage 1
@@ -216,8 +215,7 @@ grg-kit/
         │   ├── meta.json               ← Copied from app
         │   └── *.css
         └── components/
-            ├── stepper/meta.json       ← Copied from app
-            └── file-upload/meta.json
+            └── file-upload/meta.json   ← Copied from app
 ```
 
 ---

package/config/.catalog-cache.json

@@ -1 +0,0 @@
-{"timestamp":1765202627293,"data":{"themes":[{"name":"amber-minimal","title":"Amber Minimal","description":"Warm amber accents","file":"amber-minimal.css","tags":["minimal","warm","amber","orange"],"features":["dark-mode","tailwind-v4","spartan-ng","oklch"],"path":"templates/ui/themes/amber-minimal.css","defaultOutput":"src/themes/amber-minimal.css"},{"name":"claude","title":"Claude","description":"Claude-inspired warm tones","file":"claude.css","tags":["warm","orange","brown","claude"],"features":["dark-mode","tailwind-v4","spartan-ng","oklch"],"path":"templates/ui/themes/claude.css","defaultOutput":"src/themes/claude.css"},{"name":"clean-slate","title":"Clean Slate","description":"Minimal grayscale palette","file":"clean-slate.css","tags":["minimal","grayscale","neutral","clean"],"features":["dark-mode","tailwind-v4","spartan-ng","oklch"],"path":"templates/ui/themes/clean-slate.css","defaultOutput":"src/themes/clean-slate.css"},{"name":"grg-theme","title":"Grg Theme","description":"Default theme with purple/orange accents","file":"grg-theme.css","tags":["default","purple","orange","colorful"],"features":["dark-mode","tailwind-v4","spartan-ng","oklch"],"path":"templates/ui/themes/grg-theme.css","defaultOutput":"src/themes/grg-theme.css"},{"name":"mocks","title":"Mocks","description":"Theme for mockups and prototypes","file":"mocks.css","tags":["mockup","prototype","design"],"features":["dark-mode","tailwind-v4","spartan-ng","oklch"],"path":"templates/ui/themes/mocks.css","defaultOutput":"src/themes/mocks.css"},{"name":"modern-minimal","title":"Modern Minimal","description":"Contemporary minimal design","file":"modern-minimal.css","tags":["minimal","modern","contemporary","clean"],"features":["dark-mode","tailwind-v4","spartan-ng","oklch"],"path":"templates/ui/themes/modern-minimal.css","defaultOutput":"src/themes/modern-minimal.css"}],"components":[{"name":"file-upload","title":"File Upload","description":"Drag and drop file upload component","tags":["file","upload","form","drag-drop"],"dependencies":["@spartan-ng/helm/button"],"path":"templates/ui/components/file-upload","defaultOutput":"src/app/components/file-upload"},{"name":"stepper","title":"Stepper","description":"Multi-step form component with progress indicator","tags":["form","wizard","multi-step","progress"],"dependencies":["@spartan-ng/helm/button","@spartan-ng/helm/card"],"path":"templates/ui/components/stepper","defaultOutput":"src/app/components/stepper"}],"blocks":[{"name":"auth","title":"Auth","description":"Authentication pages (login, signup, forgot password)","tags":["auth","login","signup","authentication","form"],"dependencies":["@spartan-ng/helm/button","@spartan-ng/helm/card","@spartan-ng/helm/form-field"],"files":[{"id":"forgot-password","file":"forgot-password.component.ts","title":"Forgot Password","description":"Forgot Password"},{"id":"login","file":"login.component.ts","title":"Login","description":"Login"},{"id":"register","file":"register.component.ts","title":"Register","description":"Register"}],"path":"templates/ui/blocks/auth","defaultOutput":"src/app/blocks/auth"},{"name":"settings","title":"Settings","description":"Settings pages: profile, notifications, security, danger zone","tags":["settings","preferences","account","profile","security"],"dependencies":["@spartan-ng/helm/button","@spartan-ng/helm/card","@spartan-ng/helm/form-field","@spartan-ng/helm/switch"],"files":[{"id":"danger-zone","file":"danger-zone.component.ts","title":"Danger Zone","description":"Danger Zone"},{"id":"notification","file":"notification-settings.component.ts","title":"Notification Settings","description":"Notification Settings"},{"id":"profile","file":"profile-settings.component.ts","title":"Profile Settings","description":"Profile Settings"},{"id":"security","file":"security-settings.component.ts","title":"Security Settings","description":"Security Settings"}],"path":"templates/ui/blocks/settings","defaultOutput":"src/app/blocks/settings"},{"name":"shell","title":"Shell","description":"Application shell layouts: sidebar, topnav, collapsible - each with optional footer variant","tags":["shell","layout","sidebar","header","footer","navigation","topnav","collapsible"],"dependencies":["@spartan-ng/helm/button","@spartan-ng/helm/icon","@spartan-ng/helm/dropdown-menu"],"files":[{"id":"collapsible-footer","file":"collapsible-shell-footer.component.ts","title":"Collapsible Shell Footer","description":"Collapsible Shell Footer"},{"id":"collapsible","file":"collapsible-shell.component.ts","title":"Collapsible Shell","description":"Collapsible Shell"},{"id":"sidebar-footer","file":"sidebar-shell-footer.component.ts","title":"Sidebar Shell Footer","description":"Sidebar Shell Footer"},{"id":"sidebar","file":"sidebar-shell.component.ts","title":"Sidebar Shell","description":"Sidebar Shell"},{"id":"topnav-footer","file":"topnav-shell-footer.component.ts","title":"Topnav Shell Footer","description":"Topnav Shell Footer"},{"id":"topnav","file":"topnav-shell.component.ts","title":"Topnav Shell","description":"Topnav Shell"}],"path":"templates/ui/blocks/shell","defaultOutput":"src/app/blocks/shell"}]}}