@opengroundplan/core 0.1.1

package/templates/architectures/micro-frontends/blueprint.yaml

@@ -0,0 +1,124 @@
+id: micro-frontends
+kind: architecture
+name: Micro-Frontends
+description: >-
+  Folder overlay for independently deliverable frontends: a host shell that knows its remotes
+  only by name and URL, one independently built remote, a versioned design-system contract and
+  a host↔remote interface both sides share, a Module Federation 2.0 or native import-map
+  composition boundary, and a zero-dependency check that fails the build when a remote imports
+  the host or a sibling.
+
+tags:
+  - micro-frontends
+  - frontend
+  - module-federation
+  - import-maps
+  - design-system
+  - boundaries
+  - typescript
+
+requires: []
+conflicts: []
+provides:
+  - mfe-layout
+  - composition-boundary
+  - boundary-enforcement
+
+# An overlay is chosen through the architecture question, never listed as a supported target.
+supportsArchitectures: []
+
+variables:
+  # Remotes are the unit of work here, so the layout means nothing without one to show the shape.
+  - name: remoteName
+    prompt: Name of the first remote (a team-owned frontend, e.g. "checkout")
+    type: string
+    default: checkout
+    required: true
+
+  # The composition boundary is the one irreversible decision in this architecture: it fixes
+  # what a remote must publish and what the shell must run. Asked, never guessed.
+  - name: composition
+    prompt: How are remotes composed into the shell?
+    type: select
+    default: module-federation
+    required: true
+    choices:
+      - value: module-federation
+        label: Module Federation 2.0 — negotiated dependency sharing, types across remotes (Rspack, webpack, Vite)
+      - value: import-map
+        label: Native import maps — no runtime dependency, but dependency sharing is yours to manage
+
+files:
+  # ── docs and enforcement ────────────────────────────────────────────────────
+  - from: files/docs/architecture/micro-frontends.md
+    to: .
+    when: "(stack == 'typescript' || stack == 'node')"
+
+  # A boundary rule that lives only in prose gets violated; this fails the build instead.
+  - from: files/scripts/check-mfe-boundaries.mjs
+    to: .
+    when: "(stack == 'typescript' || stack == 'node')"
+
+  # Workspaces, the boundary script, and the federation runtime. Code that imports a package
+  # the manifest never installs does not build.
+  - from: files/package.json
+    to: .
+    onConflict: merge-json
+    when: "(stack == 'typescript' || stack == 'node')"
+
+  # ── host shell ──────────────────────────────────────────────────────────────
+  - from: files/apps/host/package.json
+    to: .
+    when: "(stack == 'typescript' || stack == 'node')"
+  - from: files/apps/host/remotes.example.json
+    to: .
+    when: "(stack == 'typescript' || stack == 'node')"
+  - from: files/apps/host/src/config.ts
+    to: .
+    when: "(stack == 'typescript' || stack == 'node')"
+  - from: files/apps/host/src/remote-loader.ts
+    to: .
+    when: "(stack == 'typescript' || stack == 'node')"
+
+  # One loader per strategy — both satisfy RemoteLoader, so nothing else in the shell changes.
+  - from: files/apps/host/src/loaders/module-federation.ts
+    to: .
+    when: "(stack == 'typescript' || stack == 'node') && composition == 'module-federation'"
+  - from: files/apps/host/src/loaders/import-map.ts
+    to: .
+    when: "(stack == 'typescript' || stack == 'node') && composition == 'import-map'"
+
+  # ── first remote ────────────────────────────────────────────────────────────
+  - from: files/apps/remotes/__remoteName.kebab__/package.json
+    to: .
+    when: "(stack == 'typescript' || stack == 'node')"
+  - from: files/apps/remotes/__remoteName.kebab__/src/**/*
+    to: .
+    when: "(stack == 'typescript' || stack == 'node')"
+
+  # Per-remote federation declaration, fed to @module-federation/enhanced or /vite. Meaningless
+  # under import maps, where the browser does the resolving.
+  - from: files/apps/remotes/__remoteName.kebab__/module-federation.config.mjs
+    to: .
+    when: "(stack == 'typescript' || stack == 'node') && composition == 'module-federation'"
+
+  # ── shared packages — the only code both sides may import ───────────────────
+  - from: files/packages/host-contract/**/*
+    to: .
+    when: "(stack == 'typescript' || stack == 'node')"
+  - from: files/packages/design-system/**/*
+    to: .
+    when: "(stack == 'typescript' || stack == 'node')"
+
+postApply:
+  # A boundary check that is not in `lint` is a boundary check that gets skipped. Appends to
+  # whatever the base's lint script already is, and is a no-op on a second run.
+  - run: node -e "const fs=require('fs'),f='package.json',c='node scripts/check-mfe-boundaries.mjs',p=JSON.parse(fs.readFileSync(f,'utf8'));p.scripts=p.scripts||{};if(!(p.scripts.lint||'').includes(c))p.scripts.lint=p.scripts.lint?p.scripts.lint+' && '+c:c;fs.writeFileSync(f,JSON.stringify(p,null,2)+'\n')"
+    when: "(stack == 'typescript' || stack == 'node')"
+    optional: true
+
+  # The manifest declares the federation runtime for every stack because the loader imports it;
+  # the import-map composition never loads it, so drop it rather than ship an unused dependency.
+  - run: node -e "const fs=require('fs'),f='package.json',p=JSON.parse(fs.readFileSync(f,'utf8'));if(p.dependencies)delete p.dependencies['@module-federation/runtime'];fs.writeFileSync(f,JSON.stringify(p,null,2)+'\n')"
+    when: "(stack == 'typescript' || stack == 'node') && composition == 'import-map'"
+    optional: true

