Merge pull request #47 from btravstack/codex/refresh-project-brand

feat: introduce framework-first website and illustrated logo family

Author: btravers

.changeset/coherent-beetroot-brand.md

@@ -0,0 +1,5 @@
+---
+"@btravstack/theme": patch
+---
+
+Refresh the shared ecosystem attribution mark to match the coordinated beetroot logo family.

.hallmark/log.json

@@ -1,4 +1,13 @@
 [
+  {
+    "date": "2026-10-07",
+    "scope": "app",
+    "macrostructure": "Ecosystem Index (framework first)",
+    "theme": "Beetroot Stack",
+    "brief": "Framework-first homepage, corrected DI links, illustrated SVG mascots preserving the approved beetroot artwork and project motifs, refreshed social previews",
+    "nav": "N1b",
+    "footer": "Ft3 index"
+  },
   {
     "date": "2026-07-16",
     "macrostructure": "Ecosystem Index (extended)",
@@ -54,4 +63,4 @@
     "footer": "Ft4 dense colophon",
     "brief": "btravstack org rebrand v1 \u2014 Beetroot Riso (REJECTED by user; PR #27)"
   }
-]
+]

README.md

@@ -18,7 +18,7 @@ pnpm build        # builds the theme, then the website
 ## How it fits together
 
 - **`@btravstack/theme`** wraps VitePress's default theme with the btravstack
