CODITECT Multi-Tenant Admin: UI Design Specification

Version: 1.0
Date: January 19, 2026
Design Philosophy: Lean, Self-Service, Minimal, Flat, Apple-Like

Quick Reference

Design Principles (In Priority Order)

1. Content First - Landing page = most accessed content, not dashboard widgets
2. Single Header - One consolidated top bar, never nested headers
3. Minimal Navigation - Max 2 clicks to any content, 3-4 top-level items only
4. Visual Over Text - Dots/icons/bars instead of status labels
5. Flat Design - No double borders, minimal shadows, toned backgrounds
6. Self-Service - Inline help, smart defaults, clear next actions

Color System

/* Neutrals */
--white: #FFFFFF;
--gray-50: #F9FAFB;    /* Page background */
--gray-200: #E5E7EB;   /* Borders */
--gray-400: #9CA3AF;   /* Secondary text */
--gray-600: #6B7280;   /* Tertiary text */
--gray-900: #111827;   /* Primary text */

/* Primary */
--blue-500: #3B82F6;   /* Actions, links */
--blue-600: #2563EB;   /* Hover */

/* Semantic */
--green-500: #10B981;  /* Success, active */
--yellow-500: #F59E0B; /* Warning, in progress */
--red-500: #EF4444;    /* Error, blocked */

Typography Scale

/* Font Stack */
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;

/* Sizes */
--text-display: 32px / 600;  /* Page titles (rare) */
--text-headline: 24px / 600; /* Section headers */
--text-title: 18px / 600;    /* Card titles */
--text-body: 16px / 400;     /* Primary content */
--text-secondary: 14px / 400; /* Metadata */
--text-caption: 12px / 400;  /* Labels, hints */

/* Line Heights */
--leading-tight: 1.2;
--leading-normal: 1.5;
--leading-relaxed: 1.6;

Spacing (8px Grid)

--space-xs: 4px;   /* Tight groups */
--space-sm: 8px;   /* Related items */
--space-md: 16px;  /* Component padding */
--space-lg: 24px;  /* Section spacing */
--space-xl: 32px;  /* Major sections */
--space-2xl: 48px; /* Page margins */

---

Header System (CRITICAL)

The Problem (What to Avoid)

❌ BAD: Multiple Nested Headers

┌─────────────────────────────────────────┐
│ [App Header with Logo + Nav]           │ 60px
├─────────────────────────────────────────┤
│ [Breadcrumb Navigation]                 │ 40px
├─────────────────────────────────────────┤
│ [Page Title Header]                     │ 80px
├─────────────────────────────────────────┤
│ [Section Header]                        │ 60px
├─────────────────────────────────────────┤
│                                         │
│ Content finally starts here             │ ← 240px from top!
│                                         │
└─────────────────────────────────────────┘

Total wasted space: 240px
Content visible: Limited
User frustration: High

The Solution (What to Build)

✅ GOOD: Single Consolidated Header

┌─────────────────────────────────────────┐
│ [Logo] Nav1 Nav2 Nav3    Search [User] │ 64px
├─────────────────────────────────────────┤
│                                         │
│ Page Title (h1, in content flow)       │
│                                         │
│ Content starts immediately              │ ← 64px from top!
│                                         │
│ More content visible                    │
│                                         │
└─────────────────────────────────────────┘

Total header height: 64px
Content visible: Maximum
User efficiency: High

Header Implementation Rules

Structure:

<header style="height: 64px; position: sticky; top: 0;">
  <div style="display: flex; align-items: center; justify-content: space-between;">
    <!-- Left: Logo + Navigation -->
    <div style="display: flex; gap: 32px;">
      <div>LOGO</div>
      <nav>Nav Items (3-4 max)</nav>
    </div>
    
    <!-- Right: Actions -->
    <div style="display: flex; gap: 16px;">
      <input type="search" />
      <button>User Icon</button>
    </div>
  </div>