package/templates/architectures/micro-frontends/files/apps/host/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@{{ solutionName | kebab }}/host",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "@{{ solutionName | kebab }}/design-system": "*",
+    "@{{ solutionName | kebab }}/host-contract": "*"
+  }
+}

package/templates/architectures/micro-frontends/files/apps/host/remotes.example.json

@@ -0,0 +1,9 @@
+{
+  "$comment": "Serve this as MFE_MANIFEST_URL. Each team edits only its own line, and the shell is never rebuilt to add a remote. Under Module Federation `entry` points at the remote's mf-manifest.json; under import maps it points at the remote's ES module.",
+  "remotes": [
+    {
+      "name": "{{ remoteName | kebab }}",
+      "entry": "https://{{ remoteName | kebab }}.example.invalid/mf-manifest.json"
+    }
+  ]
+}

package/templates/architectures/micro-frontends/files/apps/host/src/config.ts

@@ -0,0 +1,34 @@
+// Every tunable the shell has. Nothing else in the host reads the environment, and no remote
+// URL is ever written in code — remotes deploy on their own schedule to their own origins.
+
+export interface HostConfig {
+  /** Federation name of this shell; remotes negotiate shared deps against it. */
+  hostName: string;
+  /** Runtime manifest listing every remote. The only URL the shell is built with. */
+  manifestUrl: string;
+  /** Fail fast rather than hang the whole page when one remote's origin is down. */
+  remoteTimeoutMs: number;
+}
+
+export const HOST_CONFIG_DEFAULTS: HostConfig = {
+  hostName: 'host',
+  manifestUrl: '/remotes.json',
+  remoteTimeoutMs: 5000,
+};
+
+/**
+ * Env is passed in rather than read, because the shell's bundler decides where env lives
+ * (`import.meta.env` on Vite, `process.env` on Next/webpack) and this file must not care.
+ */
+export function resolveHostConfig(env: Record<string, string | undefined> = {}): HostConfig {
+  return {
+    hostName: env.MFE_HOST_NAME ?? HOST_CONFIG_DEFAULTS.hostName,
+    manifestUrl: env.MFE_MANIFEST_URL ?? HOST_CONFIG_DEFAULTS.manifestUrl,
+    remoteTimeoutMs: toPositiveInt(env.MFE_REMOTE_TIMEOUT_MS, HOST_CONFIG_DEFAULTS.remoteTimeoutMs),
+  };
+}
+
+function toPositiveInt(raw: string | undefined, fallback: number): number {
+  const parsed = Number(raw);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback;
+}

package/templates/architectures/micro-frontends/files/apps/host/src/loaders/import-map.ts

