CODITECT UI/UX Standard

CAPaaS - Coditect Agentic Platform as a Service Copyright 2026 AZ1.AI Inc. All Rights Reserved

Version: 1.0.0 Status: ACTIVE Last Updated: 2026-01-19 Related ADRs: ADR-084, ADR-085, ADR-086, ADR-087

---

Overview

This master standard consolidates all UI/UX requirements for CODITECT applications. It references and extends the specialized standards for design tokens, accessibility, and component library.

Related Standards

Standard	Purpose
CODITECT-STANDARD-DESIGN-TOKENS.md	CSS variables, colors, spacing
CODITECT-STANDARD-ACCESSIBILITY.md	WCAG 2.1 AA compliance
CODITECT-STANDARD-COMPONENT-LIBRARY.md	Atomic design methodology

---

Core Design Principles

1. Single Header Principle

Maximum header height: 64px. Consolidate ALL navigation into a single, fixed header.

┌──────────────────────────────────────────────────────────────────┐
│ Logo   [Nav Item] [Nav Item] [Nav Item]            🔍  👤        │ ← Max 64px
└──────────────────────────────────────────────────────────────────┘

Rules:

• ✅ One header per page
• ✅ Logo + primary nav + user menu + search
• ❌ No dashboard widgets in header
• ❌ No secondary navigation bars
• ❌ No sticky sub-headers

2. Content-First Landing

Users should see actual content immediately upon landing, not dashboard widgets or empty states.

Correct Pattern:

┌─────────────────────────────────────────────┐
│ Header                                       │
├─────────────────────────────────────────────┤
│ ┌─────────┐ ┌─────────┐ ┌─────────┐        │
│ │ Project │ │ Project │ │ Project │        │
│ │ Card 1  │ │ Card 2  │ │ Card 3  │        │
│ └─────────┘ └─────────┘ └─────────┘        │
│ ┌─────────┐ ┌─────────┐                    │
│ │ Project │ │ + New   │                    │
│ │ Card 4  │ │ Project │                    │
│ └─────────┘ └─────────┘                    │
└─────────────────────────────────────────────┘

Incorrect Pattern:

┌─────────────────────────────────────────────┐
│ Header                                       │
├─────────────────────────────────────────────┤
│ ┌─────────────────────────────────────────┐ │
│ │    Welcome back, User!                  │ │ ← Remove this
│ │    Here's your dashboard summary...     │ │
│ └─────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────┐ │
│ │    Quick Stats Widget                   │ │ ← Remove this
│ └─────────────────────────────────────────┘ │
└─────────────────────────────────────────────┘

3. Visual Status Indicators

Use visual indicators (dots, icons) instead of text-only status labels.

Status	Visual Indicator
Success	🟢 Green dot + "Complete"
Warning	🟡 Yellow dot + "Pending"
Error	🔴 Red dot + "Failed"
Info	🔵 Blue dot + "In Progress"

Implementation:

<!-- ✅ CORRECT: Visual + text -->
<span class="status">
  <span class="status__dot status__dot--success"></span>
  <span class="status__text">Complete</span>
</span>

<!-- ❌ WRONG: Text only -->
<span class="status status--green">Complete</span>

4. Card-Based Layouts

Use cards (not tables) for displaying entities on listing pages.

Card Grid Specifications:

• Responsive: 4 → 3 → 2 → 1 columns
• Gap: 24px (--coditect-space-6)
• Card max-width: 320px
• Card aspect ratio: flexible (content-driven)

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

5. Flat Design 2.0

Modern flat design with minimal depth cues.

Property	Limit	Rationale
Shadow levels	2 max	Reduce visual noise
Border radius	8px (--coditect-radius-md)	Consistent corners
Double borders	0	Never stack borders
Gradients	Subtle only	Avoid skeuomorphism

/* ✅ CORRECT: Subtle, consistent */
.card {
  border-radius: var(--coditect-radius-md);
  box-shadow: var(--coditect-shadow-sm);
  border: 1px solid var(--coditect-border-default);
}

/* ❌ WRONG: Multiple shadows, excessive depth */
.card {
  border-radius: 4px 8px 16px 4px;
  box-shadow: 0 2px 4px #000, 0 4px 8px #000, 0 8px 16px #000;
  border: 2px solid #333;
}

6. Minimal Navigation Depth

Maximum navigation depth: 2 clicks to reach any feature.

Level 1: Header Navigation (3-4 items max)
└── Level 2: Page Content or Dropdown
    └── Level 3: [MAXIMUM - avoid if possible]

Navigation Optimization Formula:

Priority Score = (Frequency × 3) + (Criticality × 2) + Breadth

Where:
- Frequency: How often used (1-5)
- Criticality: Business importance (1-5)
- Breadth: % of users who need it (1-5)

---

Navigation Patterns

Primary Navigation (Header)

Slot	Content	Max Items
Left	Logo	1
Center	Primary nav links	3-4
Right	Search + User menu	2

Secondary Navigation (Sidebar)

Use sidebar for:

• 5+ navigation items
• Nested hierarchies (up to 2 levels)
• Settings/admin sections

┌────────────────────────────────────────────────┐
│ Header                                          │
├───────────┬────────────────────────────────────┤
│ Sidebar   │ Main Content                        │
│           │                                     │
│ ▸ Section │                                     │
│   • Item  │                                     │
│   • Item  │                                     │
│ ▸ Section │                                     │
│           │                                     │
└───────────┴────────────────────────────────────┘

Breadcrumbs

Use breadcrumbs on:

• Detail pages (3+ levels deep)
• Nested hierarchies
• Settings pages

