@kierto/design-system 0.1.0

package/README.md

@@ -0,0 +1,71 @@
+# @kierto/design-system
+
+The **canonical Kierto brand design system** — one source of truth for every
+Kierto frontend. A change to the brand tokens, fonts, or base theme here
+propagates to all consuming apps automatically.
+
+It exports:
+
+- **`brand`** — the brand color tokens (spruce ink, recycle green, bone paper, …).
+- **`fonts`** + **`fontImportUrl`** — the Bricolage Grotesque / Hanken Grotesk /
+  Space Mono stack and the Google Fonts URL that backs it.
+- **`radii`** — shared corner radii.
+- **`baseThemeOptions`** — a plain MUI `ThemeOptions` object (no MUI version
+  coupling), and **`createBaseTheme(overrides?)`** / **`baseTheme`** convenience
+  builders.
+
+## Why `ThemeOptions`, not a constructed theme
+
+The marketing site (`kierto-commerce`) is on **MUI 6** while the store apps
+(`kierto-store`) are on **MUI 7**. To stay agnostic to the consumer's MUI major
+version, the package declares `@mui/material` as a wide **peer dependency**
+(`>=6 <8`) and exports plain options. Each app calls its **own** `createTheme`:
+
+```ts
+import { createTheme } from '@mui/material/styles';
+import { baseThemeOptions, brand } from '@kierto/design-system';
+
+const theme = createTheme(baseThemeOptions, {
+  /* app-specific overrides — see consumers below */
+});
+```
+
+## Consumers
+
+| App | How it consumes | Adoption |
+| --- | --- | --- |
+| `kierto-commerce` (marketing) | published package | full base theme (`baseTheme`) |
+| `kierto-store` / dashboard | via `@kierto-store/frontend-shared` | brand tokens + fonts; keeps dense app UI, neutral surfaces, dark mode. Green stays the primary action color. |
+| `kierto-store` / tenant storefronts | via `@kierto-store/frontend-shared` | full design system; **per-tenant** primary/secondary colors still override |
+
+**The golden rule:** apps reference `brand.*` / `fonts.*` tokens — never hardcode
+brand hex values. That is what makes a brand change propagate everywhere.
+
+> Each consuming app must also load the font stack. Add `fontImportUrl` (or the
+> equivalent `<link>`) to the app's `index.html`.
+
+## How propagation works
+
+- **Within `kierto-store`** the three frontends consume this package through the
+  pnpm **workspace**, so a change here is reflected **instantly** — no publish.
+- **Across repos** (to `kierto-commerce`) the package is **published**; consumers
+  track a `^` range and pick up changes with `pnpm update @kierto/design-system`
+  (or a Renovate/Dependabot auto-PR). The `.github/workflows/publish-design-system.yml`
+  workflow builds and publishes on a `design-system-vX.Y.Z` tag.
+
+### Releasing a change
+
+1. Edit tokens/theme here; bump `version` in `package.json`.
+2. Within `kierto-store`, nothing else is needed — workspace consumers are current.
+3. To roll it out to `kierto-commerce`: tag `design-system-vX.Y.Z` (or run the
+   publish workflow), then `pnpm update @kierto/design-system` in that repo.
+
+Published as a **public** package on **npmjs.org** under the `kierto` npm org. The
+CI workflow needs an `NPM_TOKEN` repository secret (an npm automation/granular
+token with publish rights on the `@kierto` scope). No consumer `.npmrc` changes are
+needed — public npm is the default registry.
+
+## Scripts
+
+- `pnpm build` — emit `dist/` (ESM JS + d.ts) for publishing.
+- `pnpm typecheck` / `pnpm test` / `pnpm lint`.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { brand, fonts, fontImportUrl, radii, type Brand, type Fonts } from './tokens.js';
+export { baseThemeOptions, createBaseTheme, default as baseTheme } from './theme.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+// @kierto/design-system — canonical Kierto brand design system.
+// Tokens + fonts + base MUI theme, shared across every Kierto frontend so a
+// brand change here propagates automatically to all apps that consume it.
+export { brand, fonts, fontImportUrl, radii } from './tokens.js';
+export { baseThemeOptions, createBaseTheme, default as baseTheme } from './theme.js';

package/dist/theme.d.ts

