mdm-ordinis/DESIGN.md

# DESIGN.md — Ordinis Admin UI Design System

**Status:** v0 baseline (2026-05-14). Captured from observed patterns в
codebase after approval workflow saga (MR !179–!190). To be refined через
`/design-consultation` skill in a dedicated sprint.

**Goal:** Lock the implicit design system как source of truth для будущих
features (Phase 4 webhook approvals, notifications surfaces, MDM expansion).
Document invariants (tokens, primitives, semantic rules) — NOT specific
components.

---

## 1. Voice & Tone

- **Russian-first.** UI primary language ru-RU; en-US is parallel mirror.
  Every user-facing string registered in `src/i18n.ts`.
- **Operational, not aspirational.** Copy describes what user sees / does
  ("Очередь чистая", "Reject требует comment") — no marketing-speak.
- **Domain-precise.** Use exact role names (maker / reviewer / publisher)
  and operation codes (CREATE / UPDATE / CLOSE) — no generic "user".
- **Apologize on failure.** Empty states + error messages name what went
  wrong и what to do next ("Refresh page + retry", "Укажите причину").

---

## 2. Color Tokens

CSS variables defined в `src/styles.css`. Three themes: `default` (light
Anthropic warm), `nstart` (medium contrast brand), `dark` (Anthropic dark).

### Semantic roles

| Token | Light | Dark | Use |
|---|---|---|---|
| `--color-ink` | `#1a1714` | `#f0ece4` | Primary text |
| `--color-ink-2` | `#52483d` | `#c8c1b3` | Secondary text |
| `--color-mute` | `#8c8276` | `#8a8474` | Tertiary text / placeholders |
| `--color-bg` | `#faf9f5` | `#1c1a17` | App background |
| `--color-surface` | `#ffffff` | `#262421` | Card / panel surface |
| `--color-surface-2` | `#f5f3ec` | `#2e2b27` | Hover / nested surface |
| `--color-line` | `#e6e1d4` | `#3a3733` | Dividers / borders |
| `--color-line-2` | `#efeae0` | `#2d2a27` | Subtle dividers |
| `--color-accent` | `#b05a2e` | `#d97757` | Primary CTA / links |
| `--color-accent-bg` | accent @ 11% | accent @ 16% | Accent tint |
| `--color-on-accent` | `#ffffff` | `#1c1a17` | Text on accent |
| `--color-green` | `#4f7038` | `#4a7d4f` | Success / APPROVED |
| `--color-green-bg` | `#e4ead0` | `#dde9da` | Success tint |
| `--color-warn` | `#a8762a` | `#b97c2f` | Warning / CHANGES_REQUESTED |
| `--color-warn-bg` | `#f6e8bc` | `#fcecc7` | Warning tint |
| `--color-pink` | `#a64636` | `#b34d6a` | Danger / REJECTED |
| `--color-pink-bg` | `#f4d9cd` | `#f8d8de` | Danger tint |

### Rules

- **Never hard-code hex.** Use `bg-line`, `text-mute`, `border-accent` через
  Tailwind utilities mapped to these tokens.
- **Status colors are stable across themes.** `success` always green-family;
  `danger` always pink-family.
- **Tint backgrounds (`*-bg`) use 11-16% alpha** — for badge backgrounds
  and subtle highlights. Never tint at higher opacity (loses contrast).

---

## 3. Typography

### Font families

| Token | Stack | Use |
|---|---|---|
| `--font-sans` | `Inter, -apple-system, BlinkMacSystemFont, sans-serif` | Body, UI |
| `--font-mono` | `JetBrains Mono, SF Mono, monospace` | Code, UUIDs, business keys, versions |
| `--font-display` | `Tektur, Inter, sans-serif` | Caps headers, brand mark |

### Type scale (Tailwind utilities)

| Utility | Use |
|---|---|
| `text-title-md` | Section headings (Panel title) |
| `text-body` | Body copy |
| `text-cell` | Table cell, dense info |
| `text-cap` | Caps tracking-wide labels (column headers) — uses `--font-display` |
| `text-mono` | Code / monospaced |

### Rules

- **Mono для identity:** UUIDs (truncated `slice(0,8)…`), business keys,
  version strings (`v1.1.0`). Reads as "this is an exact identifier".
- **Display caps для column headers:** `text-cap text-mute font-display
  uppercase tracking-wider` — visual hierarchy через caps, not size.
- **`tabular-nums` для timestamp + count columns** — prevents jitter on
  refresh.
- **Never use system-ui / -apple-system as primary display font.** Inter
  is fallback only.

---

## 4. Spacing & Layout

### Base scale

Tailwind default 4px scale (`gap-1` = 4px, `gap-2` = 8px, `gap-3` = 12px,
`gap-4` = 16px). Avoid arbitrary spacing values (`mt-[13px]`) — use scale
or extend tokens.

### Layout primitives

