forge-vs-brand-kit-strategy-2026-04-16

Strategy: The Forge (Next.js) vs brainforge-brand-kit (Astro)

Date: 2026-04-16
Status: Adopted for engineering alignment (not a legal/commercial decision record).

Facts

	The Forge (apps/platform)	brand-kit (component-library)
Runtime	Next.js App Router, React 19	Astro 5, static output
UI stack	MUI + Tailwind 4 (globals.css, minimal @theme)	Tailwind 4 + semantic CSS + .astro primitives
Design source	src/app/globals.css, MUI theme, CopilotKit overrides	src/styles/*.css + themes/brainforge.css
Components	React (src/components/**)	.astro only

Astro components cannot be dropped into the Forge without a rewrite to React or a separate iframe/microfrontend (usually not worth it for internal tools).

Decisions

1. Marketing sites, client microsites, “demo in a box”
   Use brand-kit as-is: clone or submodule component-library, ship static dist, keep tokens in CSS as upstream defines.

2. The Forge

   • Default: Keep improving existing React + MUI + Tailwind patterns; do not fork a second full design system.
   • Token parity (optional, incremental): When a screen should match marketing, pull semantic names and values from themes/brainforge.css into Forge @theme / CSS variables deliberately (same --accent meaning, same off-white root), then map to MUI where needed.
   • New shared package: Only if multiple apps need identical tokens; extract CSS variables to a small @brainforge/theme (or copy-on-build) — future work; not required to ship individual features.

3. Agents

   • On Astro repos: constrain to brainforge-brand-kit-allowed-surface-2026-04-16.md.
   • On Forge: constrain to existing MUI + globals.css tokens; ESLint warns on arbitrary px / hex bracket classes (eslint.config.mjs).

Out of scope (for this note)

• Replacing MUI across the Forge with Astro (not planned here).
• Publishing brand-kit to npm (possible later; current consumption is source reference).

References

• Map: brainforge-brand-kit-map-2026-04-16.md
• Allowed surface: brainforge-brand-kit-allowed-surface-2026-04-16.md
• Agent playbook: ui-agent-design-contracts-playbook-2026-04-16.md