@@ -0,0 +1,34 @@
+import type { RemoteModule } from '@{{ solutionName | kebab }}/host-contract';
+import type { RemoteEntry, RemoteLoader } from '../remote-loader.js';
+
+// Native import maps: the browser resolves the specifier, so the shell ships no federation
+// runtime at all. The trade is that dependency sharing is your problem, not a plugin's.
+
+export function importMapLoader(entries: RemoteEntry[]): RemoteLoader {
+  installImportMap(entries);
+
+  return {
+    async load(entry) {
+      const loaded = (await import(/* @vite-ignore */ /* webpackIgnore: true */ entry.name)) as {
+        default?: RemoteModule;
+      };
+      if (!loaded.default) {
+        throw new Error(`Remote "${entry.name}" has no default export implementing RemoteModule`);
+      }
+      return loaded.default;
+    },
+  };
+}
+
+/**
+ * Must run before anything the map covers is imported. Browsers accept a second import map
+ * only from Chrome 133 / Safari 18.4 — serve the map inline in the shell's HTML if you must
+ * support older ones, and use this path for locally-added remotes.
+ */
+function installImportMap(entries: RemoteEntry[]): void {
+  const imports = Object.fromEntries(entries.map((entry) => [entry.name, entry.entry]));
+  const script = document.createElement('script');
+  script.type = 'importmap';
+  script.textContent = JSON.stringify({ imports });
+  document.head.append(script);
+}

package/templates/architectures/micro-frontends/files/apps/host/src/loaders/module-federation.ts

@@ -0,0 +1,29 @@
+import { init, loadRemote } from '@module-federation/runtime';
+import type { RemoteModule } from '@{{ solutionName | kebab }}/host-contract';
+import type { HostConfig } from '../config.js';
+import type { RemoteEntry, RemoteLoader } from '../remote-loader.js';
+
+// Module Federation 2.0 runtime: remotes are registered from the manifest at startup, so
+// adding one is a deploy of that remote plus a manifest edit — never a rebuild of the shell.
+
+/** Every remote exposes this one module id, so the shell needs no per-remote knowledge. */
+const EXPOSED_MODULE = 'remote';
+
+export function moduleFederationLoader(config: HostConfig, entries: RemoteEntry[]): RemoteLoader {
+  init({
+    name: config.hostName,
+    remotes: entries.map((entry) => ({ name: entry.name, entry: entry.entry })),
+    // Singletons, so one design system loads instead of one per remote.
+    shared: {},
+  });
+
+  return {
+    async load(entry) {
+      const loaded = await loadRemote<{ default: RemoteModule }>(`${entry.name}/${EXPOSED_MODULE}`);
+      if (!loaded?.default) {
+        throw new Error(`Remote "${entry.name}" did not expose ./${EXPOSED_MODULE} as a default export`);
+      }
+      return loaded.default;
+    },
+  };
+}

package/templates/architectures/micro-frontends/files/apps/host/src/remote-loader.ts

@@ -0,0 +1,45 @@
+import type { RemoteModule, RemoteProps } from '@{{ solutionName | kebab }}/host-contract';
+import type { HostConfig } from './config.js';
+
+// The seam. The shell knows a remote by name and URL and by nothing else — there is no import
+// of remote source anywhere in this app, and the boundary check fails the build if one appears.
+
+export interface RemoteEntry {
+  /** Federated / import-map name. Must match the name the remote was built under. */
+  name: string;
+  /** Where that remote is deployed right now. Comes from the manifest, never from code. */
+  entry: string;
+}
+
+export interface RemoteManifest {
+  remotes: RemoteEntry[];
+}
+
+/** Implemented once per composition strategy; the rest of the shell is strategy-agnostic. */
+export interface RemoteLoader {
+  load(entry: RemoteEntry): Promise<RemoteModule>;
+}
+
+export async function fetchManifest(config: HostConfig): Promise<RemoteManifest> {
+  const response = await fetch(config.manifestUrl, {
+    signal: AbortSignal.timeout(config.remoteTimeoutMs),
+  });
+  if (!response.ok) {
+    throw new Error(`Remote manifest ${config.manifestUrl} responded ${response.status}`);
+  }
+  return (await response.json()) as RemoteManifest;
+}
+
+/** Mounts a remote into a host-owned element and returns its teardown. */
+export async function mountRemote(
+  loader: RemoteLoader,
+  entry: RemoteEntry,
+  element: HTMLElement,
+  props: RemoteProps,
+): Promise<() => Promise<void>> {
+  const remote = await loader.load(entry);
+  await remote.mount(element, props);
+  return async () => {
+    await remote.unmount(element);
+  };
+}

