Design System Enforcement

Purpose: Enforce consistent, accessible, and beautiful UI across all Next.js projects using shadcn/ui with Tailwind v4.

Activation Triggers:

• Creating new components or pages
• Generating UI elements
• Styling React components
• Setting up project design system
• Before ANY UI code generation
• Component library initialization
• Design system validation needed

Key Resources:

• scripts/setup-design-system.sh - Interactive design system configuration
• scripts/validate-design-system.sh - Validate code against design system
• templates/design-system-template.md - Template with placeholders
• examples/taskflow-ai-example.md - Complete example configuration

Core Design Principles (MANDATORY)

1. Typography: 4 Sizes, 2 Weights ONLY

STRICTLY ENFORCED:

• ✅ Size 1: Large headings

• ✅ Size 2: Subheadings

• ✅ Size 3: Body text

• ✅ Size 4: Small text/labels

• ✅ Semibold: Headings and emphasis

• ✅ Regular: Body text and UI

❌ FORBIDDEN:

• More than 4 font sizes
• Additional font weights (bold, light, etc.)
• Inconsistent size application

2. 8pt Grid System

STRICTLY ENFORCED:

• ALL spacing MUST be divisible by 8 or 4
• ✅ Allowed: 8, 16, 24, 32, 40, 48, 56, 64px
• ❌ Forbidden: 25, 11, 7, 13, 15, 19px

Tailwind Classes:

p-2 (8px)   | m-2 (8px)   | gap-2 (8px)
p-4 (16px)  | m-4 (16px)  | gap-4 (16px)
p-6 (24px)  | m-6 (24px)  | gap-6 (24px)
p-8 (32px)  | m-8 (32px)  | gap-8 (32px)

3. 60/30/10 Color Rule

STRICTLY ENFORCED:

• 60% Neutral (bg-background) - White/dark backgrounds
• 30% Complementary (text-foreground) - Text and icons
• 10% Accent (bg-primary) - CTAs and highlights only

❌ FORBIDDEN:

• Overusing accent colors (>10%)
• Multiple competing accent colors
• Insufficient contrast ratios

4. Clean Visual Structure

REQUIRED:

• Logical grouping of related elements
• Deliberate spacing following 8pt grid
• Proper alignment within containers
• Simplicity over flashiness

Setup Workflow

1. Initialize Design System

Run setup script during project initialization:

# Interactive setup
./scripts/setup-design-system.sh

# Guided configuration:
# 1. Project name and brand color
# 2. Typography scale (4 sizes)
# 3. Color configuration (OKLCH format)
# 4. Dark mode colors
# 5. Figma design system URL

# Generates: design-system.md in project root

What Gets Configured:

• Project-specific brand colors
• Font size scale (must be 4 sizes)
• OKLCH color values
• Dark mode palette
• globals.css color variables
• Design system metadata

2. Validate Existing Code

Check if existing code follows design system:

# Validate all components
./scripts/validate-design-system.sh

# Checks performed:
# - Font size count (must be ≤ 4)
# - Font weight usage (must be 2)
# - Spacing divisibility (by 8 or 4)
# - Color distribution (60/30/10)
# - Custom CSS usage (should use Tailwind)
# - shadcn/ui component usage
# - Accessibility compliance

Validation Output:

✅ Typography: 4 sizes, 2 weights
✅ Spacing: All divisible by 8/4
❌ Colors: Accent usage at 15% (exceeds 10%)
❌ Custom CSS: Found 3 instances, use Tailwind utilities
⚠️  Accessibility: Missing ARIA labels on 2 components

3. Before Creating UI

MANDATORY AGENT WORKFLOW:

# 1. Read design system (REQUIRED)
cat design-system.md

# 2. Understand constraints
# - Only 4 font sizes from config
# - Only 2 font weights
# - All spacing divisible by 8/4
# - Color distribution 60/30/10
# - OKLCH colors only
# - shadcn/ui components only

# 3. Generate code following design system

# 4. Self-validate before completion
./scripts/validate-design-system.sh app/components/MyNewComponent.tsx

Design System Configuration

Typography Configuration

From Template:

Size 1: {{FONT_SIZE_1}} - Large headings
Size 2: {{FONT_SIZE_2}} - Subheadings
Size 3: {{FONT_SIZE_3}} - Body text
Size 4: {{FONT_SIZE_4}} - Small text

After Setup (Example):

Size 1: text-2xl (24px) - Large headings
Size 2: text-lg (18px) - Subheadings
Size 3: text-base (16px) - Body text
Size 4: text-sm (14px) - Small text

Color Configuration

Template (OKLCH format):

:root {
  --background: {{BACKGROUND_OKLCH}};
  --foreground: {{FOREGROUND_OKLCH}};
  --primary: {{PRIMARY_OKLCH}};
  --primary-foreground: {{PRIMARY_FOREGROUND_OKLCH}};
}

After Setup:

:root {
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  --primary: oklch(0.549 0.175 252.417);
  --primary-foreground: oklch(0.985 0 0);
}

@theme {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
}

Agent Enforcement Rules

Before Generating ANY UI Code

MANDATORY CHECKLIST:

1. Read design-system.md file
2. Understand font size constraints (4 only)
3. Understand font weight constraints (2 only)
4. Understand spacing constraints (divisible by 8/4)
5. Understand color distribution (60/30/10)
6. Know OKLCH color variables
7. Use only shadcn/ui components

During Code Generation

ENFORCE:

• Use only configured font sizes
• Use only Semibold or Regular weights
• All spacing values divisible by 8 or 4
• 60% bg-background, 30% text-foreground, 10% bg-primary
• OKLCH colors from globals.css
• shadcn/ui components from @/components/ui/
• Proper accessibility (ARIA labels, keyboard nav)

After Code Generation

VALIDATE:

# Self-validation
./scripts/validate-design-system.sh path/to/component.tsx

# Must pass all checks before completion:
# ✅ Typography constraints
# ✅ Spacing constraints
# ✅ Color distribution
# ✅ No custom CSS
# ✅ Accessibility

❌ AUTOMATIC REJECTION:

• More than 4 font sizes
• Font weights other than Semibold/Regular
• Spacing not divisible by 4 or 8
• Accent color usage > 10%
• Custom CSS instead of Tailwind
• Non-shadcn/ui components

Example Component (Compliant)

import { Button } from '@/components/ui/button';
import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';

export function ExampleComponent() {
  return (
    <Card className="p-6 bg-background">
      {' '}
      {/* 24px padding - ✅ divisible by 8 */}
      <CardHeader className="mb-4">
        {' '}
        {/* 16px margin - ✅ divisible by 8 */}
        <CardTitle className="text-2xl font-semibold">
          {' '}
          {/* ✅ Size 1, Semibold */}
          Welcome to TaskFlow
        </CardTitle>
      </CardHeader>
      <CardContent className="space-y-4">
        {' '}
        {/* 16px gap - ✅ divisible by 8 */}
        <p className="text-base font-normal text-foreground">
          {' '}
          {/* ✅ Size 3, Regular, 60% */}
          Manage your tasks efficiently with AI-powered workflows.
        </p>
        <div className="flex gap-4">
          {' '}
          {/* 16px gap - ✅ divisible by 8 */}
          <Button className="bg-primary text-primary-foreground">
            {' '}
            {/* ✅ 10% accent */}
            Get Started
          </Button>
          <Button variant="outline" className="text-foreground">
            {' '}
            {/* ✅ 30% complementary */}
            Learn More
          </Button>
        </div>
      </CardContent>
    </Card>
  );
}

Validation:

• ✅ Typography: 2 sizes (text-2xl, text-base), 2 weights (semibold, normal)
• ✅ Spacing: All divisible by 8 (p-6=24px, mb-4=16px, space-y-4=16px, gap-4=16px)
• ✅ Colors: 60% bg-background, 30% text-foreground, 10% bg-primary
• ✅ Components: shadcn/ui Button and Card
• ✅ No custom CSS
• ✅ Accessible: Proper semantic HTML

Integration with Commands

add-page.md Integration

Phase 1: Parse Arguments
Actions:

- **FIRST**: Read design system: !{bash cat design-system.md}
- Parse page name from $ARGUMENTS

Phase 4: Page Generation

- Agent MUST validate against design system before completion

add-component.md Integration

Phase 1: Parse Arguments
Actions:

- **FIRST**: Read design system: !{bash cat design-system.md}
- Parse component name from $ARGUMENTS

Phase 4: Implementation

- Agent MUST enforce all design system constraints
- Self-validate before returning component

Troubleshooting

Violation: Too Many Font Sizes

Error:

❌ Found 6 font sizes: text-xs, text-sm, text-base, text-lg, text-xl, text-2xl
Expected: 4 font sizes only

Fix:

1. Review configured sizes in design-system.md
2. Consolidate to 4 sizes (typically: 2xl, lg, base, sm)
3. Update components to use only allowed sizes

Violation: Invalid Spacing

Error:

❌ Found spacing not divisible by 8/4:
  - padding: 15px (line 42)
  - margin: 25px (line 58)

Fix:

// ❌ Before
<div className="p-[15px] mb-[25px]">

// ✅ After
<div className="p-4 mb-6"> {/* 16px and 24px */}

Violation: Color Distribution

Error:

❌ Accent color usage: 18% (exceeds 10% limit)
Found 12 instances of bg-primary

Fix:

1. Review component layout
2. Reduce accent color to CTAs and highlights only
3. Use bg-background and text-foreground for majority

Resources

Scripts: scripts/ directory:

• setup-design-system.sh - Interactive configuration
• validate-design-system.sh - Code validation
• update-colors.sh - Batch color updates
• check-typography.sh - Typography audit

Templates: templates/ directory:

• design-system-template.md - Base template with placeholders
• globals-css-template.css - Color variable template
• components-json-template.json - shadcn/ui config

Examples: examples/ directory:

• taskflow-ai-example.md - Complete configured example
• e-commerce-example.md - E-commerce design system
• dashboard-example.md - Admin dashboard design system

Framework: Next.js 13+ with App Router UI Library: shadcn/ui (Radix UI + Tailwind CSS v4) Color Format: OKLCH Enforcement: Mandatory for all agents Version: 1.0.0