CODITECT UI/UX Technical Requirements

Version: 1.0
Date: January 19, 2026
Status: PRIORITY IMPLEMENTATION
Owner: Hal Casteel
Reviewer: Will McKinley

Problem Statement

Current CODITECT AI-generated interfaces exhibit characteristics that make them "look AI-generated":

• Excessive header usage (3-4 nested levels)
• Poor information hierarchy
• Icon overuse (decorative, not functional)
• Key content pushed below fold
• Repeated text/navigation elements
• Generic enterprise SaaS appearance

Business Impact: Design quality is the primary differentiator between CODITECT and generic Claude Code output. Poor UI/UX = commodity positioning = price pressure.

---

UI/UX Agent Skill Requirements

Core Design Principles to Encode

1. Header Consolidation & Compression

Current Anti-Pattern:

[Main App Header]
  [Breadcrumb Navigation]
    [Page Header]
      [Section Header]
        → Content starts ~400px from top

Target Pattern:

[Consolidated Top Bar: Logo | Navigation | Search | User]
  → Content starts ~80px from top

Implementation Rules:

header_consolidation:
  max_levels: 1
  height_budget: 80px
  
  consolidation_logic:
    - Merge breadcrumb into top navigation
    - Page title becomes first h1 in content area
    - Section headers remain in content flow
    - User actions collapse under profile icon
    
  exceptions:
    - Complex multi-level apps may need 2 levels
    - Must justify with user research data

Code Generation Prompt:

When generating navigation structure:
1. Use single top navigation bar (max 80px height)
2. Place logo/brand (left), main nav (center), user/actions (right)
3. Breadcrumb trail only if navigation depth > 3 levels
4. Page title = first content element, not separate header
5. Eliminate redundant headers that repeat navigation

2. Information Hierarchy & Content Priority

Principle: Most-accessed content = landing page, fewest clicks to daily tasks

Frequency-Based Navigation Prompt:

For each UI section/tab, evaluate:

ACCESS_FREQUENCY = {
  "Daily": ["Projects", "Issues", "Dashboard"],
  "Weekly": ["Reports", "Team", "Analytics"],
  "Monthly": ["Settings", "Billing", "Licenses"],
  "Rare": ["Profile", "Security", "Logout"]
}

NAVIGATION_RULES = {
  "Daily": "Top-level navigation, default landing page",
  "Weekly": "Top-level navigation, secondary priority",
  "Monthly": "Nested under settings icon/menu",
  "Rare": "Nested 2+ levels deep"
}

Default landing page = highest access frequency section.

Dashboard Definition:

dashboard_content:
  purpose: "Morning check-in for managers/teams"
  primary_focus: "Project status and advancement"
  secondary_focus: "Issues requiring attention"
  
  display_format:
    - Live feed (chronological updates)
    - Project cards with status indicators
    - Issues sidebar (or inline when relevant)
    - Minimal administrative content
    
  exclude:
    - Settings/H.P.009-CONFIGuration (rare access)
    - Product/license info (static)
    - User profile details (rare access)

Content Prioritization Algorithm:

def prioritize_content(sections: List[Section]) -> Dict[str, int]:
    """Assign priority scores for UI layout."""
    
    priority_matrix = {
        ('live_data', 'daily_access'): 100,
        ('live_data', 'weekly_access'): 75,
        ('static_data', 'daily_access'): 60,
        ('live_data', 'monthly_access'): 40,
        ('static_data', 'weekly_access'): 30,
        ('static_data', 'monthly_access'): 10,
        ('static_data', 'rare_access'): 1
    }
    
    scores = {}
    for section in sections:
        data_type = 'live_data' if section.updates_frequently else 'static_data'
        access_freq = determine_access_frequency(section.name)
        scores[section.name] = priority_matrix[(data_type, access_freq)]
    
    return scores