@@ -0,0 +1,11 @@
+import { type Theme, type ThemeOptions } from '@mui/material/styles';
+export declare const baseThemeOptions: ThemeOptions;
+/**
+ * Build a MUI theme from the canonical base, optionally layering app-specific
+ * overrides on top (e.g. the dashboard's dark mode + dense surfaces, or a
+ * tenant's custom brand colors).
+ */
+export declare function createBaseTheme(overrides?: ThemeOptions): Theme;
+/** The canonical base theme, ready to use directly (marketing site default). */
+declare const baseTheme: Theme;
+export default baseTheme;

package/dist/theme.js

@@ -0,0 +1,152 @@
+import { createTheme } from '@mui/material/styles';
+import { brand, fonts } from './tokens.js';
+// ── Kierto base theme — "Nordic Field Manual" ─────────────────────────────
+// Dominant ink + paper, one sharp green signal — a warm, editorial, utilitarian
+// key echoing the looping arrows in the logo. This is the canonical base that
+// every Kierto frontend builds on via `createTheme(baseThemeOptions, appOverrides)`.
+//
+// Exported as plain `ThemeOptions` (not a constructed Theme) so the package stays
+// agnostic to the consumer's MUI major version: the marketing site is on MUI 6,
+// the store apps on MUI 7. Each app calls its OWN `createTheme` with these options.
+export const baseThemeOptions = {
+    palette: {
+        mode: 'light',
+        primary: {
+            main: brand.ink,
+            dark: brand.inkDeep,
+            light: brand.inkSoft,
+            contrastText: brand.paper,
+        },
+        secondary: {
+            main: brand.signal,
+            dark: brand.signalDeep,
+            light: brand.signalSoft,
+            contrastText: '#FFFFFF', // white reads on the green accent (and its darker hover)
+        },
+        background: {
+            default: brand.paper,
+            paper: brand.surface,
+        },
+        text: {
+            primary: brand.ink,
+            secondary: brand.inkSoft,
+        },
+        success: { main: '#2E7D5B' },
+        warning: { main: '#C77A0A' },
+        error: { main: '#B23A22' },
+        divider: brand.line,
+    },
+    shape: { borderRadius: 6 },
+    typography: {
+        fontFamily: fonts.body,
+        h1: {
+            fontFamily: fonts.display,
+            fontWeight: 800,
+            letterSpacing: '-0.035em',
+            lineHeight: 0.96,
+            fontSize: 'clamp(2.9rem, 6.2vw, 5.1rem)',
+        },
+        h2: {
+            fontFamily: fonts.display,
+            fontWeight: 800,
+            letterSpacing: '-0.03em',
+            lineHeight: 1.0,
+            fontSize: 'clamp(2.3rem, 4.6vw, 3.6rem)',
+        },
+        h3: {
+            fontFamily: fonts.display,
+            fontWeight: 700,
+            letterSpacing: '-0.025em',
+            lineHeight: 1.05,
+            fontSize: 'clamp(1.8rem, 3.4vw, 2.7rem)',
+        },
+        h4: {
+            fontFamily: fonts.display,
+            fontWeight: 700,
+            letterSpacing: '-0.02em',
+            lineHeight: 1.1,
+        },
+        h5: { fontFamily: fonts.display, fontWeight: 700, letterSpacing: '-0.015em' },
+        h6: { fontFamily: fonts.display, fontWeight: 700, letterSpacing: '-0.01em' },
+        subtitle1: { fontWeight: 600 },
+        subtitle2: { fontWeight: 700 },
+        body1: { lineHeight: 1.72 },
+        body2: { lineHeight: 1.7 },
+        button: {
+            fontFamily: fonts.body,
+            textTransform: 'none',
+            fontWeight: 700,
+            letterSpacing: '0.01em',
+        },
+        overline: {
+            fontFamily: fonts.mono,
+            fontWeight: 700,
+            letterSpacing: '0.2em',
+            textTransform: 'uppercase',
+            fontSize: '0.72rem',
+            lineHeight: 1.6,
+        },
+    },
+    components: {
+        MuiButton: {
+            defaultProps: { disableElevation: true },
+            styleOverrides: {
+                root: {
+                    borderRadius: 4,
+                    paddingInline: 20,
+                    paddingBlock: 9,
+                    fontWeight: 700,
+                },
+                sizeLarge: {
+                    paddingInline: 30,
+                    paddingBlock: 14,
+                    fontSize: '1.02rem',
+                },
+                containedSecondary: {
+                    '&:hover': { backgroundColor: brand.signalDeep },
+                },
+                outlined: {
+                    borderWidth: '1.5px',
+                    '&:hover': { borderWidth: '1.5px' },
+                },
+            },
+        },
+        MuiPaper: {
+            styleOverrides: { root: { backgroundImage: 'none' } },
+        },
+        MuiCard: {
+            defaultProps: { elevation: 0 },
+            styleOverrides: {
+                root: {
+                    backgroundImage: 'none',
+                    border: `1px solid ${brand.line}`,
+                    borderRadius: 8,
+                },
+            },
+        },
+        MuiContainer: {
+            defaultProps: { maxWidth: 'lg' },
+        },
+        MuiChip: {
+            styleOverrides: {
+                root: {
+                    fontFamily: fonts.mono,
+                    fontWeight: 700,
+                    letterSpacing: '0.08em',
+                    borderRadius: 4,
+                },
+            },
+        },
+    },
+};
+/**
+ * Build a MUI theme from the canonical base, optionally layering app-specific
+ * overrides on top (e.g. the dashboard's dark mode + dense surfaces, or a
+ * tenant's custom brand colors).
+ */
+export function createBaseTheme(overrides) {
+    return overrides ? createTheme(baseThemeOptions, overrides) : createTheme(baseThemeOptions);
+}
+/** The canonical base theme, ready to use directly (marketing site default). */
+const baseTheme = createTheme(baseThemeOptions);
+export default baseTheme;