package/templates/architectures/micro-frontends/files/apps/remotes/__remoteName.kebab__/module-federation.config.mjs

@@ -0,0 +1,19 @@
+// Feed this to the bundler's Module Federation plugin (@module-federation/enhanced for
+// Rspack/webpack, @module-federation/vite for Vite). Kept as data so the exposed name and the
+// shared list are one edit, not one per bundler config.
+export default {
+  name: '{{ remoteName | kebab }}',
+  filename: 'remoteEntry.js',
+
+  // One exposed module, matching what the shell's loader asks for. Expose more and the shell
+  // starts depending on this team's internals, which is the boundary this overlay enforces.
+  exposes: {
+    './remote': './src/index.ts',
+  },
+
+  // singleton keeps one copy on the page; strictVersion turns a silent skew into a load error.
+  shared: {
+    '@{{ solutionName | kebab }}/design-system': { singleton: true, strictVersion: true },
+    '@{{ solutionName | kebab }}/host-contract': { singleton: true, strictVersion: true },
+  },
+};

package/templates/architectures/micro-frontends/files/apps/remotes/__remoteName.kebab__/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@{{ solutionName | kebab }}/{{ remoteName | kebab }}",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@{{ solutionName | kebab }}/design-system": "*",
+    "@{{ solutionName | kebab }}/host-contract": "*"
+  }
+}

package/templates/architectures/micro-frontends/files/apps/remotes/__remoteName.kebab__/src/config.ts

@@ -0,0 +1,28 @@
+// Every tunable this remote has. It is deployed independently of the shell, so it resolves
+// its own backend rather than borrowing one from the host.
+
+export interface RemoteConfig {
+  apiBaseUrl: string;
+  requestTimeoutMs: number;
+}
+
+export const REMOTE_CONFIG_DEFAULTS: RemoteConfig = {
+  apiBaseUrl: '/api/{{ remoteName | kebab }}',
+  requestTimeoutMs: 10000,
+};
+
+/** Env is passed in, never read here — the remote's bundler decides where env lives. */
+export function resolveRemoteConfig(env: Record<string, string | undefined> = {}): RemoteConfig {
+  return {
+    apiBaseUrl: env['{{ remoteName | upperSnake }}_API_BASE_URL'] ?? REMOTE_CONFIG_DEFAULTS.apiBaseUrl,
+    requestTimeoutMs: toPositiveInt(
+      env['{{ remoteName | upperSnake }}_REQUEST_TIMEOUT_MS'],
+      REMOTE_CONFIG_DEFAULTS.requestTimeoutMs,
+    ),
+  };
+}
+
+function toPositiveInt(raw: string | undefined, fallback: number): number {
+  const parsed = Number(raw);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback;
+}

package/templates/architectures/micro-frontends/files/apps/remotes/__remoteName.kebab__/src/index.ts

@@ -0,0 +1,5 @@
+// The federated / import-map entry point. The shell loads this module and nothing else, so
+// anything not reachable from here is private to this team.
+import { remote } from './mount.js';
+
+export default remote;

package/templates/architectures/micro-frontends/files/apps/remotes/__remoteName.kebab__/src/mount.ts

