read-only

Recalibrate the Dossier brand identity — demote color, promote type + restraint + craft — then build the showcase landing

0018-brand-identity-recalibration

decision read as Explain confidence asserted status active 2026-06-15 owner ux-engineer
Reversibility
two-way door

DEC-0018 — Brand-identity recalibration & the showcase landing

Status: Phase 1 + 2 BUILT & VERIFIED (dogfooded on our own site), 2026-06-15. The approved direction below is now realized in code: @dossier/design recalibrated (stone base, demoted clay, mono identity, editorial card — drift-test green) and packages/site shipped a showcase landing at / with ClientRouter page transitions. confidence: asserted is kept deliberately — the work is built and verified green (pnpm test 268 passed / 1 skipped, astro build 27 pages, light+dark confirmed via Playwright), but not yet user/market-validated. The evidence behind the direction is Brand Identity & Premium-Surface Research — June 2026; sub-decisions #1 and #4 are now resolved, #2 (type licensing) and #3 (commissioned logomark) remain open; see the Review update — 2026-06-15 at the end.

Context

Establish the design system and the UX-engineering function set the design language — tokens-first, with "warm-paper neutrals + a clay/terracotta signature accent." Astro Starlight as the docs-site generator + the product-owner, starlight-engineer, and documentation-engineer functions built the Astro Starlight surface (@dossier/site) that renders it. On reviewing the live surface, the user's verdict: the warm-editorial direction fits the use case, but the execution is "lackluster / too plain" and carries "too much of a pink/brown tint."

A deep-research pass (Brand Identity & Premium-Surface Research — June 2026 — 5 angles, 22 sources, 101 claims → 25 adversarially verified → 19 confirmed / 6 refuted) studied the polish bar the user chose: Anthropic (warm/editorial/restrained), institutional/editorial/archive systems, docs-as-product (Stripe/Mintlify/Scalar), and frontier software (Linear/Vercel/Resend). This decision records the resulting direction and the sequenced plan; the user chose identity foundations first, then the marketing/showcase landing.

The core insight (the why)

