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:

• Read design-system.md file

• Understand font size constraints (4 only)

• Understand font weight constraints (2 only)

• Understand spacing constraints (divisible by 8/4)

• Understand color distribution (60/30/10)

• Know OKLCH color variables

• 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:

• Review configured sizes in design-system.md

• Consolidate to 4 sizes (typically: 2xl, lg, base, sm)

• 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:

• Review component layout

• Reduce accent color to CTAs and highlights only

• 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