Gurbani Soul — Brand Book

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 (source of truth) · contrast-report.md (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.

6. Components

Component	Spec
Primary button	accentFill + 1-pt accent border (light) · onAccent label · radius 4 · one per screen
Secondary button	Card surface · hairline · accentText label
Selected pill	As primary button, radius 8
Card	Unchanged: shadow in light, hairline in dark, radius 12
Explore hub	No hero slab: a dated masthead (Source Serif 4 hero line), then cards on the Card surface. The only gold fill is the Featured today capsule: accentFill + 1-pt accent border, onAccent label (the selected-pill recipe). Card previews (ribbon, dot field, dial, sky) use accent tints and the family/voice tokens; Gurmukhi raag names and the one quoted verse are ink. Gradient accentFill -> accentDeep allowed only on the share-card rule
Focus highlight	accent at 18%
Glow	A radial/linear accentFill (or accent) wash at ≤14% over an AA-checked surface — a light, never a text background. Used on the Nitnem hero, the Raag Clock now-card, Lineage, and every widget’s PaperGround. Distinct from the opaque accentFill→accentDeep gradient, which stays limited to the share-card rule.
Reader paper	Ink.paper (default), Ink.paperWarm (#FDF6E3 light — hue-shifted, still clears every accent pair), or Night (the warm-ink dark scheme forced on the reader subtree; no new colours).
Share card (VerseCard)	Paper surface, ink Gurmukhi, gold rule, full citation “Sri Guru Granth Sahib Ji · Ang N”
Widgets	Card surface, gold rule, accentText labels; same tokens as the app. The Raag Now dial (PaharDialRenderer) is the same face as the app: accentFill current watch with an accent stroke, accent hand; lock-screen accessories render it mono. The 12-hour analog face (ClockHandsLayer) uses ink tapered hands and an accent seconds hand (app only; widgets show hour/minute at the entry minute); the day/date number is accentText.
Badge / count	Brand red fill, white label — the only routine use of red

Website exception (owner decision, 2026-10-18): the marketing site never uses red, except the HELP heart — a solid heart with “HELP” set inside it in white (4.87:1), in the top bar on every page (desktop and phones), linking to /contribute. It is the heart’s fill only, set through the single --contribute-heart token in frontend/src/styles/marketing.css; never text, never a background, never beside Gurmukhi. BrandDisciplineInSource allows exactly that one declaration.

7. Voice

Reverent, plain, exact. Short sentences. Say what a thing is. Never playful about the text, never promotional inside the reader, never “AI” as a selling point. Every quotation carries its Ang. Explanation is always labelled as explanation. UI strings that tests depend on are frozen unless the test suite is updated with them.

8. Accessibility

All text pairs >= 4.5:1 and all UI pairs >= 3:1 across light, dark and both Increase Contrast modes — proven by the contrast report and, once implemented, by ThemeContrastTests. Tap targets >= 44 pt. Dynamic Type to AX5. Reduce Motion honoured through the existing motion helpers. Gold, red and maroon are never the sole signal of state.

9. Do / Don’t

Do	Don’t
Let gold lead; one gold action per screen	Set words, icons or links in #FFBC0D on a light surface
Border every gold fill in light mode	Put a gold mark on a red square
Keep Gurmukhi in ink on paper	Colour, tint or decorate scripture text
Use red for a badge, sparingly	Use red for text, large areas, or near Gurbani
Use the serif for headings only	Set buttons, lists or body in the serif
Cite “Sri Guru Granth Sahib Ji · Ang N”	Call the text “Gurbani Soul”

10. Pre-ship checklist

• ☐ python3 scripts/brand/contrast_report.py exits 0
• ☐ No hex outside DesignTokens.swift; no raw system colours in screens
• ☐ Every gold fill bordered in light mode; one primary action per screen
• ☐ Red under ~10% and never text
• ☐ Light, dark, Increase Contrast and AX5 screenshots reviewed
• ☐ Widgets and share card match the app
• ☐ Icon: no red; mark and pothi one flat colour; three flat variants, the layered icon and the launch logo present; make app-icon runs clean
• ☐ Scripture text, corpus and database untouched

11. Governance

tokens.json is the source of truth, and the app is pinned to it. gurbani-soul-ios’s BrandTokensParityTests (gurbani-soul-ios PR #20) checks ios/App/Shared/DesignTokens.swift against this file in all four legs (light, dark, lightHC, darkHC): AccentPalette.soul (accent, accentFill, accentText, onAccent, accentDeep), the Ink surfaces (canvas, card, paper, paperWarm) and status colours (positive, negative, info, special), the theme-group colours (themeGroup.*), and Theme.Space / Theme.Radius. The test reads a copy vendored by the iOS repo’s scripts/vendor_sync.py and pinned by platform commit and sha256 in its vendor.lock.json, so the app moves only when it re-vendors. It fails closed both ways: a value changed on either side, or a role added, renamed or removed here, fails with the role and leg named. brand.red, brand.onRed, brand.maroon, brand.kraft and radius.button are declared there as having no Swift token; giving one a token means adding it to the test’s mapping.

A colour change, in order:

1. Here — edit tokens.json, re-run python3 scripts/brand/contrast_report.py (must exit 0) and commit both (contrast_report.py --check, in make docs-check and the wiki’s docs job, fails if they disagree). CI also holds the web theme (frontend/src/theme.ts, WebThemeMatchesTokens) and the wiki theme (docs-site/src/styles/theme.css, tools/docs_check.py) to the light and dark legs, so they change in the same PR.
2. Release — the change reaches a platform release tag (or another ref the iOS repo can pin).
3. Vendor — in gurbani-soul-ios, make vendor-sync-platform REF=<tag or commit> re-vendors the file and updates vendor.lock.json; BrandTokensParityTests now fails on every role and leg that moved.
4. Swift — change the literal in DesignTokens.swift to match and commit it with the vendored file and the lock; the test is green again.

Decisions are logged below.

Date	Decision
2026-09-18	Palette values adopted from the reference kit; marks, typeface and voice rejected
2026-09-18	Accent split into accentFill / accent after literal gold measured 1.69:1 on white
2026-09-18	New palette case soul; existing gold palette left untouched
2026-09-18	Brand red is fill-only; Ink.negative stays the text red
2026-09-18	G1 passed: icon concept A (gold ੴ on warm ink) and Source Serif 4 for headings chosen by the product owner
2026-10-14	Icon v2, “Pothi & Naad” chosen by the product owner: a bold ੴ above an open pothi, ink on gold; gold on warm ink in dark mode. G3 to be re-run on it
2026-09-18	accentDeep given Increase Contrast legs so the hero label holds 4.5:1 at both gradient ends
2026-09-18	Source Serif 4 (variable, SIL OFL 1.1, from adobe-fonts/source-serif) bundled for navigation titles and hero lines only; widgets stay on the system face
2026-10-18	Website exception: brand red allowed only as the fill of the HELP heart (links to /contribute) (--contribute-heart), chosen by the product owner; the BrandDisciplineInSource gate allows exactly that one declaration
2026-09-26	DesignTokens.swift pinned to tokens.json in all four legs by gurbani-soul-ios BrandTokensParityTests (PR #20), against a copy vendored by commit; a colour change now flows JSON → release → make vendor-sync-platform → Swift literal
2026-10-23	Six theme-group colours (themeGroup.*) added for Constellation v2 (a new mini-palette, decided by the product owner; values proposed in the palette PR): one per theological group, AA as text on every surface, no red, no gold

Visual audit set

Screenshots are local audit evidence (git-ignored): ios/App/new_shots/brand-<date>/{light,dark}/ — reader, search_results, themes, clock, explore_hub, more_display. Re-capture after any token, type or icon change and compare with the previous dated set. First set: brand-2026-09-18.

12. Gates before any code

Gate	Owner	Pass condition
G1 Visual	Product owner	Specimen sheet approved; icon concept and serif chosen
G2 Contrast	Script	Zero failures, four legs, real surfaces
G3 Sensitivity	Granthi / scholar, with the scripture-fidelity charter	ੴ treatment, icon, and any red near Gurbani accepted
G4 Legal	Professional clearance, with the pending trademark review	Gold-and-red palette without Arches or Token cleared for the App Store

Status at the first submission (1.3.10, 2026-09-26):

• G3 closed 2026-09-26. The ੴ icon treatment, the launch screen and the default traditional saroop were accepted with no change requested, recorded by the owner. The review pack is kept with the release records.
• G4 closed 2026-09-26 by the owner on a documented self-search (trademark registers in Australia, the US, the EU and WIPO, both app stores, and the trade-dress rule above); full professional clearance is scheduled after launch. The search record is private and stays out of the public repositories.

Status at icon v2 (2026-10-14):

• G3 is open again for the icon and the launch screen. The 2026-09-26 acceptance covered icon v1 and the v1 launch screen. Icon v2 changes the weight and the field and adds an open pothi beneath ੴ, and the launch screen now matches it, so both go back to the scholar before any release that carries them.
• G4 to be re-checked for the gold field: the self-search note should record that an ink mark on gold, with no red and no arch, was considered.

Status at the Knowledge Base redesign (web 1.4.0):

• G3 for the web themes is open. The five themes copied from the app are approved. The eight web-only themes, and the rule that Gurmukhi is ink in every theme, have not been seen by a scholar; they ship marked review in docs/brand/web-themes.json. The owner waived the review for the 1.4.0 release on 2026-10-13; it runs after the release, and a theme can be withdrawn by setting it to held.

13. Implementation map (phase 2 — shipped in PRs #28–#31; kept as the record)

One pull request per step, tests green at each:

1. Tokens — add soul, accentFill, AccentPalette.brandDefault in ios/App/Shared/DesignTokens.swift; default read from it in RootView.swift (two sites), PaletteKey, Theme.accent; AccentColor.colorset -> #A87900 / #FFBC0D. For the four existing palettes accentFill == accent, so nothing of theirs moves. Tests: existing assertions kept; onAccent asserted on accentFill; asset-parity pinned to brandDefault; JSON-to-Swift parity planned (it landed after the repo split as gurbani-soul-ios PR #20; see §11).
2. Components — fills to accentFill + border (Buttons.swift, ModePill.swift, Explore hero); VerseCard, FocusHighlight; hard-coded saffron in Widgets/SGGSWidgets.swift; Lineage “Guru” colour.
3. Type — bundle the serif and its OFL text; UIAppFonts in project.yml for app and widget; Brand.heading(_:relativeTo:) beside Brand.gurmukhi.
4. Icon and launch — new values in ios/tools/make_app_icon.swift; regenerate with make app-icon, which writes the icon and the launch logo (since the repo split this lives in gurbani-soul-ios; see §5).
5. Docs and CI — store listing, test plan, screenshots, changelog; script the token-leak check.