def determine_access_frequency(section_name: str) -> str:
    """Classify section by expected user access pattern."""
    
    daily_keywords = ['project', 'issue', 'task', 'dashboard', 'feed']
    weekly_keywords = ['report', 'analytics', 'team', 'review']
    monthly_keywords = ['setting', 'billing', 'license', 'product']
    rare_keywords = ['profile', 'security', 'logout', 'help']
    
    name_lower = section_name.lower()
    
    if any(kw in name_lower for kw in daily_keywords):
        return 'daily_access'
    elif any(kw in name_lower for kw in weekly_keywords):
        return 'weekly_access'
    elif any(kw in name_lower for kw in monthly_keywords):
        return 'monthly_access'
    else:
        return 'rare_access'

3. Visual Design Simplification

Rule Set:

text_optimization:
  eliminate_repeated_words:
    bad: "Project Dashboard > Dashboard View > Dashboard Content"
    good: "Projects"
  
  eliminate_redundancy:
    bad: ["Support", "Feedback", "Assigned"]
    good: "Issues" (consolidates all)
  
  simplify_phrases:
    bad: "My Account Settings and Profile"
    good: "Profile"

visual_hierarchy:
  avoid_double_framing:
    description: "No borders within bordered containers"
    bad: "[Card border [Button border Click]]"
    good: "[Card with button (no button border)]"
  
  use_toned_backgrounds:
    instead_of: "Stroke borders (lines)"
    use: "Background color differentiation"
    rationale: "Cleaner, flatter appearance"
  
  flatten_design:
    description: "Minimize visual layers"
    max_depth: 2  # Container + content, rarely 3
    avoid: "Nested shadows, multiple border styles"

icon_usage:
  purposeful_only: true
  decorative_icons: false
  
  icon_criteria:
    - Action-oriented (clickable)
    - Universally recognizable
    - Reduces text label needs
    - Improves scanability
  
  bad_examples:
    - Icons on every list item (visual noise)
    - Multiple icon styles mixed
    - Icons that require labels to understand

4. Navigation Optimization

Consolidation Rules:

user_menu_consolidation:
  rare_actions_nested:
    profile:
      - "Settings"
      - "Security" 
      - "Logout"
    
    rationale: "Users log out rarely, no need for top-level button"
  
  context_grouping:
    issues:
      - "Support requests"
      - "Feedback submissions"
      - "Assigned tasks"
    
    rationale: "All are 'items requiring attention'"

navigation_structure:
  top_level_max: 5-7 items
  nesting_max_depth: 2
  
  priority_order:
    1: Most accessed (Projects)
    2: Secondary frequent (Issues)
    3-5: Weekly access items
    6: Settings/Admin (collapsed)
    7: User menu (far right)

Navigation Generation Prompt:

When generating navigation menus:

1. Classify each section by access frequency (daily/weekly/monthly/rare)
2. Daily access = top-level navigation
3. Monthly/rare access = nested under icons
4. Group related items (e.g., "Issues" instead of separate "Support", "Feedback")
5. Use clear, single-word labels where possible
6. Icons for actions, text for sections
7. User-related actions under user profile icon (far right)
8. Max 5-7 top-level navigation items

---

Design System Standardization

Template Structure

design_system:
  colors:
    primary: "#HEX"
    secondary: "#HEX"
    accent: "#HEX"
    neutral: ["#HEX", "#HEX", "#HEX"]  # Light to dark
    semantic:
      success: "#HEX"
      warning: "#HEX"
      error: "#HEX"
      info: "#HEX"
  
  typography:
    font_family:
      primary: "System font stack or custom"
      monospace: "For code/data"
    
    scale:
      h1: {size: "32px", weight: "700", line_height: "1.2"}
      h2: {size: "24px", weight: "600", line_height: "1.3"}
      h3: {size: "20px", weight: "600", line_height: "1.4"}
      body: {size: "16px", weight: "400", line_height: "1.5"}
      small: {size: "14px", weight: "400", line_height: "1.4"}
  
  spacing:
    scale: [4, 8, 16, 24, 32, 48, 64, 96]  # pixels
    component_padding: 16
    section_spacing: 32
  
  components:
    button:
      height: 40
      padding: "12px 24px"
      border_radius: 6
      shadow: "0 2px 4px rgba(0,0,0,0.1)"
    
    card:
      padding: 24
      border_radius: 8
      shadow: "0 2px 8px rgba(0,0,0,0.08)"
      background: "neutral[0]"
    
    input:
      height: 40
      padding: "8px 12px"
      border: "1px solid neutral[2]"
      focus_border: "primary"

