cleanup phase 1

.claude/skills/frontend-designer/SKILL.md

@@ -12,9 +12,22 @@ description: >-
 # Balinyaar Frontend Designer
 
 Build UI that looks like Balinyaar and behaves correctly in both locales and both
-color schemes on the first try. This skill is the design contract; the engineering
-contract (providers, fetch, cookies, routing) lives in [client/CLAUDE.md](../../../client/CLAUDE.md) — read it
-before touching layout/provider/data code, **don't restate it**, and never violate it.
+color schemes on the first try.
+
+**Precedence.** This skill is the **design** contract — brand, tone, and the visual
+decisions. The **engineering** contract is [client/CLAUDE.md](../../../client/CLAUDE.md)
+(hard rules) plus [docs/rules/client/](../../../docs/rules/client/) (one reference file
+per area). Where the two overlap — tokens, typography, the component library, shells,
+icons — **`docs/rules/client/` is authoritative and this skill defers to it.** Read the
+relevant one before touching layout, provider, or data code; don't restate it here, and
+never violate it.
+
+| For | Read |
+|-----|------|
+| Tokens, palette, dark mode, RTL, fonts, motion | [docs/rules/client/theme.md](../../../docs/rules/client/theme.md) |
+| The `App*` library, shells, navigation, icons | [docs/rules/client/components.md](../../../docs/rules/client/components.md) |
+| Copy and Persian orthography | [docs/rules/client/i18n.md](../../../docs/rules/client/i18n.md) |
+| Forms | [docs/rules/client/forms.md](../../../docs/rules/client/forms.md) |
 
 **Stack:** Next.js 16 (App Router, Turbopack) · React 19 · MUI v9 (`@mui/material`) ·
 Emotion (RTL via `stylis-plugin-rtl`) · next-intl v4 · notistack. Everything below
@@ -106,6 +119,16 @@ these; they're define-only in CSS):
 - **Money emphasis** — `--bal-money-emphasis`, an AA-contrast-safe color for emphasized
   money text. `--bal-secondary` (terracotta) fails AA contrast at small sizes on light
   backgrounds — never use it for money text, use this token instead.
+- **Soft fills** — every brand and semantic color has a `-soft` variant
+  (`--bal-primary-soft`, `--bal-warning-soft`, …) for a tinted background. Reach for it
+  before hand-mixing an alpha over a surface.
+- **Avatar** — `--bal-avatar-1..6` (+ each `-contrast`), the six warm pairs
+  `InitialsAvatar` picks from by a deterministic name hash. Add a seventh to **both**
+  scheme blocks or don't add one.
+- **Map** — `--bal-pin-shadow`, the address-picker pin.
+
+Full catalogue, with what each group backs:
+[docs/rules/client/theme.md](../../../docs/rules/client/theme.md) §2.
 
 ---
 
@@ -149,15 +172,23 @@ wrapper over the bare MUI component — the wrappers carry the house defaults.
 | `AppIconButton` | icon-only actions | takes an icon `name`, `title`, `to`/`onClick` |
 | `AppIcon` | any icon | `icon="home"` by registered name (§6); `size`, `color` props |
 | `AppLink` | internal/external links | locale-aware Next navigation; default underline `hover` |