- **Page chrome:** `<PageHeader title description>` for top of every route
- **Content area:** `space-y-4` (16px) between top-level sections
- **Panel:** `<Panel>` wraps tables / forms with `bg-surface border border-line`
- **Card:** `<Card>` для individual content blocks (`bg-surface-2`)
- **Drawer:** Right-side slide-in for detail views (review draft, schema
  draft, history)
- **Modal:** Centered overlay для destructive confirmations + create flows

### Drawer-vs-Modal rules

| Pattern | Use Drawer | Use Modal |
|---|---|---|
| Review existing entity | ✓ | |
| Read-only history | ✓ | |
| Diff side-by-side | ✓ (max-w-3xl) | |
| Create new entity | | ✓ |
| Destructive confirmation | | ✓ (size=sm) |
| Maker action requiring focus | | ✓ |

Drawer = "look at this thing, maybe act on it". Modal = "do this thing now,
then dismiss".

### Width caps

- Drawer: `max-w-md` (notifications), `max-w-xl` (schema draft), `max-w-3xl`
  (record review with diff panes)
- Modal: `size="sm"` (confirm), `"md"` (form), `"xl"` (JSON editor)
- Body copy: implicit via Panel padding; for description text apply
  `max-w-prose` если viewport wide

---

## 5. Component Primitives

Locations: `src/ui/components/*.tsx`. Re-exported via `@/ui`.

### Stable primitives (use freely)

- `<Button variant size>` — `primary | secondary | ghost | danger`, `sm | md | lg`
- `<Badge variant>` — `info | success | warning | danger | default | primary | outline`
- `<Panel>` — surface wrapper для table/form blocks
- `<Card>` — content block (lighter surface than Panel)
- `<Drawer isOpen onClose title side widthClassName>` — slide-in detail view
- `<Modal isOpen onClose title size>` — centered overlay
- `<Table TableHead TableRow TableHeaderCell TableBody TableCell>` — tabular data
- `<Tabs items value onValueChange>` — Radix-based tabs with badge slot
- `<EmptyState icon title description action>` — no-data fallback
- `<Alert variant title>` — banner with `info | success | warning | error`
- `<LoadingBlock size label>` — skeleton / spinner
- `<QueryErrorState error onRetry>` — generic 4xx/5xx state с retry
- `<UserCell uuid>` — resolves sub → display name (three-tier cache)
- `<TextInput TextArea Checkbox Select MultiSelect>` — form inputs

### Domain-specific (in `src/components/`)

- `<ReviewDrawer>` — record draft review (records tab + Мои tab)
- `<SchemaDraftDrawer>` — schema draft review (dict page + Мои tab redirect)
- `<DictionaryEditorDialog>` — schema-aware editor с approval flow
- `<MyDraftsPanel>` — Мои tab on /reviews
- `<NotificationsDrawer>` + `<NotificationsBell>` — TODO 7 notification surfaces
- `<ChangelogDiffModal>` — historical schema diff viewer
- `<TimeTravelModal>` — record at point-in-time

---

## 6. Badge Variant Mapping

Visual category по semantic role, applied везде через `<Badge variant=…>`:

### Operations (DraftOperation)

| Op | Variant | Color | Reason |
|---|---|---|---|
| CREATE | success | green | Net-new record — positive change |
| UPDATE | info | accent | Most common; neutral default |
| CLOSE | warning | warn | Soft-delete; destructive but reversible |

### Record draft status (DraftStatus)

| Status | Variant | Reason |
|---|---|---|
| PENDING | info | Awaiting reviewer action |
| APPROVED | success | Terminal positive |
| REJECTED | danger | Terminal negative |
| WITHDRAWN | default | Maker-initiated cancel, neutral |

### Schema draft status (SchemaDraftStatus)

| Status | Variant | Reason |
|---|---|---|
| draft | warning | Pre-submit, maker action pending |
| review_pending | info | Reviewer queue |
| approved | success | Awaiting publish |
| changes_requested | warning | Bounced to maker |
| rejected | danger | Terminal negative |
| published | primary | Terminal live (strongest signal) |
| withdrawn | default | Maker cancel |

### Notification event type

| Pattern in eventType | Variant |
|---|---|
| `*Approved`, `*Published` | success |
| `*Rejected`, `*Withdrawn` | danger |
| `*Submitted`, `*ChangesRequested` | info |
| other | default |

---

## 7. Code / Diff Visual Language

### Live vs proposed panes

- **Live (current state):** `bg-line/30` background — muted, "established"
- **Proposed (draft):** `bg-accent/4` background — accent-tinted, "your suggestion"
- **CLOSE op note:** `text-aurora italic` — call-out пустой proposed pane

### Diff summary chips (above panes)

- `+N added`: text-aurora (green-family) with `+` prefix
- `−M removed`: text-danger with `−` prefix
- `~K changed`: text-warn with `~` prefix
- Bucket details в `text-mute lowercase` parens

Rendered via `shallowDiffSummary()` from `src/lib/diff.ts`.

---

## 8. Interaction States

### Required for all interactive elements

