Ship a world-class brand + design system for the WebJs website

[vivek7405]

Problem

The WebJs website needs a world-class brand and design system comparable to (ideally better than) nextjs.org. A "Velocity" brand direction was started but is sitting UNCOMMITTED in the primary checkout: a new /brand guidelines page (website/app/brand/page.ts), logo assets (website/public/velocity-wordmark.svg, velocity-favicon.svg), a header/footer logo swap (website/app/layout.ts, website/lib/site-footer.ts), a replaced website/public/favicon.svg, glow-token zeroing, and site-wide removal of the KICKER eyebrow labels. That draft has real defects, and beyond it the site's overall design polish needs to be raised to the Vercel/Geist bar. The owner has explicitly authorized changing the theme and color tokens if that produces a better site, and requires the work to be grounded in a PROPER design system (defined tokens and scales applied consistently), not ad-hoc per-page styling.

Reference: Next.js's official brand guidelines live on Vercel's Geist system at https://vercel.com/geist/brands. What they have that we lack: light AND dark logo variants packaged as a real ZIP, a quantified clear-space rule (the symbol's height defines the safety area), name-spelling standards ("Next.js" vs "Next"), and trademark/attribution language.

Design / approach

Adopt and finish the Velocity brand direction, then raise the whole site to it through a real design system:

1. Design system first. Consolidate the site's visual language into an explicit token system in website/app/layout.ts @theme: color roles (bg/surface/border/fg/accent scales in oklch, both themes), a type scale (display/h2/lede/body/mono with fixed leading and tracking), a spacing rhythm, radii, and shadow/glow rules. The claude.ai/design project named webjs design system holds the direction (check the DesignSync tool); every page then consumes tokens only, no page-local magic values that fight the system.
2. Fix the logo assets. The wordmark SVG is 76KB because it embeds a base64 woff2 and renders live text; convert to outlined paths (~1-2KB). Produce explicit light-background and dark-background variants of both wordmark and monogram (the site currently fakes light mode with CSS invert). Ship a real downloadable brand package (ZIP of all variants) instead of the current single-SVG "Download Brand Package" link.
3. Fix the /brand page content. Cyan-vs-amber copy bug (prose says "electric cyan accents", swatches are warm amber, the actual direction is warm orange per the 2026-06 redesign direction). Em-dash (U+2014) in prose at website/app/brand/page.ts:64 violates AGENTS.md invariant 11. Add a quantified clear-space spec (e.g. the W cap-height as minimum padding, with a diagram). Add a "Writing the name" section codifying the existing brand-casing rule from invariant 11 (WebJs in prose, webjs only as a code token) plus short trademark language, since the page metadata already promises "trademark guidelines". Align swatch values with the live oklch tokens in website/app/layout.ts (the page hand-writes hex like #E59500 while the tokens are oklch, drift risk).
4. Site-wide design elevation. Free rein on theme/tokens (owner-approved). Compare each page against nextjs.org quality: hero, feature grid, code samples, docs shell, blog/articles/changelog hubs, /ui gallery. Keep the dark-first + light translation, warm accent direction unless a better system emerges.
5. Housekeeping. Add /brand to staticRoutes in website/app/sitemap.ts (around L41). Remove website/public/logo-concept-a.jpg (249KB) and logo-concept-b.jpg (681KB), publicly-served exploration artifacts. Unify the two wordmark download filenames (webjs-wordmark.svg vs webjs-velocity-wordmark.svg).

Related, NOT superseded: #1064 (cross-app design consistency), #1116 (Refactoring-UI-grounded design guidance), #1000 (closed website-redesign exploration app).

Implementation notes (for the implementing agent)

• The draft work is uncommitted in the PRIMARY checkout on main (hook-blocked for edits; it must stay a mirror of main). Copy the draft into your task worktree (e.g. git diff > patch + apply, plus the untracked website/app/brand/ and website/public/velocity-*.svg files), then leave the primary checkout alone. A parallel website-redesign worktree may exist from another agent, do not touch it.
• Where to edit: website/app/brand/page.ts (the whole brand page), website/app/layout.ts (theme tokens ~L250-300, header ~L365), website/lib/site-footer.ts, website/public/ (assets), website/app/sitemap.ts staticRoutes (~L41), website/app/page.ts and the other page files for the site-wide polish.
• Landmines: the prose-punctuation hook (.claude/hooks/block-prose-punctuation.sh) blocks em-dashes and enforces brand casing on new content, so drafting copy with U+2014 will be rejected at edit time. website/package.json sets "webjs": { "seed": false }, keep it. A fresh worktree has no node_modules, symlink from the primary checkout or npm install. The site is dark-first; every token change must hold in BOTH themes (prefers-color-scheme + the explicit theme toggle). The favicon has a prior defect history (seo: rank first for "what is webjs" across site, repo, and Pages #1088: declared 32x32 on a mismatched asset), get the sizes right. The components/ui/ and lib/ui/ dirs are gitignored mirrors, never hand-edit.
• Invariants: AGENTS.md invariant 11 (no em-dash prose, brand casing), invariant 8 (only the root layout writes the shell), the website AGENTS.md (light DOM + Tailwind + @theme tokens; sections as <section> wrappers; sitemap/robots/llms.txt generate from live queries so a new static page needs the staticRoutes entry only).
• Tests + docs: run the website's own checks (cd website && webjs check), boot it and eyeball every page (npm run dev, port 5001). CI boots blog+website; verify the changelog COPY line still works if assets move. If the brand page ships, sync doc surfaces per the webjs-doc-sync skill (the marketing site is itself the surface here; README/AGENTS.md only if the public API story changes, likely not).

Acceptance criteria

• A coherent token-based design system is defined in the root layout @theme (color roles, type scale, spacing, radii, shadows) and pages consume tokens rather than page-local magic values
• Wordmark SVG is outlined paths, no embedded font, under ~5KB; light + dark variants of wordmark and monogram exist
• "Download Brand Package" delivers a real ZIP with all variants
• /brand has a quantified clear-space rule, a naming/casing section, and trademark language; no cyan copy, no em-dash
• Brand swatches match the live tokens in layout.ts (stated in oklch or provably equal)
• /brand is in the sitemap; concept JPGs removed
• Site-wide pass reviewed against nextjs.org quality in BOTH themes; header/footer/favicon coherent with the final logo
• webjs check clean; site boots and every page renders in dev

[vivek7405]

Duplicate of #1178, both filed within the same minute and identical in scope. The work shipped in #1179 (merged into main), which already closed #1178 via its PR body. Closing this one as a duplicate rather than reopening tracking for already-shipped work.