@@ -0,0 +1,32 @@
+import { token } from '@{{ solutionName | kebab }}/design-system';
+import type { RemoteModule, RemoteProps } from '@{{ solutionName | kebab }}/host-contract';
+import { resolveRemoteConfig } from './config.js';
+
+// This remote's entire public surface. Swap the body for your framework's render call —
+// React `createRoot`, Vue `createApp`, whatever this team chose. That choice is the point:
+// nothing outside this folder knows or cares which one it is.
+
+const roots = new WeakMap<HTMLElement, () => void>();
+
+export const remote: RemoteModule = {
+  mount(element, props) {
+    const config = resolveRemoteConfig();
+    element.innerHTML = render(props, config.apiBaseUrl);
+    roots.set(element, () => {
+      element.innerHTML = '';
+    });
+  },
+
+  unmount(element) {
+    // Teardown must be exact — the shell reuses the element for the next remote.
+    roots.get(element)?.();
+    roots.delete(element);
+  },
+};
+
+function render(props: RemoteProps, apiBaseUrl: string): string {
+  return `<section style="color: ${token('colorText')}; padding: ${token('spaceMd')}">
+    <h1>{{ remoteName | title }}</h1>
+    <p>mounted at ${props.basePath} — locale ${props.locale} — api ${apiBaseUrl}</p>
+  </section>`;
+}

package/templates/architectures/micro-frontends/files/docs/architecture/micro-frontends.md