package/dist/tokens.d.ts

@@ -0,0 +1,28 @@
+export declare const brand: {
+    readonly paper: "#F1ECDF";
+    readonly paperDeep: "#E8E1CF";
+    readonly surface: "#FBF8F0";
+    readonly ink: "#15322A";
+    readonly inkDeep: "#0D211B";
+    readonly inkSoft: "#4B6258";
+    readonly signal: "#177A3A";
+    readonly signalDeep: "#125C2C";
+    readonly signalSoft: "#C4E8D1";
+    readonly signalBright: "#2FBF71";
+    readonly line: "rgba(21,50,42,0.16)";
+    readonly lineStrong: "rgba(21,50,42,0.42)";
+    readonly paperLine: "rgba(241,236,223,0.16)";
+};
+export declare const fonts: {
+    readonly display: "\"Bricolage Grotesque\", \"Hanken Grotesk\", system-ui, sans-serif";
+    readonly body: "\"Hanken Grotesk\", system-ui, -apple-system, BlinkMacSystemFont, sans-serif";
+    readonly mono: "\"Space Mono\", ui-monospace, \"SFMono-Regular\", Menlo, monospace";
+};
+export declare const fontImportUrl = "https://fonts.googleapis.com/css2?family=Bricolage+Grotesque:opsz,wght@12..96,500;12..96,600;12..96,700;12..96,800&family=Hanken+Grotesk:wght@400;500;600;700;800&family=Space+Mono:wght@400;700&display=swap";
+export declare const radii: {
+    readonly sm: 4;
+    readonly md: 6;
+    readonly lg: 8;
+};
+export type Brand = typeof brand;
+export type Fonts = typeof fonts;

package/dist/tokens.js