Customer Brand Template Process

def generate_brand_template(customer_specs: Dict) -> DesignSystem:
    """Generate customer-specific design standards."""
    
    template = {
        'customer_name': customer_specs.get('name'),
        'brand_colors': extract_colors(customer_specs.get('logo')),
        'font_preferences': customer_specs.get('fonts', 'system'),
        'design_style': customer_specs.get('style', 'modern'),  # modern/classic/minimal
    }
    
    # Generate full design system
    design_system = DesignSystem(
        colors=generate_color_palette(template['brand_colors']),
        typography=generate_typography_scale(template['font_preferences']),
        spacing=STANDARD_SPACING,  # Usually consistent
        components=generate_component_library(template['design_style'])
    )
    
    # Save as reusable template
    save_template(f"{template['customer_name']}_design_system.yaml")
    
    return design_system

def apply_design_system(ui_code: str, design_system: DesignSystem) -> str:
    """Apply design system to generated UI code."""
    
    # Parse UI code
    ui_ast = parse_ui_code(ui_code)
    
    # Apply design tokens
    for element in ui_ast.elements:
        element.apply_colors(design_system.colors)
        element.apply_typography(design_system.typography)
        element.apply_spacing(design_system.spacing)
        element.apply_component_styles(design_system.components)
    
    # Regenerate code with applied styles
    return ui_ast.to_code()

---

Implementation Phases

Phase 1: Agent Skill Development (24-48 Hours)

Deliverables:

1. ui_ux_agent_skill.md - Core skill documentation
2. header_consolidation_patterns.md - Header-specific rules
3. navigation_frequency_algorithm.md - Content prioritization
4. design_system_template.yaml - Reusable template structure

Acceptance Criteria:

• Will McKinley review and approval
• Successfully regenerates Avivate designs
• Before/after comparison shows measurable improvement
• Rules can be consistently applied by AI

Testing Process:

# Test cases
1. Generate dashboard with 8 sections
   → Validate: Max 5-7 top-level nav, rest nested
   
2. Generate project management UI
   → Validate: Projects = landing page, single header

3. Generate settings page
   → Validate: Nested under icon, not top-level
   
4. Apply customer brand template
   → Validate: Consistent colors/fonts throughout

Phase 2: Design System Generator (Week 1)

Tool Development:

class DesignSystemGenerator:
    """Generate consistent design systems for customers."""
    
    def from_brand_assets(self, logo_path: str, color_hex: str) -> DesignSystem:
        """Extract design system from logo/brand color."""
        pass
    
    def from_industry_template(self, industry: str) -> DesignSystem:
        """Use industry-appropriate design patterns."""
        # Fintech: Professional, trustworthy (blues, grays)
        # Healthcare: Clean, accessible (high contrast)
        # Creative: Bold, expressive (vibrant colors)
        pass
    
    def validate_accessibility(self, design_system: DesignSystem) -> bool:
        """Ensure WCAG 2.1 AA compliance."""
        pass

Phase 3: Quality Assurance Checklist (Ongoing)

Automated Checks:

