pad/docs/brand.md

Pad Brand Spec

Audience: developers working on pad-web (../pad-web, the getpad.dev marketing site) and web/ (the SvelteKit app embedded in this repo's Go binary, served at app.getpad.dev in Cloud mode and at localhost:7777 or operator domains in self-hosted mode).

Purpose: define the visual contract for surfaces that border between marketing and product, so the two codebases can converge intentionally rather than drift accidentally.

This doc is not a full design system. It only covers what is actually shared. The interior of the Pad app (the workspace shell, item detail pages, board views, etc.) keeps its own conventions and is explicitly out of scope here.

Tracked under PLAN-900 (Cohesive UX between getpad.dev and Pad Cloud), TASK-904. When you change anything in this doc, update the citations in the source files listed under How both repos cite this doc.

---

1. Where parity matters / where divergence is fine

This is the most important decision in this document. Read this section first.

Surface	Parity?	Notes
getpad.dev marketing pages (home, docs, blog, legal)	—	The reference. Other surfaces converge toward this.
app.getpad.dev auth-page family (login, register, forgot-password, reset-password, join, OAuth-error) in Cloud mode	Full parity	Header + footer + tokens match getpad.dev. See PLAN-900 / TASK-902 / TASK-903.
app.getpad.dev 404 / 500 error pages in Cloud mode	Full parity	Same chrome as auth pages. See TASK-906.
Transactional emails (invite, password reset, etc.) in Cloud mode	Full parity	Header + footer treatment + token palette. See TASK-907.
In-app Resources menu (links to docs / changelog / GitHub / support)	Brand-consistent text + icon treatment, but lives inside the workspace shell — does not import marketing chrome. See TASK-905.
Self-hosted auth pages, error pages, emails	Neutral — no parity	Operators ship Pad under their own brand. Self-hosted UI must NOT carry getpad.dev branding. Gated on the existing cloud_mode flag (see Cloud-mode flag).
App workspace shell (TopBar, sidebar, item detail, board, list views)	Divergent — keep as-is	Tool aesthetic. Don't homogenize.

Two-line summary: Cohesion applies at the seams between marketing and product, and only when the user is on Cloud. Inside the app and on self-hosted, leave things alone.

---

2. Cloud-mode flag

Every parity decision in this doc is conditional on Cloud mode. The flag is already plumbed end-to-end and no new env var should be introduced:

• Server: cloud_mode is returned on /api/v1/auth/session (see internal/server/handlers_auth.go).
• Client: cloud_mode?: boolean in web/src/lib/api/client.ts (lines 119, 127). Auth pages already read it (web/src/routes/login/+page.svelte line 18, cloudMode = $state(false)).
• Components: LegalFooter and SupportFooter accept a cloudMode prop today and switch behavior on it (web/src/lib/components/auth/).

Reuse this signal everywhere. If a new component needs to know whether it's on Cloud, plumb the same prop — do not add a parallel mechanism.

---

3. Color tokens

The marketing site (pad-web/src/app.css) is the canonical source for bordering surfaces. The accent palette is already aligned across both repos; the structural tokens (bg / text / border) currently diverge and the convergence direction is app moves toward marketing, not the other way around.

Canonical values (bordering surfaces only)

--color-bg              #111113   /* primary surface */
--color-bg-raised       #1a1a1e   /* card surface */
--color-bg-surface      #222226   /* nested surface */
--color-bg-hover        #2a2a30

--color-text            #ededef   /* body text */
--color-text-secondary  #a0a0a8   /* nav links, secondary copy */
--color-text-muted      #8a8a93   /* footer links, captions     ←  AA-passing */

--color-border          #2a2a30   /* card borders, dividers */
--color-border-subtle   #1f1f24   /* header / footer separators */

--color-accent          #4a9eff   /* primary action, focus ring */
--color-accent-hover    #3b8de6
--color-green           #4ade80
--color-amber           #fbbf24
--color-purple          #a78bfa
--color-red             #f87171

Accent palette parity

The accent values (blue, green, amber, purple) are already identical between pad-web/src/app.css and web/src/app.css. Treat them as fixed and do not re-pick them.

Known drift to clean up (out of scope for this doc)

• web/src/app.css defines --text-muted: #666666, which gives ≈3.2:1 against --bg-primary: #1a1a1a and fails WCAG AA for body-size text. The marketing site uses #8a8a93 (≈4.7:1) which passes. When the auth-page header/footer convergence work (TASK-902 / TASK-903) lands, surfaces that consume the marketing palette automatically inherit the AA-passing value. The deep-app fix is a separate concern — file a follow-up if it bites.

---

4. Type scale

Font families

Bordering surfaces use:

--font-sans  'Inter', ui-sans-serif, system-ui, -apple-system, sans-serif
--font-mono  'JetBrains Mono', 'SF Mono', 'Fira Code', monospace

The deep app (web/src/app.css) currently uses system-ui as primary — that's intentional for the workspace shell (system feel inside a tool) and stays as-is. Bordering surfaces only should pull in Inter + JetBrains Mono so they feel continuous with the marketing site.

If Inter / JetBrains Mono aren't already self-hosted on the app side, loading them costs an HTTP request — fine for auth pages, error pages, and emails (low-frequency surfaces); not justifiable inside the workspace shell.

Sizes (Tailwind utility names — both repos use Tailwind)

Use	Class	Computed
Logo wordmark	text-lg font-bold tracking-tight	18px / bold / tightened tracking
Nav link	text-sm	14px
Body copy	base (no class)	16px
Footer copy	text-sm	14px
Footer muted (legal)	text-sm text-text-muted	14px in --color-text-muted
Copyright line	text-sm text-text-muted	14px

---

5. Spacing & layout

Container

mx-auto max-w-6xl px-6

max-w-6xl = 72rem = 1152px. Same on both repos. Use this on every header / footer / page-content container that's part of the bordering surfaces.

Header

fixed top-0 z-50 w-full border-b border-border-subtle bg-bg/80 backdrop-blur-xl

• Fixed to top of viewport, full width, stays above page content.
• 80% opacity background plus backdrop-blur-xl for the soft-glass effect. Don't drop the blur — the bordering surfaces match each other via this exact treatment.
• border-b border-border-subtle is the only divider.
• Vertical padding py-4 (16px), horizontal px-6 (24px) inside the max-w-6xl row.

Main content offset

<main class="pt-16"> — 64px top padding so content doesn't slide under the fixed header. Every bordering surface needs this.

Footer

border-t border-border-subtle

Inside container:

flex flex-col items-center justify-between gap-4 px-6 py-8 sm:flex-row

• Stacks vertically on mobile, lays out horizontally at the sm: breakpoint.
• Link row uses flex flex-wrap items-center justify-center gap-x-6 gap-y-3.

Mobile breakpoint

Tailwind's md: (768px). Above this, full nav; below, hamburger menu. Both repos must use the same breakpoint to avoid awkward jumps when a user opens the app from a marketing link on a tablet.

Hamburger spec

• Closed: 24x24 SVG, two horizontal lines (y=8 and y=16).
• Open: 24x24 SVG, X mark (lines from corner to corner).
• Stroke width 2, round caps and joins, currentColor so it inherits.
• Toggling the menu reveals an inline panel with the same nav links stacked, border-t border-border-subtle px-6 py-4 for the panel.

(Pulled from the existing pad-web/src/routes/+layout.svelte implementation — see lines 60–127. The auth-page header in this repo must match this byte-for-byte for the SVG path so the visual transition is identical.)

---

6. Header pattern

Anatomy (left to right)

1. Wordmark — <a href="/" class="text-lg font-bold tracking-tight text-text">pad</a>. Lowercase. Always links to root of the current property (getpad.dev/ on marketing, app.getpad.dev/login on auth pages pre-auth, etc.).
2. Spacer — flex items-center justify-between distributes.
3. Link row (desktop) — hidden items-center gap-8 md:flex containing nav links. Each link text-sm text-text-secondary transition-colors hover:text-text.
4. Hamburger button (mobile) — flex items-center justify-center md:hidden, aria-labelled "Toggle menu", aria-expanded reflects state, aria-controls="mobile-menu".

Link list — what goes in the header

The header link list is not the same between marketing and auth pages. Don't try to homogenize it.

Surface	Header links
getpad.dev (marketing)	Docs, Blog, GitHub, Login (added by TASK-901)
app.getpad.dev auth pages, Cloud mode	Docs, Blog, GitHub (but linking to https://getpad.dev/...)
app.getpad.dev auth pages, self-hosted	No header at all — render null

Marketing nav adds a Login CTA because that's its job. Auth-page nav omits it because the user is already on /login. Both nav surfaces otherwise mirror each other so the user feels they're on the same property.

External links

Anything pointing off the current property opens in a new tab:

<a href={link.href} target="_blank" rel="noopener noreferrer" ...>

rel="noopener noreferrer" is required — both for security (noopener prevents the new page from accessing window.opener) and because Tailwind/Svelte tooling will warn without it.

---

7. Footer pattern

Anatomy

<footer class="border-t border-border-subtle">
  <div class="mx-auto flex max-w-6xl flex-col items-center justify-between gap-4 px-6 py-8 sm:flex-row">
    <p class="text-sm text-text-muted">
      © 2026 Pad
      <span class="mx-1">·</span>
      <a href="https://perpetualsoftware.org" target="_blank" rel="noopener noreferrer" class="text-text-muted/60 transition-colors hover:text-text-secondary">
        Perpetual Software LLC
      </a>
    </p>
    <div class="flex flex-wrap items-center justify-center gap-x-6 gap-y-3">
      <!-- link list — see canonical order below -->
    </div>
  </div>
</footer>

Canonical link order

Always the same order. This is the contract:

1. GitHub (external)
2. Community (external — the repo's GitHub Discussions; TASK-2888)
3. Docs
4. Tutorials (TASK-3452: in-app on Pad Cloud, getpad.dev/learn elsewhere; the app's user menu carries it, the marketing footer omits it while /learn is unlisted)
5. Changelog
6. Contribute
7. FAQ
8. Security
9. Privacy
10. Terms
11. Sub-processors

If a surface omits a link (e.g. self-hosted footer skips Changelog because there's no Changelog page on a self-hosted install), keep the relative order intact — don't reshuffle.

Link styling

text-sm text-text-muted transition-colors hover:text-text-secondary

Hover lifts from --color-text-muted (#8a8a93) to --color-text-secondary (#a0a0a8). Subtle by design — the footer is secondary navigation, not a CTA strip.

Copyright line

• Format: © <current year> Pad · Perpetual Software LLC
• The middot is · (·). Not |, not -, not /.
• "Perpetual Software LLC" links to https://perpetualsoftware.org with the muted treatment shown above.
• Year is the current calendar year. If you're updating this doc, also audit the inline 2026 in pad-web/src/routes/+layout.svelte line 142.

Self-hosted footer

When cloud_mode === false, render only the legal-essential subset:

• Privacy (if the operator has hosted a privacy doc)
• Terms (if applicable)
• A copyright line that says the operator's name, not Pad's (this is out of scope for the immediate cohesion work — for now keep the current self-hosted footer behavior; flag for the operator-branding follow-up plan).

---

8. How both repos cite this doc

When you change tokens, header structure, or footer link list in this doc, update the source files that follow this contract. To make drift auditable, each consuming file carries a one-line comment pointing back here.

Source of truth: pad-web/src/routes/+layout.svelte

<!-- Visual contract: docs/brand.md (Pad repo). When changing tokens,
     header structure, or footer link list, update both this file and
     the auth-page header/footer in the Pad repo to match. -->

App-side consumers (each gets a similar comment):

• web/src/lib/components/auth/AuthHeader.svelte (new in TASK-902)
• web/src/lib/components/auth/LegalFooter.svelte
• web/src/lib/components/auth/SupportFooter.svelte
• web/src/routes/+error.svelte (touched by TASK-906)
• Email templates in internal/email/ (touched by TASK-907)

The comment doesn't need to be elaborate — one line citing the path is enough. The point is that anyone touching one file can grep for the others and keep them in sync.

---

9. The Pad mark

Adopted (Dave, 2026-10-09; TASK-3514), with a FLAT app icon: a solid dark tile, no edge glow and no tile sheen. The rollout runs repo by repo (plan on TASK-3514); a surface not yet switched still shows its old mark.

The mark is a 3x3 grid of rounded tiles. It replaces both earlier marks: the purple "P" (the app's favicons and app icons) and the raster nine-square icons (mobile, video, marketing), which came from one bitmap and drifted in crop, glow and tile size. The SVGs in docs/brand/mark/ are the source. Every PNG anywhere is an export of one of them, never a hand-edited copy.

The master set (docs/brand/mark/)

File	What it is	Use it for
pad-mark.svg	The mark, full colour, no background	Headers, the README, any lockup at about 20px and up
pad-mark-small.svg	Pixel-aligned at 16px: 4px tiles, 1px gaps, 1px inset (the favicon tile's grid)	Favicons at 16, 32 and 48px, and icon.svg; scale by whole multiples only
pad-favicon-tile.svg	The small mark on a dark tile	Places that need a solid backing: PWA maskable, Windows tiles
pad-app-icon.svg	The mark on a solid dark tile (#0a0b16), full-bleed	iOS AppIcon and apple-touch-icon (iOS masks it; no transparency)
pad-app-icon-shaped.svg	The same tile, transparent outside its rounded shape	PWA icon-192/512, Android legacy launcher, in-app logos (iOS PadIcon, Android pad_logo), video lockups, OG and store art
pad-org-avatar.svg	The mark, smaller, on a full-bleed dark tile with no edge ring; every tile clears a circle crop	The PerpetualSoftware GitHub org avatar, which GitHub's default social card shows
pad-mark-mono.svg	One colour (currentColor), with the two slate tiles at 40%	One-colour contexts: print, embossing, a single-ink badge

Geometry and colour

• Grid: tiles of 200, gaps of 38, tile corners of 37, on a 676 square, measured from the mobile app icon (icon_1024.png). In the app icon the grid sits at 174..850 on a 1024 canvas, and the tile's own corner radius is 222.
• Tile colours, row by row:
  • #007bfc #2f2ffb #8406fb
  • #01bc81 #fdb600 #45496c
  • #0090fd #004ffb #424668
• The two slate tiles are part of the mark, as in the mobile icon. Keep them slate; do not recolour them to the accent.
• App-icon tile: solid #0a0b16, corner radius 222 of 1024 when shaped. Flat by ruling: the mobile icon's edge glow and tile sheen were mocked and declined.

Rules

• On light and dark backgrounds alike, use pad-mark.svg as is. No outline, shadow or glow anywhere, the app icon included.
• Below 20px, use pad-mark-small.svg. Drawn at 16px, the full mark's 38/200 gaps come out under one pixel wide, and at 1x density they render as smeared half-tones in both Chromium and WebKit. The small variant snaps every edge to a pixel, so its gaps stay crisp. Its gaps were 2px (gap/tile 0.50) at first; TASK-3974 tightened them to 1px with a 1px inset (0.25, near the master's 0.19), the grid pad-favicon-tile.svg already used. That reads as the same mark as the full one and stays crisp at 1x, 2x and 3x (the TASK-3974 comparison renders). A 2x2 simplification was tried and dropped: it loses the identity (TASK-3514 mockups).
• The lockup is the mark followed by the lowercase wordmark pad (section 6). In the mockups the mark is about 1.2x the wordmark's font size (22px beside an 18px wordmark). In a header the mark sits beside the wordmark and never replaces it.

GitHub social preview

Ruled (Dave, 2026-10-09): keep GitHub's default card, which keeps the live counts, and make the mark the org avatar (pad-org-avatar-1024.png, uploaded in the org settings). The custom card below is parked, kept in case it is wanted later.

docs/brand/social/render.mjs renders it in GitHub's own card layout, with the mark where the org avatar goes:

• a: durable facts (license, stack, hosting, agent access) in place of counts.
• b: a snapshot of the counts.

GitHub has no API for the social preview: an owner uploads the PNG under Settings › Social preview, and it stays as uploaded. Version b's numbers are therefore as of the render. Run node docs/brand/social/render.mjs b and re-upload to refresh them.

Exporting

node docs/brand/mark/export.mjs <static-dir> [--og] writes the web icon set from the masters: favicon-16x16.png, favicon-32x32.png, favicon.ico (16/32/48), icon.svg (the small mark, which a browser prefers in a tab), pad-mark.svg, icon-192.png and icon-512.png (shaped), apple-touch-icon.png (full-bleed), padicon.png (shaped, for links to the old name), and with --og the 1200x630 og-card.png. This repo runs it on web/static --og; pad-web runs it on its static/. Never edit an exported PNG: change the SVG and export again.

Where it goes

Each surface gets an export from the master set. The rollout plan by repo is on TASK-3514.

---

10. What this doc explicitly does NOT do

• It is not a full design system. The deep app (workspace shell, item views, etc.) has its own conventions and stays as-is.
• It does not extract a shared component package. Both repos hand-implement to this contract. The cost of an @pad/ui package isn't justified by the small surface area being shared.
• It does not define operator-customizable branding for self-hosted. That's a separate, larger plan to be opened after PLAN-900 ships.
• It does not address mobile / responsive behavior inside the workspace shell — only at the bordering surfaces.

---

11. References

• PLAN-900 — Cohesive UX between getpad.dev and Pad Cloud
• IDEA-888 — Original idea this plan implements
• pad-web/src/app.css — canonical token values
• pad-web/src/routes/+layout.svelte — canonical header + footer reference implementation
• web/src/app.css — app-side tokens (currently divergent on bg / text / border / fonts; aligned on accent palette)
• web/src/lib/components/auth/ — auth-page chrome components
• docs/brand/mark/ — the mark's master SVGs (section 9)