<nav aria-label="Breadcrumb">
  <ol class="breadcrumb">
    <li><a href="/">Home</a></li>
    <li><a href="/projects">Projects</a></li>
    <li aria-current="page">Project Alpha</li>
  </ol>
</nav>

---

Responsive Design

Breakpoints

Name	Width	Columns	Use Case
sm	< 640px	1	Mobile
md	640-1023px	2	Tablet
lg	1024-1279px	3	Desktop
xl	≥ 1280px	4	Wide desktop

Mobile-First Approach

/* Base styles (mobile) */
.card-grid {
  grid-template-columns: 1fr;
}

/* Tablet and up */
@media (min-width: 640px) {
  .card-grid {
    grid-template-columns: repeat(2, 1fr);
  }
}

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

Responsive Patterns

Component	Mobile	Tablet	Desktop
Header	Hamburger menu	Full nav	Full nav
Sidebar	Hidden/overlay	Collapsed	Expanded
Cards	Single column	2 columns	3-4 columns
Tables	Card view	Horizontal scroll	Full table
Modals	Full screen	Centered	Centered

---

Visual Hierarchy

Typography Scale

Level	Element	Size	Weight
H1	Page title	2.25rem (36px)	700
H2	Section title	1.5rem (24px)	600
H3	Card title	1.125rem (18px)	600
Body	Paragraph	1rem (16px)	400
Small	Helper text	0.875rem (14px)	400
Caption	Labels	0.75rem (12px)	500

Visual Weight Distribution

┌─────────────────────────────────────────────────┐
│ Page Title (H1) - Heaviest weight               │
├─────────────────────────────────────────────────┤
│ ┌─────────────────────────────────────────────┐ │
│ │ Section Title (H2)                          │ │
│ │                                             │ │
│ │ ┌───────────────────┐ ┌───────────────────┐ │ │
│ │ │ Card Title (H3)   │ │ Card Title (H3)   │ │ │
│ │ │ Body text...      │ │ Body text...      │ │ │
│ │ │ Caption           │ │ Caption           │ │ │
│ │ └───────────────────┘ └───────────────────┘ │ │
│ └─────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────┘

---

Interaction Patterns

Button Hierarchy

Priority	Style	Use Case
Primary	Filled	Main action (1 per section)
Secondary	Outlined	Alternative actions
Ghost	Text only	Tertiary/cancel actions
Danger	Red filled	Destructive actions

Rule: Only ONE primary button per visible section.

Loading States

Duration	Pattern
< 1s	Spinner on button
1-3s	Skeleton screen
3s+	Progress indicator with message

Empty States

Every list/grid MUST have an empty state:

<div class="empty-state">
  <svg class="empty-state__icon"><!-- Illustration --></svg>
  <h3 class="empty-state__title">No projects yet</h3>
  <p class="empty-state__description">
    Create your first project to get started.
  </p>
  <button class="button button--primary">
    Create Project
  </button>
</div>

Error States

Type	Treatment
Field error	Inline below input
Form error	Banner above form
Page error	Full page with retry
Toast	Temporary notification

---

Quality Metrics

Visual Consistency Score

Metric	Target	Measurement
Hierarchy	≥ 85	Visual weight distribution
Spacing	≥ 85	8px grid compliance
Polish	≥ 90	Alignment, consistency
Token compliance	100%	No hardcoded values

Performance Metrics

Metric	Target
First Contentful Paint	< 1.5s
Largest Contentful Paint	< 2.5s
Cumulative Layout Shift	< 0.1
Time to Interactive	< 3s

---

MoE Agent Pipeline

UI generation follows this agent pipeline:

User Request
    │
    ▼
┌─────────────────────────────────┐
│ moe-ui-quality-gate-enforcer   │ ← Validate requirements
└─────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────┐
│ moe-ui-navigation-optimizer    │ ← Optimize IA
└─────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────┐
│ moe-ui-design-system-enforcer  │ ← Apply design tokens
└─────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────┐
│ moe-ui-visual-design-specialist│ ← Ensure polish
└─────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────┐
│ moe-ui-a2ui-renderer           │ ← Generate A2UI tree
└─────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────┐
│ moe-ui-agui-event-coordinator  │ ← Add streaming events
└─────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────┐
│ moe-ui-hitl-orchestrator       │ ← HITL approval
└─────────────────────────────────┘
    │
    ▼
Final Output

---

Commands Reference

Command	Purpose
/ui-optimize	Full optimization pipeline
/ui-design-system	Load/enforce design system
/ui-a2ui-render	Generate A2UI tree
/ui-approve	HITL approval interface
/ui-quality	Run quality gates

---

Compliance Checklist

Before Generating UI

• Requirements specify UI type (component/page/app)
• Target framework defined (React/Vue/Angular)
• User flows documented
• Acceptance criteria present

During Generation

• Using design tokens exclusively
• Following Atomic Design hierarchy
• Accessibility requirements met
• Navigation depth ≤ 2 clicks
• Single header principle followed
• Card-based layouts for listings

After Generation

• Quality gates passed
• Visual consistency score ≥ 85
• WCAG AA compliance verified
• Performance budgets met
• HITL approval (if required)

---

Related Documents:

• CODITECT-STANDARD-DESIGN-TOKENS.md
• CODITECT-STANDARD-ACCESSIBILITY.md
• CODITECT-STANDARD-COMPONENT-LIBRARY.md
• ADR-084-moe-ui-agent-architecture.md
• ADR-085-atomic-design-component-library.md

---

Version: 1.0.0 Last Updated: 2026-01-19 Maintained by: AZ1.AI Inc.