@@ -0,0 +1,161 @@
+# Architecture — Micro-Frontends
+
+Independently deliverable frontend applications, each owned by a separate team, composed into
+one product by a host shell.
+
+## The one rule that matters
+
+> **A remote may not import from the host, and may not import from a sibling remote.**
+> The host may not import a remote's source either — it loads it by name, at runtime.
+> `scripts/check-mfe-boundaries.mjs` fails the build the moment any of those appears.
+
+That single rule is the entire value proposition. The moment a remote imports the host, the two
+must be released together, and you are paying the full cost of this architecture — extra
+payloads, version negotiation, a runtime registry, per-team pipelines — while getting none of
+the deployment independence it was bought for. Everything else on this page is bookkeeping.
+
+The only code both sides may import is `packages/*`. Shared packages may import neither back.
+
+## Before you use this
+
+Cam Jackson's article names the cost first, and so should you: **payload size**, with "a direct
+relationship between page performance and user engagement and conversion." You are spending
+your users' load time to buy your org chart's independence. That is a good trade at four or
+more autonomous frontend teams, and a bad one below three.
+
+Two alternatives, in order of how often they are the right answer:
+
+1. **[Next.js multi-zones](https://nextjs.org/docs/app/guides/multi-zones)** — separate apps
+   split by path prefix, routed by rewrites. No runtime module loading, no shared-dependency
+   negotiation, no version skew. Navigation within a zone is soft, across zones is hard.
+   For most teams reaching for micro-frontends, this is the right answer.
+2. **A monorepo with enforced boundaries** (Nx, Turborepo) — most of the modularity, none of
+   the runtime cost.
+
+And one thing to never do: mixing React and Vue and Angular on a single page. ThoughtWorks
+holds this specifically, as
+[micro frontend anarchy](https://www.thoughtworks.com/radar/techniques/micro-frontend-anarchy) —
+"far from advisable when not part of a deliberate transition strategy." Different frameworks in
+different *remotes* is fine and is a feature; different frameworks composed into one *page* is
+the failure mode.
+
+## Layout
+
+```
+apps/
+  host/                            # the shell — routing, chrome, remote loading
+    remotes.example.json           #   shape of the runtime manifest
+    src/
+      config.ts                    #   every tunable the shell has; nothing else reads env
+      remote-loader.ts             #   the seam: name + URL in, RemoteModule out
+      loaders/                     #   one file per composition strategy
+  remotes/
+    {{ remoteName | kebab }}/      # one independently built, independently deployed app
+      src/
+        index.ts                   #   THE exposed module — the team's whole public surface
+        mount.ts                   #   implements RemoteModule
+        config.ts                  #   this remote's own env; it does not borrow the host's
+packages/
+  host-contract/                   # RemoteModule / RemoteProps — the host↔remote interface
+  design-system/                   # the versioned visual contract, shared as a singleton
+scripts/
+  check-mfe-boundaries.mjs         # the fitness test
+```
+
+Add a remote by copying `apps/remotes/{{ remoteName | kebab }}/` and adding a line to the
+manifest. The checker discovers any folder under `apps/remotes/`, so there is nothing to
+register with it, and the shell is not rebuilt.
+
+## How the shell and a remote talk
+
+Every remote default-exports a `RemoteModule`:
+
+```ts
+mount(element: HTMLElement, props: RemoteProps): void | Promise<void>;
+unmount(element: HTMLElement): void | Promise<void>;
+```
+
+The shell owns the element and the URL; the remote owns everything painted inside it. `props`
+carries `basePath`, `locale`, and `onNavigate` — a remote asks the shell to navigate rather
+than touching a router it does not own. This is the only conversation there is. There is no
+shared store, no shared router instance, and no direct call between remotes; when two remotes
+genuinely need to coordinate, they do it through the shell or through the backend.
+
+`CONTRACT_VERSION` in `packages/host-contract` is a real version. Bump it on any breaking
+change and the shell can refuse a remote built against another major, instead of failing
+somewhere deep inside a `mount()` at runtime.
+
+## Composition
+
+Both strategies implement the same `RemoteLoader`, so the rest of the shell does not know which
+one is in use.
+
+| | Module Federation 2.0 | Native import maps |
+|---|---|---|
+| Runtime dependency | `@module-federation/runtime` | none |
+| Dependency sharing | negotiated, `singleton` + `strictVersion` | your problem |
+| Bundler support | Rspack (the perf default), webpack 5, Vite, Metro | any that emits ESM |
+| TypeScript across remotes | dynamic type hinting, fixed in 2.0 | hand-written declarations |
+
+Under Module Federation, `apps/remotes/*/module-federation.config.mjs` is the per-remote
+declaration — exposed module and shared list — and gets fed to `@module-federation/enhanced`
+(Rspack/webpack) or `@module-federation/vite`. It exposes exactly one module, `./remote`, so
+the shell needs no per-remote knowledge.
+
+Under import maps, the shell injects a map built from the manifest. Note that a *second*
+import map is only accepted from Chrome 133 / Safari 18.4; serve the map inline in the shell's
+HTML if you need to support older browsers.
+
+## Configuration
+
+No remote URL appears in code. `apps/host/src/config.ts` holds one typed default set and reads
+`MFE_HOST_NAME`, `MFE_MANIFEST_URL`, `MFE_REMOTE_TIMEOUT_MS`; the manifest at `MFE_MANIFEST_URL`
+lists every remote and where it is deployed right now. That indirection is not ceremony — it is
+what makes "deploy a remote without deploying the shell" true.
+
+Env is passed *into* `resolveHostConfig(env)` rather than read inside it, because the shell's
+bundler decides where env lives (`import.meta.env` on Vite, `process.env` on Next/webpack) and
+config code should not care.
+
+## Enforcement
+
+```
+npm run check:mfe          # node scripts/check-mfe-boundaries.mjs
+```
+
+Wired into `lint`, so a boundary violation fails the same command CI already runs. It exits
+non-zero and prints every offending file and specifier.
+
+It reads import specifiers as written and never resolves them on disk, so it is immune to
+bundler and TypeScript resolution differences. It matches a zone by folder name *and* by the
+`name` in that folder's `package.json`, which is what catches `import … from '@scope/orders'`
+as well as `../../orders/src/thing.js`. Run `--self-test` to prove the rule still fires; the
+script refuses to run at all if its own known-bad cases stop being detected.
+
+Override the roots with `MFE_HOST_ROOT`, `MFE_REMOTES_ROOT`, `MFE_SHARED_ROOT` if this repo
+moves them.
+
+### What it cannot enforce
+
+Say it here rather than pretend the script covers it:
+
+- **Runtime coupling.** Two remotes agreeing on a `window` global, a shared `localStorage` key,
+  or a custom event name is a boundary violation the checker cannot see — there is no import to
+  find. Code review and a documented event contract are the only defence.
+- **Duplicate dependencies.** Whether React actually loaded once or four times is a property of
+  the built bundles, not the source. Measure it: bundle analysis per remote plus centralized
+  RUM, because a bundle regression in one remote is invisible to every other team.
+- **Design-system drift.** The checker enforces that remotes import the design system rather
+  than a sibling; it cannot tell whether a remote reimplemented the button locally instead.
+- **Framework mixing.** Nothing here stops one remote choosing Angular. That is deliberate —
+  it is legitimate during a strangler-fig migration and a mistake the rest of the time.
+- **Contract version skew.** `CONTRACT_VERSION` is checked at runtime by the shell, not at
+  build time, because the remote was built by another pipeline on another day.
+
+## Sources
+
+- [Cam Jackson / Martin Fowler — Micro Frontends](https://martinfowler.com/articles/micro-frontends.html)
+- [ThoughtWorks Radar — micro frontend anarchy (Hold)](https://www.thoughtworks.com/radar/techniques/micro-frontend-anarchy)
+- [Next.js — Multi-Zones](https://nextjs.org/docs/app/guides/multi-zones)
+- [Module Federation 2.0](https://module-federation.io/)
+- [MDN — Import maps](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/script/type/importmap)

package/templates/architectures/micro-frontends/files/package.json

@@ -0,0 +1,14 @@
+{
+  "private": true,
+  "workspaces": [
+    "apps/host",
+    "apps/remotes/*",
+    "packages/*"
+  ],
+  "scripts": {
+    "check:mfe": "node scripts/check-mfe-boundaries.mjs"
+  },
+  "dependencies": {
+    "@module-federation/runtime": "^2.8.0"
+  }
+}

package/templates/architectures/micro-frontends/files/packages/design-system/README.md

@@ -0,0 +1,27 @@
+# `@{{ solutionName | kebab }}/design-system`
+
+The one dependency every remote is allowed to share with the shell.
+
+Micro-frontends have no shared runtime and no shared router, so the design system is the only
+thing keeping the product from looking like four products. It is versioned like a published
+library, not edited like app code.
+
+## Rules
+
+- **Semver, always.** A breaking change is a major, and remotes upgrade on their own schedule.
+  That is the whole point — a design-system change that forces a coordinated release has
+  removed the independence the architecture was bought for.
+- **Tokens are names, not values.** `token('colorAccent')` resolves to
+  `var(--ds-color-accent)`; the shell sets the value on `:root`. One theme, one place, no
+  duplicated palette shipped in every remote bundle.
+- **Share it as a singleton.** Configure the composition layer so a single copy loads
+  (`shared: { singleton: true }` under Module Federation, one entry in the import map).
+  Otherwise every remote ships its own copy and the users pay for the org chart twice.
+- **No app logic.** Anything domain-specific belongs in the remote that owns the domain. This
+  package must import neither the host nor any remote — `scripts/check-mfe-boundaries.mjs`
+  fails the build if it does.
+
+## Adding a component
+
+Export it from `src/index.ts`. Anything not exported there does not exist as far as the
+remotes are concerned, which is what lets you refactor the internals without a migration.

package/templates/architectures/micro-frontends/files/packages/design-system/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@{{ solutionName | kebab }}/design-system",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  }
+}

package/templates/architectures/micro-frontends/files/packages/design-system/src/index.ts

@@ -0,0 +1,10 @@
+// Public surface of the design system. The shell and every remote import this and nothing
+// deeper — reaching past this file is how a shared package becomes an unversionable liability.
+export { tokens, token } from './tokens.js';
+export type { TokenName } from './tokens.js';
+
+/**
+ * Semver of the visual contract, exposed at runtime so the shell can log which version each
+ * remote was built against. Two majors on one page is the anarchy this architecture invites.
+ */
+export const DESIGN_SYSTEM_VERSION = '1.0.0';

package/templates/architectures/micro-frontends/files/packages/design-system/src/tokens.ts

@@ -0,0 +1,20 @@
+// Design tokens are CSS custom property NAMES, not values: the shell owns the values so a
+// theme switch happens once, not once per independently deployed remote.
+
+export const tokens = {
+  colorSurface: '--ds-color-surface',
+  colorText: '--ds-color-text',
+  colorAccent: '--ds-color-accent',
+  spaceSm: '--ds-space-sm',
+  spaceMd: '--ds-space-md',
+  spaceLg: '--ds-space-lg',
+  radius: '--ds-radius',
+  fontBody: '--ds-font-body',
+} as const;
+
+export type TokenName = keyof typeof tokens;
+
+/** `token('colorAccent')` -> `var(--ds-color-accent)`. Remotes never hardcode a hex value. */
+export function token(name: TokenName): string {
+  return `var(${tokens[name]})`;
+}