shadcn Dark Mode Broken by AI-Generated Hardcoded Colors

// Conceptual pipeline — illustrates the workflow stages
// v0.dev and Cursor do not expose programmatic APIs; this is a process diagram in code form

interface ComponentSpec {
  name: string;          // PascalCase: UserAvatar, MetricCard, DataTable
  description: string;   // One sentence: what it does, not how it looks
  props: PropSpec[];
  variants: VariantSpec[];
  states: string[];      // Always include: loading, error, empty
  isServerComponent: boolean; // React 19: explicit decision required
}

interface PipelineStage {
  tool: 'v0.dev' | 'cursor' | 'developer';
  input: string;
  output: string;
  qualityCheck: string;
}

const pipeline: PipelineStage[] = [
  {
    tool: 'developer',
    input: 'Product requirement or design file',
    output: 'ComponentSpec — structured definition of props, variants, states',
    qualityCheck: 'Does the spec describe one cohesive component, or should it be split?',
  },
  {
    tool: 'v0.dev',
    input: 'ComponentSpec converted to a structured prompt',
    output: 'React component scaffold with Tailwind classes and TypeScript types',
    qualityCheck: 'Does it render? Are hardcoded colors present? Check Design Mode for layout issues.',
  },
  {
    tool: 'cursor',
    input: 'v0.dev scaffold pasted into project',
    output: 'Project-native component using design tokens, existing hooks, and proper types',
    qualityCheck: 'Does tsc --noEmit pass? Does it render correctly in light and dark mode?',
  },
  {
    tool: 'developer',
    input: 'Cursor-adapted component',
    output: 'Reviewed, tested, and merged component with Storybook story',
    qualityCheck: 'All four quality gates passed. PR approved.',
  },
];

Create a shadcn/ui {COMPONENT_NAME} component with the following requirements:

Core function: {ONE_SENTENCE — what it does, not how it looks}

Props:
- {PROP_NAME}: {TYPE} — {ONE_LINE_DESCRIPTION}
- {PROP_NAME}: {TYPE} — {ONE_LINE_DESCRIPTION}
- {PROP_NAME}: {TYPE} (optional) — {ONE_LINE_DESCRIPTION}

Variants:
- {VARIANT_NAME}: {OPTION_1} | {OPTION_2} | {OPTION_3}
- size: sm | md | lg

States to handle:
- loading: show a Skeleton placeholder
- error: show an inline error message with retry option
- empty: show an empty state with a descriptive message

Technical requirements:
- Use these shadcn/ui primitives: {LIST — e.g., Card, Button, Badge, Skeleton}
- Style exclusively with semantic color tokens: bg-primary, text-muted-foreground,
  border-border, text-foreground, bg-muted (Tailwind v4 @theme tokens — no hardcoded scales)
- All props must have explicit TypeScript types — no any
- Export the component as a named export
- Include a Props interface above the component definition
- {IF CLIENT COMPONENT}: Add 'use client' directive at top
- {IF SERVER COMPONENT}: No useState or useEffect — accept data as props

// Cursor refactoring sequence — use these as Cmd+K prompts or Agent mode instructions
// Run them in order for consistent results

// Step 1: Token compliance
// "Replace all hardcoded Tailwind color classes with semantic tokens.
//  Reference the @theme block in src/styles/globals.css for available token names.
//  Do not use bg-white, text-gray-*, bg-gray-*, or any raw color scale."

// Step 2: Hook integration
// "Replace the local useState and useEffect data fetching logic with our
//  custom useDataTable hook from @/hooks/useDataTable.
//  The hook accepts: { data, pageSize, sortable, filterable }.
//  It returns: { rows, pagination, sort, filter, isLoading, error }."

// Step 3: Type alignment
// "Replace the generic Row type with the TableRow interface from @/types/table.ts.
//  Replace any with the specific types from that file.
//  Run tsc --noEmit after changes to confirm no type errors."

// Step 4: State handling
// "Add loading state using our Skeleton component from @/components/ui/skeleton.
//  Add error state using our Alert component with a retry button.
//  Add empty state with an EmptyState component showing the emptyMessage prop."

// Step 5: Server/client boundary (React 19)
// "Evaluate whether this component requires 'use client'.
//  If it only receives data via props and has no browser-only APIs,
//  remove 'use client' and convert to a server component."

// Step 6: Variant extraction
// "Using the base component above as the default variant,
//  create a compact variant that reduces row padding to py-1
//  and hides the checkbox selection column.
//  Export it as DataTableCompact from the same file."

