# Design System Audit — Phase 11A1

**Status:** Read-only audit.  No Vue, CSS, route, or business-rule changes were made.

## Scope and method

This inventory reviews the Vue templates in `resources/js`, the shared component and layout layer, and the Tailwind configuration.  Findings are source-level observations, not a replacement for device/browser visual QA.  The application uses Tailwind utilities directly in templates; `resources/css/app.css` contains only Tailwind directives and `tailwind.config.js` only extends the sans font with Figtree.  There are no project design tokens, component CSS classes, or an application-level component library beyond the small shared set below.

## Current strengths

- The product has a coherent operational baseline: most newer portal screens use white cards, slate text, indigo actions, rounded corners, and `max-w-*` content containers.
- `AuthenticatedLayout` supplies one signed-in shell, desktop/mobile navigation, an account dropdown, notification panel, page-header slot, and an onboarding-modal mount point.
- Existing foundational controls (`PrimaryButton`, `SecondaryButton`, `DangerButton`, `TextInput`, `InputLabel`, `InputError`, `Checkbox`, `Modal`, and dropdown/navigation links) demonstrate an intended reuse boundary.
- Newer high-density tables commonly use a scroll wrapper, `text-sm`, subdued `bg-slate-50` headers, row dividers, and a visible no-results message.
- Validation is generally supplied by Inertia form errors; core auth/profile flows consistently pair `InputLabel`, `TextInput`, and `InputError`.
- The agent leads board, notification list, timelines, responsive authenticated navigation, and CMS public pages contain useful purpose-specific interaction and responsive patterns.

## UI inventory

### Shared building blocks

| Area | Present implementation | Notes |
| --- | --- | --- |
| Buttons | `PrimaryButton`, `SecondaryButton`, `DangerButton`; 65 native `<button>` occurrences across 34 files | Shared buttons use uppercase `text-xs` with wide tracking, while most in-page buttons are ad hoc `rounded bg-indigo-600 px-3/4 py-2 text(-sm)`. |
| Inputs | `TextInput` (gray border/shadow, indigo focus); 64 native `<input>` occurrences across 25 files | Native fields vary among `border`, `border-slate-300`, `rounded`, `rounded-md`, and `rounded-lg`; public quotation uses `p-3`. |
| Textareas | 11 occurrences in 10 files | No shared textarea.  Shapes/padding range from browser-style to `rounded-lg` / `text-sm`. |
| Checkboxes | `Checkbox` plus native checkboxes in onboarding, coupon, registration, quotation | No shared field wrapper or required/help text convention. |
| Radio buttons | None found | No radio component/pattern currently exists. |
| Selects | 32 occurrences in 14 files | Mostly native selects; labels are often absent for compact admin filter controls. |
| Dropdowns | Shared `Dropdown` / `DropdownLink` for account menu; custom notification popover | Two separate popover presentations and no common menu-item states beyond the account dropdown. |
| Navigation | Shared desktop `NavLink` and mobile `ResponsiveNavLink`; public CMS navigation is inline per page | Signed-in menu has many admin links; public navigation uses a different inline system. |
| Icons | Inline SVG only (logo, hamburger, notification bell, chevron) | No icon registry, sizing convention, or shared icon-button component. |

### Layout, hierarchy, and feedback

| Area | Present implementation | Notes |
| --- | --- | --- |
| Page headers | Authenticated header slot with `max-w-7xl`, `py-6`; pages commonly provide `h2 text-xl font-semibold` | Detail and public pages frequently create a separate in-content `h1 text-2xl`; hierarchy is not fully uniform. |
| Section headers | Mostly inline `h2`/`h3 font-semibold`, sometimes card `<header>` with `px-5 py-4` | No reusable section-header/action alignment pattern. |
| Cards | Repeated local shells (at least 16 `rounded-xl bg-white`, 12 `rounded-xl border border-slate-200 bg-white`, 11 `rounded-xl border bg-white`) | Radius, border, shadow, and internal padding vary materially. |
| Tabs | None found | No existing tab semantics or visual treatment. |
| Breadcrumbs | None found | Back links appear in selected detail/editor pages instead. |
| Badges/status pills | Inline status text; small amber repeat/reason labels; CMS revision pills; notification count | Shape ranges from no background to `rounded`, and color semantics are page-specific. |
| Alerts/notifications | Inline flash alerts in emerald/amber; authenticated notification dropdown and index list | Alert padding, border use, and color scale differ.  No shared live-region/alert component. |
| Modals/dialogs | Shared native `<dialog>` `Modal` (sm/md/lg/xl/2xl); profile delete confirmation; forced agent onboarding flow | Content/header/footer and action order are supplied ad hoc by callers.  Only profile deletion has a conventional destructive confirmation. |
| Loading | Form controls commonly disable and reduce opacity while `processing`; lead board fades in-flight cards | No visible spinner, button loading label, page loader, skeleton, or standardized loading state found. |
| Empty states | Text-only messages in tables, lists, timeline/notes, notifications, partner history, board lanes, revisions | Copy is specific and useful, but alignment/padding/container treatment is inconsistent; no illustrations/actions standard. |
| Pagination | Inline `rounded border px-3 py-1` links/buttons in leads/coupons and selected list pages | No shared pagination component or active/focus/ellipsis convention. |

