CODITECT UI Design System

License Management Platform - Design Specifications

Version: 1.0 Date: November 24, 2025 Status: APPROVED ✅ Platform: app.coditect.ai, admin.coditect.ai, api.coditect.ai Based On: workflow.coditect.ai design system

---

Table of Contents

1. Brand Identity
2. Color System
3. Typography
4. Spacing & Layout
5. Component Library
6. Navigation & Header
7. Footer
8. Dark Mode
9. Responsive Breakpoints
10. Accessibility
11. Implementation Examples

---

Brand Identity

AZ1.AI / CODITECT

Company: AZ1.AI INC Product: CODITECT License Management Platform Tagline: "Autonomous Development Intelligence"

Logo Usage

Primary Logo:

• Format: SVG (scalable)
• Location: Top-left of all pages
• Height: 40px (desktop), 32px (mobile)
• Link: Always links to home page

Logo Variants:

/assets/logo/az1-logo-light.svg    # Light mode
/assets/logo/az1-logo-dark.svg     # Dark mode
/assets/logo/az1-logo-icon.svg     # Icon only (mobile)

Clear Space:

• Minimum 16px padding around logo
• Never place logo on busy backgrounds
• Never distort or rotate logo

---

Color System

Primary Colors (Blue)

Based on workflow.coditect.ai color palette:

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

Usage:

• primary-500: Primary buttons, links, focus states
• primary-600: Hover states
• primary-700: Active/pressed states
• primary-50 to primary-200: Backgrounds, subtle highlights

Secondary Colors

:root {
  /* Gray Scale (Neutral) */
  --gray-50: #f9fafb;
  --gray-100: #f3f4f6;
  --gray-200: #e5e7eb;
  --gray-300: #d1d5db;
  --gray-400: #9ca3af;
  --gray-500: #6b7280;
  --gray-600: #4b5563;
  --gray-700: #374151;
  --gray-800: #1f2937;
  --gray-900: #111827;
  --gray-950: #030712;
}

Semantic Colors

:root {
  /* Success (Green) */
  --success-50: #f0fdf4;
  --success-500: #22c55e;
  --success-600: #16a34a;
  --success-700: #15803d;

  /* Warning (Amber) */
  --warning-50: #fffbeb;
  --warning-500: #f59e0b;
  --warning-600: #d97706;
  --warning-700: #b45309;

  /* Error (Red) */
  --error-50: #fef2f2;
  --error-500: #ef4444;
  --error-600: #dc2626;
  --error-700: #b91c1c;

  /* Info (Blue) */
  --info-50: #eff6ff;
  --info-500: #3b82f6;
  --info-600: #2563eb;
  --info-700: #1d4ed8;
}

Usage:

• Success: Successful operations, confirmations, positive metrics
• Warning: Warnings, cautions, approaching limits
• Error: Errors, failures, critical issues
• Info: Informational messages, tips, help text

Background Colors

:root {
  /* Light Mode */
  --bg-primary: #ffffff;
  --bg-secondary: #f9fafb;  /* gray-50 */
  --bg-tertiary: #f3f4f6;   /* gray-100 */
  --bg-elevated: #ffffff;   /* Cards, modals */

  /* Dark Mode */
  --bg-primary-dark: #111827;    /* gray-900 */
  --bg-secondary-dark: #1f2937;  /* gray-800 */
  --bg-tertiary-dark: #374151;   /* gray-700 */
  --bg-elevated-dark: #1f2937;   /* Cards, modals */
}

---

Typography

Font Stack

Primary: System font stack (optimal performance, native rendering)

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

Monospace: For code blocks and technical content

font-family: ui-monospace, SFMono-Regular, 'SF Mono', Menlo,
             Consolas, 'Liberation Mono', monospace;

Font Sizes

