feat(webapp): unify Hephaestus brand identity

Author: FelixTJDietrich

.changeset/brand-review-board.md

@@ -1,4 +1,5 @@
 ---
+"hephaestus": patch
 ---
 
-No release note: this adds a Storybook-only brand review board and does not change the shipped application.
+Gives Hephaestus one consistent identity across the application, documentation, README, browser icons, installable app icons, and social previews.

README.md

@@ -1,11 +1,9 @@
 <div align="center">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="./docs/static/img/brand/hammer_bg_dark.svg">
-    <source media="(prefers-color-scheme: light)" srcset="./docs/static/img/brand/hammer_bg.svg">
-    <img alt="" height="100" src="./docs/static/img/brand/hammer_bg.svg">
+    <source media="(prefers-color-scheme: dark)" srcset="./docs/static/img/brand/hephaestus-lockup-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="./docs/static/img/brand/hephaestus-lockup-light.svg">
+    <img alt="Hephaestus" height="100" src="./docs/static/img/brand/hephaestus-lockup-light.svg">
   </picture>
-
-  <h1>Hephaestus</h1>
   <p><strong>Learn from the work you're already doing</strong></p>
 
   <p>

docs/contributor/brand-assets.mdx

@@ -0,0 +1,53 @@
+---
+title: Brand assets
+---
+
+# Brand assets
+
+Hephaestus uses one identity system:
+
+- the **solid signal-blue Heph mark** for product identity, app icons, favicons, and external profiles;
+- the **Heph-accent wordmark** for lockups; and
+- the bare, animated Heph drawing only when Heph is acting as the mentor persona.
+
+The vector sources live in `webapp/brand/`. Do not edit the copies or PNG derivatives under
+`webapp/public/` or `docs/static/img/` directly. Regenerate them with:
+
+```bash
+pnpm --filter webapp run export:brand-assets
+```
+
+The solid mark keeps `#315FDC` in both color modes. UI text uses the mode-aware `brand-accent` token,
+so the wordmark remains legible on dark surfaces. Product prose always spells the name normally as
+“Hephaestus”; the accent is visual identity, not punctuation or a new product name.
+
+White on signal blue has a 5.52:1 contrast ratio. This clears the WCAG 2.2 AA threshold for normal
+text and the mark's essential shapes clear the 3:1 non-text threshold; see the W3C guidance for
+[text contrast](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html) and
+[non-text contrast](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html).
+
+## Choosing an asset
+
+| Context | Asset |
+|---|---|
+| App header, sign-in, product page | React `HephaestusLogo` or `HephMark` |
+| Mentor conversation | React `HephIcon` |
+| README | Theme-aware lockup SVGs |
+| Documentation navbar | Docusaurus `logo.src` and `logo.srcDark` |
+| Browser tab | `favicon.png` |
+| Installed web app | 192px, 512px, and maskable PNGs declared in the manifest |
+| GitHub App or another external profile | `hephaestus-app-icon-1024.png` |
+| Link preview | `hephaestus-social-card.png` |
+
+These choices follow the native surfaces rather than adding theme-detection code: GitHub supports
+[theme-specific README pictures](https://github.blog/changelog/2021-11-24-specify-theme-context-for-images-in-markdown/),
+Docusaurus supports [`favicon`, `logo.src`, and `logo.srcDark`](https://docusaurus.io/docs/api/themes/configuration),
+and web app manifests support icon sizes and purposes including
+[`maskable`](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/icons).
+The maskable export keeps the drawing inside the platform
+[safe zone](https://web.dev/articles/maskable-icon). Decorative copies use empty alternative text or
+are hidden from assistive technology; informative images follow the
+[W3C image text-alternative guidance](https://www.w3.org/WAI/tutorials/images/).
+Opaque app-icon exports also follow Apple's guidance to keep icons simple and recognizable and to
+let each platform apply its own mask; see the
+[Apple app-icon guidance](https://developer.apple.com/design/human-interface-guidelines/app-icons).

docs/docusaurus.config.ts

@@ -31,7 +31,7 @@ function rawMermaidSourcePlugin(_context: LoadContext): Plugin {
 const config: Config = {
 	title: "Hephaestus Documentation",
 	tagline: "Learn from the work you're already doing",
-	favicon: "img/favicon.ico",
+	favicon: "img/favicon.png",
 
 	future: {
 		v4: true,
@@ -154,7 +154,7 @@ const config: Config = {
 	],
 
 	themeConfig: {
-		image: "img/hephaestus-social-card.jpg",
+		image: "img/hephaestus-social-card.png",
 		colorMode: {
 			respectPrefersColorScheme: true,
 			disableSwitch: false,
@@ -171,10 +171,12 @@ const config: Config = {
 			{ name: "twitter:description", content: DESCRIPTION },
 		],
 		navbar: {
-			title: "Hephaestus",
 			logo: {
-				alt: "Hephaestus logo",
-				src: "img/hammer.svg",
+				alt: "Hephaestus",
+				src: "img/brand/hephaestus-lockup-light.svg",
+				srcDark: "img/brand/hephaestus-lockup-dark.svg",
+				width: 155,
+				height: 32,
 			},
 			items: [
 				{

docs/sidebars.contributor.ts

@@ -18,6 +18,7 @@ const sidebars: SidebarsConfig = {
 				"accessibility-audit-plan",
 				"security-mutation-testing",
 				"coding-guidelines",
+				"brand-assets",
 				"api-error-handling",
 				"workspace-context",
 				"ai-agent-workflow",

docs/src/css/custom.css

@@ -41,10 +41,6 @@
 	--docusaurus-highlighted-code-line-bg: oklch(0.546 0.245 262.881 / 0.18);
 }
 
-[data-theme="dark"] .navbar__logo img {
-	filter: invert(1);
-}
-
 /*
  * Every override below re-points an Infima default at a value the web app already uses.
  * `scripts/check-docs-tokens.ts` pins the ones copied from `webapp/src/styles.css`.