## Color audit

### Observed palette and roles

| Role | Current usage | Audit finding |
| --- | --- | --- |
| Primary | Indigo, chiefly `bg-indigo-600`, `text-indigo-600/700`, `ring-indigo-500` | Clear emerging action color, but `PrimaryButton` is gray-800 rather than indigo. |
| Secondary / neutral action | White + gray/slate border; shared secondary uses gray | Multiple neutral families (`gray` and `slate`) are used interchangeably. |
| Success | Emerald (`bg-emerald-50`, `text-emerald-700/800`, `bg-emerald-600`) plus `green-600` | Success is not mapped to a single family. |
| Warning | Amber 50/100/200/300/400/500 and 700/800/900/950 | Good visual distinction but very broad tonal range and no semantic token. |
| Danger | Red 50/500/600/700 and rose-600 | Two destructive families; `DangerButton` is red while premium-lead rejection is rose. |
| Info | Indigo is used for links, actions, active navigation, and unread items | No separate informational alert/status token; semantic overlap is high. |
| Gray scale | Gray 50–900 and slate 50–950 | Both palettes cover surface, border, and text roles.  This is the largest consistency opportunity. |
| Backgrounds | `bg-gray-100` authenticated shell; slate-50 newer/public screens; white card surfaces; operator CMS CSS variables | Base page background differs by area; CMS variables are correctly tenant/theme-driven but have no documented fallback token contract. |
| Borders | `border`, gray-100/200/300, slate-100/200/300, indigo, emerald, amber | A bare `border` depends on Tailwind defaults, creating a less explicit surface system. |
| Text | slate-900/800/700/600/500/400, gray-900/800/700/600/500, indigo/red/amber/emerald | Hierarchy is legible in newer pages but color families vary by component age. |

Other outliers are the Laravel starter `Welcome.vue` (black, zinc, and `#FF2D20`, with dark mode) and public operator pages that use runtime CSS variables.  The starter page is visually unrelated to the product palette and should be explicitly retained, replaced, or excluded when tokens are introduced.

## Typography audit

- **Font:** Figtree is configured as the application sans font; no type scale tokens are defined.
- **Heading hierarchy:** authenticated slot headers are predominantly `text-xl font-semibold`; content page titles use `text-2xl`; public marketing/CMS pages range from `text-3xl` through `text-6xl`.  `h1`, `h2`, and `h3` visual scales do not consistently correspond to semantic level.
- **Body/caption:** `text-sm` is dominant (248 utility occurrences). `text-xs` (34) is used for metadata, labels, pills, and button text; default browser-sized body copy is also common. Captions are not a named pattern.
- **Weights:** `font-semibold` (118) and `font-medium` (63) dominate; `font-bold` is used mainly in public content.  The blend is reasonable but undocumented.
- **Line-height:** most text relies on Tailwind defaults; explicit `leading-6`/`leading-8` appears in readable public copy and `leading-5` in legacy components. This creates different density across areas.
- **Spacing around text:** headings vary from no margin to `mt-1`, `mt-2`, `mt-3`, `mt-4`, and `mt-5`; no title/subtitle rhythm is standardized.

## Spacing and surface audit

- Page gutters vary between `p-4 sm:p-6`, `p-6`, `px-4 py-12`, `px-6 py-28`, and `p-10`; container widths range from `max-w-3xl` to `max-w-7xl`, sometimes absent for administrative pages.
- Card padding varies from `p-3` to `p-8` (most operational cards use `p-4`, `p-5`, or `p-6`). Header-to-body treatment appears as either a padded card, a border-separated header, or no header wrapper.
- Forms use `space-y-3`, `space-y-4`, `gap-2`, `gap-3`, and `gap-5`; field label-to-control spacing ranges from no gap to `mt-1`.
- Table cells use no explicit padding on legacy billing/support/registrations tables, `p-3` in newer admin tables, and `px-5 py-3` in dashboard/partner tables.
- Section gaps commonly use 5, 6, 10, or 12 spacing values.  These are plausible individually but not yet a reusable spacing scale in practice.