-| `AppAlert` | inline alerts | default `severity="error"`, `variant="filled"` |
-| `AppImage` | images | wrapper around next/image conventions |
+| `AppAlert` | inline alerts | defaults to a calm `severity="info"`, `variant="standard"` — pass `severity="error"` explicitly when it really is an error |
 | `AppLoading` | loading state | default circular, `primary`, `3rem` |
 | `ErrorBoundary` | wrapping fault-prone subtrees | already wraps page content in the shell |
 | `ProfileSummary` | the identity card in chrome | avatar+name+masked phone+role label+optional `TrustBadge`; vertical or `compact` horizontal chip |
 
 Defaults for these live in `src/components/config.ts` (`APP_BUTTON_VARIANT`,
-`APP_ICON_SIZE = 24`, `CONTENT_MAX_WIDTH = 800`, `CONTENT_MIN_WIDTH = 320`, alert/link/
-loading defaults). Change a default there, not per-call-site.
+`APP_ICON_SIZE = 24`, `APP_ICON_STROKE_WIDTH = 1.75`, `APP_BUTTON_ICON_SIZE = 20`,
+`CONTENT_MAX_WIDTH = 480`, `CONTENT_MIN_WIDTH = 320`, alert/link/loading defaults).
+Change a default there, not per-call-site.
+
+Beyond the `App*` wrappers there is a **state kit** — `EmptyState`, `ErrorState`,
+`QueryStateGate`, `PageHeader`, `ConfirmDialog`, `SurfaceCard`, `AccentCard`, `Money`,
+`StatusTimeline`, the `Jalali*` date inputs, `StickyActionBar`, `Pager`, `NavHubList`,
+`InitialsAvatar`, `FormDialogShell` — with **one pattern per state**. Never hand-roll a
+dashed-border "nothing here" block or a per-screen pager; and **an error state is never an
+empty state.** Catalogue in
+[docs/rules/client/components.md](../../../docs/rules/client/components.md).
 
 For layout/spacing use MUI primitives directly: `Box`, `Stack`, `Container`, `Grid`,
 `Paper`, `Card`. Use the `spacing`/`sx` system (theme spacing unit = 8px) — never inline
@@ -166,7 +197,18 @@ pixel margins for rhythm.
 **New shared component?** Put it in `src/components/<Name>/<Name>.tsx` with an
 `index.tsx` barrel, follow the `App*` prop-spreading + JSDoc style of `AppButton.tsx`,
 and add a co-located `.test.tsx` (mandatory for anything imported in >1 place — see
-CLAUDE.md "Unit Testing"; wrap with `<ThemeProvider>`, never mock MUI).
+[docs/rules/client/testing.md](../../../docs/rules/client/testing.md); wrap with
+`<ThemeProvider>`, never mock MUI). If it goes at the top of the `@/components/common`
+barrel, prefer **caller-owned copy** (required `title`/`body`/`retryLabel` string props)
+over calling `useTranslations` inside it — `next-intl` is ESM-only and poisons every test
+that transitively imports the barrel. `ErrorBoundary`/`ErrorState` are the model;
+[components.md](../../../docs/rules/client/components.md) has the why.
+
+**Any form with more than one field is a react-hook-form form**, bound through the
+`@/components/common/form` wrappers (`RhfTextField`, `RhfChipSelect`,
+`RhfJalaliDateField`, `RhfControlGroup`) and grouped into `FormSection`s. A single-field
+control is state, not a form. Full pattern:
+[docs/rules/client/forms.md](../../../docs/rules/client/forms.md).
 
 ---
 
@@ -178,12 +220,19 @@ backdrop, at **every viewport**. A wider window gets more canvas, never a wider
 design one set of states, verify one set of states. Do not add a `≥md` branch that widens
 a shell, restores a sidebar, or lays a screen out in columns.
 