-  design tokens (beetroot brand, Montserrat + JetBrains Mono, light/dark
+  design tokens (beetroot brand, Geist + JetBrains Mono, light/dark
   surfaces). Every btravstack site — this website and the `amqp-contract` /
   `temporal-contract` / `unthrown` docs — depends on it, so they all share one
   look. It's built with `tsdown` and published to npm via `.github/workflows/release.yml`
@@ -31,3 +31,27 @@ pnpm build        # builds the theme, then the website
 Add a changeset (`pnpm changeset`), merge to `main`; the Release workflow opens
 a version PR and, when merged, publishes `@btravstack/theme`. Consumers bump the
 dependency to adopt it.
+
+## Website and framework
+
+The domain root introduces the ecosystem, with the btravstack framework as
+its main entry point. Framework tutorials and reference stay at
+[/btravstack/](https://btravstack.github.io/btravstack/); independently usable
+libraries keep their own documentation URLs.
+
+## Brand assets
+
+The illustrated family keeps the approved smiling beetroot, soft shading, and
+each project’s original motif. The exact approved framework PNG is retained at
+`apps/website/public/logos/framework.png` alongside its native SVG redrawing.
+
+Run `pnpm brand` to regenerate the SVG family in `apps/website/public/logos`
+and the shared theme's attribution mark. The source and palette live in
+`scripts/generate-brand.mjs`; usage is documented in [design.md](design.md).
+
+[The logo proof sheet](branding/logo-family.png) shows light/dark variants and
+small sizes. The editable [social card](branding/social-card.html) accepts
+`?project=btravstack` (or `framework`, `unthrown`, `entity`, `amqp-contract`,
+`temporal-contract`, `tools`, `theme`). Render at 1200 × 630 with device scale
+factor 1 after its fonts and images load. Exports live under
+`apps/website/public/og-*.png`; project repositories carry local copies.

apps/website/.vitepress/config.ts

@@ -1,14 +1,15 @@
 import { defineConfig } from "vitepress";
+import { documentedProjects } from "./projects";
 
 const SITE_TITLE = "BtravStack";
 const SITE_DESCRIPTION =
-  "Type-safe building blocks for the TypeScript backend: contracts for AMQP & Temporal, typed dependency injection, and errors as values.";
+  "A TypeScript backend framework and focused libraries for typed errors, domain entities, dependency injection, AMQP and Temporal.";
 const SITE_URL = "https://btravstack.github.io";
 
 // https://vitepress.dev/reference/site-config
 export default defineConfig({
   title: SITE_TITLE,
-  titleTemplate: "An expressive, robust TypeScript backend",
+  titleTemplate: "A backend that fits together",
   description: SITE_DESCRIPTION,
   lang: "en-US",
   // user/org site (btravstack.github.io) is served from the domain root
@@ -35,13 +36,13 @@ export default defineConfig({
     ["meta", { property: "og:type", content: "website" }],
     ["meta", { property: "og:site_name", content: SITE_TITLE }],
     ["meta", { property: "og:locale", content: "en_US" }],
-    ["meta", { property: "og:title", content: `${SITE_TITLE} — an expressive, robust TypeScript backend` }],
+    ["meta", { property: "og:title", content: `${SITE_TITLE} — a backend that fits together` }],
     ["meta", { property: "og:description", content: SITE_DESCRIPTION }],
     ["meta", { property: "og:url", content: `${SITE_URL}/` }],
     ["meta", { property: "og:image", content: `${SITE_URL}/og-btravstack.png` }],
     ["meta", { property: "og:image:type", content: "image/png" }],
-    ["meta", { property: "og:image:width", content: "1280" }],
-    ["meta", { property: "og:image:height", content: "640" }],
+    ["meta", { property: "og:image:width", content: "1200" }],
+    ["meta", { property: "og:image:height", content: "630" }],
     [
       "meta",
       {
@@ -52,7 +53,7 @@ export default defineConfig({
 
     // Twitter Card
     ["meta", { name: "twitter:card", content: "summary_large_image" }],
-    ["meta", { name: "twitter:title", content: `${SITE_TITLE} — an expressive, robust TypeScript backend` }],
+    ["meta", { name: "twitter:title", content: `${SITE_TITLE} — a backend that fits together` }],
     ["meta", { name: "twitter:description", content: SITE_DESCRIPTION }],
     ["meta", { name: "twitter:image", content: `${SITE_URL}/og-btravstack.png` }],
     [
@@ -63,7 +64,7 @@ export default defineConfig({
       },
     ],
 
-    // JSON-LD: the org, the site, and the three packages it publishes
+    // Organization and project metadata share the visible project index.
     [
       "script",
       { type: "application/ld+json" },
@@ -95,59 +96,30 @@ export default defineConfig({
         "@context": "https://schema.org",
         "@type": "ItemList",
         name: "BtravStack packages",
-        itemListElement: [
-          {
-            "@type": "ListItem",
-            position: 1,
-            item: {
-              "@type": "SoftwareApplication",
-              name: "amqp-contract",
-              applicationCategory: "DeveloperApplication",
-              operatingSystem: "Cross-platform",
-              url: "https://btravstack.github.io/amqp-contract/",
-              description: "Type-safe contracts for AMQP & RabbitMQ.",
-            },
+        itemListElement: documentedProjects.map((project, index) => ({
+          "@type": "ListItem",
+          position: index + 1,
+          item: {
+            "@type": "SoftwareApplication",
+            name: project.name,
+            applicationCategory: "DeveloperApplication",
+            operatingSystem: "Cross-platform",
+            url: project.docs,
+            description: project.blurb,
           },
-          {
-            "@type": "ListItem",
-            position: 2,
-            item: {
-              "@type": "SoftwareApplication",
-              name: "temporal-contract",
-              applicationCategory: "DeveloperApplication",
-              operatingSystem: "Cross-platform",
-              url: "https://btravstack.github.io/temporal-contract/",
-              description: "Type-safe contracts for Temporal.io.",
-            },
-          },
-          {
-            "@type": "ListItem",
-            position: 3,
-            item: {
-              "@type": "SoftwareApplication",
-              name: "unthrown",
-              applicationCategory: "DeveloperApplication",
-              operatingSystem: "Cross-platform",
-              url: "https://btravstack.github.io/unthrown/",
-              description: "Explicit errors as values, for TypeScript.",
-            },
-          },
-        ],
+        })),
       }),
     ],
   ],
 
   themeConfig: {
     logo: { light: "/logos/btravstack-light.svg", dark: "/logos/btravstack-dark.svg" },
     nav: [
-      { text: "Packages", link: "/#packages" },
+      { text: "Framework", link: "/#framework" },
+      { text: "Libraries", link: "/#packages" },
       {
         text: "Docs",
-        items: [
-          { text: "amqp-contract", link: "https://btravstack.github.io/amqp-contract/" },
-          { text: "temporal-contract", link: "https://btravstack.github.io/temporal-contract/" },
-          { text: "unthrown", link: "https://btravstack.github.io/unthrown/" },
-        ],
+        items: documentedProjects.map((project) => ({ text: project.name, link: project.docs })),
       },
     ],
     socialLinks: [{ icon: "github", link: "https://github.com/btravstack" }],

apps/website/.vitepress/projects.ts

@@ -0,0 +1,57 @@
+export const framework = {
+  name: "btravstack",
+  docs: "https://btravstack.github.io/btravstack/",
+  tutorial: "https://btravstack.github.io/btravstack/tutorial/getting-started",
+  repo: "https://github.com/btravstack/btravstack",
+  blurb: "A TypeScript application kernel and starters for HTTP, Temporal and AMQP, with typed wiring and graceful shutdown.",
+};
+
+export const projects = [
+  {
+    key: "unthrown", tag: "Errors", name: "unthrown", pkg: "unthrown",
+    logo: "/logos/unthrown",
+    blurb: "Expected failures in the return type. A separate defect channel keeps unexpected failures visible without mixing them into your application errors.",
+    points: ["Errors as values, typed in E", "A separate defect channel", "Zero runtime dependencies"],
+    install: "pnpm add unthrown",
+    repo: "https://github.com/btravstack/unthrown", docs: "https://btravstack.github.io/unthrown/",
+  },
+  {
+    key: "entity", tag: "Domain", name: "entity", pkg: "@btravstack/entity",
+    logo: "/logos/entity",
+    blurb: "Declare your domain once. Derive types and request/response schemas from a field map, with sealed construction and behavior that stays with the entity.",
+    points: ["Branded fields and immutable data", "Sealed construction, enforced invariants", "Result instead of throws"],
+    install: "pnpm add @btravstack/entity",
+    repo: "https://github.com/btravstack/btravstack/tree/main/packages/entity", docs: "https://btravstack.github.io/btravstack/entity/",
+  },
+  {
+    key: "di", tag: "Wiring", name: "di", pkg: "@btravstack/di",
+    logo: "/logos/di",
+    blurb: "Declare ports, bind providers, compose modules. Check the wiring before the process starts and keep implementation details private. Part of the framework; usable on its own.",
+    points: ["Ports named by the domain, not the adapter", "Unmet dependencies are compile errors", "Scoped resources release themselves"],
+    install: "pnpm add @btravstack/di unthrown",
+    repo: "https://github.com/btravstack/btravstack/tree/main/packages/di", docs: "https://btravstack.github.io/btravstack/reference/di/",
+  },
+  {
+    key: "amqp", tag: "Messaging", name: "amqp-contract", pkg: "@amqp-contract/contract",
+    logo: "/logos/amqp-contract",
+    blurb: "Type-safe contracts for AMQP & RabbitMQ. Define your exchanges, queues and messages once — get types and runtime validation on both ends.",
+    points: ["End-to-end type safety", "Reliable retry with Dead Letter Queues", "AsyncAPI 3.0 generation"],
+    install: "pnpm add @amqp-contract/contract",
+    repo: "https://github.com/btravstack/amqp-contract", docs: "https://btravstack.github.io/amqp-contract/",
+  },
+  {
+    key: "temporal", tag: "Workflows", name: "temporal-contract", pkg: "@temporal-contract/contract",
+    logo: "/logos/temporal-contract",
+    blurb: "Type-safe contracts for Temporal.io. End-to-end types and automatic validation across workflows, activities and clients.",
+    points: ["Zod validation at every boundary", "Compile-time implementation checks", "Result / Future error handling"],
+    install: "pnpm add @temporal-contract/contract",
+    repo: "https://github.com/btravstack/temporal-contract", docs: "https://btravstack.github.io/temporal-contract/",
+  },
+];
+
+export const tooling = [
+  { name: "tools", logo: "/logos/tools", description: "Shared configs and workflows for building and shipping TypeScript.", repo: "https://github.com/btravstack/tools" },
+  { name: "@btravstack/theme", logo: "/logos/theme", description: "The VitePress theme and design tokens behind these docs.", repo: "https://github.com/btravstack/btravstack.github.io/tree/main/packages/theme" },
+];
+
+export const documentedProjects = [framework, ...projects];