# Vellum Design System

> A WhatsApp-first inbound paperwork and client-communication layer for Canadian accountants, immigration consultants, and lawyers who primarily serve Indian-origin clients.

**Vellum** sits alongside (not replacing) the firm's existing practice-management system. Mainstream Canadian PMS tools (TaxDome, Karbon, Clio) are email-first and assume Anglo-Canadian client behaviour; Indian-built tools understand the client mindset but are built for Indian compliance. Vellum is the layer in the middle.

---

## The brand in one paragraph

*Calm. Considered.* Library-quiet rather than bank-loud. The wordmark is set in Newsreader italic on a hairline masthead rule that terminates in a single 3px printer's mark — closer to a publication than a tech logo. The product is on screen for many hours a day, so the canvas is cream (`#F4EFE6`), not white. Primary is **ink blue `#1F2D4A`**; the lone accent is **burnished copper `#A85A2F`**, reserved for status and the most important actions. Display in **Newsreader**; body in **IBM Plex Sans**; Indic scripts in **IBM Plex Sans Devanagari** (Hindi) and **Noto Sans** (Gurmukhi, Gujarati). Tabular numerals everywhere by default.

---

## Index

| File | Purpose |
| --- | --- |
| `README.md` | This file — context, content fundamentals, visual foundations, iconography. |
| `SKILL.md` | Skill manifest. Read this first when invoked as a skill. |
| `colors_and_type.css` | All design tokens on `:root` — palette, type, spacing, radii, shadows, motion. Link this from any HTML you build and the rest cascades. |
| `assets/` | Vellum wordmark SVG, WhatsApp glyph. |
| `fonts/` | (Empty — all fonts loaded via Google Fonts CDN. See "Fonts" below.) |
| `preview/` | Cards consumed by the Design System tab. |
| `ui_kits/agent-web/` | Agent web-app screens: Unified Inbox (`index.html`), Family Record, Document Review Queue, File / Matter view, Assignment view, Audit Trail. |
| `ui_kits/agent-mobile/` | Agent mobile companion — 5 screens (triage, doc approve, reassign, quick reply, push). |
| `ui_kits/client-views/` | Three client-side web views linked from WhatsApp: e-sign, invoice, status summary. |
| `ui_kits/whatsapp-templates/` | WhatsApp Business API message templates — phone preview + catalog of 7 approved templates (EN / Punjabi / Hindi / Gujarati). |

---

## Sources & references

Created from a written design brief — no codebase, Figma, or existing assets were attached. The brief specified:

- **Product** — sits alongside existing PMS tools. Inbound layer only. Two users: the agent (web + mobile companion) and the end client (WhatsApp + lightweight web views for sign/pay/status).
- **Visual references to draw from** — Linear, Stripe Dashboard, Notion, Things 3, WhatsApp, early Monzo.
- **References to avoid** — Anglo-Canadian institutional tax software (TaxDome, Karbon, Clio), Indian SaaS aesthetic (Zoho, Razorpay, Khatabook), Silicon Valley fintech, overt Indian visual motifs (rangoli, paisley, marigold), AI-brand tropes (sparkles, gradient text, holographic accents).
- **Typography requirements** — must support Latin, Gurmukhi, Devanagari, Gujarati at design quality. Tabular numerals by default. A serif must appear somewhere in the system.
- **Color requirements** — neutral foundation (off-white, warm grey, or soft cream — never pure white). One confident primary, not navy or fintech purple. One accent for status/action.
- **Tone** — Trusted, Calm, Capable, Familiar, Quietly modern. **Not** playful, disruptive, bold, edgy, or friendly-in-a-Duolingo-way.

Three brand directions were explored in the first pass (Kin, Vellum, Hearth). **Vellum** was selected and the other two have been removed.

---

## Content fundamentals

The product speaks across **three distinct surfaces**, each with its own register. This is one of the most important things to get right — the same words feel wrong if moved from one surface to another.

