# View Header UI/UX Standards

**Version:** 1.0  
**Date:** 2026-01-23  
**Audit Scope:** 935 view files analyzed

## Executive Summary

Based on a comprehensive audit of all 935 ERP view files, this document establishes the **standard UI/UX pattern** for page headers to ensure consistency across the application.

### Current State Analysis

| Metric | Count | Percentage |
|--------|-------|------------|
| Total view files | 935 | 100% |
| Using h1 title | 785 | 84% |
| Using h2 title | 65 | 7% |
| With page-header class | 695 | 74.3% |
| With subtitles | 685 | 73.3% |
| Using Action Menu | 74 | 7.9% |
| Using d-flex layout | 855 | 91.4% |
| With back button | 546 | 58.4% |

### Key Findings

1. **Good Consistency**: 84% already use h1 tags, 91% use d-flex layout
2. **Inconsistent Button Styles**: 18 different button style variations found
3. **Action Menu Under-utilized**: Only 7.9% use Action Menu (should be used for 3+ buttons)
4. **Mixed Title Classes**: Some use h3 class on h1 tags (inconsistent)

## The Standard Pattern

### Visual Layout

```
┌────────────────────────────────────────────────────────┐
│  ╔════════════════════════╗  ┌─────────────────────┐   │
│  ║ Page Title             ║  │  [Action Menu ▼]    │   │
│  ║ Optional subtitle text ║  │  or [Button] [Back] │   │
│  ╚════════════════════════╝  └─────────────────────┘   │
└────────────────────────────────────────────────────────┘
      flex-grow-1                   Action buttons
```

### HTML Structure

```html
<div class="d-flex align-items-center mb-3">
    <div class="flex-grow-1">
        <h1 class="page-header mb-0">Page Title</h1>
        <p class="text-muted mb-0">Optional subtitle</p>
    </div>
    <div>
        <!-- Action Menu or Individual Buttons -->
    </div>
</div>
```

## Component Usage

### Standard Page Header Component

**Location:** `views/components/standard_page_header.php`

**Function:** `renderStandardPageHeader($title, $subtitle, $actionMenuId, $actionContext, $buttons)`

### When to Use What

| Scenario | Component | Example |
|----------|-----------|---------|
| **3+ action buttons** | Action Menu | Product Forecast, Customers, Assets |
| **1-2 buttons** | Individual buttons | Create forms, Edit forms |
| **Title only** | Simple call | Dashboard, Reports |
| **With subtitle** | Add subtitle param | Index pages with descriptions |

## Button Standards

### Button Style Guide

| Purpose | Class | Icon | Usage |
|---------|-------|------|-------|
| **Primary action** | `btn btn-primary` | `bi bi-check-lg` | Save, Submit, Create |
| **Secondary action** | `btn btn-outline-theme` | varies | Export, Filter, Settings |
| **Back/Cancel** | `btn btn-outline-theme` | `bi bi-arrow-left` | Navigation back |
| **Danger** | `btn btn-danger` | `bi bi-trash` | Delete, Remove |
| **Success** | `btn btn-success` | `bi bi-download` | Download, Import |

### Deprecated Button Styles

❌ Avoid these (found in audit):
- `btn-outline-cancel` (use `btn-outline-theme` instead)
- `btn-outline-delete` (use `btn-danger` instead)
- `btn-outline-create` (use `btn-primary` instead)
- `btn-outline-default` (use `btn-outline-theme` instead)

## Implementation Examples

### Example 1: Index Page with Action Menu

```php
<?php
require_once BASE_PATH . '/views/components/standard_page_header.php';
renderStandardPageHeader(
    'Customer Management',
    'Manage customer records and contacts',
    'customers_index',
    []
);
?>
```

### Example 2: Create/Edit Page with Buttons

```php
<?php
require_once BASE_PATH . '/views/components/standard_page_header.php';
renderStandardPageHeader(
    'Add Customer',
    null,
    null,
    [],
    [
        ['text' => 'Save', 'url' => '#', 'class' => 'btn btn-primary', 'icon' => 'bi bi-check-lg', 'onclick' => 'submitForm()'],
        ['text' => 'Back', 'url' => base_url('customers'), 'class' => 'btn btn-outline-theme', 'icon' => 'bi bi-arrow-left']
    ]
);
?>
```

### Example 3: Show/Detail Page with Action Menu

```php
<?php
require_once BASE_PATH . '/views/components/standard_page_header.php';
renderStandardPageHeader(
    'Asset: ' . e($asset['name']),
    'Status: ' . e($asset['status']),
    'asset_show',
    ['asset_id' => $asset['id']]
);
?>
```

### Example 4: Simple Dashboard

```php
<?php
require_once BASE_PATH . '/views/components/standard_page_header.php';
renderStandardPageHeader('Dashboard');
?>
```

## Migration Checklist

### For Each Page

- [ ] Replace custom header markup with `renderStandardPageHeader()`
- [ ] Ensure title uses h1 (not h2 or h3)
- [ ] Apply `page-header mb-0` class to title
- [ ] Convert 3+ buttons to Action Menu
- [ ] Standardize button classes (see Button Standards)
- [ ] Use `bi bi-arrow-left` icon for back buttons
- [ ] Add `me-2` spacing between buttons
- [ ] Remove deprecated button styles

### Priority Levels

**High Priority** (160+ pages):
- Pages using h2 tags (65 files)
- Pages with 3+ buttons not using Action Menu
- Pages without d-flex layout (80 files)

**Medium Priority** (240+ pages):
- Pages without page-header class (240 files)
- Pages with deprecated button styles
- Pages with inconsistent back button styling

**Low Priority**:
- Pages with working layouts but minor style variations
- Pages with subtitle formatting differences

## Testing After Migration

1. **Visual Consistency**: All headers should align at same height
2. **Responsive Design**: Test on mobile/tablet (buttons should wrap properly)
3. **Icon Spacing**: Icons should have `me-1` spacing from text
4. **Button Spacing**: Buttons should have `me-2` spacing between them
5. **Action Menu**: Dropdown should work, back button should be separate

## Benefits of Standardization

✅ **Consistency**: Users know where to find actions on every page  
✅ **Maintainability**: One component to update for global changes  
✅ **Accessibility**: Proper heading hierarchy (h1 → h2 → h3)  
✅ **Responsive**: Works on all screen sizes  
✅ **Development Speed**: Copy-paste pattern for new pages  

## Next Steps

1. **Phase 1**: Update high-priority pages (65 h2 pages, 80 non-flex pages)
2. **Phase 2**: Convert 3+ button pages to Action Menu
3. **Phase 3**: Standardize button styles across all pages
4. **Phase 4**: Add subtitles where beneficial (currently 73% have them)
5. **Phase 5**: Apply to next 174 new pages being built

## Questions?

See full audit report: `docs/VIEW_HEADER_AUDIT.md`  
Component code: `views/components/standard_page_header.php`  
Action Menu docs: `docs/ACTION_MENU_PATTERN.md` (see WARP.md)

---

**Remember**: The goal is consistent, predictable UI/UX across all 1000+ pages of the ERP system.