:root {
  /* Text Sizes */
  --text-xs: 0.75rem;     /* 12px */
  --text-sm: 0.875rem;    /* 14px */
  --text-base: 1rem;      /* 16px */
  --text-lg: 1.125rem;    /* 18px */
  --text-xl: 1.25rem;     /* 20px */
  --text-2xl: 1.5rem;     /* 24px */
  --text-3xl: 1.875rem;   /* 30px */
  --text-4xl: 2.25rem;    /* 36px */
  --text-5xl: 3rem;       /* 48px */
}

Font Weights

:root {
  --font-normal: 400;
  --font-medium: 500;
  --font-semibold: 600;
  --font-bold: 700;
}

Type Scale

Headings

/* H1 - Page title */
h1 {
  font-size: var(--text-3xl);      /* 30px */
  font-weight: var(--font-bold);   /* 700 */
  line-height: 1.2;
  letter-spacing: -0.01em;
}

/* H2 - Section title */
h2 {
  font-size: var(--text-2xl);      /* 24px */
  font-weight: var(--font-semibold); /* 600 */
  line-height: 1.25;
}

/* H3 - Subsection title */
h3 {
  font-size: var(--text-xl);       /* 20px */
  font-weight: var(--font-semibold); /* 600 */
  line-height: 1.3;
}

/* H4 - Component title */
h4 {
  font-size: var(--text-lg);       /* 18px */
  font-weight: var(--font-medium);  /* 500 */
  line-height: 1.4;
}

Body Text

/* Body text */
p {
  font-size: var(--text-base);     /* 16px */
  font-weight: var(--font-normal);  /* 400 */
  line-height: 1.5;
}

/* Small text */
.text-sm {
  font-size: var(--text-sm);       /* 14px */
  line-height: 1.4;
}

/* Extra small text */
.text-xs {
  font-size: var(--text-xs);       /* 12px */
  line-height: 1.3;
}

---

Spacing & Layout

Spacing Scale

:root {
  --space-0: 0;
  --space-1: 0.25rem;  /* 4px */
  --space-2: 0.5rem;   /* 8px */
  --space-3: 0.75rem;  /* 12px */
  --space-4: 1rem;     /* 16px */
  --space-5: 1.25rem;  /* 20px */
  --space-6: 1.5rem;   /* 24px */
  --space-8: 2rem;     /* 32px */
  --space-10: 2.5rem;  /* 40px */
  --space-12: 3rem;    /* 48px */
  --space-16: 4rem;    /* 64px */
  --space-20: 5rem;    /* 80px */
  --space-24: 6rem;    /* 96px */
}

Container Widths

:root {
  --container-sm: 640px;
  --container-md: 768px;
  --container-lg: 1024px;
  --container-xl: 1280px;
  --container-2xl: 1536px;
}

Usage:

• sm/md: Forms, modals, dialogs
• lg: Main content area
• xl/2xl: Full-width dashboards

Grid System

12-column grid with CSS Grid:

.grid {
  display: grid;
  grid-template-columns: repeat(12, 1fr);
  gap: var(--space-4);
}

.col-span-6 { grid-column: span 6 / span 6; }
.col-span-4 { grid-column: span 4 / span 4; }
.col-span-3 { grid-column: span 3 / span 3; }

---

Component Library

Buttons

Primary Button

// React + Tailwind
<button className="
  px-4 py-2
  bg-primary-500 hover:bg-primary-600 active:bg-primary-700
  text-white font-medium
  rounded-md
  transition-colors duration-200
  focus:outline-none focus:ring-2 focus:ring-primary-500 focus:ring-offset-2
  disabled:opacity-50 disabled:cursor-not-allowed
">
  Acquire License
</button>

Sizes:

// Small
className="px-3 py-1.5 text-sm"

// Medium (default)
className="px-4 py-2 text-base"

// Large
className="px-6 py-3 text-lg"

Secondary Button

