# WikiSubmission Brand Guidelines

> Editorial, scripture-first, theme-aware guidance for the public site and adjacent app surfaces.

Canonical page: https://wikisubmission.org/brand
Markdown export: https://wikisubmission.org/brand/brand.md

## North Star

- **Scripture first:** Every visual decision serves the reading. Surfaces stay quiet so the verses can speak.
- **Editorial, not corporate:** Type-led layouts, hairline rules, and generous whitespace beat dashboard-like chrome.
- **Theme-honest:** The brand is the system across three palettes and two modes, not one locked colorway.

## Palettes

The UI follows the active palette and light/dark mode. Brand swatches remain canonical and should not be color-corrected by theme state.

### Ink on Parchment (ink)

Editorial. Default. The canonical look.

- Light: bg #F6F2EA, fg #1A1715, accent #6B3410, rule #D9CFB9
- Dark: bg #14110E, fg #EEE4D0, accent #D4A373, rule #2A241E

### Sharpened Violet (violet)

Contemporary. High contrast. Modernist.

- Light: bg #FAFAFA, fg #121214, accent #5A1FD4, rule #E5E5EA
- Dark: bg #0C0C0E, fg #F4F4F5, accent #B48CFF, rule #27272C

### Monochrome (mono)

Minimal. True black on warm white.

- Light: bg #F4F4F2, fg #0E0E0D, accent #0E0E0D, rule #D8D8D4
- Dark: bg #0A0A09, fg #F1F1EC, accent #F1F1EC, rule #23231F

## Tokens

Use semantic tokens, not palette hex values, in ordinary implementation work.

- **--ed-bg:** Page background. Maps to --background.
- **--ed-fg:** Primary text. Maps to --foreground.
- **--ed-fg-muted:** Secondary text, captions. Maps to --muted-foreground.
- **--ed-accent:** Highlights, links, key motifs. Maps to --primary.
- **--ed-accent-soft:** Tinted accent surface. Maps to --accent.
- **--ed-rule:** Hairline borders, dividers. Maps to --border.
- **--ed-bg-alt:** Muted surface (cards, callouts). Maps to --muted.
- **--ed-surface:** Card surface (elevated). Maps to --card.

## Typography

The public site combines display typography, readable serif body copy, utility monospace, Arabic text, and a narrow uppercase UI face.

- **Cormorant Garamond:** Display, headings, italic accents. Variable --font-cormorant. Sample: In the name of God, Most Gracious, Most Merciful.
- **Source Serif 4:** Body copy, paragraphs, reading. Variable --font-source-serif. Sample: Praise be to God, Lord of the universe, Most Gracious, Most Merciful.
- **JetBrains Mono:** References, tokens, data labels, utility metadata. Variable --font-jetbrains. Sample: 1:1 · 114 chapters · --ed-accent
- **Amiri:** Arabic Quranic text. Variable --font-amiri. Sample: بِسْمِ اللَّهِ الرَّحْمَٰنِ الرَّحِيمِ
- **Glacial Indifference:** UI eyebrow, uppercase metadata, sectional chrome. Variable --font-glacial. Sample: CHAPTER · VERSE · TRANSLATION

## Responsive Behavior

These rules reflect current repository usage. I did not find a separately versioned breakpoint token file.

- **Breakpoint model:** Current implementation uses Tailwind tier prefixes (`sm`, `md`, `lg`). I could not find a separate custom breakpoint scale in the repo, so this documents current usage rather than a dedicated token file.
- **Containers:** Primary site sections use a 1240px max width with horizontal padding patterns such as `px-5 sm:px-10` or `px-4 sm:px-6 md:px-10`.
- **Grid collapse:** Marketing sections typically collapse from 2–3 columns to one column at `md` or below. Side rails become top borders on mobile rather than staying side-by-side.
- **Type scaling:** Hero and section headings use `clamp(...)` instead of fixed desktop sizes so large editorial type remains legible on narrow screens.
- **Touch targets:** Interactive mobile controls commonly land around 34–44px high, with search and location inputs often using `h-11`.

## Interaction States

States should communicate hierarchy and usability without becoming loud.

- **Hover:** Favor subtle movement: borders darken, cards lift a few pixels, links deepen in tone, and CTAs widen their internal gap before changing fills.
- **Focus Visible:** Keyboard focus must remain explicit. Shared UI primitives use visible rings, and editorial one-offs should provide an equivalent outline or ring against `--ed-bg`.
- **Active / Current:** Current location is usually signaled by an accent rail, text-weight change, or a restrained tinted background instead of a loud solid fill.
- **Disabled / Busy:** Disabled elements lower opacity and suppress pointer events. Busy states should keep layout stable and communicate progress with motion or live text, not only color.

## Forms and Components

Forms are part of the design system, not an implementation afterthought.

- **Base primitives:** Application forms use shared `ui` primitives (`Input`, `Textarea`, `Checkbox`, `Button`, `Field*`) with validation and focus-visible states already built in.
- **Field structure:** Use explicit labels, optional descriptions, and inline error text. `FieldError` is the pattern for validation feedback and should remain adjacent to the control it describes.
- **Search surfaces:** Search and picker inputs often appear on softened surfaces with understated borders, roomy internal padding, and accent-colored focus borders.
- **Error handling:** Invalid state should change both border treatment and announced error text. Never encode errors by red color alone.
- **Editorial vs app UI:** Public-site editorial buttons use `.ed-*` classes. Dashboard-like or Radix-based interactions may use shared app primitives, but palette tokens still govern the colors.

## Navigation and Wayfinding

Navigation chrome should remain quiet, legible, and structurally obvious.