</header>

<!-- Content Area -->
<main style="padding: 48px;">
  <h1>Page Title</h1> <!-- First element in content, not in header -->
  <!-- Rest of content -->
</main>

CSS Rules:

/* Header */
header {
  height: 64px;
  background: #FFFFFF;
  border-bottom: 1px solid #E5E7EB;
  position: sticky;
  top: 0;
  z-index: 10;
}

/* NO NESTED HEADERS */
header header { /* This should never exist */
  display: none !important;
}

/* Page titles go in content, not header */
main > h1:first-child {
  margin-bottom: 24px;
  font-size: 24px;
  font-weight: 600;
}

Breadcrumbs (Only When Necessary):

• Use only if navigation depth > 2 levels
• Place BELOW header, not inside it
• Keep minimal: "Overview › Detail"
• Never more than 2 levels shown

<!-- Breadcrumb (if needed) -->
<div style="padding: 16px 48px; font-size: 14px; color: #6B7280;">
  <a href="#">Overview</a> › <span>Detail</span>
</div>

---

Navigation Architecture

Role-Based Navigation Depth

Role	Max Clicks to Content	Top-Level Items	Nesting Strategy
Platform Admin	2	4 (Tenants, Analytics, Support, Admin)	Tenant click → Detail tabs
Tenant Admin	2	3 (Teams, Projects, People)	Entity click → Detail view
Team Lead	1-2	3 (Projects, Team, Issues)	Kanban → Detail modal
Team Member	1	2 (My Work, Projects)	Task click → Modal

Navigation Consolidation Rules

Frequency-Based Grouping:

daily_access:
  visibility: "Top-level navigation"
  examples: ["Projects", "My Work", "Tenants"]
  
weekly_access:
  visibility: "Top-level if space, otherwise nested"
  examples: ["Team", "Reports", "Analytics"]
  
monthly_access:
  visibility: "Nested under icon/menu"
  examples: ["Settings", "Billing", "Users"]
  
rare_access:
  visibility: "Nested 2+ levels"
  examples: ["Profile", "Security", "Logout"]

Example: User Menu Consolidation

❌ BAD: Everything Top-Level
┌────────────────────────────────────┐
│ Home  Projects  Team  Issues       │
│ Settings  Profile  Security  Help  │
│                          Logout    │
└────────────────────────────────────┘
Too many items, visual clutter

✅ GOOD: Grouped by Frequency
┌────────────────────────────────────┐
│ Projects  Team  Issues      [👤]  │
│                                    │
│ [👤] Dropdown:                     │
│   Profile                          │
│   Settings                         │
│   Security                         │
│   ─────────                        │
│   Logout                           │
└────────────────────────────────────┘
Clean, organized, rare actions hidden

---

Visual Design Patterns

Card-Based Layout (Primary)

Use cards for:

• Dashboard grids (tenants, teams, projects)
• Entity overviews
• Scannable lists
• Status displays

Card Anatomy:

<div class="card">
  <!-- Visual identifier (logo/icon) -->
  <div class="card-icon">🏢</div>
  
  <!-- Primary info -->
  <div class="card-title">Entity Name</div>
  <div class="card-meta">Metadata</div>
  
  <!-- Visual status -->
  <div class="status-indicator">
    <div class="status-dot green"></div>
    <span>Healthy</span>
  </div>
  
  <!-- Metrics (visual) -->
  <div class="progress-bar">
    <div class="progress-fill" style="width: 75%;"></div>
  </div>
  
  <!-- Actions (hover/always visible) -->
  <div class="card-actions">
    <button>View</button>
  </div>
</div>

Card Styling:

.card {
  background: #FFFFFF;
  border-radius: 8px;
  padding: 20px;
  box-shadow: 0 1px 3px rgba(0,0,0,0.08);
  transition: box-shadow 0.2s;
  cursor: pointer;
}

.card:hover {
  box-shadow: 0 4px 12px rgba(0,0,0,0.12);
}

