# UI Build Rules (AdCenter)

This file defines mandatory rules while building UI in this project.

## 0) Migration Context (Mandatory)
- Target app (new): `/var/www/php74/mason/adcenter.admedia.com`
- Legacy app (source of API/DB behavior): `/var/www/php74/mason/advertisers7_new.admedia.com`
- Design source pages/assets: `/var/www/php74/mason/adcenter.admedia.com/design`
- During migration, UI is implemented in target app while API/DB logic is ported/adapted from legacy app.
- **Epic AP-2 (Dashboard):** follow `migration/AP2_EXECUTION_PLAN.md` — especially **§4 Architecture & reusability** (shared period logic, filter DTO, KPI registry/formatter, Services vs views) and **§7 Recommended build sequence**.

## 1) Design Parity
- Match the approved design exactly for spacing, typography, colors, states, and responsive behavior.
- Do not introduce custom visual variations unless explicitly requested.
- Reuse existing design tokens/classes before adding new CSS.

## 2) Component-First Development
- Build reusable view components first (`app/Views/components/*`) before page-specific markup.
- Keep component APIs data-first (`view('components/...', $data)`).
- Avoid copy-pasting repeated HTML blocks across pages.

## 3) CodeIgniter Conventions
- Use CI view composition patterns (`extend`, `section`, `include`, `view`).
- Keep business/data logic out of views; pass prepared data from controllers.
- Keep routes explicit for shared pages (e.g., UI kit, docs, feature pages).
- Keep controller methods thin; extract shared transformation logic into helpers/services.

## 3.1) Decoupling and Reusability (Mandatory)
- Write decoupled code: no page-specific business logic embedded in component partials.
- If logic is reused across multiple pages, move it to shared helpers/services/utilities.
- Avoid duplicating API-mapping or formatting logic between controllers.
- Build reusable utility functions for repeated tasks (formatting, filters, request normalization, mapping payloads).
- Prefer composing reusable modules over adding one-off code paths.

## 4) Safety and Escaping
- Escape untrusted output with `esc()`.
- Only render raw HTML in clearly intentional fields (e.g., `bodyHtml`, table `html` cell payloads).
- Never output user input directly into HTML attributes or scripts.

## 5) Accessibility and UX Basics
- Every form field needs a label.
- Use meaningful placeholders and validation/error message placement.
- Ensure keyboard-usable controls and visible focus states.

## 6) Frontend Compatibility
- Keep compatibility with PHP 7.4 (no PHP 8+ only functions).
- Prefer progressive enhancement; UI should not break if optional JS fails.
- Keep third-party dependency usage consistent with current project strategy.

## 7) Validation Before Merge
- Run lint checks on changed files.
- Run `php -l` for updated PHP files.
- Verify affected pages render with no missing asset errors.

## 8) Git Workflow for Ticket-by-Ticket Delivery (Mandatory)
- Work one ticket at a time under epic `AP-2`; do not combine multiple tickets into one branch/commit batch.
- Create a dedicated branch per ticket using the ticket ID as the branch name (example: `AP-21`).
- Keep commit messages brief and ticket-scoped (example: `AP-21: table filter UI`).
- Commit only files required for the active ticket; avoid "drive-by" changes.
- Before opening/switching ticket work:
  1. Ensure working tree is clean (`git status`).
  2. Pull latest base branch.
  3. Create/switch to the ticket branch.
- Before each commit:
  1. Run lint checks for changed files.
  2. Run `php -l` for changed PHP files.
  3. Verify the related page/flow manually.
- Recommended ticket flow:
  1. `git checkout <base-branch>`
  2. `git pull`
  3. `git checkout -b AP-XX`
  4. Implement only AP-XX scope
  5. `git add <ticket files>`
  6. `git commit -m "AP-XX: brief description"`
  7. Push and open PR for AP-XX only
- If a dependent ticket is blocked, create a short note in the ticket and move to next independent ticket; do not overload current branch with cross-ticket work.