feat: adopt the signal-blue Heph identity

.changeset/signal-blue-heph.md

@@ -0,0 +1,5 @@
+---
+"hephaestus": patch
+---
+
+Hephaestus now uses the signal-blue Heph mark across the web app, documentation, README, browser and installable-app icons, and link previews.

.github/workflows/ci-tests.yml

@@ -161,10 +161,11 @@ jobs:
         continue-on-error: true
         run: |
           timeout --kill-after=30s 15m pnpm --filter webapp run test:storybook
-          pnpm --filter webapp run export:readme-assets
-          if [[ -n "$(git status --porcelain --untracked-files=all -- docs/images/readme)" ]]; then
-            echo "::error::README or documentation images are stale. Run 'pnpm --filter webapp run export:readme-assets' and commit the result."
-            git status --short --untracked-files=all -- docs/images/readme
+          pnpm --filter webapp run export:assets
+          BRAND_ASSETS=(webapp/brand webapp/public docs/images/readme docs/static/img/brand docs/static/img/favicon.png docs/static/img/hephaestus-social-card.png docker/compose.proxy.yaml)
+          if [[ -n "$(git status --porcelain --untracked-files=all -- "${BRAND_ASSETS[@]}")" ]]; then
+            echo "::error::Brand assets are stale. Run 'pnpm --filter webapp run export:assets' and commit the result."
+            git status --short --untracked-files=all -- "${BRAND_ASSETS[@]}"
             exit 1
           fi
       - name: Build Storybook with dependency stats

README.md

@@ -1,11 +1,11 @@
 <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">
-  </picture>
-
-  <h1>Hephaestus</h1>
+  <h1>
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="./docs/static/img/brand/hephaestus-lockup-dark.png">
+      <source media="(prefers-color-scheme: light)" srcset="./docs/static/img/brand/hephaestus-lockup-light.png">
+      <img alt="Hephaestus" width="484" src="./docs/static/img/brand/hephaestus-lockup-light.png">
+    </picture>
+  </h1>
   <p><strong>Learn from the work you're already doing</strong></p>
 
   <p>

docker/compose.proxy.yaml

