@coralreefventures/theme 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Coral Reef Ventures, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,60 @@
+# @coralreefventures/theme
+
+Builds a product's Mantine theme from its brand tokens, and generates the stylesheet of CSS variables that
+`MantineProvider` would inject for it, so a page that renders as server components only still gets the theme.
+
+Both Coral Reef sites carried the same `theme.ts` and `generate-css.ts`, differing only in their scales, primary
+color and font variable. Each product's `packages/theme` is now its tokens file plus a call into this package, and
+the stylesheet it generates is byte-identical to what it generated before: a test here runs the builder over both
+products' token files and compares the output with their committed `theme.css`.
+
+```ts
+// packages/theme/src/theme.ts in a product
+import { createBrandTheme } from "@coralreefventures/theme";
+import tokens from "@streamlane/brand/tokens";
+
+export const brand = tokens.color;
+
+export const theme = createBrandTheme(tokens, {
+  colors: {
+    // Ten shades, each a hex or the name of a brand color: ink is shade 8, ink-soft shade 7.
+    ink: ["#EEF4F4", "#D8E5E5", "#B3CBCC", "#8BAFB0", "#669496", "#4A7C7E", "#336567", "ink-soft", "ink", "#0B2728"],
+    signal: ["#FEF6EA", "#FCEBD0", "#FADAA5", "signal-soft", "#F4B658", "signal", "#DB9425", "#B97A17", "#94610F", "#704908"],
+  },
+  black: "text",
+  primaryColor: "ink",
+  primaryShade: { light: 8, dark: 5 },
+  fontVariable: "--streamlane-font-sans",
+});
+```
+
+```ts
+// packages/theme/scripts/generate-css.ts in a product
+import { themeCss, writeThemeCss } from "@coralreefventures/theme";
+import { cssVariablesResolver, theme } from "../src/theme";
+
+await writeThemeCss(
+  new URL("../theme.css", import.meta.url),
+  themeCss(theme, { generatedBy: "packages/theme (pnpm --filter @streamlane/theme generate)", resolver: cssVariablesResolver }),
+);
+```
+
+`resolver` is a product's own `CSSVariablesResolver` (Streamlane's tones and ink surface) and stays in the product;
+Driftline passes none. `generatedBy` is the first line of the stylesheet, which tells a reader what to run.
+
+## What it exports
+
+- `createBrandTheme(tokens, config)`: the `MantineThemeOverride`. `config.colors` are the scales, `primaryColor` and
+  `primaryShade` as Mantine takes them, `fontVariable` the CSS variable an app sets to its web font (Mantine's system
+  stack is the fallback), and `black` the light-scheme text color, each color a hex or a brand color's name.
+- `themeCss(theme, { generatedBy?, resolver? })`: the stylesheet.
+- `writeThemeCss(file, css)`: writes it.
+- `brandColor(tokens, nameOrHex)`, `brandFontFamily(variable)`, and the types `BrandTokens`, `BrandThemeConfig`,
+  `Scale`, `ThemeCssOptions`.
+
+## Installing
+
+This package ships TypeScript source and `@mantine/core` 9.6.3 is a peer. The code that imports it has to be
+transpiled: a product's theme package runs under `tsx` and Vitest and is bundled by Next through
+`transpilePackages`, all of which handle it. Add `@coralreefventures/theme` to `transpilePackages` where the product
+theme already is.

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@coralreefventures/theme",
+  "version": "0.1.0",
+  "description": "Builds a product's Mantine theme from its brand tokens, and the stylesheet of CSS variables MantineProvider would inject for it.",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Coral-Reef-Ventures/reef.git",
+    "directory": "packages/theme"
+  },
+  "homepage": "https://coralreefventures.com/",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "mantine",
+    "theme",
+    "design-tokens",
+    "coral-reef"
+  ],
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "peerDependencies": {
+    "@mantine/core": "9.6.3"
+  },
+  "devDependencies": {
+    "@mantine/core": "9.6.3",
+    "@mantine/hooks": "9.6.3",
+    "@types/react": "19.3.0",
+    "react": "19.3.0",
+    "react-dom": "19.3.0"
+  }
+}

package/src/css.ts