## Table audit

| Area | Tables inventoried | Current style / responsive treatment |
| --- | --- | --- |
| Admin | Agents, Coupons, Dashboard operator breakdown, Lead Credits, Leads, Partner Withdrawals, Payments, Premium Lead Approvals, Registrations, Round Robin, Support | Newer operational tables often have `overflow-x-auto`, white rounded shells, slate header fills, and `p-3`; Payments/Registrations/Support retain minimal, unwrapped `w-full` tables. |
| Agent | Billing, Partner withdrawal history, Partner commission history, Support | Partner tables match the newer padded/slate-header style. Billing is a separate simple shadowed table; Support has no overflow wrapper, cell padding, or card shell. |
| Coupons | Admin coupons index | Good scroll wrapper and empty row; differs in shadow/no explicit border and uses a local pagination implementation. |
| Leads | Admin leads, Lead Credits, Premium Lead Approvals, Round Robin, Agent premium-lead board (not a table) | Leads family mostly converges on `rounded-xl border bg-white`, `bg-slate-50`, `p-3`, row borders, and text empty rows. |
| Partner / withdrawals | Agent partner two tables; admin partner-withdrawals index | Agent partner screens use the most complete table shell. Confirm admin withdrawal indexing during implementation design; it is an inventory item but not a shared abstraction today. |
| CMS / registration | Website revisions are cards/dl rather than a table; Registrations table is minimal | CMS uses card/list presentation. Registration table lacks a responsive overflow wrapper and the newer header/cell tokens. |

**Conclusion:** tables do not yet share one common style.  A recognizable newer style exists, but legacy/minimal tables have different padding, header, border, shell, and mobile overflow behavior.

## Form audit

### Form families

- **Auth/profile:** login, register, password/reset/confirm, email verification/resubmission, and profile partials use the shared input/label/error components most consistently.
- **Administrative filters:** leads, support, registrations, payments, coupons, lead credits, premium approvals, agents, and round-robin use inline native inputs/selects with several layout patterns.
- **Administrative editors/settings:** coupon form; agents/registrations review; onboarding; receipt; website section/theme settings; withdrawal/support detail actions; dashboard financial settings.
- **Agent workflows:** partner withdrawal, premium-lead status/note, support creation/conversation, membership/billing/e-wallet/credit/affiliate flows.
- **Public:** quotation is a large all-native form using CSS-variable action colors; it exposes errors together at the bottom.

### Findings

- Labels are strong in auth/profile and many settings forms, but compact filters and several public/operational inputs rely only on placeholders. Required fields do not have a consistent visible indicator.
- Validation ranges from shared `InputError`, to local red paragraphs, to a grouped public error list; success feedback is inline on selected pages.  There is no common field help/error layout.
- Primary actions are sometimes immediately after the field, sometimes after the whole form, and sometimes paired with Cancel links/buttons.  Button order and alignment vary.
- Form density is not standardized: controls appear at `p-3`, `px-3 py-2`, plain `rounded border`, and shared shadowed styles.

## Modal and dialog audit

- **Base modal:** `Components/Modal.vue` uses a native dialog, overlay click/Escape dismissal when closeable, scroll lock, transitions, and five maximum widths.
- **Profile deletion:** one confirmation modal with a destructive action and secondary cancel action.
- **Agent onboarding:** one forced, non-dismissible modal with three flow states and local controls.
- **Other confirmations:** destructive/approval actions (for example premium approvals, withdrawals, CMS restore) execute as inline buttons; no shared confirmation convention is visible.

There is no common modal header, close affordance, footer, prescribed primary/secondary button order, or modal-size naming at call sites beyond raw max width.

## Responsive audit

| Area | What works | Obvious inconsistency / risk |
| --- | --- | --- |
| Landing/public | Public Home and CMS pages use constrained containers; CMS uses wrapped navigation, mobile padding, and responsive headings/grids. | Home has only one small breakpoint; quotation nav wraps but the long form has limited responsive field structure. `Welcome.vue` is a separate Laravel starter visual system. Operator placeholder and thank-you pages are minimal. |
| Agent portal | Authenticated navigation collapses to a hamburger; dashboards/partner screens introduce 2–4 column grids responsively; partner tables scroll. | Billing and Support tables have no explicit horizontal-scroll wrapper. Many agent pages only use a fixed `p-6`, and details/buttons do not share a mobile action-bar pattern. |
| Admin portal | Leads, dashboard, settings, CMS lists, and selected filter rows use grid/flex breakpoints; most newer tables scroll. | Navigation packs many admin items into the desktop row before collapsing at `sm`, making intermediate-width overflow likely. Several admin tables/filters retain one-line, unwrapped layouts (Payments, Registrations, Support). Breakpoint coverage is uneven and chiefly `sm`, with limited `md`/`lg`. |