<button className="
  px-4 py-2
  bg-white hover:bg-gray-50
  text-gray-700
  border border-gray-300
  rounded-md
  transition-colors duration-200
  focus:outline-none focus:ring-2 focus:ring-primary-500 focus:ring-offset-2
">
  Cancel
</button>

Danger Button

<button className="
  px-4 py-2
  bg-error-500 hover:bg-error-600
  text-white font-medium
  rounded-md
  transition-colors duration-200
  focus:outline-none focus:ring-2 focus:ring-error-500 focus:ring-offset-2
">
  Revoke License
</button>

Cards

<div className="
  bg-white dark:bg-gray-800
  border border-gray-200 dark:border-gray-700
  rounded-lg
  shadow-sm
  p-6
">
  <h3 className="text-xl font-semibold mb-2">License Usage</h3>
  <p className="text-gray-600 dark:text-gray-400">
    10 / 100 seats in use
  </p>
</div>

Inputs

<div className="space-y-2">
  <label className="block text-sm font-medium text-gray-700 dark:text-gray-300">
    Organization Name
  </label>
  <input
    type="text"
    className="
      w-full px-3 py-2
      bg-white dark:bg-gray-800
      border border-gray-300 dark:border-gray-600
      rounded-md
      focus:outline-none focus:ring-2 focus:ring-primary-500
      text-gray-900 dark:text-gray-100
      placeholder:text-gray-400
    "
    placeholder="Enter organization name"
  />
</div>

Badges

// Success badge
<span className="
  inline-flex items-center
  px-2.5 py-0.5
  bg-success-50 dark:bg-success-900/20
  text-success-700 dark:text-success-400
  text-xs font-medium
  rounded-full
">
  Active
</span>

// Warning badge
<span className="
  inline-flex items-center
  px-2.5 py-0.5
  bg-warning-50 dark:bg-warning-900/20
  text-warning-700 dark:text-warning-400
  text-xs font-medium
  rounded-full
">
  Expiring Soon
</span>

Tables

<div className="overflow-x-auto">
  <table className="min-w-full divide-y divide-gray-200 dark:divide-gray-700">
    <thead className="bg-gray-50 dark:bg-gray-800">
      <tr>
        <th className="px-6 py-3 text-left text-xs font-medium text-gray-500 dark:text-gray-400 uppercase tracking-wider">
          User
        </th>
        <th className="px-6 py-3 text-left text-xs font-medium text-gray-500 dark:text-gray-400 uppercase tracking-wider">
          Status
        </th>
      </tr>
    </thead>
    <tbody className="bg-white dark:bg-gray-900 divide-y divide-gray-200 dark:divide-gray-700">
      <tr>
        <td className="px-6 py-4 whitespace-nowrap text-sm text-gray-900 dark:text-gray-100">
          John Doe
        </td>
        <td className="px-6 py-4 whitespace-nowrap">
          <span className="px-2 inline-flex text-xs leading-5 font-semibold rounded-full bg-success-100 text-success-800">
            Active
          </span>
        </td>
      </tr>
    </tbody>
  </table>
</div>

---

Navigation & Header

Primary Navigation

Desktop (≥768px):

