# Gurbani Soul — Brand Book
The Gurbani Soul brand: the gold rule, palette, typography, mark, components, voice, accessibility and the gates before shipping.
- Page:
- Updated: 2026-10-26
- From the Sri Guru Granth Sahib Ji — Knowledge Base wiki. Sri Guru Granth Sahib Ji is quoted verbatim, cited by Ang, and never altered.
---
Status: **adopted** — G1 passed 2026-09-18; phase 2 shipped to `integration` (PRs #28–#31). G3 and G4 were closed on 2026-09-26 for the first App Store submission (1.3.10, see the gates in §12). Scope: the iOS app, its widgets, icon and share card.
The Knowledge Base website is a separate scholarly property and keeps its own name and theme.
Companion files: [`tokens.json`](https://github.com/Algorythmos-AI/sggs-platform/blob/integration/docs/brand/tokens.json) (source of truth) · [`contrast-report.md`](https://docs.gurbanisoul.com/brand/contrast-report/)
(generated by `scripts/brand/contrast_report.py`; every ratio quoted here comes from it).
---
## 1. Brand idea
**Gurbani Soul is a quiet, exact companion to Sri Guru Granth Sahib Ji.** Verbatim, cited by Ang, never invented.
| Layer | Name | Role |
|---|---|---|
| Product | **Gurbani Soul** | What people download and open |
| Endorser | **Built by Algorythmos** | Credit line only (About, store listing) |
| The text | **Sri Guru Granth Sahib Ji · Ang N** | Never branded, never abbreviated, never styled as a product |
Personality: reverent · exact · warm · unhurried · plain-spoken.
Colour story: **gold leads** — the gold of Harmandir Sahib and of basanti — on warm paper and warm ink.
**Red is a rare accent.** Gurmukhi is always set in ink, never in a brand colour.
## 2. Where the palette comes from, and what we leave behind
The palette values are taken from a McDonald's brand kit held locally as reference (`Brand-files/`, git-ignored).
**We take:** the hex values; an 8-pt spacing grid; radii 4 / 8 / 12; short spring motion; *one primary action
per screen*; *red under ~10% of any screen*; *no gold or red body text*; sentence case; flat before gradient;
a pre-ship checklist.
**We leave, without exception:** the Golden Arches in any form; the "Token" (a gold mark on a red rounded
square); cropped-arch graphics; watermark patterns; the Speedee typeface; price badges; food-photography
rules; the playful retail voice and tagline.
> **Hard rule — no gold mark on a red square, anywhere** (icon, avatar, launch, widget, marketing).
> Individual colours are free to use; that *combination* is another company's trade dress.
> Gate G4 was closed for submission on a documented self-search; professional clearance follows after launch (§12).
The kit's printed contrast ratios are inaccurate (it states 11.2:1 and 1.9:1 where the real figures are
9.94:1 and 1.69:1). This book quotes only computed values.
## 3. Colour
### 3.1 The one rule that makes gold work
Brand gold `#FFBC0D` is **1.69:1 on white and 1.58:1 on reader paper**. It cannot be text, an icon, a link
or an unbordered shape in light mode. So the accent is two tokens:
| Token | Use | Requirement |
|---|---|---|
| `accentFill` | The literal brand gold. Prominent fills only: primary button, selected pill, hero card, widget rule | Always carries a 1-pt `accent` border in light mode |
| `accent` | App tint, SF Symbols, links, toggles, borders, focus | >= 3:1 on card and paper |
| `accentText` | Accent-coloured words on a surface | >= 4.5:1 on canvas, card, paper |
| `onAccent` | Label sitting on `accentFill` | >= 4.5:1 on the fill |
In dark mode all three gold tokens are the same `#FFBC0D` (10–11:1 on warm ink) — gold is at its best there.
### 3.2 "Soul Gold" — the default palette
| Token | Light | Dark | Light, Increase Contrast | Dark, Increase Contrast |
|---|---|---|---|---|
| `accentFill` | `#FFBC0D` | `#FFBC0D` | `#8A6100` | `#FFC72C` |
| `accent` | `#A87900` | `#FFBC0D` | `#8A6100` | `#FFC72C` |
| `accentText` | `#8A6100` | `#FFBC0D` | `#5C4100` | `#FFC72C` |
| `onAccent` | `#2B1A05` | `#2B1A05` | `#FFFFFF` | `#2B1A05` |
| `accentDeep` (hero second stop) | `#FFB81C` | `#C08B00` | `#6E4E00` | `#D9A200` |
Worst-case measured ratios: `accentText` 4.96 (light canvas); `accent` 3.64 (light paper);
`onAccent` 5.54 (light Increase Contrast). Full table in the contrast report.
### 3.3 Supporting brand colours
| Colour | Light | Dark | Role | Limits |
|---|---|---|---|---|
| Brand red | `#DA291C` | `#DA291C` | **Fill only**: badge, count, one-off emphasis; white label 4.87:1 | Never text (4.36:1 on canvas). Under ~10% of a screen. Never behind or beside Gurmukhi |
| Maroon | `#8A1538` | `#E0658A` | Optional categorical / special | Passes as text on all legs |
| Kraft | `#B69A81` | `#B69A81` | Dividers, paper tint, illustration | Never text (2.48–2.65:1) |
The status reds, greens and blues stay exactly as they are (`Ink.positive / negative / info / special`).
`Ink.negative` `#B33528` remains the only *text* red.
### 3.4 Surfaces — unchanged
Light: system grouped backgrounds (`#F2F2F7` canvas, `#FFFFFF` card) and reader paper `#FBF7F0`.
Dark: the warm ink ramp `#151210` / `#1E1A17` / `#282320`, paper `#171412`. Never pure black, never the
kit's neutral greys — gold needs warmth under it, and this ramp is already regression-tested.
### 3.5 The other accents stay
Saffron, Gold (antique, `#B07D12`), Indigo and Teal remain in the accent picker with their current values
and labels. Anyone who already chose one keeps it; only readers who never chose move to Soul Gold.
### 3.6 Categorical colour (Lineage, Insights, Clock, echo bands)
Meaning is never carried by colour alone — pair with a label or symbol. With gold as the lead, contributor
kinds and chart series must stay clear of `#FFBC0D` and `#DA291C`; keep the existing info-blue / special-violet /
teal set, and move "Guru" from saffron to `accent` so it follows the palette.
### 3.7 Theme-group colours (Constellation, theme chips)
The 54 corpus themes sit in six theological groups (web `/themes` and iOS `ThemesScreen`). Each group has one
colour, `themeGroup.*` in `tokens.json`, so a theme's star, chip or legend swatch says which family it belongs to:
| Role | Group | Light | Dark |
|---|---|---|---|
| `themeGroup.divine` | The Divine Reality | kesri `#9C4D10` | `#F2A060` |
| `themeGroup.condition` | The Human Condition & Illusions | earth `#6B5440` | `#CDB39A` |
| `themeGroup.vices` | The Five Vices | plum `#7B3F91` | `#D7A0EA` |
| `themeGroup.path` | The Path & Praxis | teal `#1D6B67` | `#62CEC4` |
| `themeGroup.virtues` | Virtues & Divine Attributes | leaf `#3E6A1E` | `#A6D47A` |
| `themeGroup.states` | Spiritual States | sky `#1F62A6` | `#8EC2F5` |
Rules: every leg clears 4.5:1 on all four surfaces (the contrast report checks it), so a group colour may label
text as well as fill a star. None is red or brand gold — the Five Vices are plum, never red beside Gurmukhi, and
the centre of any constellation stays Soul Gold (`accentFill` with its `accent` edge). Colour never carries the
group alone: the legend names it and every star has a text label or list twin.
## 4. Typography
| Text | Face | Rule |
|---|---|---|
| Gurmukhi | **Sant Lipi** (bundled, OFL) | Untouched. Ink colour only. Reader size setting and Dynamic Type preserved |
| Screen titles, section headings, hero lines | **Warm serif, headings only** — candidates Fraunces, Source Serif 4 (both OFL) | Always `relativeTo:` a text style so it scales to AX5; never below 17 pt; never for buttons, tabs, lists |
| Everything else | San Francisco (system) | System text styles, no fixed point sizes |
Choosing the serif (gate G1), in order: sits calmly beside Sant Lipi; clear lining numerals for Ang numbers;
holds up at AX5 without truncation; font file size; OFL text shipped next to the font as with Sant Lipi.
Recommendation going in: **Source Serif 4** (quieter, more bookish); Fraunces is the expressive alternative.
Style: sentence case everywhere. No all-caps. Emphasis by weight, not by colour.
## 5. The mark and the app icon
The mark is **ੴ set in Sant Lipi** — flat, single colour, never outlined, shadowed, tilted or gradient-filled.
It is never cropped, redrawn or merged with another symbol.
Clear space in a layout: half the mark's height on every side. Minimum size 16 pt.
Permitted colours: brand gold, warm ink `#171412`, paper `#FBF7F0`, white.
### The app icon — v2, "Pothi & Naad" (chosen by the product owner 2026-10-14)
ੴ above an open pothi drawn in two lines, with rings of naad rising from the pothi's spine.
| Appearance | Field | Mark and pothi | Rings |
|---|---|---|---|
| Default | Top-lit gold, `#FFCE45` → `#F09A00` | Warm ink `#171412` | White, one even tone |
| Dark | Top-lit warm ink, `#2B221B` → `#0E0C0A` | Brand gold `#FFBC0D` | Gold, faint |
| Tinted | Black (the system applies the tint) | White | White, faint |
The icon has its own grid; the layout clear-space rule above would keep it too small to read.
- **Mark:** Sant Lipi at weight 800, 80% of the tile width, centred on visual mass rather than its bounding box.
The stroke must stay at or above 2 px at the 58 px size, and the kaar at least 8% inside the icon mask.
- **Pothi:** two lines, 40 px on the 1024 canvas. A plain open book, not a depiction of a Bir.
- **Light and depth live in the field only.** The mark and the pothi are one flat colour in every appearance.
The icon field is a permitted gradient, alongside the share-card rule (§6).
- **Layered icon (iOS 26 and later):** the same geometry as an Icon Composer document, with the system's
specular highlight turned off so the mark is never embossed.
- Red is not used in the icon. The field is warmer and deeper than the literal brand gold, and the mark on
it is ink, so the tile cannot be read as a gold mark on red (§2).
Source of truth: `ios/tools/make_app_icon.swift` in `gurbani-soul-ios` (`make app-icon`), which refuses to
run when a rule above is broken. The web, PWA and wiki icons are built from the same outlines by
`frontend/scripts/gen-icons.mjs` (`frontend/scripts/app-icon/`). The favicons carry the mark and the pothi
without the rings, which are noise at 16–32 px.
**Launch screen:** the icon's ੴ and pothi without the field or the rings — warm ink on paper, brand gold on
warm ink in dark — 200 pt with the artwork about 186 pt wide, written by the same `make app-icon`. While the
integrity check runs, the app shows the same logo on the same background, centred on the screen, so the
launch screen hands over without a jump.
The ੴ set inside the app (About, widgets) and on the open-graph cards stays the light weight in a single
colour; it is the mark in a layout, not the icon.
Icon v1 (2026-09-18 to 2026-10-14)
| Concept | Description | Notes |
|---|---|---|
| **A (chosen for v1)** | Gold ੴ on warm ink `#171412` | Distinctive on a home screen; furthest from any food-brand look; dark and tinted variants are trivial |
| B | Ink ੴ on brand gold | Strongest colour ownership; closer to retail yellow |
| C | Gold ੴ on paper | Softest; weakest contrast at small sizes |
Flat ExtraLight ੴ at about half the tile width. Replaced because the stroke was about 1.3 px at 58 px and
the black tile disappeared on dark backgrounds.