ADR-002: CODITECT Unified Design System

Status: APPROVED ✅ Date: November 24, 2025 Decision Makers: CODITECT Design Team, Hal Casteel (CTO) Related Documents: ADR-001, ui-design-system.md, workflow.coditect.ai analysis

Context

CODITECT is building multiple interconnected applications that users will navigate between:

coditect.com - Main website and gateway
app.coditect.ai - License management dashboard
admin.coditect.ai - Staff administration portal
coditect.ai - Cloud IDE
workflow.coditect.ai - Workflow analysis platform

Users expect a seamless, consistent experience across all applications. Inconsistent design systems lead to:

Confusion and disorientation
Reduced trust in the platform
Higher development costs (duplication)
Maintenance nightmares
Poor brand recognition

Decision

We will adopt a unified design system across all CODITECT applications based on the workflow.coditect.ai design as the primary source.

Design System Components

1. Color Palette

Primary Blue (#0ea5e9) - Brand Color:

:root {
  --primary-50: #f0f9ff;
  --primary-100: #e0f2fe;
  --primary-200: #bae6fd;
  --primary-300: #7dd3fc;
  --primary-400: #38bdf8;
  --primary-500: #0ea5e9;  /* PRIMARY */
  --primary-600: #0284c7;  /* Hover */
  --primary-700: #0369a1;  /* Active */
  --primary-800: #075985;
  --primary-900: #0c4a6e;
}

Semantic Colors:

Success: #22c55e (green)
Warning: #f59e0b (amber)
Error: #ef4444 (red)
Info: #3b82f6 (blue)

2. Typography

System Font Stack:

font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto',
             'Oxygen', 'Ubuntu', 'Cantarell', 'Fira Sans',
             'Droid Sans', 'Helvetica Neue', sans-serif;

Type Scale:

H1: 30px (1.875rem), bold
H2: 24px (1.5rem), semibold
H3: 20px (1.25rem), semibold
H4: 18px (1.125rem), medium
Body: 16px (1rem), normal
Small: 14px (0.875rem), normal
XS: 12px (0.75rem), normal

3. Spacing

8px base unit:

space-1: 4px
space-2: 8px
space-3: 12px
space-4: 16px
space-6: 24px
space-8: 32px
space-12: 48px
space-16: 64px

4. Component Library

All applications MUST use:

Buttons (primary, secondary, danger)
Input fields (text, email, password, select)
Cards with consistent shadows
Badges with semantic colors
Tables with alternating rows
Modals with backdrop
Toast notifications

5. Layout Standards

Header:

Height: 40px (mobile) to 56px (desktop)
Logo: Top-left, 24-32px height
Navigation: Center
User menu: Top-right

Footer:

Compact padding (py-2 to py-4)
Links: Company, Product, Legal, Support
Copyright: Left
Social icons: Right

6. Dark Mode

CSS Class-Based Strategy:

// All apps must support this pattern
darkMode: 'class'  // in tailwind.config.js

// Toggle via <html class="dark">
document.documentElement.classList.toggle('dark', isDark)

Rationale

Why Unified Design System?

Brand Consistency:
- Users recognize CODITECT instantly
- Professional appearance across all touchpoints
- Builds trust and credibility
Development Efficiency:
- Components built once, reused everywhere
- Faster development (no reinventing)
- Easier onboarding for new developers
Maintenance:
- Single source of truth
- Updates propagate to all apps
- Fewer bugs from inconsistency
User Experience:
- Muscle memory across applications
- No cognitive load switching apps
- Seamless navigation

Why workflow.coditect.ai as Primary Source?

Already Deployed: Production-proven design
Modern Stack: React 18 + Tailwind CSS
Complete System: Colors, typography, components all defined
User-Tested: 90% complete with positive feedback

Alternatives Considered

Alternative 1: Per-Application Design Systems

Pros:

Freedom to customize per application
Easier for teams to move independently

Cons:

❌ Inconsistent user experience
❌ Duplication of effort
❌ Higher maintenance costs
❌ Confusing for users
❌ Weak brand identity

Decision: Rejected

Alternative 2: Material-UI or Ant Design

Pros:

Pre-built component library
Large community
Accessible out of the box

Cons:

❌ Generic appearance (looks like every other app)
❌ Harder to customize
❌ Larger bundle size
❌ Doesn't match existing workflow.coditect.ai

Decision: Rejected

Alternative 3: Build from Scratch

Pros:

Complete control
Perfect match to brand

Cons:

❌ Weeks/months of design work
❌ workflow.coditect.ai already exists
❌ Reinventing the wheel
❌ Delays all projects

Decision: Rejected

Implementation Strategy

Phase 1: Component Library (Week 1-2)

Create @coditect/ui NPM Package:

{
  "name": "@coditect/ui",
  "version": "1.0.0",
  "description": "CODITECT Unified Design System",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "peerDependencies": {
    "react": "^18.0.0",
    "tailwindcss": "^3.4.0"
  }
}

Export Components:

// src/index.ts
export { Button } from './components/Button'
export { Input } from './components/Input'
export { Card } from './components/Card'
export { Badge } from './components/Badge'
export { Header } from './components/Header'
export { Footer } from './components/Footer'
// ... all shared components

Phase 2: Tailwind Preset (Week 1)

Create @coditect/tailwind-config:

// tailwind-preset.js
module.exports = {
  darkMode: 'class',
  theme: {
    extend: {
      colors: {
        primary: {
          50: '#f0f9ff',
          // ... full scale
          500: '#0ea5e9',
          // ...
        },
      },
      fontFamily: {
        sans: ['-apple-system', 'BlinkMacSystemFont', 'Segoe UI', 'Roboto', 'sans-serif'],
      },
    },
  },
  plugins: [],
}

Usage in Apps:

// app/tailwind.config.js
module.exports = {
  presets: [require('@coditect/tailwind-config')],
  content: ['./src/**/*.{js,ts,jsx,tsx}'],
}

Phase 3: Documentation (Week 1-2)

Storybook for Component Catalog:

npx storybook init

# View components
npm run storybook

Documentation Site:

Hosted at design.coditect.ai
Component examples
Code snippets
Design principles
Color swatches
Typography samples

Phase 4: Migration (Week 3-4)

Priority Order:

License Management Platform (new, Phase 2)
coditect.com (main website, new)
workflow.coditect.ai (source, validate extraction)
coditect.ai (IDE, incremental updates)
admin.coditect.ai (Django Admin, theming)

Component Specifications

Button Component

// @coditect/ui/components/Button.tsx
import { ButtonHTMLAttributes, ReactNode } from 'react'

interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: 'primary' | 'secondary' | 'danger'
  size?: 'sm' | 'md' | 'lg'
  children: ReactNode
}