<header className="bg-white dark:bg-gray-900 border-b border-gray-200 dark:border-gray-800">
  <div className="container mx-auto px-4 h-16 flex items-center justify-between">
    {/* Logo */}
    <a href="/" className="flex items-center">
      <img
        src="/assets/logo/az1-logo-light.svg"
        alt="AZ1.AI CODITECT"
        className="h-8 dark:hidden"
      />
      <img
        src="/assets/logo/az1-logo-dark.svg"
        alt="AZ1.AI CODITECT"
        className="h-8 hidden dark:block"
      />
    </a>

    {/* Navigation Links */}
    <nav className="hidden md:flex space-x-8">
      <a href="/dashboard" className="text-gray-700 dark:text-gray-300 hover:text-primary-600 dark:hover:text-primary-400">
        Dashboard
      </a>
      <a href="/licenses" className="text-gray-700 dark:text-gray-300 hover:text-primary-600 dark:hover:text-primary-400">
        Licenses
      </a>
      <a href="/team" className="text-gray-700 dark:text-gray-300 hover:text-primary-600 dark:hover:text-primary-400">
        Team
      </a>
      <a href="/settings" className="text-gray-700 dark:text-gray-300 hover:text-primary-600 dark:hover:text-primary-400">
        Settings
      </a>
    </nav>

    {/* User Menu + Dark Mode Toggle */}
    <div className="flex items-center space-x-4">
      {/* Dark mode toggle */}
      <button className="p-2 text-gray-500 hover:text-gray-700 dark:text-gray-400 dark:hover:text-gray-200">
        <SunIcon className="h-5 w-5 dark:hidden" />
        <MoonIcon className="h-5 w-5 hidden dark:block" />
      </button>

      {/* User dropdown */}
      <div className="relative">
        <button className="flex items-center space-x-2">
          <img src="/avatars/user.jpg" alt="User" className="h-8 w-8 rounded-full" />
          <span className="text-sm font-medium text-gray-700 dark:text-gray-300">John Doe</span>
        </button>
        {/* Dropdown menu */}
      </div>
    </div>
  </div>
</header>

Mobile (<768px):

{/* Mobile menu button */}
<button className="md:hidden p-2 text-gray-700 dark:text-gray-300">
  <MenuIcon className="h-6 w-6" />
</button>

{/* Mobile menu (slide-in from right) */}
<div className="fixed inset-0 bg-black bg-opacity-50 z-50">
  <div className="fixed right-0 top-0 bottom-0 w-64 bg-white dark:bg-gray-900">
    {/* Navigation links */}
  </div>
</div>

---

Footer

<footer className="bg-gray-50 dark:bg-gray-900 border-t border-gray-200 dark:border-gray-800">
  <div className="container mx-auto px-4 py-12">
    <div className="grid grid-cols-1 md:grid-cols-4 gap-8">
      {/* Company */}
      <div>
        <h4 className="font-semibold text-gray-900 dark:text-gray-100 mb-4">Company</h4>
        <ul className="space-y-2">
          <li><a href="/about" className="text-gray-600 dark:text-gray-400 hover:text-primary-600">About</a></li>
          <li><a href="/careers" className="text-gray-600 dark:text-gray-400 hover:text-primary-600">Careers</a></li>
          <li><a href="/contact" className="text-gray-600 dark:text-gray-400 hover:text-primary-600">Contact</a></li>
        </ul>
      </div>

      {/* Product */}
      <div>
        <h4 className="font-semibold text-gray-900 dark:text-gray-100 mb-4">Product</h4>
        <ul className="space-y-2">
          <li><a href="/features" className="text-gray-600 dark:text-gray-400 hover:text-primary-600">Features</a></li>
          <li><a href="/pricing" className="text-gray-600 dark:text-gray-400 hover:text-primary-600">Pricing</a></li>
          <li><a href="/docs" className="text-gray-600 dark:text-gray-400 hover:text-primary-600">Documentation</a></li>
        </ul>
      </div>

      {/* Legal */}
      <div>
        <h4 className="font-semibold text-gray-900 dark:text-gray-100 mb-4">Legal</h4>
        <ul className="space-y-2">
          <li><a href="/privacy" className="text-gray-600 dark:text-gray-400 hover:text-primary-600">Privacy Policy</a></li>
          <li><a href="/terms" className="text-gray-600 dark:text-gray-400 hover:text-primary-600">Terms of Service</a></li>
          <li><a href="/security" className="text-gray-600 dark:text-gray-400 hover:text-primary-600">Security</a></li>
        </ul>
      </div>

      {/* Support */}
      <div>
        <h4 className="font-semibold text-gray-900 dark:text-gray-100 mb-4">Support</h4>
        <ul className="space-y-2">
          <li><a href="/help" className="text-gray-600 dark:text-gray-400 hover:text-primary-600">Help Center</a></li>
          <li><a href="/status" className="text-gray-600 dark:text-gray-400 hover:text-primary-600">System Status</a></li>
          <li><a href="mailto:support@az1.ai" className="text-gray-600 dark:text-gray-400 hover:text-primary-600">support@az1.ai</a></li>
        </ul>
      </div>
    </div>

    <div className="mt-8 pt-8 border-t border-gray-200 dark:border-gray-800 flex justify-between items-center">
      <p className="text-sm text-gray-600 dark:text-gray-400">
        © 2025 AZ1.AI INC. All rights reserved.
      </p>
      <div className="flex space-x-4">
        {/* Social icons */}
        <a href="#" className="text-gray-400 hover:text-gray-600">
          <GitHubIcon className="h-5 w-5" />
        </a>
        <a href="#" className="text-gray-400 hover:text-gray-600">
          <TwitterIcon className="h-5 w-5" />
        </a>
      </div>
    </div>
  </div>