ui_quality_checks:
  header_consolidation:
    - Header count <= 1
    - Total header height < 100px
    - No redundant navigation elements
  
  navigation:
    - Top-level items between 5-7
    - Rare actions properly nested
    - Clear, concise labels
  
  visual_design:
    - No double framing detected
    - Icon usage purposeful (not decorative)
    - Consistent spacing (using scale)
  
  content_priority:
    - Most-accessed content on landing page
    - Daily tasks < 3 clicks away
    - Settings/admin properly nested
  
  accessibility:
    - Color contrast ratios meet WCAG AA
    - Text sizes readable (min 14px)
    - Interactive elements min 44x44px

---

Will McKinley's UI/UX Design Rules (Direct Quotes)

Critical Principles

Header Compression:

"The multiple headers on the current dashboard view occupy too much screen real estate and should be compressed into one bar at the top."

Content Priority:

"The priority should be the content users access every morning. They would visit projects daily but not licenses or products."

Dashboard Definition:

"Dashboard should be heavily focused on projects, serving as a live feed that shows the advancement and status of projects."

Key Difference:

"The key difference between 'settings' and 'live content' - projects are what you check every morning."

Navigation Optimization:

"For simple pages, the scrollable header might not be an issue, but for dashboards, get straight to the content immediately."

Design Quality Issues Identified

Current Problems:

• "Designs look AI-generated with excessive icon usage"
• "Failure to emphasize key dashboard information"
• "Duplicate headers"
• "Unnecessary verbiage"
• "Excessive spacing that pushes main content far down the page"

Solutions Required:

• "Eliminate extraneous information"
• "Eliminate repeated words"
• "Simplify words to focus on essential content users need daily"
• "Avoid double framing"
• "Use toned backgrounds instead of strokes (lines around components)"
• "Visually flatten the design to simplify information presented to user"

Frequency-Based Navigation Prompt

Will's Suggested Approach:

"Evaluate the frequency of user access to each section and make the most-accessed section the landing page, thereby minimizing clicks."

Implementation:

Prompt: For each navigation section, determine:
1. How often will users access this? (daily/weekly/monthly/rare)
2. Is this live data or static H.P.009-CONFIGuration?
3. What's the user's primary task when accessing this section?

Then:
- Daily + live data = Landing page + top navigation
- Weekly + live data = Top navigation, secondary priority  
- Monthly + static = Nested under settings
- Rare + static = Nested 2+ levels deep

---

Success Metrics

Quantitative Metrics

before_after_comparison:
  vertical_space_efficiency:
    before: "Content starts at 400px (3-4 headers)"
    after: "Content starts at 80px (1 header)"
    improvement: "320px reclaimed = 80% more content visible"
  
  navigation_depth:
    before: "Daily tasks 3-5 clicks away"
    after: "Daily tasks 0-1 clicks away"
    improvement: "60-80% reduction in clicks"
  
  visual_complexity:
    before: "3-4 visual layers (nested borders/shadows)"
    after: "1-2 visual layers (flat design)"
    improvement: "50% reduction in visual noise"

customer_feedback:
  design_quality_score:
    target: "> 8/10"
    measurement: "Post-project survey"
  
  ai_generated_perception:
    target: "< 10% mention 'looks AI-generated'"
    measurement: "Customer feedback analysis"
  
  professional_appearance:
    target: "> 90% rate as 'professional/enterprise-grade'"
    measurement: "A/B test with stakeholders"

Qualitative Metrics

Customer Testimonials Should Include:

• "Design looks professional/polished"
• "Better than [competitor] output"
• "Clients impressed with UI quality"
• "No need for external designer"

Internal Validation:

• Will McKinley approval: "This no longer looks AI-generated"
• Sales team: "Design quality closes deals"
• Customers: "UI quality exceeded expectations"

---

Anti-Patterns to Avoid

Common AI UI Generation Mistakes

header_sins:
  ❌ "App Header + Breadcrumb + Page Title + Section Header"
  ✅ "Single consolidated top navigation"

navigation_sins:
  ❌ "Logout as standalone top-level button"
  ✅ "Logout nested under user profile icon"
  
  ❌ "Settings, Security, Profile as separate top-level items"
  ✅ "All nested under single 'Account' or user icon"