@@ -170,64 +170,10 @@ configs:
           article { display: block; width: 700px; padding: 50px; margin: 0 auto; }
           a { color: #fff; font-weight: bold;}
           a:hover { text-decoration: none; }
-          svg.warning { 
-            width: 75px; 
-            margin-top: 1em; 
-            animation: warning-impact 1s infinite;
-          }
-          svg.hammer { 
-            translate: -135px -35px; 
-            position: absolute; 
-            width: 75px; 
-            margin-top: 1em; 
-            transform-origin: bottom left;
-            animation: hammer-swing 1s infinite;
-          }
-          @keyframes hammer-swing {
-            0% {
-              transform: rotate(0deg);
-            }
-            20% {
-              transform: rotate(-60deg);
-            }
-            30% {
-              transform: rotate(-60deg);
-            }
-            40% {
-              transform: rotate(0deg);
-            }
-            100% {
-              transform: rotate(0deg);
-            }
-          }
-          @keyframes warning-impact {
-            0%, 37% {
-              transform: scale(1) rotate(0deg);
-            }
-            40% {
-              transform: scale(1.3) rotate(15deg);
-            }
-            42% {
-              transform: scale(1.0) rotate(-10deg);
-            }
-            44% {
-              transform: scale(1.2) rotate(5deg);
-            }
-            46%, 100% {
-              transform: scale(1) rotate(0deg);
-            }
-          }
+          svg.brand { width: 96px; }
       </style>
       <article>
-          <div style="position: relative;">
-            <svg class="warning" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 202.24 202.24"><defs><style>.cls-1{fill:#fff;}</style></defs><title>Asset 3</title><g id="Layer_2" data-name="Layer 2"><g id="Capa_1" data-name="Capa 1"><path class="cls-1" d="M101.12,0A101.12,101.12,0,1,0,202.24,101.12,101.12,101.12,0,0,0,101.12,0ZM159,148.76H43.28a11.57,11.57,0,0,1-10-17.34L91.09,31.16a11.57,11.57,0,0,1,20.06,0L169,131.43a11.57,11.57,0,0,1-10,17.34Z"/><path class="cls-1" d="M101.12,36.93h0L43.27,137.21H159L101.13,36.94Zm0,88.7a7.71,7.71,0,1,1,7.71-7.71A7.71,7.71,0,0,1,101.12,125.63Zm7.71-50.13a7.56,7.56,0,0,1-.11,1.3l-3.8,22.49a3.86,3.86,0,0,1-7.61,0l-3.8-22.49a8,8,0,0,1-.11-1.3,7.71,7.71,0,1,1,15.43,0Z"/></g></g></svg>
-            <svg class="hammer" xmlns="http://www.w3.org/2000/svg" preserveAspectRatio="xMidYMid meet" viewBox="0 0 24 24" fill="none"
-              stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
-              <path d="m15 12-8.373 8.373a1 1 0 1 1-3-3L12 9"></path>
-              <path d="m18 15 4-4"></path>
-              <path d="m21.5 11.5-1.914-1.914A2 2 0 0 1 19 8.172V7l-2.26-2.26a6 6 0 0 0-4.202-1.756L9 2.96l.92.82A6.18 6.18 0 0 1 12 8.4V10l2 2h1.172a2 2 0 0 1 1.414.586L18.5 14.5"></path>
-            </svg>
-          </div>
+          <svg class="brand" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128" role="img" aria-label="Hephaestus"><circle cx="64" cy="64" r="64" fill="#315FDC"/><g transform="translate(24 20) scale(3.3333)" fill="none" stroke="#fff" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M12 7.2V3.6"/><circle cx="12" cy="2.8" r="1" fill="#fff"/><rect x="4" y="8" width="16" height="12" rx="3"/><path d="M2 14h2M20 14h2M8.6 13.5h.8M14.6 13.5h.8M9.7 16.8c1.1 1.1 3.5 1.1 4.6 0"/></g></svg>
           <h1>We&rsquo;ll be back soon!</h1>
           <div>
               <p>We&rsquo;re performing some maintenance at the moment. Sorry for the inconvenience.</p>

docs/admin/github-integration.mdx

@@ -45,6 +45,8 @@ Tokens are stored encrypted (AES-256-GCM) per workspace in the database.
 ### GitHub App mode
 
 Create the App at **Settings → Developer settings → GitHub Apps → New GitHub App**
+and use the generated
+[`external-app-icon-1024.png`](/img/brand/external-app-icon-1024.png) as its display image.
 (on your org: `https://github.com/organizations/<org>/settings/apps`).
 
 - **Homepage URL:** `https://<APP_HOSTNAME>`

docs/admin/install.mdx

@@ -121,6 +121,10 @@ Back up `.env` with the database as described in [Backup & Restore](./backup-res
 
 ## 3. Create the GitHub OAuth App (login — mandatory)
 
+Use the generated
+[`external-app-icon-1024.png`](/img/brand/external-app-icon-1024.png) as the application
+logo when the GitHub settings page offers an image upload.
+
 Without a login provider the instance boots but shows **no sign-in button**. GitHub login
 needs a plain **OAuth App** (this is *not* the same thing as the GitHub App used for data
 access — see [GitHub integration](./github-integration)):

docs/admin/production-setup.mdx

@@ -83,6 +83,10 @@ an independent key after the deployment succeeds.
 
 ### Slack app configuration
 
+After creating the app, upload
+[`slack-app-icon-512.png`](/img/brand/slack-app-icon-512.png) as its app icon. Slack applies
+its own corner treatment, so do not round the asset before uploading it.
+
 | Variable | Purpose |
 | --- | --- |
 | `HEPHAESTUS_INTEGRATION_SLACK_ENABLED` | Enables the Slack OAuth admin surface (per-workspace connect). Off by default. |

docs/contributor/brand-assets.mdx

@@ -0,0 +1,59 @@
+---
+title: Brand assets
+---
+
+# Brand assets
+
+Hephaestus uses the solid signal-blue Heph mark for product identity. The bare, animated Heph drawing
+is reserved for the mentor persona.
+
+## Source and generation
+
+`webapp/brand/hephaestus-mark.svg` is the source for the static mark. The React `HephMark` renders
+that file directly. One exporter produces every tracked browser, app, documentation, README,
+social-card, and external-profile asset. It embeds the pinned Inter font so raster output does not
+depend on fonts installed on a contributor's computer:
+
+```bash
+pnpm --filter webapp run export:assets
+```
+
+Do not edit generated files under `webapp/public/`, `docs/images/readme/`, or `docs/static/img/`.
+The exporter also synchronizes the inline maintenance-page mark in `docker/compose.proxy.yaml`. CI
+regenerates all of these outputs and fails when the committed result differs.
+
+Application icons use a tighter optical crop so Heph remains legible at small sizes. Product UI,
+favicons, and maskable icons keep their platform-appropriate spacing.
+
+## Usage
+
+| Context | Asset |
+|---|---|
+| In-app product lockup | `HephaestusLogo` or `HephMark` |
+| Mentor conversation | `HephIcon` |
+| README and documentation navbar | Light/dark lockup PNGs |
+| Browser tab | `favicon.png` |
+| Installed web app | 192px, 512px, and maskable PNGs from `webapp/public/manifest.json` |
+| Link preview | `hephaestus-social-card.png` |
+| Slack app | `docs/static/img/brand/slack-app-icon-512.png` |
+| GitHub App, GitHub OAuth App, and other external profiles | `docs/static/img/brand/external-app-icon-1024.png` |
+| GitHub repository social preview | `docs/static/img/brand/github-repository-social-preview-1280x640.png` |
+
+The static mark remains signal blue (`#315FDC`) in both color modes. UI wordmarks use the
+mode-aware `brand-accent` token from `webapp/src/styles.css`; prose always spells the product name
+“Hephaestus.” Unlabelled React marks are decorative. Informative uses need a concise accessible name.
+
+The README uses [GitHub's theme-aware picture sources](https://github.blog/changelog/2021-11-24-specify-theme-context-for-images-in-markdown/),
+the documentation navbar uses [Docusaurus light/dark logo sources](https://docusaurus.io/docs/api/themes/configuration),
+and the installed-app exports follow the manifest [icon-purpose contract](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/icons)
+and [maskable safe zone](https://web.dev/articles/maskable-icon).
+
+## External surfaces
+
+Generated files do not update third-party accounts. After changing the static mark, maintainers must
+upload the named assets in Slack and GitHub settings. The 1024px external icon is a high-resolution
+master, not a vendor-mandated size; upload controls may resize it. Keep the mark square, without text
+or pre-rounded corners. [Slack renders app logos at 36px on mobile and applies its own corner
+treatment](https://api.slack.com/start/designing#logo_assets). GitHub's
+[repository social-preview settings](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/customizing-your-repositorys-social-media-preview)
+use the separately composed 1280×640 export.

docs/docusaurus.config.ts

@@ -11,7 +11,6 @@ const envBaseUrl = process.env.DOCUSAURUS_BASE_URL;
  */
 const baseUrl = envBaseUrl === undefined || envBaseUrl === "" ? "/" : envBaseUrl;
 
-/** The site's one-sentence definition of the product, kept in step with the README's opening. */
 const DESCRIPTION =
 	"Hephaestus is an open-source AI mentor for software teams. It reads the work developers already do against the practices their project cares about, and writes back feedback they can act on.";
 
@@ -31,7 +30,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 +153,7 @@ const config: Config = {
 	],
 
 	themeConfig: {
-		image: "img/hephaestus-social-card.jpg",
+		image: "img/hephaestus-social-card.png",
 		colorMode: {
 			respectPrefersColorScheme: true,
 			disableSwitch: false,
@@ -171,10 +170,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.png",
+				srcDark: "img/brand/hephaestus-lockup-dark.png",
+				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`.