Premium "warm + intelligent" brands get their warmth from type strategy + editorial restraint + craft, NOT color saturation. Anthropic's own brand team states they balance a "bookish" serif against a "synthetic" sans precisely to escape cold AI visual conventions, with a single warm accent used sparingly (Brand Identity & Premium-Surface Research — June 2026 §2). Dossier's pink/brown wash is the opposite failure: the clay accent (#CC785C) is both the brand signature and over-applied (links, tinted surface washes, badge fills, the favicon) over warm-cream paper — saturation doing the work craft should do. The fix is to demote color and promote type + restraint + craft — not to pick a new warm color.

Options considered

  1. Elevate the current palette as-is — keep warm-paper/clay, just polish — rejected: it keeps the pink/brown wash that is the actual complaint.
  2. Full rebrand to a cooler frontier-tech idiom — deferred: bigger than needed, and the user likes the warm-editorial soul; throwing it out would discard a fit that already works.
  3. Recalibrate (chosen) — neutralize the base, demote the accent, and add a real identity + craft, keeping DEC-0010's architecture intact.

Decision

Option 3 — recalibrate, don't rebrand. The approved plan, foundations first:

Palette recalibration (@dossier/design)

In src/tokens/color.ts, then regenerate the drift-tested styles/dossier.css (which propagates to the site via the existing bridge.css --sl-* → --ds-* aliasing):

  • Near-monochrome warm-neutral base — low-chroma "stone," not cream-pink.
  • A single demoted accent — a deepened clay (≈ #B5603F) reserved for links / primary CTA / focus / the decision concept type only.
  • Remove the clay surface washes.
  • Monochrome wordmark — never accent-colored.
  • A sophisticated low-chroma warm dark canvas.

This revises DEC-0010's palette values/usage, not its architecture — the tokens-first SSOT, two-tier color, light/dark ColorRoles enforcement, and the CSS drift test all stand (Establish the design system and the UX-engineering function).

Three-tier identity (Linear model)

Wordmark (primary) + logomark (tight layouts) + icon/chip (social). A pure typographic wordmark with one coded detail evoking archive/loop (Anthropic model). Monochrome on light and dark.

Role-based type (formalize what the tokens already gesture at)

Serif = display headlines (especially the dark editorial cards); sans = all UI + body; mono = metadata / OKF ids / classification only.

Motion language

Astro <ClientRouter /> for near-zero-config site-wide page transitions (+ transition:persist on the wordmark). Motion-for-React scroll techniques reserved for the landing.

Diagram / illustration language

A visual vocabulary for the abstract concepts (learning loop, knowledge graph, provenance), plus dynamic OG/social cards (Astro + Satori) so shared / agent-quoted pages render branded.

Then the marketing/showcase landing

Centered hero + the verified five-section dev-tool anatomy (hero → trust → features → social proof → final CTA) + a "how it works" diagram. First hero = a code-snippet of real OKF Markdown+YAML ("your institutional memory is just files in your git"). An abstract animated "learning loop" visual as the second-pass signature. Built on a Starlight splash/custom (blank-canvas) layout.

Rationale

Each move is grounded in a verified finding (Brand Identity & Premium-Surface Research — June 2026):

  • Near-monochrome neutral base + a single demoted accent reserved for backgrounds, a monochrome wordmark, a three-tier logo — Linear brand guidelines (§1). We copy the structure and swap in warm stone/clay (Linear's own hue is cool).
  • Warmth from type, not tint — Anthropic brand-team interview + the Geist case study (§2).
  • Two-tier / role-based type — editorial-institutional practice (§3, role structure only).
  • Centered hero + five-section anatomy + code-snippet / abstract hero for infra products — the Evil Martians n=100 dev-tool study (§4).
  • Scroll motion via Motion useTransform — the Vercel engineering blog (§5).
  • Shippable on the existing stack — Astro <ClientRouter />, Starlight customCss + unlayered override + the live color-theme editor (§6).

Ties to the non-negotiables: sovereignty (Adopt OKF as Dossier's canonical knowledge format) — the surface stays a derived, replaceable view over the OKF git repo, and the identity is portable; we are not binding the brand to a proprietary surface.

Consequences

Open sub-decisions (deferred — lock before/at execution)

  1. RESOLVED / built (2026-06-15). The exact recalibrated token set + WCAG AA: the paper ramp was neutralized warm-cream/brown → low-chroma warm stone (every step changed; bg #F4F1E9→#F4F4F1, text #26211A→#23231F, dark bg #1A1611→#181815); accent deepened #B5603F→#AD5C3A, which fixed a pre-existing WCAG AA miss (white-on-accent 4.46 → 4.81). AA verified on real token values (text/bg 14.31 light / 16.15 dark; textMuted 7.50/7.69; white onAccent 4.81; link 5.86/7.74). See the Review update.
  2. RESOLVED (2026-06-15) — libre trio adopted, self-hosted. The recommended "assemble from libre faces" path was taken (the "institutions always commission custom type" claim was refuted 0-3 — Brand Identity & Premium-Surface Research — June 2026). The commercial faces (Tiempos Text, Copernicus, Styrene A/B, Berkeley Mono) are dropped from the tokens, replaced by a SIL OFL 1.1 trio — Newsreader (serif), Inter (sans), IBM Plex Mono (mono) — self-hosted, no runtime CDN (sovereignty + privacy): @fontsource-variable/newsreader 5.2.10 + @fontsource-variable/inter 5.2.8 + @fontsource/ibm-plex-mono 5.2.7 (no variable build exists — static weights) in packages/site, wired via Starlight customCss in astro.config.mjs. Family-name tokens in src/tokens/typography.ts now name the registered @font-face faces ("Newsreader Variable" / "Inter Variable" / "IBM Plex Mono") + generic fallbacks; dossier.css regenerated (drift-test green). Verified self-hosted: built dist CSS has 40 @font-face rules + 40 emitted woff2 and zero fonts.googleapis.com/gstatic.com/remote font src. @dossier/design's zero-runtime-deps property holds (opentype.js/wawoff2 are devDeps only).
  3. RESOLVED (2026-06-15) — refined in-house to launch quality (option A). Rather than commission externally, the in-house mark was lifted to launch quality. packages/design/brand/wordmark.svg is now outlined to SVG <path> data (font-independent — the old hard-coded 'Tiempos Text' reference is gone), generated by a new build-side script scripts/build-wordmark.mjs using opentype.js on the self-hosted Newsreader woff2 (font.getPath('Dossier', …)), with a closed loop-ring coded detail beneath the first 'o' (the learning-loop/archive). logomark.svg + favicon.svg were refined to match (archive brackets + loop-D), legible at 16/32px on light+dark; the favicon is mirrored to packages/site/public/favicon.svg. All monochrome currentColor, no accent in the mark (DEC-0018). A build:wordmark script was added to the design package.json.
  4. FULLY RESOLVED (2026-06-15). Both heroes now exist. The recommended code-snippet hero shipped (real OKF Markdown+YAML pulled from The produces edge is canonical on the producing process only) and remains the "proof" beat; the abstract animated learning-loop signature is now built & verified as the hero centerpiece (packages/site/src/components/HeroLoop.astro, between the subhead and the CTAs). Technique is dependency-free inline SVG + scoped CSS — a stroke-dashoffset ring-draw, a clay "pass" token riding the closed ring via CSS offset-path/offset-distance, and a centre knowledge-graph that accretes nodes/edges per pass then resets seamlessly at the loop seam; monochrome stone + the single clay accent, all --ds-* tokens (no new hex, @dossier/design consumed unchanged — no WebGL/Motion/new npm deps, the VoidZero/Vite lean held). It is aria-hidden/decorative (meaning lives in the labelled twin); prefers-reduced-motion: reduce is honored — verified at the emitted-CSS level that every animation declaration sits inside the lone @media (prefers-reduced-motion: no-preference) block (0 outside), so reduce renders an elegant static composition; a vanilla IntersectionObserver pauses motion offscreen and re-binds on astro:page-load (survives ClientRouter). The static labelled loop diagram remains lower as the SR-accessible twin (now lead-framed as "the labelled view of the cycle running in the hero above") — two structurally different artifacts, not a duplicate loop. Build-side only; no knowledge/ file touched. Verified: astro check 0/0 (19 pre-existing Zod z hints only), astro build 27 pages (no new route), pnpm typecheck exit 0, pnpm test 268 passed / 1 skipped on clean runs. (One transient single-test failure occurred on a run under heavy concurrent load — background test + Playwright + preview at once; it did not reproduce on two subsequent clean full runs (both 268/1). The change is additive site markup, so this is assessed as a load-sensitive flaky test, not a regression — worth a separate follow-up, not a blocker.)

Review

Revisit after the recalibrated tokens ship, with a before/after — confirm the pink/brown read is gone and the surface reads premium without forking DEC-0010's system (Establish the design system and the UX-engineering function). Revisit again after landing v1.

Review update — 2026-06-15

Phase 1 + 2 built & verified, dogfooded on our own site. The recalibration and the showcase landing are live in code, reproduced green this session.

Phase 1 — @dossier/design (drift-test green). The paper ramp was neutralized from warm-cream/brown to low-chroma warm stone (every step changed; text-backing mids fixed paper[700] #574E3F→#4F4F47, paper[600] #766B57→#6B6B62; bg #F4F1E9→#F4F4F1, text #26211A→#23231F, dark bg #1A1611→#181815). Clay was demoted to detail-only — the pink surface washes were removed (accentSurface light clay[50]→paper[150], accentBorder light clay[200]→paper[300], dark equivalents to neutral rgba(255,255,255,…)), dark surfaces de-browned to stone; clay kept only for accent/CTA/links/focus/selection + the decision concept hue. accent deepened #B5603F→#AD5C3A, which fixed a pre-existing WCAG AA miss (white-on-accent 4.46 → 4.81); the decision concept hue now tracks the accent exactly (#AD5C3A), the other 12 concept hues unchanged and all 13 still distinct. A monochrome three-tier identity was added — packages/design/brand/{wordmark,logomark,favicon}.svg (all currentColor, one coded detail = a loop-D evoking the learning loop/archive), wired into package exports; packages/site/public/favicon.svg replaced (was the solid clay "D" badge). A new displayEditorial text style + .ds-card--editorial component (dark surface + serif display — a signature "considered document" moment, colors resolved from the token tree, no magic hex) shipped with a before/after A/B in preview/index.html. DEC-0010's architecture is untouched — tokens-first SSOT, two-tier color, ColorRoles, the drift test all stand; only values/usage changed. One test/tokens.test.ts assertion was re-pointed from a frozen #cc785c literal to the invariant decision === clay[600] === accent. AA verified on real token values (text/bg 14.31 light / 16.15 dark; textMuted/bg 7.50/7.69; white onAccent 4.81; link 5.86/7.74).

Phase 2 — packages/site (motion + showcase landing). Astro <ClientRouter /> page transitions were wired the Starlight-correct way: a custom Head component override (src/components/Head.astro, registered in astro.config.mjs components.Head) renders Starlight's default Head then appends ClientRouter — dependency-free (no astro-vtbot), prefers-reduced-motion honored (confirmed in emitted CSS). A new marketing/showcase landing at / ships; the KB index was remapped to /knowledge/ via a derived-route change only (src/content.config.ts generateId + mirror in src/lib/okf-routes.mjs) — no sovereign knowledge/ file touched (DEC-0001 preserved; wiki-links / sidebar still resolve dossier-knowledge-root). The landing follows the verified centered dev-tool anatomy: serif hero ("Your knowledge is just files in your git.") + CTAs + a hero code-snippet of real OKF pulled from The produces edge is canonical on the producing process only; the Nadella north-star verbatim from Dossier — Mission & North Star in a .ds-card--editorial pull-quote; five real value props sourced from mission + README; a static learning-loop diagram (ingest→extract→OKF graph→serve→curate, clay return arc) as inline SVG from --ds-* tokens only with an aria-label; a final CTA. No fabricated social proof — footer honestly states "Build stage, pre-launch." Consumes @dossier/design unchanged (no new hex; wordmark inlined ?raw, stays mono).

Landing-route architecture (decided here). / = the marketing/showcase landing; the OKF KB index moved to /knowledge/ via derived routes only (generateId + the route-map mirror), never by editing a knowledge/ file. ClientRouter is installed via a Head override rather than astro-vtbot or a layout fork. transition:persist on the header wordmark was deliberately skipped — Starlight's Header isn't a clean override slot, so we "skip rather than hack"; it stays an optional follow-up.

Verification (reproduced this session, no fabrication, all build-side): pnpm test 268 passed / 1 skipped (27 files); pnpm typecheck (tsc -b) exit 0; @dossier/design tests 9/9 incl. CSS drift; astro build 27 pages; astro check 0 errors / 0 warnings (19 pre-existing Zod z-deprecation hints in content.config.ts, not ours); pnpm build all 8 packages; light and dark confirmed via Playwright on the live astro preview for the landing, a decision page, and the design preview (measured body bg #F4F4F1 light / #181815 dark — the recalibrated tokens are live). Nothing was added to the client-facing plugin subset.

Confirmed met: the pink/brown read is gone (stone base, washes removed, clay demoted to detail) and the surface reads premium without forking DEC-0010's system (Establish the design system and the UX-engineering function); the recalibration even corrected a latent AA failure. The before/after is shippable.

Update (2026-06-15) — sub-decision #4 fully closed. The deferred half of #4, the abstract animated learning-loop hero, is now built & verified (packages/site/src/components/HeroLoop.astro): a dependency-free inline-SVG + scoped-CSS signature (ring-draw via stroke-dashoffset, a clay "pass" token on the closed ring via offset-path, an accreting-then-reseeding centre knowledge-graph; --ds-* tokens only, no new deps), aria-hidden/decorative with prefers-reduced-motion: reduce honored (all animation inside the lone no-preference block — 0 outside) and a vanilla IntersectionObserver that pauses offscreen and re-binds on astro:page-load. The static labelled diagram stays as the SR-accessible twin. Verified green: astro check 0/0, astro build 27 pages (no new route), pnpm typecheck exit 0, pnpm test 268/1 on clean runs (one transient failure under heavy concurrent load did not reproduce on two clean full runs — assessed a load-sensitive flaky test, not a regression). So #4 is fully resolved (static labelled diagram + abstract animated signature both exist).

Update (2026-06-15) — sub-decisions #2 + #3 closed. #2 (type) is resolved: the commercial faces (Tiempos Text, Copernicus, Styrene A/B, Berkeley Mono) are dropped from the tokens for a SIL OFL 1.1 libre trio — Newsreader / Inter / IBM Plex Mono — self-hosted in packages/site with no runtime CDN (@fontsource packages via Starlight customCss; family-name tokens updated to the registered face names; dossier.css regenerated). Verified self-hosted at the built-CSS level (40 @font-face + 40 woff2, zero remote font src) and verified rendering live (h1 → "Newsreader Variable"…, body → "Inter Variable"… via Playwright on astro preview). #3 (logo) is resolved by refining the mark in-house to launch quality (option A, not commission): wordmark.svg outlined to font-independent <path> data via a new scripts/build-wordmark.mjs (opentype.js on the Newsreader woff2) with a coded loop-ring under the first 'o'; logomark.svg/favicon.svg refined to match (mirrored to packages/site/public/favicon.svg), all monochrome currentColor, no accent. Reverified green: pnpm test 268 passed / 1 skipped on clean runs (design drift+token 9/9); pnpm typecheck exit 0; pnpm build all packages; astro build 27 pages; astro check 0/0 (19 pre-existing Zod-z hints only). With #1–#4 all resolved, the only remaining open items are user/market validation (why confidence stays asserted, not verified), the optional wordmark transition:persist follow-up, and the load-sensitive flaky test (passes on every clean run; fails only as a background job under heavy concurrent load alongside Playwright + preview — a flaky test, not a regression; still un-isolated, worth a separate follow-up).