-- `AppFrame` owns three structural guarantees, and is the only place any of them is
-  solved: the width cap; the **frame, not the document, owns the scroll** (header /
-  `<main>` / footer are flex siblings, so a top bar is `position: static` and no page
-  needs a top offset); and `overflowX: hidden` + `minWidth: 0`, so an over-wide child
-  clips rather than dragging the app sideways. Genuinely wide content (a data table)
-  scrolls **inside its own container** — see `AdminDataTable`'s `TableContainer`.
+- `AppFrame` owns four structural guarantees, and is the only place any of them is
+  solved: the width cap; the **frame, not the document, owns the scroll** (a single
+  scrolling `<main>` fills the frame, with the bars pinned **`position: absolute`** over
+  it — never `fixed`, which would break out of the centered column — and `<main>`
+  reserving each bar's exact height as padding, so no page needs a top offset);
+  `overflowX: hidden` + `minWidth: 0`, so an over-wide child clips rather than dragging
+  the app sideways; and, above `sm`, the column **floats** as a rounded shadowed card
+  with a gutter all round (edge-to-edge on a phone). Genuinely wide content (a data
+  table) scrolls **inside its own container** — see `AdminDataTable`'s `TableContainer`.
+- `AppFrame` also publishes **`--bal-chrome-top` / `--bal-chrome-bottom`** on the scroll
+  container (already including `env(safe-area-inset-*)`, and `0px` in a chrome-free
+  shell), so any `position: sticky` element can clear the bars without importing a
+  constant. `StickyActionBar` is the reference consumer — don't recompute an offset.
 - **One authenticated shell**: `MobileShell` = `AppFrame` + a contextual `TopBar` (brand
   lockup on a tab's own path, back chevron + `useRouteTitle()` on anything deeper) +
   `BottomBar` + `ErrorBoundary` + `RouteFadeIn`. The four actor layouts (`CustomerLayout`
@@ -191,9 +240,17 @@ a shell, restores a sidebar, or lays a screen out in columns.
   only `tabs` and `headerActions`. Add a destination by adding a tab or a hub row — never
   by forking the shell.
 - **The chrome is light, not structural.** The top bar is *not* an `AppBar` — no filled
-  surface, no rule, no elevation; it sits on the page background. The bottom bar *floats*:
-  inset from the frame edges, fully rounded (`--bal-radius-pill`), elevated. Neither should
-  read as a slab sealing off an edge of a 480px screen.
+  surface, no rule, no elevation of its own; `AppFrame` wraps both bars in the shared
+  `FLOATING_BAR_SX`, so the header is the bottom bar mirrored: inset from the frame edges,
+  fully rounded (`--bal-radius-pill`), elevated. Neither should read as a slab sealing off
+  an edge of a 480px screen. The bottom bar is **icon-only** (at five tabs the caption was
+  the widest thing in it and cost a whole line — the label survives as `aria-label`/
+  `title`), each tab a fixed 44px circle laid out `space-around`.
+- **A stateful card carries its state in its content, not a stripe.** `AccentCard`'s
+  colored edge stripe was removed — a column of them read as a row of loose vertical rules
+  down the RTL edge of the screen. `tone` survives as the semantic label (reaching the DOM
+  as `data-accent-tone`); the `StatusChip`, icon and copy inside carry the state.
+  **Do not reintroduce the stripe.**
 - **Navigation is the bottom bar. There is no drawer.** Tabs are `LinkToPage` arrays
   (`@/utils`) built with `useTranslations('nav')`, 3–5 of them, and by convention the last
   is a settings/«بیشتر» hub. Active state comes from the shared `matchActivePath`
@@ -254,7 +311,7 @@ Icons also default to `flexShrink: 0` — an icon squashed by a flex sibling was
 layout bug this component kept quietly reintroducing on narrow rows.
 
 **Directional icons mirror automatically.** Icons authored for LTR that must flip under
-RTL (`back`, `chevron_start`, `chevron_end`) are registered in `AppIcon/config.ts`'s
+RTL (`back`, `chevron_start`, `chevron_end`, `forward`, `send`) are registered in `AppIcon/config.ts`'s
 `DIRECTIONAL_ICONS` set. `AppIcon` stamps `data-icon-directional` on those, and one CSS
 rule (`app/globals.css`) does
 `[dir='rtl'] [data-icon-directional] { transform: scaleX(-1); }`. Adding a new directional
@@ -284,11 +341,16 @@ Every screen/component you produce must satisfy **all** of these:
    switches automatically. Verify on both schemes — never assume a light background.
 4. **Tokens, not hexes.** No raw color literals in `sx`/`styled`/components (§2).
 5. **Constants, not magic values.** Cookie names, routes, repeated dimensions, event
-   names → named constants (CLAUDE.md "Constants").
+   names → named constants ([components.md](../../../docs/rules/client/components.md) §5).
 6. **Use the wrappers** (§4) and the **icon registry** (§6) before bare MUI.
 7. **Shared component ⇒ co-located test** (§4).
 8. **MUI v9 API only.** No v5/v6-era props (e.g. `Stack` `useFlexGap`, `storageWindow`).
    Avoid deprecated APIs that throw.
+9. **Persian copy follows the style guide** — «بالین‌یار» with a ZWNJ, تأیید with a hamza,
+   جستجو in one form, formal شما. `npm run lint:copy` fails the gate on a banned variant.
+   Glossary and the full rules: [i18n.md](../../../docs/rules/client/i18n.md) §4.
+10. **A screen never fabricates a figure.** A summary reads only off a query that already
+    answers it; a count still in flight is omitted, never faked or defaulted.
 
 ---
 
@@ -304,13 +366,15 @@ Every screen/component you produce must satisfy **all** of these:
 5. **Verify the four axes:** `/fa` (RTL) and `/en` (LTR) × light and dark. The default
    route is `/fa` — start there.
 6. **Tests** for any new shared component; **never** add a layout above `[locale]`
-   (breaks locale/dir — see CLAUDE.md).
-7. Data/fetch/auth/cookies/toasts → follow CLAUDE.md (`serverFetch`/`clientFetch`,
+   (breaks locale/dir — see [structure.md](../../../docs/rules/client/structure.md)).
+7. Data/fetch/auth/cookies/toasts → follow
+   [services.md](../../../docs/rules/client/services.md) and
+   [auth.md](../../../docs/rules/client/auth.md) (`serverFetch`/`clientFetch`,
    `@/lib/cookies/*`, `dispatchToast`/`useSnackbar`). Don't reinvent these.
 
 ---
 
-## 9. Anti-patterns (design-specific — CLAUDE.md has the full engineering list)
+## 9. Anti-patterns (design-specific — `docs/rules/client/` has the full engineering list)
 
 - Hard-coded hex/rgb in components → use palette keys or `--bal-*` tokens.
 - MUI default success/error colors for feedback → use `--bal-*` semantic tokens.
@@ -321,6 +385,14 @@ Every screen/component you produce must satisfy **all** of these:
 - Raw MUI icon where a registry name is expected → register it in `AppIcon/config.ts`.
 - New shared component without a `.test.tsx`, or mocking MUI in tests.
 - Re-introducing `src/app/layout.tsx` / any layout above `[locale]`.
+- A `≥md` branch that widens a shell, restores a sidebar, or goes multi-column → there is
+  one layout, and it is a phone (§5).
+- A numeric `sx={{ borderRadius: n }}` → it multiplies the shape unit; use the radius token.
+- `fontWeight: 600` → neither face loads it, so it silently renders full Bold. 700/500/400.
+- Reintroducing `AccentCard`'s edge stripe, a drawer, a top-bar theme/locale toggle, or a
+  caption under a bottom-nav icon → each was deliberately removed.
+- A hand-rolled empty/error/loading block, or a per-screen pager → use the state kit (§4).
+- A second `prefers-reduced-motion` branch → there is exactly one, in `globals.css`.
 
 ---
 
@@ -351,4 +423,6 @@ pushing code back into Figma.
 | Layout shells | `client/src/layout/` |
 | Layout dimensions | `client/src/layout/config.ts` |
 | Messages (i18n) | `client/messages/{en,fa}.json` |
-| Engineering contract | `client/CLAUDE.md` |
+| Persian copy lint | `client/scripts/check-copy.mjs` |
+| Engineering hard rules | `client/CLAUDE.md` |
+| Engineering reference (per area) | `docs/rules/client/` |