content_sins:
  ❌ "Dashboard = Settings page with static info"
  ✅ "Dashboard = Live project feed with status updates"
  
  ❌ "Most-accessed content buried 3 clicks deep"
  ✅ "Most-accessed content = landing page"

visual_sins:
  ❌ "Icon on every list item (decorative)"
  ✅ "Icons only for actions (functional)"
  
  ❌ "[Card border [Section border [Button border]]]"
  ✅ "[Card background change, no borders]"
  
  ❌ "Repeated navigation terms: 'Project Dashboard > Project View > Project List'"
  ✅ "Concise: 'Projects'"

---

Integration with Existing CODITECT Workflow

Agent Skill Loading

# In CODITECT agent initialization
agent_H.P.003-SKILLS = [
    load_skill("ui_ux_agent_skill"),
    load_skill("header_consolidation_patterns"),
    load_skill("navigation_frequency_algorithm"),
    load_skill("design_system_template")
]

# On UI generation request
def generate_ui(requirements: Dict, customer_id: str) -> str:
    # Load customer design system if exists
    design_system = load_design_system(customer_id) or generate_default()
    
    # Apply UI/UX H.P.003-SKILLS
    ui_code = ai_agent.generate(
        requirements=requirements,
        H.P.003-SKILLS=agent_H.P.003-SKILLS,
        design_system=design_system
    )
    
    # Quality check
    quality_score = validate_ui_quality(ui_code, agent_H.P.003-SKILLS)
    
    if quality_score < 0.8:
        ui_code = ai_agent.refine(ui_code, feedback=quality_violations)
    
    return ui_code

Customer Onboarding

project_initialization:
  step_1:
    action: "Request design assets (logo, brand colors)"
    optional: true
    fallback: "Use industry template"
  
  step_2:
    action: "Generate design system"
    output: "{customer_name}_design_system.yaml"
  
  step_3:
    action: "Customer review and approval"
    iterations: "Until satisfied"
  
  step_4:
    action: "Lock design system for project"
    enforcement: "All UI generation uses this system"

---

Timeline & Ownership

Task	Owner	Duration	Deadline	Dependencies
UI/UX skill documentation	Hal	8 hours	Jan 20 EOD	Will's input
Will's design principles doc	Will	2 hours	Jan 20 EOD	None
Header consolidation patterns	Hal	4 hours	Jan 20 EOD	Will's review
Navigation frequency algorithm	Hal	4 hours	Jan 20 EOD	Will's review
Design system template	Hal	4 hours	Jan 21 EOD	Skills complete
Avivate design regeneration	Hal	2 hours	Jan 21 EOD	Skills complete
Before/after comparison	Matias	2 hours	Jan 21 EOD	Regeneration done
Will's approval	Will	1 hour	Jan 21 EOD	Comparison ready

Critical Path: Hal's skill development → Will's review → Avivate regeneration → Approval

---

Appendix: Research & References

Will McKinley to Research & Send to Hal

Topics:

1. Modern UI/UX best practices (2024-2026)
2. Dashboard design patterns for SaaS
3. Navigation hierarchy principles
4. Visual design simplification techniques
5. Accessibility standards (WCAG 2.1)

Sources to Review:

• Nielsen Norman Group (UX research)
• Refactoring UI (design principles book)
• Material Design 3 (Google)
• Apple Human Interface Guidelines
• Tailwind UI patterns (practical examples)

Competitive Analysis

Tools to Analyze:

• Linear (project management - excellent UI)
• Notion (information hierarchy master)
• Figma (design tool - clean interface)
• Stripe Dashboard (data-heavy, simple design)
• Retool (no-code tool - inspect for patterns)

Evaluation Criteria:

• Header structure and compression
• Navigation depth and organization
• Content prioritization
• Visual simplicity
• Information density vs. whitespace