// After all steps, the component should:
// - Import from project barrel exports, not direct component paths
// - Use semantic color tokens exclusively
// - Delegate state management to useDataTable
// - Handle loading, error, and empty states
// - Pass tsc --noEmit with zero errors
// - Render correctly in light and dark mode

// Component Specification Schema
// Every component is defined here before generation begins
// This file is reviewed once; the generated component is reviewed once
// Both together take less time than manual component creation

interface PropSpec {
  name: string;
  type: string;
  required: boolean;
  description: string;
  defaultValue?: string;
}

interface VariantSpec {
  name: string;      // e.g., "size", "status", "density"
  options: string[]; // e.g., ["sm", "md", "lg"]
  default: string;
}

interface ComponentSpec {
  name: string;              // PascalCase
  description: string;       // One sentence — what it does
  props: PropSpec[];
  variants: VariantSpec[];
  states: string[];          // loading, error, empty — always all three
  shadcnPrimitives: string[]; // Exact primitives to reference in the prompt
  isServerComponent: boolean; // React 19: explicit decision before generation
  storybook: boolean;        // Always true — every component gets a story
}

// Example specs
const componentSpecs: ComponentSpec[] = [
  {
    name: 'DataTable',
    description: 'Sortable, filterable table with pagination and row selection',
    props: [
      { name: 'data', type: 'T[]', required: true, description: 'Array of row data objects' },
      { name: 'columns', type: 'ColumnDef<T>[]', required: true, description: 'Column configuration array' },
      { name: 'onRowSelect', type: '(rows: T[]) => void', required: false, description: 'Callback fired when row selection changes' },
      { name: 'emptyMessage', type: 'string', required: false, defaultValue: 'No results found', description: 'Message shown in empty state' },
    ],
    variants: [
      { name: 'density', options: ['compact', 'default', 'comfortable'], default: 'default' },
    ],
    states: ['loading', 'error', 'empty'],
    shadcnPrimitives: ['Table', 'Checkbox', 'Button', 'Skeleton', 'Alert'],
    isServerComponent: false, // Requires interactivity for sorting and selection
    storybook: true,
  },
  {
    name: 'MetricCard',
    description: 'Displays a single KPI metric with label, value, trend indicator, and comparison period',
    props: [
      { name: 'label', type: 'string', required: true, description: 'Metric name' },
      { name: 'value', type: 'string | number', required: true, description: 'Current metric value' },
      { name: 'trend', type: "'up' | 'down' | 'neutral'", required: false, description: 'Trend direction vs comparison period' },
      { name: 'trendValue', type: 'string', required: false, description: 'e.g., "+12.4%" — shown next to trend indicator' },
    ],
    variants: [
      { name: 'size', options: ['sm', 'md', 'lg'], default: 'md' },
    ],
    states: ['loading', 'error', 'empty'],
    shadcnPrimitives: ['Card', 'CardHeader', 'CardContent', 'Skeleton'],
    isServerComponent: true, // Display only — no interactivity required
    storybook: true,
  },
];

// Quality gate runner — run before any generated component is merged
// Requires: Storybook running, dev server running, tsc available

interface QualityReport {
  componentName: string;
  passed: boolean;
  failures: string[];
  warnings: string[];
}

async function runQualityGates(componentPath: string, componentName: string): Promise<QualityReport> {
  const report: QualityReport = {
    componentName,
    passed: true,
    failures: [],
    warnings: [],
  };

  console.log(`\nRunning quality gates for ${componentName}...`);

  // Gate 1: TypeScript check
  // Run before visual checks — type errors indicate structural problems
  const typeCheckPassed = await runCommand(`npx tsc --noEmit --strict ${componentPath}`);
  if (!typeCheckPassed) {
    report.failures.push('Gate 1 failed: TypeScript type errors detected. Run tsc --noEmit to see full output.');
  }

  // Gate 2: Visual regression — requires Storybook
  // Checks both light and dark mode renders for all variants
  const visualPassed = await runVisualRegression(componentName);
  if (!visualPassed) {
    report.failures.push('Gate 2 failed: Visual regression detected. Check Storybook screenshots for diff.');
  }

  // Gate 3: Accessibility audit — requires dev server
  // Target the Storybook story URL for the component
  const storybookUrl = `http://localhost:6006/iframe.html?id=${componentName.toLowerCase()}--default`;
  const a11yViolations = await runCommand(
    `npx @axe-core/cli "${storybookUrl}" --tags wcag2a,wcag2aa --exit`
  );
  if (!a11yViolations) {
    report.failures.push('Gate 3 failed: Accessibility violations found. Run axe-core manually to see full report.');
  }

  // Gate 4: Hardcoded color audit
  const colorAuditPassed = await runCommand(
    `! grep -rn -e 'bg-white' -e 'bg-black' -e 'text-gray-[0-9]' -e 'bg-gray-[0-9]' ${componentPath}`
  );
  if (!colorAuditPassed) {
    report.failures.push('Gate 4 failed: Hardcoded color classes detected. Replace with semantic tokens.');
  }

  // Gate 5: Bundle size impact
  // Warning if over 5KB, failure if over 20KB for a single component
  const bundleImpactKB = await measureBundleImpact(componentPath);
  if (bundleImpactKB > 20) {
    report.failures.push(`Gate 5 failed: Component adds ${bundleImpactKB}KB to bundle. Investigate imports.`);
  } else if (bundleImpactKB > 5) {
    report.warnings.push(`Gate 5 warning: Component adds ${bundleImpactKB}KB. Review imports for tree-shaking opportunities.`);
  }

  report.passed = report.failures.length === 0;

  if (report.passed) {
    console.log(`✓ ${componentName} passed all quality gates`);
    if (report.warnings.length > 0) {
      console.log(`  Warnings: ${report.warnings.join(', ')}`);
    }
  } else {
    console.log(`✗ ${componentName} failed ${report.failures.length} gate(s):\n  ${report.failures.join('\n  ')}`);
  }

  return report;
}