export function Button({
  variant = 'primary',
  size = 'md',
  className = '',
  children,
  ...props
}: ButtonProps) {
  const baseClasses = 'inline-flex items-center justify-center font-medium rounded-md transition-colors focus:outline-none focus:ring-2 focus:ring-offset-2 disabled:opacity-50 disabled:cursor-not-allowed'

  const variantClasses = {
    primary: 'bg-primary-500 hover:bg-primary-600 active:bg-primary-700 text-white focus:ring-primary-500',
    secondary: 'bg-white hover:bg-gray-50 text-gray-700 border border-gray-300 focus:ring-primary-500',
    danger: 'bg-red-500 hover:bg-red-600 active:bg-red-700 text-white focus:ring-red-500',
  }

  const sizeClasses = {
    sm: 'px-3 py-1.5 text-sm',
    md: 'px-4 py-2 text-base',
    lg: 'px-6 py-3 text-lg',
  }

  return (
    <button
      className={`${baseClasses} ${variantClasses[variant]} ${sizeClasses[size]} ${className}`}
      {...props}
    >
      {children}
    </button>
  )
}

Header Component

// @coditect/ui/components/Header.tsx
import { ReactNode } from 'react'

interface HeaderProps {
  logo: ReactNode
  navigation?: ReactNode
  userMenu?: ReactNode
  darkModeToggle?: ReactNode
}

export function Header({ logo, navigation, userMenu, darkModeToggle }: HeaderProps) {
  return (
    <header className="sticky top-0 z-50 bg-white dark:bg-gray-900 border-b border-gray-200 dark:border-gray-800">
      <div className="container mx-auto px-4 h-14 flex items-center justify-between">
        {/* Logo */}
        <div className="flex items-center">{logo}</div>

        {/* Navigation */}
        {navigation && (
          <nav className="hidden md:flex space-x-8">{navigation}</nav>
        )}

        {/* Right side */}
        <div className="flex items-center space-x-4">
          {darkModeToggle}
          {userMenu}
        </div>
      </div>
    </header>
  )
}

Governance

Design System Team

Maintainers:

Design Lead (approve visual changes)
Frontend Architect (approve component APIs)
Developer Representative (community feedback)

Change Process:

Propose change (GitHub issue)
Design review (visual mockups)
Implementation (PR to @coditect/ui)
Testing (Storybook + visual regression)
Release (semantic versioning)
Migration (update all apps)

Versioning

Semantic Versioning:

Major (1.0.0): Breaking changes (API changes)
Minor (0.1.0): New components/features
Patch (0.0.1): Bug fixes, minor tweaks

Update Policy:

All apps MUST use latest major version within 1 month
Security patches MUST be applied immediately
Minor updates optional but recommended

Success Metrics

Technical KPIs