/* NO BORDERS - Use shadow instead */
.card {
  border: none; /* ← Important */
}

/* NO NESTED CARDS */
.card .card {
  display: none !important; /* This should never happen */
}

Progress Indicators (Visual Over Text)

Progress Bars (Preferred):

<!-- ✅ GOOD: Visual progress -->
<div class="progress-container">
  <div class="progress-bar">
    <div class="progress-fill" style="width: 65%;"></div>
  </div>
  <span class="progress-label">65%</span>
</div>

<!-- ❌ BAD: Text-only -->
<div>Progress: 65 percent complete</div>

Status Dots (Minimal):

<!-- ✅ GOOD: Dot + minimal text -->
<div class="status">
  <div class="dot green"></div>
  <span>Active</span>
</div>

<!-- ❌ BAD: Text-only status -->
<div class="badge">Status: Active and Running</div>

CSS:

/* Progress Bar */
.progress-container {
  display: flex;
  align-items: center;
  gap: 12px;
}

.progress-bar {
  flex: 1;
  height: 6px;
  background: #F3F4F6;
  border-radius: 3px;
  overflow: hidden;
}

.progress-fill {
  height: 100%;
  background: #10B981;
  border-radius: 3px;
  transition: width 0.3s ease;
}

.progress-label {
  font-size: 14px;
  font-weight: 500;
  color: #111827;
  min-width: 40px;
  text-align: right;
}

/* Status Dot */
.dot {
  width: 8px;
  height: 8px;
  border-radius: 50%;
}