#!/bin/bash
# Component generation workflow — run these commands in sequence
# Assumes: main branch is clean, Storybook is configured

COMPONENT_NAME=$1
GROUP=$2 # e.g., data-display, form-inputs, navigation

if [ -z "$COMPONENT_NAME" ] || [ -z "$GROUP" ]; then
  echo "Usage: ./component-workflow.sh ComponentName group-name"
  exit 1
fi

# Step 1: Ensure you are on the correct feature branch
BRANCH="feat/components-${GROUP}"
git checkout "$BRANCH" 2>/dev/null || git checkout -b "$BRANCH"

echo "Branch: $BRANCH"
echo "Ready to generate: $COMPONENT_NAME"
echo ""
echo "Workflow:"
echo "1. Open v0.dev — paste spec prompt — review in Design Mode — copy output"
echo "2. Create file: src/components/${COMPONENT_NAME}.tsx"
echo "3. Paste v0.dev output"
echo "4. Open Cursor — run refactoring sequence (see Phase 2 prompts)"
echo "5. Run type check:"
echo "   npx tsc --noEmit"
echo "6. Run color audit:"
echo "   grep -rn -e 'bg-white' -e 'text-gray-[0-9]' src/components/${COMPONENT_NAME}.tsx"
echo "7. Generate Storybook story with Cursor Agent mode"
echo "8. Verify in Storybook: light mode, dark mode, all variants, all states"
echo "9. Commit:"
echo "   git add src/components/${COMPONENT_NAME}.tsx src/components/${COMPONENT_NAME}.stories.tsx"
echo "   git commit -m 'feat(components): add ${COMPONENT_NAME} — ${GROUP} group'"
echo "10. Next component — repeat from step 1"

// io.thecodeforge.ai/shadcn-tokens === 0.3.2

// Inject this into every v0.dev prompt
export const designTokens = {
  radius: {
    sm: '4px',
    md: '6px',
    lg: '8px',
    xl: '12px',
  },
  spacing: {
    xs: '4px',
    sm: '8px',
    md: '16px',
    lg: '24px',
    xl: '32px',
  },
  colors: {
    primary: {
      DEFAULT: 'hsl(222.2 47.4% 11.2%)',
      foreground: 'hsl(210 40% 98%)',
    },
    muted: {
      DEFAULT: 'hsl(210 40% 96.1%)',
      foreground: 'hsl(215.4 16.3% 46.9%)',
    },
  },
} as const;

// Expected output from AI: consistent border radius read from token, not hardcoded

<!-- io.thecodeforge.ai/prompt-spec === 0.1.0 -->

Generate a shadcn Combobox component with:

**Props Interface:**
- options: Array<{ label: string; value: string }>
- placeholder?: string (default: 'Select...')
- onSelect: (value: string) => void
- loading?: boolean
- error?: string

**States:**
1. Default: show placeholder
2. Open dropdown: filterable search input visible
3. Empty state: 'No results found' centered in dropdown
4. Loading: spinner inside dropdown
5. Error: red text below input
6. Selected: show selected label, hide placeholder

**Behavior:**
- Close dropdown on outside click
- Keyboard navigation: arrow keys, Enter to select
- Escape closes dropdown without selecting