@@ -0,0 +1,52 @@
+import { writeFile } from "node:fs/promises";
+
+import {
+  type CSSVariablesResolver,
+  convertCssVariables,
+  DEFAULT_THEME,
+  defaultCssVariablesResolver,
+  type MantineThemeOverride,
+  mergeMantineTheme,
+} from "@mantine/core";
+
+export type ThemeCssOptions = {
+  /**
+   * Named in the stylesheet's first line so a reader knows what to run instead of editing it, such as
+   * `packages/theme (pnpm --filter <product>/theme generate)`; this package's name when nothing is given.
+   */
+  generatedBy?: string;
+  /**
+   * The theme's own CSS variables and its corrections to Mantine's, per scheme, merged as MantineProvider merges a
+   * resolver it is given: the theme's variables over Mantine's own.
+   */
+  resolver?: CSSVariablesResolver;
+};
+
+/**
+ * The CSS variables MantineProvider would inject for a theme, as a stylesheet. A page that renders without the
+ * provider (a server component with no client code under it) still gets the theme's colors, type, spacing and radii,
+ * and a page that renders with it loads nothing twice (`withCssVariables={false}`).
+ */
+export const themeCss = (theme: MantineThemeOverride, options: ThemeCssOptions = {}): string => {
+  const merged = mergeMantineTheme(DEFAULT_THEME, theme);
+  const base = defaultCssVariablesResolver(merged);
+  const own = options.resolver?.(merged) ?? { variables: {}, light: {}, dark: {} };
+  const css = convertCssVariables(
+    {
+      variables: { ...base.variables, ...own.variables },
+      light: { ...base.light, ...own.light },
+      dark: { ...base.dark, ...own.dark },
+    },
+    ":root",
+  );
+  const generatedBy = options.generatedBy ?? "@coralreefventures/theme";
+  return `/* Generated by ${generatedBy}; do not edit. */\n${css.trim()}\n`;
+};
+
+/**
+ * Writes the stylesheet, for a product's `generate` script; its test compares the committed file with `themeCss()`
+ * and fails when the two differ, which is how a stale file is caught.
+ */
+export const writeThemeCss = async (file: URL | string, css: string): Promise<void> => {
+  await writeFile(file, css);
+};

package/src/index.ts

@@ -0,0 +1,9 @@
+export { type ThemeCssOptions, themeCss, writeThemeCss } from "./css";
+export {
+  type BrandThemeConfig,
+  type BrandTokens,
+  brandColor,
+  brandFontFamily,
+  createBrandTheme,
+  type Scale,
+} from "./theme";

package/src/theme.ts

@@ -0,0 +1,74 @@
+import { createTheme, DEFAULT_THEME, type MantineColorsTuple, type MantineThemeOverride } from "@mantine/core";
+
+/**
+ * A product's brand tokens (its `packages/brand/brand.tokens.json`): the name and the colors are all this package
+ * reads. The file carries more (the mark's geometry, the lockup's proportions), which the product's own components
+ * read and this package leaves alone.
+ */
+export type BrandTokens = {
+  name: string;
+  color: Record<string, string>;
+};
+
+/** Ten shades, each a hex color or the name of a brand color (`"ink"`, `"signal-soft"`), the brand's fixed points. */
+export type Scale = readonly [string, string, string, string, string, string, string, string, string, string];
+
+export type BrandThemeConfig = {
+  /** Mantine's ten-shade scales, by the name a component asks for (`c="ink"`). */
+  colors: Record<string, Scale>;
+  /** The scale primary actions are filled with. */
+  primaryColor: string;
+  /** The shade of the primary scale a filled control takes, per scheme. */
+  primaryShade: { light: MantineShade; dark: MantineShade };
+  /**
+   * The CSS variable an app sets when it loads a web font (`--streamlane-font-sans`); Mantine's system stack is the
+   * fallback, so an app that sets nothing keeps the stack it had.
+   */
+  fontVariable: `--${string}`;
+  /** Mantine's black, the text color in the light scheme: a brand color's name or a hex. Mantine's own when unset. */
+  black?: string;
+};
+
+type MantineShade = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
+
+/** A brand color by name, or a hex as it is; an unknown name is a mistake in the config, not a color. */
+export const brandColor = (tokens: BrandTokens, value: string): string => {
+  if (value.startsWith("#")) {
+    return value;
+  }
+  const color = tokens.color[value];
+  if (color === undefined) {
+    throw new Error(`${tokens.name}'s brand has no color named "${value}"`);
+  }
+  return color;
+};
+
+/** Mantine's system font stack behind the app's variable. */
+export const brandFontFamily = (variable: `--${string}`) => `var(${variable}, ${DEFAULT_THEME.fontFamily})`;
+
+/**
+ * A product's theme: its scales with the brand colors at their fixed points, the primary color and shade, and the
+ * font behind the app's variable, everything that becomes a CSS variable. It imports no stylesheet, so `themeCss`
+ * can generate the stylesheet outside a bundler, and a product adds its components' class names on top (as
+ * Streamlane's product theme does) without changing a variable.
+ */
+export const createBrandTheme = (tokens: BrandTokens, config: BrandThemeConfig): MantineThemeOverride => {
+  const colors = Object.fromEntries(
+    Object.entries(config.colors).map(([name, scale]) => [
+      name,
+      scale.map((shade) => brandColor(tokens, shade)) as unknown as MantineColorsTuple,
+    ]),
+  );
+  if (!(config.primaryColor in colors)) {
+    throw new Error(`primaryColor "${config.primaryColor}" is not one of the theme's scales`);
+  }
+  const fontFamily = brandFontFamily(config.fontVariable);
+  return createTheme({
+    colors,
+    ...(config.black !== undefined && { black: brandColor(tokens, config.black) }),
+    primaryColor: config.primaryColor,
+    primaryShade: config.primaryShade,
+    fontFamily,
+    headings: { fontFamily, fontWeight: "700" },
+  });
+};