@@ -0,0 +1,40 @@
+// ── Kierto design system — canonical brand tokens ─────────────────────────
+// Single source of truth for every Kierto frontend (marketing site, merchant
+// dashboard, tenant storefronts). Apps MUST reference these tokens rather than
+// hardcoding hex values, so a brand change here propagates everywhere.
+//
+// kierto (fi.) = circulation / cycle. The rental loop: book → pay → pick up →
+// return → repeat. Kierto exists to keep goods in circulation and spare the
+// planet — so the palette is rooted in green: deep spruce ink + a single vivid
+// recycle-green accent.
+export const brand = {
+    paper: '#F1ECDF', // warm bone — page background
+    paperDeep: '#E8E1CF', // tinted band for section rhythm
+    surface: '#FBF8F0', // raised card surface
+    ink: '#15322A', // deep spruce — primary text & brand color
+    inkDeep: '#0D211B', // near-black spruce — full-bleed dark sections
+    inkSoft: '#4B6258', // muted spruce — secondary text
+    signal: '#177A3A', // recycle green — the single sharp accent (eco values). Deep
+    // enough to clear WCAG AA as text on the bone paper (≈4.6:1) and under white (≈5.4:1).
+    signalDeep: '#125C2C', // deeper green — hover / pressed (white text ≈7:1)
+    signalSoft: '#C4E8D1', // pale green — soft accent on dark sections
+    signalBright: '#2FBF71', // vivid green — accents on dark surfaces (dashboard dark mode)
+    line: 'rgba(21,50,42,0.16)', // hairline on paper
+    lineStrong: 'rgba(21,50,42,0.42)',
+    paperLine: 'rgba(241,236,223,0.16)', // hairline on dark
+};
+const displayFamily = '"Bricolage Grotesque", "Hanken Grotesk", system-ui, sans-serif';
+const bodyFamily = '"Hanken Grotesk", system-ui, -apple-system, BlinkMacSystemFont, sans-serif';
+const monoFamily = '"Space Mono", ui-monospace, "SFMono-Regular", Menlo, monospace';
+export const fonts = {
+    display: displayFamily,
+    body: bodyFamily,
+    mono: monoFamily,
+};
+// The Google Fonts stylesheet that backs `fonts`. Every consuming app loads this
+// exact URL (index.html <link> or @import) so the type system never falls back.
+// Keep in sync with `fonts` above.
+export const fontImportUrl = 'https://fonts.googleapis.com/css2?family=Bricolage+Grotesque:opsz,wght@12..96,500;12..96,600;12..96,700;12..96,800&family=Hanken+Grotesk:wght@400;500;600;700;800&family=Space+Mono:wght@400;700&display=swap';
+// Corner radii used across the system. Base shape is `md`; buttons trend tighter,
+// cards looser.
+export const radii = { sm: 4, md: 6, lg: 8 };

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@kierto/design-system",
+  "version": "0.1.0",
+  "description": "Canonical Kierto brand design system — tokens, fonts, and base MUI theme shared across every Kierto frontend.",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PoggersOy/kierto-store.git",
+    "directory": "packages/design-system"
+  },
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./tokens": "./src/tokens.ts",
+    "./theme": "./src/theme.ts"
+  },
+  "files": ["src", "dist"],
+  "sideEffects": false,
+  "scripts": {
+    "lint": "eslint . --report-unused-disable-directives --max-warnings 0",
+    "typecheck": "tsc --noEmit",
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "pnpm build",
+    "test": "vitest run"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "./tokens": {
+        "types": "./dist/tokens.d.ts",
+        "default": "./dist/tokens.js"
+      },
+      "./theme": {
+        "types": "./dist/theme.d.ts",
+        "default": "./dist/theme.js"
+      }
+    }
+  },
+  "peerDependencies": {
+    "@emotion/react": "^11",
+    "@emotion/styled": "^11",
+    "@mui/material": ">=6 <8"
+  },
+  "devDependencies": {
+    "@emotion/react": "^11.13.3",
+    "@emotion/styled": "^11.13.0",
+    "@mui/material": "^7.3.11",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9"
+  }
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+// @kierto/design-system — canonical Kierto brand design system.
+// Tokens + fonts + base MUI theme, shared across every Kierto frontend so a
+// brand change here propagates automatically to all apps that consume it.
+export { brand, fonts, fontImportUrl, radii, type Brand, type Fonts } from './tokens.js';
+export { baseThemeOptions, createBaseTheme, default as baseTheme } from './theme.js';

package/src/theme.test.ts

@@ -0,0 +1,27 @@
+import { describe, it, expect } from 'vitest';
+
+import baseTheme, { baseThemeOptions, createBaseTheme } from './theme';
+import { brand, fonts } from './tokens';
+
+describe('@kierto/design-system base theme', () => {
+  it('maps the brand palette: spruce ink primary, recycle green secondary', () => {
+    expect(baseTheme.palette.primary.main).toBe(brand.ink);
+    expect(baseTheme.palette.secondary.main).toBe(brand.signal);
+  });
+
+  it('uses the Hanken Grotesk body font family', () => {
+    expect(baseTheme.typography.fontFamily).toBe(fonts.body);
+    expect(baseTheme.typography.fontFamily).toContain('Hanken Grotesk');
+  });
+
+  it('exposes base options that can be extended with app overrides', () => {
+    const dark = createBaseTheme({ palette: { mode: 'dark' } });
+    expect(dark.palette.mode).toBe('dark');
+    // brand secondary still flows through from the base options
+    expect(dark.palette.secondary.main).toBe(brand.signal);
+  });
+
+  it('keeps baseThemeOptions as plain options (MUI-major agnostic)', () => {
+    expect(baseThemeOptions.shape?.borderRadius).toBe(6);
+  });
+});