### Agent UI (web + mobile companion)
**Terse, accurate, no marketing tone.** This is professional software for people doing serious work; they don't want to read.

- Buttons are verbs: `Assign`, `Approve`, `Reroute`, `Mark reviewed`. **Not** "Let's assign this!" or "Approve →".
- Empty states are matter-of-fact: `No documents awaiting review.` **Not** "All caught up! 🎉".
- Status labels are nouns or short adjectives: `Awaiting client`, `In review`, `Filed`. **Not** "Hey, this is waiting on your client!".
- Time is exact and short: `2 min ago`, `Yesterday 4:18 pm`, `Fri 12 Oct`. **Never** "a few moments ago".
- Address the agent in second person where needed (`Reassign to you?`), but most labels are headless. The agent does not need to be greeted.
- Never use emoji in agent UI. Document-type tags use neutral type+color glyphs (see Iconography).

### Client WhatsApp messages
**Warm, respectful, addressed by name, never robotic.** Should sound like a competent human assistant at the firm wrote them.

- Always address the client by their preferred name. `Hello, Mrs. Brar` — never `Dear Customer`.
- Use of *ji* / *aunty* / *uncle* is firm-configurable per client (older clients often expect *ji*, younger don't). Default templates are neutrally respectful.
- Stick to the *aap* register in Hindi/Punjabi/Gujarati — never *tu*/*tum*. Slightly formal, respectful of age.
- Confirm receipt explicitly: `Got it — your Form 16. Manpreet will look at this and reply by Monday evening.` Names the next human, names the timeframe.
- No emoji. No exclamation points except in rare welcome messages. No "Cheers!", "Take care!", or other casual sign-offs — sign with the firm name or the agent's first name.

### Client web views (linked from WhatsApp)
**As few words as possible. One job per page. Read at arm's length on an older phone.**

- Page headline is the job: `Sign return — 2025 tax year`. Subhead is the person whose name is on it: `For Surinder Singh Brar`.
- One primary action button, full-width, ≥56px tall, ≥20px label.
- No navigation. No footer. No "Related links". The user came from a single WhatsApp link to do a single thing and return to WhatsApp.
- Receipts and confirmations are equally minimal: `Signed. Manpreet has been notified.` Plus a single button: `Return to WhatsApp`.

### Localization tone
When the same template ships in Punjabi/Hindi/Gujarati, the **register** must match — slightly formal, respectful of age, never overly casual. Numbers, dates, and money always render in the script the rest of the message is in (Indic numerals optional per client preference; default is Western numerals because they appear on the CRA forms the agent is referencing).

### What we don't do
- No "Hi 👋" or any greeting emoji.
- No motivational copy. The product is not a coach.
- No urgency engineering ("Only 2 days left!"). Deadlines are stated; the urgency is the user's to decide.
- No exclamation points in confirmations. `Filed.` is more confident than `Filed!`.
- No AI mentions in the UI surface. "AI suggested" never appears as label text — the agent sees a confidence indicator (•••) and approves or corrects. The model is a tool, not a personality.

---

## Visual foundations

### Palette

| Token | Hex | Use |
| --- | --- | --- |
| `--primary` | `#1F2D4A` (Ink blue) | Headers, primary buttons, active-row accent, lead-agent pill |
| `--primary-soft` | `#E0E3EA` | Active row backgrounds, tinted surfaces |
| `--accent` | `#A85A2F` (Burnished copper) | Status only — never UI navigation. Variables highlighted in templates, deadline pills, key dates |
| `--canvas` | `#F4EFE6` (Cream) | Page background. **Never pure white** — the product is on screen for many hours a day |
| `--canvas-2` | `#FBF7EE` | Card surface, one step lighter than canvas |
| `--canvas-sunk` | `#EAE4D7` | Sunk areas — sunk row strips, side rail |
| `--fg-1` | `#1A1714` | Primary text |
| `--fg-2` | `#5A544A` | Secondary text, icons default |
| `--fg-3` | `#87806F` | Tertiary text, timestamps |
| `--border` | `#DCD3BF` | Hairline borders |
| `--doc-ca-bg` / `--doc-ca-fg` | `#DDE3D5` / `#2D4934` | Canadian document tags (T4, NOA, T1135) |
| `--doc-in-bg` / `--doc-in-fg` | `#EFD8C6` / `#6E3B1C` | Indian document tags (Form 16, PAN, NRE, FEMA) |

Plus a full semantic set: `--success / --warning / --error / --info`, each paired with a `*-soft` background variant. See `colors_and_type.css`.

### Typography

| Family | Use |
| --- | --- |
| Newsreader | Display — headings, the wordmark (italic), section titles. Optical size 60. |
| IBM Plex Sans | Body — UI labels, rows, paragraph text. |
| IBM Plex Sans Devanagari | Body — Hindi |
| Noto Sans Gurmukhi | Body — Punjabi |
| Noto Sans Gujarati | Body — Gujarati |
| ui-monospace (system) | Document codes, hashes, IDs — `T1135`, `pmh_doc_received_v3`, `4f7b·d2e1` |

**Indic line-height is `1.65`** (vs `1.5` for Latin) so the head-marks (शिरोरेखा / sirorekha) get breathing room.

### Structural decisions

| Aspect | Decision |
| --- | --- |
| **Background** | Never pure white. `--canvas` is `#F4EFE6`. |
| **Density** | High but not crammed — Linear-like. Inbox row height ~52px desktop / 64px mobile. |
| **Corner radii** | `4px` for inputs, buttons, tags. `6px` for chips. `8px` for cards. `12px` for modals. Never fully pill. |
| **Borders** | Hairline `1px` at `--border`. Borders carry structure; shadows are for elevation only. |
| **Shadow** | Three levels: `--shadow-1` (cards), `--shadow-2` (popovers), `--shadow-3` (modals). Warm-toned, never blue. No inner shadows on inputs. |
| **Cards** | 1px border + `--shadow-1`. Background `--canvas-2`, one step lighter than canvas. |
| **Spacing scale** | 4px base — `2, 4, 6, 8, 12, 16, 20, 24, 32, 40, 56, 80`. Agent surface uses the tight end; client web views use 16/24/32. |
| **Layout — agent** | Three-pane: 240px nav rail · 360px list · flex right detail. Top bar 48px. |
| **Layout — client web view** | Single column, max-width 480px, generous vertical rhythm. Primary action bottom-fixed on mobile. |
| **Transparency / blur** | Reserved for the command-bar overlay and the "scroll under sticky header" gradient. Not decorative. |
| **Gradients** | None on surfaces. The only gradient is a single 16px "fade under sticky header" protection gradient. |
| **Imagery** | Minimal. No stock photography. Document thumbnails are rendered from the actual client document; avatars are initials in a neutral chip. |
| **Animation** | Quiet. 120ms ease-out for state changes (button press, panel open). 240ms for sheet entry. No spring physics, no bounces. |
| **Hover** | Foreground 4% darker on neutral surfaces; primary buttons shift to `--primary-700`. No scale, no glow. |
| **Press** | Color step darker still, no scale change. Active state for nav rows is a 2px left accent in `--primary`. |
| **Focus ring** | 2px ring at `--primary` with 2px offset. Visible on keyboard only (`:focus-visible`). |
| **Tabular numerals** | Default everywhere. `font-variant-numeric: tabular-nums lining-nums` on the root. |

### Visual motifs we will not use
- Rangoli, paisley, marigold, mandala backgrounds. Devanagari letters used decoratively in English UI.
- Navy + grey "Anglo-Canadian institutional" surfaces. Saturated purple + orange "Indian SaaS" surfaces.
- Gradient text on the word "AI". Sparkle icons. Particle effects. Holographic chrome.
- Glassmorphism on agent surfaces. Skeuomorphic shadows. Inner shadows on inputs.
- The Inter typeface (overused in the category). Stock Roboto/Arial/system sans.

---

## Iconography

**Approach: a hand-curated set of ~40 glyphs, drawn from Lucide, at a single stroke weight, in a single style.** The brief warns against AI-brand tropes, and a sparkle-laden generic icon set is exactly that — so we use a single restrained set across the whole product.

### What we ship
- **UI glyphs** — sourced from **Lucide** (CDN, MIT licensed). 1.5px stroke at 20px size, 1.25px at 16px. Used for nav, action buttons, file types, status. Lucide chosen over Heroicons because its proportions are slightly more editorial and it has the right glyphs for our needs (`paperclip`, `mic`, `phone`, `file-text`, `users`, `inbox`, `archive`, `flag`, `calendar`, `circle-check`, `circle-alert`). **Flag: Lucide is a substitution** — if you have a preferred icon set we'll swap.
- **Document-type tags** — **custom typographic tags**, not pictographic icons. A T4 is a small mono-set label `T4` in a 1px-bordered chip; a Form 16 is `Form 16`; a PAN card is `PAN`. This solves the hybrid Canadian + Indian document problem cleanly: no contrived flag icons, no clash of visual styles. Color carries Canadian (green tint) vs Indian (copper tint) at a glance, without flag chauvinism.
- **Wordmark** — see `assets/wordmark-vellum.svg`. Newsreader italic, hairline rule beneath terminating in a 3px printer's-mark dot.
- **WhatsApp glyph** — official Meta-distributed mark, used only on client-facing buttons (`Reply on WhatsApp`).

### What we don't use
- **Emoji** anywhere in the agent UI. Only on the client side, **and only when explicitly authored into a WhatsApp template by the firm** (e.g. a 🪔 in a Diwali greeting template the firm chose to use — the product itself never adds emoji).
- **Flag icons** for languages or document origin. We use the text label instead (`EN`, `ਪੰਜਾਬੀ`, `हिन्दी`, `ગુજરાતી`) to avoid the brittleness of national-flag iconography in a product for diaspora users.
- **Sparkles / AI glyphs.** The model's confidence is shown as three-dot dim indicators, not a sparkle.
- **PNG icons.** Everything is vector.

### Stroke and sizing rules
- Default UI icon size: `20px`. Inline-with-text size: `16px`. Toolbar-large: `24px`.
- All icons render at `--fg-2` color by default — not the primary — so they don't compete with content. Active state lifts to `--fg-1`.
- The copper accent is reserved for **status icons only** — never UI navigation.

---

## Fonts

All fonts loaded via Google Fonts CDN. No `fonts/` payload required.

| Family | Use | License |
| --- | --- | --- |
| Newsreader | Display, wordmark | SIL OFL |
| IBM Plex Sans | Body, Latin | SIL OFL |
| IBM Plex Sans Devanagari | Body, Hindi | SIL OFL |
| Noto Sans Gurmukhi | Body, Punjabi | SIL OFL |
| Noto Sans Gujarati | Body, Gujarati | SIL OFL |

**Flag for upgrade:** the original brief mentioned Söhne and the Indian Type Foundry as possible paid alternatives. The Google Fonts choices above are production-acceptable in their own right (IBM Plex's Devanagari is excellent), but if budget exists for ITF, *Tasa Orbiter* or *Eczar* for the serif and one of their multi-script families for the body would be a meaningful upgrade.

---

## Caveats

1. **No source materials provided.** No codebase, Figma, screenshots, or existing brand assets were attached. All visuals are originated from the written brief alone.
2. **Iconography is Lucide for now.** Happy to swap for a hand-drawn set or a different open library.
3. **Wordmark is set in Newsreader italic with a hand-added rule + dot — not hand-drawn.** A real wordmark engineering session (custom letterforms, manual kerning, ligature design) is a separate exercise.
4. **Indic-script samples in the mockups** use real translations of the labels shown — checked against standard practice but worth a native-speaker pass before any of this ships.