# ADbotix — DESIGN SYSTEM

The single source of truth for visual design. Claude Code reads this before building any
view. The aesthetic is **refined-minimal fintech**: soft grey canvas, generous white
cards, one warm accent used sparingly, deep teal for dark surfaces, near-black teal-ink
text. Reference: see `adbotix-components.html` for the live, approved look — translate those
exact patterns into Yii2 + Tailwind partials.

> Build approach follows Anthropic's frontend-design skill: commit to ONE cohesive
> direction (this one), use CSS variables/Tailwind tokens for consistency, distinctive
> typography (NOT Inter/Roboto/Arial), dominant neutral canvas with a sharp single accent.

---

## 1. Aesthetic direction (locked)

- **Tone:** luxury/refined minimal — calm, trustworthy, money-grade. Restraint over decoration.
- **Differentiator:** the deep-teal dark "feature" card + a single warm-orange accent on an
  otherwise quiet neutral canvas. Accent appears on ~one element per card, never everywhere.
- **Feel:** soft rounded corners, airy spacing, light shadows, crisp data typography.

---

## 2. Color tokens (locked)

| Token | Hex | Use |
|---|---|---|
| `--primary` | `#e35728` | Accent: primary buttons, active states, key badges, 1 chart bar |
| `--primary-600` | `#c8461d` | Primary hover |
| `--primary-100` | `#fbe3d9` | Accent tint (soft badges, icon chips) |
| `--primary-50` | `#fdf1ec` | Focus ring |
| `--secondary` | `#034854` | Dark surfaces (feature card, wallet card), dark buttons |
| `--secondary-700` | `#023840` | Dark button hover |
| `--secondary-100` | `#d6e4e6` | Teal icon chips |
| `--ink` | `#002329` | All primary text + headings |
| `--ink-60` | `#4a6a70` | Secondary text |
| `--ink-40` | `#8aa3a8` | Faint text, placeholders, axis labels |
| `--canvas` | `#eef1f3` | App background |
| `--surface` | `#ffffff` | Cards |
| `--surface-2` | `#f5f7f8` | Inset rows, ghost buttons, hover |
| `--border` | `#e4e9eb` | Card & divider borders |
| `--border-strong` | `#d3dadd` | Input borders, outline buttons |
| `--pos` / `--pos-bg` | `#1f9d6b` / `#e6f5ee` | Positive deltas, completed |
| `--neg` / `--neg-bg` | `#d24b3c` / `#fbe9e6` | Negative deltas, errors |

**Accent discipline:** orange is a spice, not a base. One accent moment per card max.
Dark cards use teal; never a wall of orange.

Tailwind: define these in `tailwind.config.js` under `theme.extend.colors` (e.g.
`primary`, `secondary`, `ink`, `canvas`, `surface`, `pos`, `neg`) so classes read
`bg-primary`, `text-ink`, `bg-surface`, `border-border`.

---

## 3. Typography (locked)

- **Display / headings:** `Bricolage Grotesque` (600/700), tight tracking `-0.02em`.
- **Body / UI:** `Plus Jakarta Sans` (400/500/600/700).
- **Numbers/metrics:** display font, 700, tabular feel — big stat values, table amounts,
  card balances.
- Do NOT use Inter, Roboto, Arial, system fonts, or Space Grotesk.

Scale: page title 30px · card heading 19px · stat value 30–33px · body 14–15px ·
labels/caption 12–13px · uppercase tag 11px (letter-spacing .1em).

---

## 4. Shape, spacing, elevation

| Token | Value |
|---|---|
| Radius small (inputs, icon chips) | 10px |
| Radius medium (inner cards, credit card) | 16px |
| Radius large (cards) | 22px |
| Radius pill (buttons, badges) | 999px |
| Card padding | 22px |
| Grid gap | 20px |
| Shadow sm (rest) | `0 1px 2px rgba(0,35,41,.05)` |
| Shadow md (hover) | `0 6px 20px rgba(0,35,41,.06)` |