</footer>

---

Dark Mode

Implementation Strategy

CSS Class-Based (class):

// Root HTML element
<html className={isDark ? 'dark' : ''}>

// Tailwind config
export default {
  darkMode: 'class',
  // ...
}

Toggle Implementation

import { useState, useEffect } from 'react'
import { SunIcon, MoonIcon } from 'lucide-react'

export function DarkModeToggle() {
  const [isDark, setIsDark] = useState(false)

  useEffect(() => {
    // Check system preference or localStorage
    const stored = localStorage.getItem('theme')
    const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches

    setIsDark(stored === 'dark' || (!stored && prefersDark))
  }, [])

  useEffect(() => {
    // Update DOM and localStorage
    if (isDark) {
      document.documentElement.classList.add('dark')
      localStorage.setItem('theme', 'dark')
    } else {
      document.documentElement.classList.remove('dark')
      localStorage.setItem('theme', 'light')
    }
  }, [isDark])

  return (
    <button
      onClick={() => setIsDark(!isDark)}
      className="p-2 rounded-md hover:bg-gray-100 dark:hover:bg-gray-800 transition-colors"
      aria-label="Toggle dark mode"
    >
      {isDark ? (
        <SunIcon className="h-5 w-5 text-gray-400" />
      ) : (
        <MoonIcon className="h-5 w-5 text-gray-600" />
      )}
    </button>
  )
}

---

Responsive Breakpoints

/* Tailwind breakpoints */
:root {
  --screen-sm: 640px;   /* @media (min-width: 640px) */
  --screen-md: 768px;   /* @media (min-width: 768px) */
  --screen-lg: 1024px;  /* @media (min-width: 1024px) */
  --screen-xl: 1280px;  /* @media (min-width: 1280px) */
  --screen-2xl: 1536px; /* @media (min-width: 1536px) */
}

Usage:

<div className="
  grid
  grid-cols-1       /* Mobile: 1 column */
  sm:grid-cols-2    /* Small: 2 columns */
  lg:grid-cols-3    /* Large: 3 columns */
  xl:grid-cols-4    /* XL: 4 columns */
  gap-4
">
  {/* Cards */}
</div>

---

Accessibility

Focus States

/* All interactive elements must have visible focus */
.btn:focus-visible {
  outline: 2px solid var(--primary-500);
  outline-offset: 2px;
}

ARIA Labels

<button aria-label="Close modal">
  <XIcon className="h-5 w-5" />
</button>

<input type="text" aria-label="Search licenses" placeholder="Search..." />

Semantic HTML

// ✅ Correct
<nav>
  <ul>
    <li><a href="/dashboard">Dashboard</a></li>
  </ul>
</nav>

// ❌ Incorrect
<div>
  <div><a href="/dashboard">Dashboard</a></div>
