# UI Design System Migration

## Goal

Create one controlled design system for the admin UI so typography, colors, spacing,
radius, controls, tables, menus, and page geometry are managed from a single source,
then migrate pages gradually with visual checks.

## Current Findings

- `header.php` owns runtime DB variables and large inline CSS.
- `footer.php` still adds late global overrides.
- `assets/css/ua_modern.css`, `ua_sidebar3.css`, `ua_global_feedback.css`,
  `ua_app_shell_contract.css`, and `ua_extracted_pages.css` are active layers.
- There are about 60 inline `<style>` blocks in PHP pages.
- CSS files contain thousands of `!important` declarations, so direct cleanup must be
  page-by-page, not a single delete.
- `template_page.php` already saves basic theme settings, but it needs to evolve into
  a controlled Theme Studio with a migration mode.

## New Foundation

- `ui_design_system.php`
  Central registry for design settings and sanitizers.
- `assets/css/ua_design_tokens.css`
  Shared design tokens: spacing, control height, table row height, surfaces, menus.
- `assets/css/ua_design_system.css`
  Opt-in V2 component layer scoped to `body.ua-design-v2`.
- `ui_design_mode`
  Saved setting with two modes:
  - `legacy`: current program appearance.
  - `v2`: new design system, used for gradual migration and visual QA.

## Migration Rules

1. Keep `legacy` as the default until a page is verified.
2. Move repeated page CSS into design tokens or shared components.
3. Reduce page CSS to layout-only rules; color/radius/spacing should come from tokens.
4. For every page, test desktop and narrow viewport visually.
5. Only delete old CSS after the replacement page is verified.
6. Prefer removing `!important` by lowering layer conflict, not by adding stronger rules.

## Suggested Page Order

1. `template_page.php` and common shell.
2. Simple CRUD pages using standard `.card`, `.form-control`, `.table`.
3. Finance pages.
4. Subscriber child modal pages.
5. `subscribers.php`.
6. `dashboard.php` last, because it has its own manual shell and large CSS surface.

## Progress Snapshot

- Foundation and Theme Studio are in place.
- Simple V2 pages and subscriber child/modal pages are active.
- Finance pages now force V2 for QA:
  - `finance_reports.php`
  - `finance_cashbox.php`
  - `finance_day_report.php`
  - `finance_month_close.php`
  - `finance_month_report.php`
  - `finance_payments.php`
  - `finance_expenses.php`
- Billing and purchases pages now force V2 for the next QA pass, while print
  pages remain print-safe until paper layout is verified.
- Sales pages now force V2 for the same QA pass.
- Settings/security/admin pages now force V2 for the same QA pass.
- `dashboard.php` already forces V2 and remains the dedicated dashboard shell.
- QA was run on `http://127.0.0.1:8080/mikrotik/admin/` with representative
  migrated pages and print-safe pages; the checked set had no page-level
  horizontal overflow and no visible PHP fatal/parse errors.
- The root progress file `UI_DESIGN_SYSTEM_PROGRESS.txt` is the working checklist
  linked from `template_page.php`.
- The remaining non-print admin shell pages have now been force-enabled for V2,
  with a compatibility layer for older card/tab/table/form markup. Public payment,
  print, Theme Studio, and bootstrap helper files remain intentionally outside
  forced V2.
- A final mobile shell guard keeps normal V2 pages full-width at narrow
  breakpoints when the sidebar setting is pinned, while preserving internal
  horizontal scrolling for dense tables and tab rails.
- Theme Studio accent propagation now includes a shared bridge for older fixed
  shell/page colors so migrated V2 pages visually follow `--ua-accent`, not only
  receive the CSS variable.

## Visual QA Checklist

- Page opens without PHP errors.
- No overlapping text or controls.
- Inputs have consistent height and readable labels.
- Tables keep stable row height and sticky columns if present.
- Dropdowns align RTL and remain above content.
- Modal/embed pages do not duplicate shell chrome.
- Sidebar, topbar, and page windowbar keep expected geometry.