- `hover:bg-line/30` или similar hover affordance
- `focus-visible:ring-2 focus-visible:ring-ring` focus ring (NEVER
  `outline: none` без replacement)
- `disabled:opacity-50 disabled:cursor-not-allowed` для disabled
- Touch target ≥ 44×44 — use `min-h-[44px]` for icon buttons (current gap;
  audit findings P1 in TODOS.md TODO 6)

### Success / error affordances

- **Mutation success:** прокачка через `toast.success()` (sonner) — auto-dismiss 4s
- **Mutation error:** `toast.error()` с structured message via
  `extractReviewError()` / `humanizeBulkReason()` mappings
- **In-form validation:** inline error under input с `role="alert"` +
  `aria-invalid` + `aria-describedby`
- **Approve/reject decision flash:** 600ms bg-green-bg/30 или bg-pink-bg/30
  band на drawer footer перед `onClose()` — ack ack для reviewer

### Empty states (warmth required)

Every `<EmptyState>` MUST have:
- `icon` — phosphor duotone, size 28-32
- `title` — outcome-framed ("Очередь пуста", not "No results")
- `description` — actionable hint (what to do next, where data appears)
- `action` (optional) — Link / Button to relevant route

---

## 9. Term Glossary (canonical)

| Code | EN | RU | Definition |
|---|---|---|---|
| maker | maker | автор | User who creates / submits a draft |
| reviewer | reviewer | ревьюер | User who approves / rejects drafts |
| publisher | publisher | публикатор | User who publishes approved schema drafts |
| draft | draft | черновик | Pending change awaiting approval |
| pending | pending | на ревью | Status: awaiting reviewer decision |
| approved | approved | одобрено | Status: reviewer approved (record published OR schema awaits publish) |
| rejected | rejected | отклонён | Status: reviewer rejected (terminal) |
| withdrawn | withdrawn | отозван | Status: maker cancelled (terminal) |
| WIP | in progress | в работе | Schema draft pre-submit OR changes_requested |
| decided | decided | закрыты | Any terminal status — APPROVED + REJECTED + WITHDRAWN |
| changes requested | changes requested | запрошены правки | Reviewer bounced schema draft back to maker |
| published | published | опубликован | Schema draft → live (terminal positive) |

Source: backend domain types (DraftStatus, SchemaDraftStatus, DraftOperation).
NEVER use synonyms ("submitter" for maker, "validator" for reviewer) —
breaks consistency with audit log + RBAC roles.

---

## 10. RBAC & Role Visibility

Backend gates (single source of truth). Frontend hide UI elements when
roles missing — backend still enforces if frontend leaks.

| Composite role | Members | UI surface |
|---|---|---|
| `ordinis:reviewer` | `schema:reviewer` + `record:reviewer` | /reviews tabs (Records, Schemas) — approve/reject buttons |
| (maker is implicit) | any authenticated user | /reviews Мои tab, draft create modals, dict editor |

Identity check pattern (in components):
```ts
const auth = useAuth()
const currentSub = auth.user?.profile?.sub
const isMine = draft.makerId === currentSub
```

For role gating use `usePermissions()` (src/auth/usePermissions.ts).

---

## 11. AI Slop Anti-Patterns (banned)

Per /design-review gstack skill plus our own observations:

- ❌ Purple/violet/indigo gradient backgrounds
- ❌ 3-column feature grid with icon-in-circle headers
- ❌ Decorative blobs / wavy SVG dividers / floating circles
- ❌ Emoji as design elements (rocket in heading)
- ❌ Colored left-border-only cards
- ❌ Generic hero copy ("Welcome to Ordinis", "Unlock the power…")
- ❌ Bubbly uniform `rounded-full` on every element
- ❌ Centered everything (`text-align: center` on all body content)
- ❌ system-ui / -apple-system as PRIMARY display font

Pass test: every visual element should be there because it does a job, not
because empty space looks empty.

---

## 12. Open Items (gaps to address in /design-consultation sprint)

- Responsive breakpoint policy (mobile 375, tablet 768, desktop 1024,
  wide 1440 — confirm + lint)
- Touch target enforcement (P1 in TODO 6 a11y findings)
- Loading state taxonomy (skeleton vs spinner vs LoadingBlock vs Suspense
  — when to use which)
- Motion duration policy (currently ad-hoc — set 150ms quick / 300ms medium
  / 500ms entrance)
- Long-content overflow rules (truncate vs wrap vs ellipsis vs scroll —
  per surface type)
- Dark mode parity audit (some tokens have alpha inconsistency between
  themes)
- Notifications channel UI policy (in-app vs email vs both — currently
  every event goes to all enabled channels; should be user-configurable)

---

## Changelog

- **2026-05-14 v0** — Initial document. Captured tokens, components, badge
  semantics, term glossary, drawer-vs-modal rules from approval workflow
  saga codebase. Marked open items для full `/design-consultation`
  sprint. Authored as part of TODO 5 closeout.