# Agency Module UI requirements

Read `docs/UI-DESIGN-STANDARD.md` before changing any page, tab, or component.
The approved visual reference is Training Haven and the Licensing Renewal workspace.
Before every future UI change, inspect the closest existing implemented layout and use it as the reference. Match its spacing, field arrangement, document metadata, button grouping/order/width, and status placement; do not invent a new arrangement for an existing workflow. Reuse its shared components/classes, then visually compare the result at desktop and narrow widths. Passing style checks alone does not establish visual consistency.
Use the root-loaded `app/globals.css` and `app/design-tokens.css` for all screens.
Reuse existing shared classes and installed UI primitives. Do not introduce page-specific
themes, literal colors, alternate fonts, oversized rounded fields, or per-page overrides
of shared controls. Put a needed reusable variant in the shared stylesheet.
Preserve red pending/incomplete and green completed states and visible status text.
Keep PDF/print typography scoped to document classes. Never replace the Training Haven
logo in the application shell with an agency logo. Generated agency forms, print
previews and PDFs must use only the uploaded agency logo via AgencyDocumentBranding
and addAgencyPdfLogo. With no agency logo, omit the image; never fall back to the
Training Haven logo. Preserve existing signed files and record data.
Run `npm run check:design`, `npx tsc --noEmit`, and `npm run build` after UI changes.
The style check enforces palette and stylesheet boundaries; review layout and responsive
behavior as well. Do not weaken the check to bypass a design inconsistency.

Before implementing DCS packet exports, read docs/DCS-PACKET-DOCUMENT-RULES.md. Superseded uploads must remain history-only; use the current-version selection gate.

<!-- BEGIN:nextjs-agent-rules -->

## This is NOT the Next.js you know

This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices.

This block is written and re-added by `next dev` — verify at `node_modules/next/dist/server/lib/generate-agent-files.js`. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.

<!-- END:nextjs-agent-rules -->

## Upload and action layout contract
All future upload, review, approval and signing UI must follow the September 25 pattern in docs/UI-DESIGN-STANDARD.md and docs/UPLOAD-ACTION-DESIGN-AUDIT.md. Use action-section, document-file-row, document-toolbar action-document-toolbar, details.document-review and actions action-footer. Keep functional handlers and permissions unchanged during visual changes. Use existing document controls and avoid duplicate previews. Verify desktop and narrow layouts and required validation states before completion.

## Training Haven developer handoff requirement
For every change to the mock Training Haven Users or Agencies tabs, or any connection involving TrainingHaven.com, read and update docs/TRAINING-HAVEN-INTEGRATION-HANDOFF.md in the same change. This includes additions, modifications, removals, labels, controls, permissions, data mappings and synchronization behavior. Explain the purpose and why the connection exists, the user action or event that triggers it, expected behavior, data ownership and direction, permissions, error/retry handling, and acceptance criteria. Identify affected code and clearly separate implemented Agency Management behavior from mock behavior and work still required in the separate Training Haven application. Keep the current contract accurate and append a dated change entry. Documentation is part of completion, not a deferred handoff task. Never imply that a mock connection is live.

## Shared Training Haven rule authority
When an observed Training Haven rule overlaps Agency Management behavior, match Agency Management to Training Haven's canonical rule. Record the source, current mismatch, intended mapping and validation in the integration handoff. Never override Training Haven with prototype defaults. If Training Haven pages disagree, flag the discrepancy for its developer and confirm the canonical value before changing behavior. A review/proposal task does not authorize live rule changes. Management-only requirements remain separately documented.

## Approved icon style
For every future Agency Module icon request, follow the October 1, 2026 approved icon-style section in `docs/UI-DESIGN-STANDARD.md` and inspect the reference assets in `public/avatars/`. This is the user's locked visual direction: Training Haven teal/aqua circular illustrations, inclusive human portraits, no stars on animal or human avatars, and existing gold/star accents retained on symbol avatars. Extend the approved family without redesigning it unless the user explicitly requests a change.
