# Lovable — Notifications + UI States Kit (Micro-App)

Before you start: read and follow `DESIGN_SYSTEM_BRIEF.md`, `UX_TOKEN_CONTRACT.md`, `REPO_SCOPING_RULES.md`, and `ACCEPTANCE_CHECKLIST.md`.

## Goal

Build a **UI/UX-rich** Next.js micro-app that serves as a reusable **Notifications + UI States Kit** we can copy into:

- `dashboards/admin-web`
- `dashboards/tracker-web`
- product web dashboards

This is design-led: prioritize interaction polish, spacing, typography, and accessibility.

## Constraints

- Only modify files in this repository.
- pnpm only.
- Next.js 16 App Router, React 19, TypeScript strict.
- TailwindCSS v4.
- No network calls.
- No `console.log`.
- No hardcoded colors — use `--ux-*` CSS variables from `UX_TOKEN_CONTRACT.md`.
- Avoid unnecessary dependencies. If you add a dependency, justify why it is required.

## Must-have routes

- `/` overview landing + links
- `/toasts` toast system demos
- `/banners` inline banner demos
- `/states` loading / empty / error patterns
- `/dialogs` confirm dialog patterns
- `/forms` validation + helper text patterns

## App shell

- Left sidebar navigation
- Top bar with:
  - theme toggle (light/dark)
  - “Shortcuts” button

## Toast system (core deliverable)

Build a toast system that supports:

- Variants: info, success, warning, error
- Title + optional description
- Optional action button (e.g. Undo)
- Optional progress countdown bar
- Stacking / queue behavior (max visible, overflow count)
- Dismiss: close button, swipe (optional), timeout
- Position selector demo: top-right (default), bottom-right, bottom-center

Accessibility requirements:

- ARIA live region (`polite` for info/success, `assertive` for error)
- Focus behavior: toasts should not steal focus by default

## Banners

Create inline banners for page-level messaging:

- Variants: info/success/warn/error
- Optional “Retry” action
- Dismissible

## States gallery

Create reusable components:

- `Skeleton` primitives (text line, avatar, card)
- `EmptyState` with icon + title + description + CTA
- `ErrorState` with retry + “copy details” action (copies JSON)

Provide demos:

- Table loading skeleton
- Card grid loading skeleton
- Detail drawer loading skeleton

## Dialogs

- Confirm dialog (destructive)
- Confirm dialog (non-destructive)
- Modal focus trap + Esc close

## Forms

Create a small form with:

- Required fields + inline errors
- Disabled state
- Helper text
- Success state

## Visual / UX bar

- Premium spacing/typography
- Subtle animations (not flashy)
- Excellent focus rings (token-driven)
- Mobile responsive

## Deliverables

- Full Next.js app with scripts:
  - `dev`
  - `check` (must run `tsc --noEmit` + `eslint`)
  - `build` (must run `next build --webpack`)

## Verification

From repo root:

- `pnpm install`
- `pnpm run check`
- `pnpm run build`

## Output expectation

Open a PR that only changes files in this repo.