package/src/theme.ts

@@ -0,0 +1,157 @@
+import { createTheme, type Theme, type ThemeOptions } from '@mui/material/styles';
+
+import { brand, fonts } from './tokens.js';
+
+// ── Kierto base theme — "Nordic Field Manual" ─────────────────────────────
+// Dominant ink + paper, one sharp green signal — a warm, editorial, utilitarian
+// key echoing the looping arrows in the logo. This is the canonical base that
+// every Kierto frontend builds on via `createTheme(baseThemeOptions, appOverrides)`.
+//
+// Exported as plain `ThemeOptions` (not a constructed Theme) so the package stays
+// agnostic to the consumer's MUI major version: the marketing site is on MUI 6,
+// the store apps on MUI 7. Each app calls its OWN `createTheme` with these options.
+export const baseThemeOptions: ThemeOptions = {
+  palette: {
+    mode: 'light',
+    primary: {
+      main: brand.ink,
+      dark: brand.inkDeep,
+      light: brand.inkSoft,
+      contrastText: brand.paper,
+    },
+    secondary: {
+      main: brand.signal,
+      dark: brand.signalDeep,
+      light: brand.signalSoft,
+      contrastText: '#FFFFFF', // white reads on the green accent (and its darker hover)
+    },
+    background: {
+      default: brand.paper,
+      paper: brand.surface,
+    },
+    text: {
+      primary: brand.ink,
+      secondary: brand.inkSoft,
+    },
+    success: { main: '#2E7D5B' },
+    warning: { main: '#C77A0A' },
+    error: { main: '#B23A22' },
+    divider: brand.line,
+  },
+  shape: { borderRadius: 6 },
+  typography: {
+    fontFamily: fonts.body,
+    h1: {
+      fontFamily: fonts.display,
+      fontWeight: 800,
+      letterSpacing: '-0.035em',
+      lineHeight: 0.96,
+      fontSize: 'clamp(2.9rem, 6.2vw, 5.1rem)',
+    },
+    h2: {
+      fontFamily: fonts.display,
+      fontWeight: 800,
+      letterSpacing: '-0.03em',
+      lineHeight: 1.0,
+      fontSize: 'clamp(2.3rem, 4.6vw, 3.6rem)',
+    },
+    h3: {
+      fontFamily: fonts.display,
+      fontWeight: 700,
+      letterSpacing: '-0.025em',
+      lineHeight: 1.05,
+      fontSize: 'clamp(1.8rem, 3.4vw, 2.7rem)',
+    },
+    h4: {
+      fontFamily: fonts.display,
+      fontWeight: 700,
+      letterSpacing: '-0.02em',
+      lineHeight: 1.1,
+    },
+    h5: { fontFamily: fonts.display, fontWeight: 700, letterSpacing: '-0.015em' },
+    h6: { fontFamily: fonts.display, fontWeight: 700, letterSpacing: '-0.01em' },
+    subtitle1: { fontWeight: 600 },
+    subtitle2: { fontWeight: 700 },
+    body1: { lineHeight: 1.72 },
+    body2: { lineHeight: 1.7 },
+    button: {
+      fontFamily: fonts.body,
+      textTransform: 'none',
+      fontWeight: 700,
+      letterSpacing: '0.01em',
+    },
+    overline: {
+      fontFamily: fonts.mono,
+      fontWeight: 700,
+      letterSpacing: '0.2em',
+      textTransform: 'uppercase',
+      fontSize: '0.72rem',
+      lineHeight: 1.6,
+    },
+  },
+  components: {
+    MuiButton: {
+      defaultProps: { disableElevation: true },
+      styleOverrides: {
+        root: {
+          borderRadius: 4,
+          paddingInline: 20,
+          paddingBlock: 9,
+          fontWeight: 700,
+        },
+        sizeLarge: {
+          paddingInline: 30,
+          paddingBlock: 14,
+          fontSize: '1.02rem',
+        },
+        containedSecondary: {
+          '&:hover': { backgroundColor: brand.signalDeep },
+        },
+        outlined: {
+          borderWidth: '1.5px',
+          '&:hover': { borderWidth: '1.5px' },
+        },
+      },
+    },
+    MuiPaper: {
+      styleOverrides: { root: { backgroundImage: 'none' } },
+    },
+    MuiCard: {
+      defaultProps: { elevation: 0 },
+      styleOverrides: {
+        root: {
+          backgroundImage: 'none',
+          border: `1px solid ${brand.line}`,
+          borderRadius: 8,
+        },
+      },
+    },
+    MuiContainer: {
+      defaultProps: { maxWidth: 'lg' },
+    },
+    MuiChip: {
+      styleOverrides: {
+        root: {
+          fontFamily: fonts.mono,
+          fontWeight: 700,
+          letterSpacing: '0.08em',
+          borderRadius: 4,
+        },
+      },
+    },
+  },
+};
+
+/**
+ * Build a MUI theme from the canonical base, optionally layering app-specific
+ * overrides on top (e.g. the dashboard's dark mode + dense surfaces, or a
+ * tenant's custom brand colors).
+ */
+export function createBaseTheme(overrides?: ThemeOptions): Theme {
+  return overrides ? createTheme(baseThemeOptions, overrides) : createTheme(baseThemeOptions);
+}
+
+/** The canonical base theme, ready to use directly (marketing site default). */
+const baseTheme: Theme = createTheme(baseThemeOptions);
+
+export default baseTheme;