</div>

Color Contrast

WCAG AA Compliance:

• Normal text: 4.5:1 contrast ratio minimum
• Large text (18px+): 3:1 contrast ratio minimum
• UI components: 3:1 contrast ratio minimum

Test Tools:

• Chrome DevTools Lighthouse
• WAVE Browser Extension
• axe DevTools

---

Implementation Examples

Complete Dashboard Page

import { DarkModeToggle } from '@/components/DarkModeToggle'
import { Card } from '@/components/ui/card'

export function DashboardPage() {
  return (
    <div className="min-h-screen bg-gray-50 dark:bg-gray-900">
      {/* Header */}
      <header className="bg-white dark:bg-gray-800 border-b border-gray-200 dark:border-gray-700">
        <div className="container mx-auto px-4 h-16 flex items-center justify-between">
          <img src="/logo.svg" alt="CODITECT" className="h-8" />
          <div className="flex items-center space-x-4">
            <DarkModeToggle />
            <div className="flex items-center space-x-2">
              <img src="/avatar.jpg" className="h-8 w-8 rounded-full" />
              <span className="text-sm font-medium">John Doe</span>
            </div>
          </div>
        </div>
      </header>

      {/* Main Content */}
      <main className="container mx-auto px-4 py-8">
        <h1 className="text-3xl font-bold text-gray-900 dark:text-gray-100 mb-8">
          License Dashboard
        </h1>

        {/* Stats Grid */}
        <div className="grid grid-cols-1 md:grid-cols-3 gap-6 mb-8">
          <Card>
            <div className="p-6">
              <p className="text-sm text-gray-600 dark:text-gray-400 mb-1">Total Seats</p>
              <p className="text-3xl font-bold text-gray-900 dark:text-gray-100">100</p>
            </div>
          </Card>
          <Card>
            <div className="p-6">
              <p className="text-sm text-gray-600 dark:text-gray-400 mb-1">Seats Used</p>
              <p className="text-3xl font-bold text-gray-900 dark:text-gray-100">45</p>
            </div>
          </Card>
          <Card>
            <div className="p-6">
              <p className="text-sm text-gray-600 dark:text-gray-400 mb-1">Available</p>
              <p className="text-3xl font-bold text-success-600 dark:text-success-400">55</p>
            </div>
          </Card>
        </div>

        {/* Active Sessions Table */}
        <Card>
          <div className="p-6">
            <h2 className="text-xl font-semibold text-gray-900 dark:text-gray-100 mb-4">
              Active Sessions
            </h2>
            {/* Table component */}
          </div>
        </Card>
      </main>
    </div>
  )
}

---

Asset Checklist

Required Assets

• AZ1.AI logo (SVG, light mode)
• AZ1.AI logo (SVG, dark mode)
• AZ1.AI logo icon (SVG, mobile)
• Favicon (ICO, 32x32, 16x16)
• Default avatar placeholder
• Social preview image (1200x630)

Icon Library

Recommended: Lucide React

npm install lucide-react

import { Check, X, AlertCircle, Info } from 'lucide-react'

---

Deployment Checklist

• All color variables defined in CSS
• Dark mode toggle implemented and persisted
• All interactive elements have focus states
• ARIA labels added where needed
• Color contrast tested (WCAG AA)
• Responsive breakpoints tested (mobile, tablet, desktop)
• Logo assets deployed to CDN
• Fonts loaded and optimized
• Performance tested (Lighthouse score >90)

---

References

• Workflow.coditect.ai: Design System Source
• Tailwind CSS: https://tailwindcss.com
• Radix UI: https://radix-ui.com
• Lucide Icons: https://lucide.dev
• WCAG Guidelines: https://www.w3.org/WAI/WCAG21/quickref/

---

Document Version: 1.0 Last Updated: November 24, 2025 Status: APPROVED ✅ Maintained By: CODITECT Design Team