docs: foundational specs (PRD, architecture, design system, database, security, code style, testing) + AGENTS operational rulebook

DESIGN_SYSTEM.md

@@ -0,0 +1,74 @@
+# DESIGN_SYSTEM — anwarpy.ai
+
+> Canonical tokens live in `web/src/app/design.css`. This file documents them and the rules for using them. If CSS and this file disagree, fix one of them in the same PR.
+
+## 1. Design personality
+
+Editorial, calm, premium-dark. Ink surfaces, champagne accents, generous whitespace, Arabic-first typography. Restraint is the brand: one accent color, used sparingly; motion is short and soft; nothing blinks, nothing bounces.
+
+## 2. Color tokens
+
+| Token | Value | Role |
+|---|---|---|
+| `--ink` | `#131519` | page background (`--bg`) |
+| `--ink-2` | `#17191d` | raised background |
+| `--basalt` | `#1c1f24` | card/surface (`--surface`) |
+| `--seam` | `#2b2f36` | hairline borders (`--border`) |
+| `--seam-2` | `#3a3f47` | hover border, stronger seam |
+| `--mist` | `#ece9e3` | primary text (`--fg`) |
+| `--stone` | `#a3a09a` | muted text (`--muted`) |
+| `--dim` | `#7b7974` | faintest text (meta only) |
+| `--champagne` | `#d4b47c` | THE accent (`--accent`) — badges, CTAs, highlights |
+| `--champagne-ink` | `#1a150c` | text/icons on champagne (`--accent-ink`) |
+
+Rules:
+- Never introduce a new hue. Semantic aliases (`--bg`, `--surface`, `--fg`, `--muted`, `--border`, `--accent`) are the only tokens components may use — raw hex is for `design.css` only.
+- Champagne on ink or champagne-ink on champagne. Never champagne text on basalt for body copy (contrast), never stone below 14px.
+- Success/warning/error states (form errors, honest 503s) use `--mist`/`--stone` + wording first; reserve red only where the CSS already defines it. Do not invent traffic-light colors.
+
+## 3. Typography
+
+- **Readex Pro** (Arabic + Latin, single family), loaded in `layout.tsx` via `next/font/google`, weights 300–700. `--font-display: var(--font-sans), "Segoe UI", sans-serif`.
+- Scale: hero H1 ~2.5rem/700; section H2 ~1.5rem/600; body 1rem/400 with line-height ≥1.8 for Arabic; meta/captions 0.875rem `--stone`.
+- Arabic-first: `direction: rtl` at the page root; Arabic quotes «»; numerals via `formatNumber` (Arabic-Indic where the site does).
+- **LTR islands** inside RTL text use `<bdi dir="ltr">`: `anwarpy.ai`, `$10`, code, identifiers, agent names (GPTBot…). Never let a raw Latin token break RTL flow.
+- No `<br>` for spacing; use margins. No font-size below 0.75rem.
+
+## 4. Spacing & shape
+
+- Space scale: 4 / 8 / 12 / 16 / 24 / 32 / 48 / 64px. Section padding 48–64px; card padding 16–24px; page max-width container per existing layout (centered, ≥24px gutters).
+- Radii: cards/pills 8–12px; badges/buttons pill (999px) where the existing CSS does; inputs match buttons.
+- Borders: 1px `--seam` everywhere; hover → `--seam-2`. No heavy shadows; elevation = `--ink-2`/`--basalt` layering, not blur.
+
+## 5. Component inventory (build from these, extend the list, never fork it)
+
+Existing, in `src/components/` + route CSS: `topnav.tsx`, `site-menu.tsx`, `nav-links.tsx`, `footer.tsx`, `anwarpi-background.tsx`, `set-body-attr.tsx`.
+
+Recurring patterns (CSS classes are the contract):
+- **Buttons**: `.btn`, `.btn.btn-primary` (champagne bg, `--accent-ink` text), disabled/coming-soon state = «قريباً» pill, wired to `subscribe-button.tsx comingSoon` prop. Disabled buttons are visually disabled from first paint and explain why in Arabic.
+- **Badges/pills**: access badge «مجاني» / «للأعضاء»; content-type badge (note/tutorial/case_study/comparison); «وصول مبكر مجاني» champagne strip.
+- **Notice strip**: the early-access notice on articles — champagne-tinted band, verbatim copy from PRD §3.2, never a modal.
+- **Guide card**: surface card, dek line, meta row (category · reading minutes · «حُدّث»), champagne hover seam. Topic hubs and «ابدأ من هنا» reuse it.
+- **Article body**: headings, paragraphs, lists, blockquote, code (LTR island, scrollable), **real `<table>`** for tabular data (never screenshot/ASCII), links `--champagne` underline.
+- **Forms**: label above input, input bg `--ink-2`, border `--seam`, error text = the API's Arabic sentence verbatim, loading state disables + keeps label, success replaces form state («تم! سنراسلك عند تفعيل العضوية.»).
+- **Tables renderer**: for Lexical table nodes — mobile-safe overflow wrapper.
+
+New components: reuse an existing class first, then extend `design.css` (or the route's CSS) — do not add a component library (no shadcn/radui/MUI) and no Tailwind (decision, 2026-10-11).
+
+## 6. Motion
+
+- Durations 150–250ms, ease-out. Hover: border color + 1–2px translate. Entrances: fade/rise ≤8px.
+- No parallax, no infinite loops, no scroll-hijack. Reduced-motion: honor `prefers-reduced-motion` for any added animation.
+- Micro-interactions (like button) may pulse once on success — once, not looping.
+
+## 7. Accessibility floor (enforced by `npx hyperframes check` on the brag video; treat as the site bar too)
+
+- Contrast: body text ≥ 4.5:1, large text ≥ 3:1 (`--stone` on `--basalt` passes; `--dim` only ≥1.5rem or decorative).
+- Focus visible: 2px `--champagne` outline on interactive elements.
+- Every image has meaningful Arabic `alt` (covers: the guide title); icon buttons have `aria-label`.
+- Landmarks: header/nav/main/footer; one H1 per page; heading order never skips.
+- Forms: `<label for>`, `aria-live="polite"` status regions (existing pattern: `#notify-done`).
+
+## 8. Cover images
+
+Generated via `npm run covers` (`scripts/generate-covers.mjs`) — 1200×630, ink/champagne system, Arabic title shaping checked. og:image dimensions are asserted in tests/evidence (1200×630). Don't hand-drop covers of other sizes.