Metric	Target	Measurement
Component Reuse	≥ 80%	% of components from @coditect/ui
Bundle Size	≤ 50KB	Compressed size of @coditect/ui
Tree-shakable	100%	No unused code in bundles
TypeScript Coverage	100%	All components typed
Test Coverage	≥ 90%	Component unit tests

User Experience KPIs

Metric	Target	Measurement
Visual Consistency	≥ 95%	Design audit score
User Confusion	≤ 5%	User testing feedback
Brand Recognition	≥ 80%	User survey
Navigation Ease	≥ 85%	User satisfaction score

Documentation Requirements

Component Documentation

Each component MUST have:

API Documentation: Props, types, defaults
Visual Examples: Light + dark mode
Code Snippets: Copy-paste ready
Accessibility Notes: ARIA labels, keyboard nav
Design Rationale: Why designed this way

Design Tokens

Published as:

CSS variables (:root)
Tailwind theme config
JSON file (for other tools)
TypeScript types (type safety)

Migration Path

For Existing Apps (workflow.coditect.ai, coditect.ai)

Step 1: Extract current components Step 2: Refactor to match @coditect/ui API Step 3: Replace incrementally (page by page) Step 4: Remove old component code Step 5: Verify visual consistency

For New Apps (License Platform, coditect.com)

Step 1: Install @coditect/ui from day 1 Step 2: Import components as needed Step 3: Follow design system 100% Step 4: No custom components without approval

Consequences

Positive

Consistency: Users get unified experience
Speed: Faster development (reuse components)
Quality: Well-tested, accessible components
Maintenance: Single source to update
Branding: Strong, recognizable identity

Negative

Flexibility: Less freedom per application
Complexity: Need to maintain shared package
Coordination: Changes require team agreement
Migration: Existing apps need updates

Mitigation

Flexibility: Provide composition patterns (slots, variants)
Complexity: Automated testing + clear docs
Coordination: Design system team + RFC process
Migration: Incremental, page-by-page updates

References

workflow.coditect.ai: Design System Source
ui-design-system.md: Complete Specifications
Tailwind CSS: https://tailwindcss.com
Radix UI: https://radix-ui.com (accessible primitives)
Storybook: https://storybook.js.org (component catalog)

Approval

Decision: APPROVED ✅ Date: November 24, 2025 Approved By: Hal Casteel, Founder/CEO/CTO Next Steps:

Create @coditect/ui NPM package ⏸️
Extract components from workflow.coditect.ai ⏸️
Create Storybook documentation site ⏸️
Apply to License Management Platform (Phase 2) ⏸️
Create coditect.com with unified design ⏸️

Document Version: 1.0 Last Updated: November 24, 2025 Status: APPROVED ✅ Related ADRs: ADR-001 (Django + React Hybrid Architecture)

Context​

Decision​

Design System Components​

1. Color Palette​

2. Typography​

3. Spacing​

4. Component Library​

5. Layout Standards​

6. Dark Mode​

Rationale​

Why Unified Design System?​

Why workflow.coditect.ai as Primary Source?​

Alternatives Considered​

Alternative 1: Per-Application Design Systems​

Alternative 2: Material-UI or Ant Design​

Alternative 3: Build from Scratch​

Implementation Strategy​

Phase 1: Component Library (Week 1-2)​

Phase 2: Tailwind Preset (Week 1)​

Phase 3: Documentation (Week 1-2)​

Phase 4: Migration (Week 3-4)​

Component Specifications​

Button Component​

Header Component​

Governance​

Design System Team​

Versioning​

Success Metrics​

Technical KPIs​

User Experience KPIs​

Documentation Requirements​

Component Documentation​

Design Tokens​

Migration Path​

For Existing Apps (workflow.coditect.ai, coditect.ai)​

For New Apps (License Platform, coditect.com)​

Consequences​

Positive​

Negative​

Mitigation​

References​

Approval​

Context

Decision

Design System Components

1. Color Palette

2. Typography

3. Spacing

4. Component Library

5. Layout Standards

6. Dark Mode

Rationale

Why Unified Design System?

Why workflow.coditect.ai as Primary Source?

Alternatives Considered

Alternative 1: Per-Application Design Systems

Alternative 2: Material-UI or Ant Design

Alternative 3: Build from Scratch

Implementation Strategy

Phase 1: Component Library (Week 1-2)

Phase 2: Tailwind Preset (Week 1)

Phase 3: Documentation (Week 1-2)

Phase 4: Migration (Week 3-4)

Component Specifications

Button Component

Header Component

Governance

Design System Team

Versioning

Success Metrics

Technical KPIs

User Experience KPIs

Documentation Requirements

Component Documentation

Design Tokens

Migration Path

For Existing Apps (workflow.coditect.ai, coditect.ai)

For New Apps (License Platform, coditect.com)

Consequences

Positive

Negative

Mitigation

References

Approval