package/src/tokens.ts

@@ -0,0 +1,48 @@
+// ── Kierto design system — canonical brand tokens ─────────────────────────
+// Single source of truth for every Kierto frontend (marketing site, merchant
+// dashboard, tenant storefronts). Apps MUST reference these tokens rather than
+// hardcoding hex values, so a brand change here propagates everywhere.
+//
+// kierto (fi.) = circulation / cycle. The rental loop: book → pay → pick up →
+// return → repeat. Kierto exists to keep goods in circulation and spare the
+// planet — so the palette is rooted in green: deep spruce ink + a single vivid
+// recycle-green accent.
+export const brand = {
+  paper: '#F1ECDF', // warm bone — page background
+  paperDeep: '#E8E1CF', // tinted band for section rhythm
+  surface: '#FBF8F0', // raised card surface
+  ink: '#15322A', // deep spruce — primary text & brand color
+  inkDeep: '#0D211B', // near-black spruce — full-bleed dark sections
+  inkSoft: '#4B6258', // muted spruce — secondary text
+  signal: '#177A3A', // recycle green — the single sharp accent (eco values). Deep
+  // enough to clear WCAG AA as text on the bone paper (≈4.6:1) and under white (≈5.4:1).
+  signalDeep: '#125C2C', // deeper green — hover / pressed (white text ≈7:1)
+  signalSoft: '#C4E8D1', // pale green — soft accent on dark sections
+  signalBright: '#2FBF71', // vivid green — accents on dark surfaces (dashboard dark mode)
+  line: 'rgba(21,50,42,0.16)', // hairline on paper
+  lineStrong: 'rgba(21,50,42,0.42)',
+  paperLine: 'rgba(241,236,223,0.16)', // hairline on dark
+} as const;
+
+const displayFamily = '"Bricolage Grotesque", "Hanken Grotesk", system-ui, sans-serif';
+const bodyFamily = '"Hanken Grotesk", system-ui, -apple-system, BlinkMacSystemFont, sans-serif';
+const monoFamily = '"Space Mono", ui-monospace, "SFMono-Regular", Menlo, monospace';
+
+export const fonts = {
+  display: displayFamily,
+  body: bodyFamily,
+  mono: monoFamily,
+} as const;
+
+// The Google Fonts stylesheet that backs `fonts`. Every consuming app loads this
+// exact URL (index.html <link> or @import) so the type system never falls back.
+// Keep in sync with `fonts` above.
+export const fontImportUrl =
+  'https://fonts.googleapis.com/css2?family=Bricolage+Grotesque:opsz,wght@12..96,500;12..96,600;12..96,700;12..96,800&family=Hanken+Grotesk:wght@400;500;600;700;800&family=Space+Mono:wght@400;700&display=swap';
+
+// Corner radii used across the system. Base shape is `md`; buttons trend tighter,
+// cards looser.
+export const radii = { sm: 4, md: 6, lg: 8 } as const;
+
+export type Brand = typeof brand;
+export type Fonts = typeof fonts;