refactor(webapp): harden brand asset ownership

Author: FelixTJDietrich

.changeset/brand-review-board.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.

.changeset/signal-blue-heph.md

@@ -162,11 +162,18 @@ jobs:
         run: |
           timeout --kill-after=30s 15m pnpm --filter webapp run test:storybook
           pnpm --filter webapp run export:readme-assets
+          pnpm --filter webapp run export:brand-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
             exit 1
           fi
+          BRAND_ASSETS=(webapp/brand webapp/public docs/static/img/brand docs/static/img/favicon.png docs/static/img/hephaestus-social-card.png)
+          if [[ -n "$(git status --porcelain --untracked-files=all -- "${BRAND_ASSETS[@]}")" ]]; then
+            echo "::error::Brand assets are stale. Run 'pnpm --filter webapp run export:brand-assets' and commit the result."
+            git status --short --untracked-files=all -- "${BRAND_ASSETS[@]}"
+            exit 1
+          fi
       - name: Build Storybook with dependency stats
         run: |
           pnpm --filter webapp run build-storybook

.github/workflows/ci-tests.yml

@@ -1,9 +1,11 @@
 <div align="center">
-  <picture>
-    <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>
+    <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" height="100" src="./docs/static/img/brand/hephaestus-lockup-light.png">
+    </picture>
+  </h1>
   <p><strong>Learn from the work you're already doing</strong></p>
 
   <p>

README.md

@@ -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 0M6.8 15.2h.6M16.6 15.2h.6"/></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>

docker/compose.proxy.yaml

@@ -4,50 +4,44 @@ title: Brand assets
 
 # Brand assets
 
-Hephaestus uses one identity system:
+Hephaestus uses the solid signal-blue Heph mark for product identity. The bare, animated Heph drawing
+is reserved for the mentor persona.
 
-- 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.
+## Source and generation
 
-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:
+`webapp/brand/hephaestus-mark.svg` is the source for the static mark. The React `HephMark` renders
+that file directly. `webapp/scripts/export-brand-assets.ts` produces the tracked browser, app,
+documentation, README, social-card, and external-profile assets:
 
 ```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.
+Do not edit generated files under `webapp/public/` or `docs/static/img/`. CI regenerates them and
+fails when the committed output differs.
 
-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
+## Usage
 
 | 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` |
+| 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 declared in the manifest |
-| GitHub App or another external profile | `hephaestus-app-icon-1024.png` |
+| Installed web app | 192px, 512px, and maskable PNGs from `webapp/public/manifest.json` |
 | Link preview | `hephaestus-social-card.png` |
+| GitHub App profile | `docs/static/img/brand/github-app-icon-1024.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
 
-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).
+Generated files do not update third-party accounts. After changing the static mark, a repository
+maintainer must upload `github-app-icon-1024.png` in the GitHub App settings.

docs/contributor/brand-assets.mdx

@@ -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.";
 
@@ -173,8 +172,8 @@ const config: Config = {
 		navbar: {
 			logo: {
 				alt: "Hephaestus",
-				src: "img/brand/hephaestus-lockup-light.svg",
-				srcDark: "img/brand/hephaestus-lockup-dark.svg",
+				src: "img/brand/hephaestus-lockup-light.png",
+				srcDark: "img/brand/hephaestus-lockup-dark.png",
 				width: 155,
 				height: 32,
 			},