## Tailwind repetition and component-duplication candidates

Repeated utility clusters are the safest evidence for future reusable visual components; no change is proposed in this phase.

1. **AppButton** — variants: primary indigo, secondary outline, danger/destructive, quiet/text; sizes; loading/disabled; link rendering.
2. **FormField** — label, required/optional indicator, hint, input/select/textarea slot, unified validation message.
3. **TextInput / Select / Textarea / CheckboxField** — shared visual primitives building on (or replacing after migration from) the existing isolated `TextInput` and `Checkbox`.
4. **Surface/Card and CardHeader** — normalized radius, border/shadow, padding, and header/action slots.
5. **DataTable** — scroll wrapper, header/cell density, empty slot, loading slot, responsive behavior; retain domain columns in pages.
6. **StatusBadge** — semantic success/warning/danger/info/neutral variants with one compact and one pill option.
7. **Alert** — semantic variants, optional title/action, consistent live-region behavior.
8. **EmptyState and LoadingState** — standardized text/action/illustration slot and spinner/skeleton/button-loading patterns.
9. **Pagination** — active, disabled, ellipsis, accessible labels, and common spacing.
10. **PageHeader / SectionHeader** — title, description, breadcrumbs/back link, and action slots.
11. **DialogContent / ConfirmDialog** — standardized header/body/footer, size, button order, and dismiss policy while retaining `Modal` as the low-level primitive.
12. **AppNav / PublicNav, IconButton, PopoverMenu** — consolidate separate navigation/popup patterns without forcing public tenant theming into the authenticated shell.

## Recommended Design System structure

```text
resources/js/Components/DesignSystem/
  foundations/       # semantic color, type, spacing, radius, elevation decisions
  primitives/        # Button, IconButton, Input, Select, Textarea, Checkbox
  patterns/          # FormField, Card, DataTable, Pagination, StatusBadge, Alert
  overlays/          # DialogContent, ConfirmDialog, Menu/Popover
  layout/            # PageHeader, SectionHeader, EmptyState, LoadingState
  icons/             # named SVG exports or wrapper
```

Foundation values should be semantic (`surface`, `text-muted`, `border-default`, `action-primary`, `status-success`, etc.), with Tailwind theme aliases or component recipes.  Keep public operator CSS variables as a documented themed layer mapping to the same semantic roles; do not hard-code tenant colors into authenticated portal primitives.

## Priority and recommended implementation order

1. **P0 — Define foundations and document tokens.** Choose one neutral family (recommend slate for newer operational UI), one primary action treatment, semantic status colors, type scale, spacing scale, radii, borders, and elevation. Resolve legacy `PrimaryButton` gray vs. in-page indigo and red vs. rose destructive actions.
2. **P0 — Normalize controls and field validation.** Deliver button variants/loading, input/select/textarea/checkbox primitives, and FormField. Migrate auth/profile first as the low-risk reference, then public quotation and high-frequency admin filters.
3. **P0 — Establish responsive data-table, pagination, empty, and loading patterns.** Begin with Admin Leads/Lead Credits/Premium Approvals and Agent Partner, then bring Billing, Support, Registrations, and Payments to parity. Include mobile overflow and accessible labels.
4. **P1 — Normalize structural patterns.** Introduce PageHeader, SectionHeader, Card, StatusBadge, and Alert; migrate operational dashboards/detail pages.
5. **P1 — Normalize overlays and menus.** Define dialog layout/dismiss requirements and icon/button/popover patterns. Preserve the onboarding modal's deliberate non-dismissible behavior.
6. **P2 — Reconcile navigation and public surfaces.** Address authenticated navigation density at intermediate widths; establish public CMS/quotation primitives that honour operator theme variables; decide the fate of the Laravel starter `Welcome.vue`.
7. **P2 — Visual regression and accessibility QA.** Test core public, agent, and admin pages at mobile/tablet/desktop widths; check focus visibility, labels, error announcements, modal focus management, table overflow, contrast, and tenant themes.

## Deliberately absent or not yet standardized

No radio buttons, tabs, breadcrumbs, skeletons, standardized spinners, common loading overlays, or a shared icon system were found.  These should be added only when a real product flow needs them; their absence is not itself a redesign mandate.