- **Header behavior:** Desktop navigation lives at `lg` and above. Below that, the site collapses to an animated mobile menu with grouped rails and nested links.
- **Brand anchor:** The site brand is always a functional home link. The mark and wordmark animate lightly unless reduced motion is requested.
- **Wayfinding:** Current-page states rely on typography, accent rails, and restrained fills instead of heavy badges. Secondary navigation should preserve this quiet hierarchy.
- **Footer role:** The footer is not ornamental. It repeats core IA, support pathways, and community links in the same editorial palette language as the rest of the site.

## Content Patterns

The site mixes manifesto-like editorial layouts with practical data-heavy surfaces.

- **Hero blocks:** Landing heroes are type-led, asymmetric, and often pair one large display statement with a quieter side note or verse rail.
- **Cards:** Cards are usually bordered rectangles on muted or surface backgrounds. They read as editorial clippings, not glossy product tiles.
- **Data callouts:** Stats, verse keys, and metadata use mono or uppercase utility type, while the explanatory copy returns to serif body text.
- **Tables and schedules:** Dense data views use thin dividers, compact metadata, and strong alignment. Reserve strong accent color for live or important values only.
- **Article content:** Long-form reading surfaces should preserve generous line-height, subdued chrome, and strong heading hierarchy. Decorative assets should never compete with the text column.

## Geometry

- **Max content width:** 1240px
- **Section padding:** roughly 20–40px horizontal and 80–120px vertical depending on breakpoint
- **Hairlines:** 1px solid `var(--ed-rule)`
- **Editorial corners:** preferably square to 3px radii on brand-led surfaces
- **Rhythm:** 8, 12, 16, 24, 32, 48, 64, 96

## Accessibility

The design language only works when the structure remains usable.

- **Headings:** Pages must expose a real heading hierarchy. Section chrome may be styled richly, but the underlying element should still be `h1`–`h6` as appropriate.
- **Focus and keyboard:** Every interactive control must be reachable by keyboard, with a visible focus indicator. Hover-only behavior is insufficient.
- **Live regions:** Rotating verses, prayer timing, and other dynamically updated content should use `aria-live="polite"` when changes matter to assistive technology.
- **Contrast:** Muted text is acceptable for secondary content only. Essential labels, controls, and active states must stay readable in every palette and both modes.
- **Targets and labels:** Controls need adequate touch size and text labels or accessible names. Icon-only controls require `aria-label`.

## Motion

Motion exists across the site, but it stays restrained and text-respectful.

- **Default feel:** Motion is soft and editorial. The shared GSAP helper defaults to `power3.out` easing and about 0.6s duration, favoring fade-up and staggered reveals over flashy transforms.
- **Enter patterns:** Common entrances use 20–24px vertical fade-ups, gentle scale-ins, and small stagger values around 0.1s.
- **Reduced motion:** Important animated surfaces check `prefers-reduced-motion` and should degrade to immediate state changes or simplified fades.
- **Meaningful motion only:** Animate hierarchy, continuity, and state change. Avoid ornamental perpetual motion except for rare ambient accents with very low visual weight.

## Internationalization

Bilingual and bidirectional behavior are first-class requirements.

- **Document direction:** The root layout sets `dir` from locale. RTL locales currently include `ar`, `ac`, `fa`, and `ur`.
- **Script isolation:** Arabic content should explicitly declare `dir="rtl"` and `lang="ar"` where relevant. Mixed-script UI should isolate directional runs rather than relying on luck.
- **Directional icons:** Chevron-like directional icons use `.rtl-flip` so arrows mirror naturally in right-to-left contexts.
- **Language pairing:** Arabic remains the most spacious script on the page. Do not crowd it with tight containers or force it into Latin line-height assumptions.

## Voice

Copy should sound as serious as the subject matter.

- **Scholarly:** Precise, sourced, footnoted. Never speculative.
- **Reverent:** Quiet, deliberate. The verses are the focus.
- **Plain:** No jargon. A 12-year-old can read every page.
- **Timeless:** No trends. No novelty styling or disposable visual slang.

## Implementation Notes

This is the practical contract between design guidance and the actual codebase.

- **Token layering:** Editorial `--ed-*` aliases sit on top of standard semantic tokens such as `--background`, `--foreground`, `--primary`, and `--border`. Both layers matter because shared UI primitives often consume the base layer directly.
- **Public-site primitives:** The public site uses a mix of inline editorial styling, `.ed-*` helper classes in `globals.css`, and small shared helpers like `SectionDivider`, `Hairline`, and the editorial markdown components.
- **Application surfaces:** Authenticated or tool-heavy experiences lean on Radix/shadcn-style primitives. Those components are valid within the system as long as palette semantics and accessibility rules are preserved.
- **Source of truth:** When written guidance and shipped UI disagree, trust the repo first, then update the brand document so it describes reality or intentionally directs a cleanup.
- **LLM export:** This page ships with a Markdown export so internal tooling and language models can consume a text-first version of the design system.

## Application

### Do

- Use --ed-* tokens for public-site editorial surfaces.
- Pair Cormorant displays with Source Serif body copy.
- Keep dividers and hairlines at exactly 1px.
- Let Arabic breathe with generous line-height and generous horizontal room.
- Use visible keyboard focus, not hover-only affordances.
- Verify public pages in all three palettes and both light and dark modes.

### Don't

- Hardcode product colors into ordinary page components.
- Round editorial surfaces heavily by default.
- Decorate empty space without structural purpose.
- Rely on color alone to communicate active, invalid, or disabled state.
- Ship icon-only actions without accessible labels.
- Recolor or distort the logo mark.

## Closing Note

"We will show them Our proofs in the horizons, and within themselves, until they realize that this is the truth." — 41:53