All cards: `bg-surface border border-border rounded-[22px]`, sm shadow at rest, md on hover.

---

## 5. Component inventory (build as Yii2 partials)

Build these once in `frontend/views/components/` and `backend/views/components/`, then
compose every page from them. Each is a thin PHP partial taking params.

| Partial | Params | Notes |
|---|---|---|
| `_stat_card` | label, value, icon, delta, deltaDir, foot | KPI card. Icon chip tinted primary/teal/pos. Delta as pill. |
| `_card` | title, headerRight (slot), body (slot) | Generic white card with head row. |
| `_card_dark` | title, body (slot) | Teal feature card; headings white. |
| `_pill` | text, variant (pos/neg/primary/soft) | Delta & label badges. |
| `_status` | text, variant (active/pending/locked) | Dot + label, used in tables. |
| `_btn` | text, variant (primary/dark/ghost/outline), size, icon, href | Pill button. |
| `_bar_chart` | labels[], values[], activeIndex | CSS bars; active bar = primary, rest hatched grey. |
| `_donut` | segments[{pct,color}], centerBig, centerSm | conic-gradient donut + legend. |
| `_progress` | pct, label | Used inside dark card (track translucent, fill primary). |
| `_table` | columns[], rows[], headerRight (slot) | Avatar+name cell, amount color by sign, status pill. |
| `_list_row` | icon, name, sub, value | Money-plan / active-plans rows. |
| `_credit_card` | balance, name, sub | Teal card w/ orange corner accent. |
| `_field` | label, name, type, placeholder, value | Form input; focus ring primary-50. |
| `_sidebar` | items[], active | Nav; active item = solid teal, white text. |
| `_topbar` | search, actions (slot), user | Search pill + icon buttons + user chip. |
| `_section_tag` | text | Small uppercase primary label between sections. |

**Reuse rule (from PROJECT_INSTRUCTIONS §8):** never inline a styled element that a partial
already covers. Pages = composition of partials only.

---

## 6. Patterns from the references (apply consistently)

- **Stat cards:** icon chip (tinted) + label on one row; big value; delta pill + caption foot.
- **Deltas:** always a pill — green `pill-pos` with up-arrow / red `pill-neg` with down-arrow.
- **Dark feature card:** one per dashboard, teal, used for the headline module (Global Pool);
  white text, a primary CTA button, optional progress bar.
- **Tables:** avatar initials chip + name + sub-id; amounts colored by sign; status pill;
  muted date; hover row tint `surface-2`; Sort/Filter as outline buttons in the head.
- **Donut:** conic-gradient, teal + primary + primary-100 segments, hollow center with metric.
- **Empty space is a feature** — keep cards airy; don't crowd.

---

## 7. Two builds, two CSS files

- One Tailwind build for `frontend` (public site + investor/leader panel), one for
  `backend` (admin). Same tokens in both `tailwind.config.js` files so the theme is identical.
- All images in `frontend/web/media/` (and backend reuses via URL). No inline SVG sprites
  scattered — keep icons as a small set of partials or an inline-svg helper.

---

## 8. Accessibility & polish

- Text contrast: ink on surface/canvas passes AA. Never put `ink-40` on white for body text.
- Focus states on every input/button (primary-50 ring).
- Hover transitions 120–180ms, subtle. One orchestrated page-load fade-in is fine; avoid
  scattered micro-animations.
- Touch targets ≥ 40px; buttons ≥ 44px tall on mobile.

---

## 9. Sources referenced (for Claude Code, not dependencies)

- **Anthropic frontend-design skill** (official) — install first; governs design discipline.
- **21st.dev** (MIT) — visual reference for table/card/input/modal Tailwind patterns; do NOT
  import React components, translate the patterns into Yii2 HTML partials.
- **shadcn admin templates** (MIT, e.g. `satnaing/shadcn-admin`) — reference for admin
  layout (sidebar, data table, KPI grid) only; re-express in plain Tailwind.

The approved visual target is `adbotix-components.html` in this repo. When in doubt, match it.