.dot.green { background: #10B981; }
.dot.yellow { background: #F59E0B; }
.dot.red { background: #EF4444; }

Avatar Patterns (Team Presence)

Avatar Stack (Overlapping):

<div class="avatar-stack">
  <div class="avatar" style="background: #10B981;">👩</div>
  <div class="avatar" style="background: #3B82F6;">👨</div>
  <div class="avatar" style="background: #F59E0B;">👤</div>
</div>

CSS:

.avatar-stack {
  display: flex;
}

.avatar {
  width: 32px;
  height: 32px;
  border-radius: 50%;
  border: 2px solid #FFFFFF;
  display: flex;
  align-items: center;
  justify-content: center;
  font-size: 16px;
  margin-left: -8px; /* Overlap */
}

.avatar:first-child {
  margin-left: 0;
}

---

Layout Patterns

Single Column (Primary Pattern)

Use for:

• Most pages (90% of views)
• Detail views
• Forms
• Lists

Layout:

.single-column {
  max-width: 1200px;
  margin: 0 auto;
  padding: 48px 24px;
}

/* Content flows vertically */
.single-column > * + * {
  margin-top: 24px;
}

Grid (Card Galleries)

Use for:

• Dashboard overviews
• Entity browsing
• Photo/asset galleries

Layout:

.card-grid {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(320px, 1fr));
  gap: 24px;
}

/* Responsive */
@media (max-width: 768px) {
  .card-grid {
    grid-template-columns: 1fr;
  }
}

Kanban (Project Views)

Use for:

• Project status boards
• Workflow visualizations
• Multi-stage processes

Layout:

.kanban {
  display: grid;
  grid-template-columns: repeat(4, 1fr);
  gap: 24px;
  overflow-x: auto;
}

.kanban-column {
  min-width: 300px;
}

.kanban-cards {
  display: flex;
  flex-direction: column;
  gap: 12px;
}

Main + Sidebar (Secondary Pattern)

Use for:

• Detail views with quick stats
• Content with contextual actions
• Toggleable info panels

Layout:

.main-sidebar {
  display: flex;
  gap: 32px;
}

.main-content {
  flex: 1;
  min-width: 0; /* Allow shrinking */
}

.sidebar {
  width: 280px;
  flex-shrink: 0;
}

/* Sidebar can be toggleable */
.sidebar.hidden {
  display: none;
}

---

Component Library

Buttons

<!-- Primary Action -->
<button class="btn btn-primary">
  Create Project
</button>

<!-- Secondary Action -->
<button class="btn btn-secondary">
  Cancel
</button>

<!-- Danger Action -->
<button class="btn btn-danger">
  Delete
</button>

<!-- Icon Only -->
<button class="btn-icon">
  <svg>...</svg>
</button>

CSS:

.btn {
  height: 40px;
  padding: 0 20px;
  border: none;
  border-radius: 6px;
  font-size: 14px;
  font-weight: 500;
  cursor: pointer;
  transition: all 0.2s;
}

.btn-primary {
  background: #3B82F6;
  color: #FFFFFF;
}

.btn-primary:hover {
  background: #2563EB;
}

.btn-secondary {
  background: #F3F4F6;
  color: #111827;
}

.btn-secondary:hover {
  background: #E5E7EB;
}

.btn-danger {
  background: #FEE2E2;
  color: #991B1B;
}

.btn-danger:hover {
  background: #FEF2F2;
}

.btn-icon {
  width: 40px;
  height: 40px;
  padding: 0;
  background: transparent;
  border: none;
  border-radius: 6px;
  cursor: pointer;
}

.btn-icon:hover {
  background: #F3F4F6;
}

Inputs

<!-- Text Input -->
<input
  type="text"
  class="input"
  placeholder="Enter text..."
/>

<!-- Select -->
<select class="input">
  <option>Option 1</option>
  <option>Option 2</option>
</select>

<!-- Textarea -->
<textarea
  class="input"
  rows="4"
  placeholder="Description..."
></textarea>

CSS:

.input {
  width: 100%;
  height: 40px;
  padding: 0 12px;
  border: 1px solid #E5E7EB;
  border-radius: 6px;
  font-size: 14px;
  color: #111827;
  outline: none;
  transition: border-color 0.2s;
}

.input:focus {
  border-color: #3B82F6;
}

textarea.input {
  height: auto;
  padding: 12px;
  resize: vertical;
}

Modals

<!-- Modal Overlay -->
<div class="modal-overlay">
  <div class="modal">
    <!-- Header -->
    <div class="modal-header">
      <h2>Modal Title</h2>
      <button class="btn-icon modal-close">×</button>
    </div>
    
    <!-- Content -->
    <div class="modal-content">
      <!-- Form or content here -->
    </div>
    
    <!-- Actions -->
    <div class="modal-actions">
      <button class="btn btn-secondary">Cancel</button>
      <button class="btn btn-primary">Save</button>
    </div>
  </div>
</div>

CSS:

.modal-overlay {
  position: fixed;
  top: 0;
  left: 0;
  right: 0;
  bottom: 0;
  background: rgba(0, 0, 0, 0.5);
  display: flex;
  align-items: center;
  justify-content: center;
  z-index: 50;
}

.modal {
  width: 90%;
  max-width: 600px;
  max-height: 90vh;
  background: #FFFFFF;
  border-radius: 12px;
  box-shadow: 0 20px 60px rgba(0, 0, 0, 0.3);
  overflow: hidden;
  display: flex;
  flex-direction: column;
}

.modal-header {
  padding: 24px;
  border-bottom: 1px solid #E5E7EB;
  display: flex;
  justify-content: space-between;
  align-items: center;
}

.modal-content {
  padding: 24px;
  overflow-y: auto;
  flex: 1;
}

.modal-actions {
  padding: 16px 24px;
  border-top: 1px solid #E5E7EB;
  display: flex;
  justify-content: flex-end;
  gap: 12px;
}

Badges

<!-- Status Badge -->
<span class="badge badge-success">Active</span>
<span class="badge badge-warning">Pending</span>
<span class="badge badge-error">Blocked</span>

<!-- Count Badge -->
<span class="badge badge-count">3</span>

CSS:

.badge {
  display: inline-block;
  padding: 4px 8px;
  border-radius: 10px;
  font-size: 12px;
  font-weight: 500;
  line-height: 1;
}

.badge-success {
  background: #D1FAE5;
  color: #065F46;
}

.badge-warning {
  background: #FEF3C7;
  color: #92400E;
}

.badge-error {
  background: #FEE2E2;
  color: #991B1B;
}

.badge-count {
  background: #EF4444;
  color: #FFFFFF;
  min-width: 20px;
  text-align: center;
}

---

Interaction Patterns

Loading States

Skeleton Screens (Preferred):

<div class="skeleton-card">
  <div class="skeleton skeleton-title"></div>
  <div class="skeleton skeleton-text"></div>
  <div class="skeleton skeleton-text"></div>
</div>

CSS:

.skeleton {
  background: linear-gradient(
    90deg,
    #F3F4F6 25%,
    #E5E7EB 50%,
    #F3F4F6 75%
  );
  background-size: 200% 100%;
  animation: loading 1.5s infinite;
  border-radius: 4px;
}

@keyframes loading {
  0% { background-position: 200% 0; }
  100% { background-position: -200% 0; }
}

.skeleton-title {
  width: 60%;
  height: 20px;
  margin-bottom: 12px;
}

.skeleton-text {
  width: 100%;
  height: 14px;
  margin-bottom: 8px;
}

Toast Notifications

<div class="toast toast-success">
  <div class="toast-icon">✓</div>
  <div class="toast-message">Project created successfully</div>
  <button class="toast-close">×</button>
</div>

CSS:

.toast {
  position: fixed;
  top: 80px;
  right: 24px;
  min-width: 300px;
  background: #FFFFFF;
  border-radius: 8px;
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
  padding: 16px;
  display: flex;
  align-items: center;
  gap: 12px;
  z-index: 100;
  animation: slideIn 0.3s ease;
}

@keyframes slideIn {
  from {
    transform: translateX(400px);
    opacity: 0;
  }
  to {
    transform: translateX(0);
    opacity: 1;
  }
}

.toast-success {
  border-left: 4px solid #10B981;
}

.toast-error {
  border-left: 4px solid #EF4444;
}

.toast-icon {
  font-size: 20px;
}

.toast-message {
  flex: 1;
  font-size: 14px;
  color: #111827;
}

Empty States

<div class="empty-state">
  <div class="empty-icon">📁</div>
  <div class="empty-title">No Projects Yet</div>
  <div class="empty-message">
    Get started by creating your first project.
  </div>
  <button class="btn btn-primary">Create Project</button>
</div>

CSS:

.empty-state {
  text-align: center;
  padding: 64px 24px;
}

.empty-icon {
  font-size: 64px;
  margin-bottom: 16px;
  opacity: 0.5;
}

.empty-title {
  font-size: 18px;
  font-weight: 600;
  color: #111827;
  margin-bottom: 8px;
}

.empty-message {
  font-size: 14px;
  color: #6B7280;
  margin-bottom: 24px;
  max-width: 400px;
  margin-left: auto;
  margin-right: auto;
}

---

Responsive Design

Breakpoints

/* Mobile First Approach */
:root {
  --mobile: 640px;
  --tablet: 768px;
  --desktop: 1024px;
  --wide: 1280px;
}

/* Mobile (default) */
.container {
  padding: 24px 16px;
}

/* Tablet */
@media (min-width: 768px) {
  .container {
    padding: 32px 24px;
  }
  
  .card-grid {
    grid-template-columns: repeat(2, 1fr);
  }
}

/* Desktop */
@media (min-width: 1024px) {
  .container {
    padding: 48px;
  }
  
  .card-grid {
    grid-template-columns: repeat(3, 1fr);
  }
}

/* Wide */
@media (min-width: 1280px) {
  .card-grid {
    grid-template-columns: repeat(4, 1fr);
  }
}

Mobile Adaptations

Header:

<!-- Desktop -->
<header class="header-desktop">
  <div class="logo">CODITECT</div>
  <nav>
    <a href="#">Projects</a>
    <a href="#">Team</a>
    <a href="#">Issues</a>
  </nav>
  <div class="user-menu">👤</div>
</header>

<!-- Mobile -->
<header class="header-mobile">
  <button class="menu-toggle">☰</button>
  <div class="logo">CODITECT</div>
  <div class="user-menu">👤</div>
</header>

Navigation:

/* Desktop: Horizontal */
.nav-desktop {
  display: flex;
  gap: 32px;
}

/* Mobile: Drawer */
.nav-mobile {
  position: fixed;
  top: 0;
  left: 0;
  width: 80%;
  max-width: 300px;
  height: 100vh;
  background: #FFFFFF;
  transform: translateX(-100%);
  transition: transform 0.3s;
  z-index: 100;
}

.nav-mobile.open {
  transform: translateX(0);
  box-shadow: 0 0 20px rgba(0, 0, 0, 0.3);
}

---

Accessibility Checklist

Color Contrast

• Text meets 4.5:1 ratio (WCAG AA)
• Large text meets 3:1 ratio
• Interactive elements meet 3:1 ratio
• Never rely on color alone (use icons too)

Keyboard Navigation

• All interactive elements focusable
• Focus indicators visible (blue outline)
• Tab order logical
• Escape closes modals
• Enter submits forms

Screen Readers

• Alt text on images
• ARIA labels on icon buttons
• Semantic HTML (h1, nav, main, aside)
• Form labels associated with inputs
• Dynamic content announced

Touch Targets

• Minimum 44x44px
• Adequate spacing (8px min)
• No hover-only interactions
• Swipe gestures optional

---

Performance Targets

Page Load

• Initial Render: < 1 second
• Fully Interactive: < 2 seconds
• No Layout Shift: CLS < 0.1

Interactions

• Click Response: < 100ms
• Search Results: < 200ms
• Page Transition: < 300ms

Optimization

• Lazy load images
• Paginate lists > 50 items
• Cache aggressively
• Optimistic UI updates
• Service worker for offline

---

Implementation Checklist

Phase 1: Core Layout (Week 1)

• Single header component
• Navigation system
• Page layouts (single column, grid)
• Responsive breakpoints

Phase 2: Components (Week 2)

• Buttons (all variants)
• Inputs (text, select, textarea)
• Cards
• Modals
• Badges
• Avatars

Phase 3: Patterns (Week 3)

• Loading states (skeleton screens)
• Empty states
• Error states
• Toast notifications
• Progress indicators

Phase 4: Polish (Week 4)

• Animations (subtle, purposeful)
• Accessibility audit
• Performance optimization
• Dark mode (optional)
• Documentation

---

Quality Gates

Before deploying any page:

• Single header only (64px max)
• No nested headers
• Content starts within 100px from top
• Max 2 clicks to any content
• 3-4 top-level nav items
• Status indicators visual (not text)
• No double borders
• Meets contrast ratios
• Keyboard navigable
• Touch targets 44x44px+
• Loads in < 2 seconds

---

Design System Maintenance

Version Control

• Design system in Git
• Semantic versioning (1.0.0)
• Changelog for updates
• Component documentation

Updates

• Monthly design review
• Quarterly major updates
• Customer feedback incorporation
• Competitive analysis

Governance

• Designer approval required
• Breaking changes announced
• Deprecation warnings (90 days)
• Migration guides provided

---

Resources

Design Inspiration

• Apple.com (minimalism)
• Linear.app (project management)
• Stripe.com (dashboard design)
• Notion.so (information hierarchy)

Tools

• Figma (design mockups)
• Tailwind CSS (utility framework)
• Storybook (component library)
• Chromatic (visual testing)

Documentation

• Component examples
• Code snippets
• Usage guidelines
• Accessibility notes