@nu-appdev/northwestern-starlight-theme 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] - 2025-06-01
+
+- Initial public release
+- Northwestern Purple color palette mapped to Starlight's accent system
+- Akkurat Pro (body) and Poppins (headings) loaded from Northwestern CDN
+- Styled tables, badges, asides, cards, tabs, and code blocks
+- Mermaid diagram support with Northwestern colors and fullscreen viewer
+- OpenAPI plugin compatibility with method badge preservation
+- Reduced motion support for transitions
+
+[Unreleased]: https://github.com/NIT-Administrative-Systems/northwestern-starlight-theme/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/NIT-Administrative-Systems/northwestern-starlight-theme/releases/tag/v1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Northwestern University
+
+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,52 @@
+<h1 align="center">
+    <img src="/art/logo.svg" width="80" alt="Northwestern Starlight Theme"><br/>
+    Northwestern Starlight Theme
+</h1>
+
+<p align="center">
+    <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-22+-339933?style=flat&logo=node.js&logoColor=white" alt="Node Version"></a>
+    <a href="https://astro.build"><img src="https://img.shields.io/badge/Astro-5.x+-BC52EE?style=flat&logo=astro&logoColor=white" alt="Astro Version"></a>
+    <a href="https://starlight.astro.build"><img src="https://img.shields.io/badge/Starlight-0.32+-FF5D01?style=flat&logo=astro&logoColor=white" alt="Starlight Version"></a>
+</p>
+
+<p align="center">
+    A branded <a href="https://starlight.astro.build">Starlight</a> theme plugin for <a href="https://www.northwestern.edu">Northwestern University</a> documentation sites.
+</p>
+
+## Quick Start
+
+```bash
+pnpm add @nu-appdev/northwestern-starlight-theme
+```
+
+```ts
+import starlight from "@astrojs/starlight";
+import { defineConfig } from "astro/config";
+import northwesternTheme from "@nu-appdev/northwestern-starlight-theme";
+
+export default defineConfig({
+    integrations: [
+        starlight({
+            plugins: [northwesternTheme()],
+            title: "My Docs",
+        }),
+    ],
+});
+```
+
+The plugin applies Northwestern's purple palette, Akkurat Pro + Poppins typography, branded navigation, styled components, and full dark mode support. No additional CSS or configuration required.
+
+See the **[documentation](https://starlight-theme.entapp.northwestern.edu)** for setup options, customization, and component examples.
+
+## Development
+
+```bash
+pnpm install
+pnpm docs:dev      # Start docs dev server
+pnpm verify        # Lint, fix, and build
+pnpm verify:full   # Above + accessibility tests
+```
+
+## License
+
+The MIT License (MIT). Please see [LICENSE](LICENSE) for more information.

package/expressive-code.mjs

@@ -0,0 +1,18 @@
+import { pluginLineNumbers } from "@expressive-code/plugin-line-numbers";
+
+/**
+ * @param {import("@astrojs/starlight/expressive-code").StarlightExpressiveCodeOptions} [config]
+ * @returns {import("@astrojs/starlight/expressive-code").StarlightExpressiveCodeOptions}
+ */
+export function northwesternExpressiveCode(config = {}) {
+    const { defaultProps, plugins, ...rest } = config;
+
+    return {
+        ...rest,
+        plugins: [pluginLineNumbers(), ...(plugins ?? [])],
+        defaultProps: {
+            showLineNumbers: false,
+            ...(defaultProps ?? {}),
+        },
+    };
+}

package/index.ts

@@ -0,0 +1,170 @@
+import type { StarlightPlugin } from "@astrojs/starlight/types";
+
+export interface NorthwesternHomepageConfig {
+    /**
+     * Hero layout style.
+     *
+     * - `"centered"` (default) — image above title, everything centered
+     * - `"split"` — text + buttons on the left, image on the right (60/40 split)
+     */
+    layout?: "centered" | "split";
+
+    /**
+     * Whether to display the page title in the hero.
+     *
+     * Set to `false` when the hero image is a lockup that already contains the title.
+     *
+     * @default true
+     */
+    showTitle?: boolean;
+}
+
+export interface NorthwesternThemeConfig {
+    /**
+     * Homepage hero layout configuration.
+     */
+    homepage?: NorthwesternHomepageConfig;
+
+    /**
+     * Mermaid diagram support.
+     *
+     * - `true` (default) — auto-detect: enables mermaid if `astro-mermaid` and `mermaid`
+     *   are installed, skips silently if they are not
+     * - `false` — disables mermaid entirely
+     * - `object` — enables mermaid with custom config (merged with Northwestern defaults)
+     */
+    mermaid?: boolean | Record<string, unknown>;
+}
+
+/**
+ * Try to resolve a module. Returns true if it can be imported.
+ */
+async function canResolve(id: string): Promise<boolean> {
+    try {
+        await import(/* @vite-ignore */ id);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+const VIRTUAL_MODULE_ID = "virtual:northwestern-theme/config";
+const RESOLVED_VIRTUAL_MODULE_ID = `\0${VIRTUAL_MODULE_ID}`;
+
+export default function northwesternTheme(config: NorthwesternThemeConfig = {}): StarlightPlugin {
+    const { homepage = {}, mermaid = true } = config;
+    const themeConfig = { homepage: { layout: homepage.layout ?? "centered", showTitle: homepage.showTitle ?? true } };
+
+    return {
+        name: "northwestern-starlight-theme",
+        hooks: {
+            async "config:setup"({ config: starlightConfig, updateConfig, addIntegration, logger }) {
+                addIntegration({
+                    name: "northwestern-theme-config",
+                    hooks: {
+                        "astro:config:setup": ({ updateConfig: updateAstroConfig }) => {
+                            updateAstroConfig({
+                                vite: {
+                                    plugins: [
+                                        {
+                                            name: "northwestern-theme-virtual-config",
+                                            resolveId(id: string) {
+                                                if (id === VIRTUAL_MODULE_ID) return RESOLVED_VIRTUAL_MODULE_ID;
+                                            },
+                                            load(id: string) {
+                                                if (id === RESOLVED_VIRTUAL_MODULE_ID) {
+                                                    return `export default ${JSON.stringify(themeConfig)};`;
+                                                }
+                                            },
+                                        },
+                                    ],
+                                },
+                            });
+                        },
+                    },
+                });
+                // Detect mermaid availability
+                let mermaidEnabled = mermaid !== false;
+
+                if (mermaidEnabled) {
+                    const hasMermaid = await canResolve("astro-mermaid");
+
+                    if (!hasMermaid) {
+                        if (typeof mermaid === "object") {
+                            // User explicitly configured mermaid but it's not installed
+                            logger.warn(
+                                'Mermaid config was provided but "astro-mermaid" and "mermaid" are not installed.\n' +
+                                    "  Run: pnpm add astro-mermaid mermaid",
+                            );
+                        }
+                        mermaidEnabled = false;
+                    }
+                }
+
+                updateConfig({
+                    components: {
+                        ...(starlightConfig.components ?? {}),
+                        Hero:
+                            starlightConfig.components?.Hero ??
+                            "@nu-appdev/northwestern-starlight-theme/src/components/Hero.astro",
+                        EditLink:
+                            starlightConfig.components?.EditLink ??
+                            "@nu-appdev/northwestern-starlight-theme/src/components/ConditionalEditLink.astro",
+                        ThemeSelect:
+                            starlightConfig.components?.ThemeSelect ??
+                            "@nu-appdev/northwestern-starlight-theme/src/components/ThemeToggle.astro",
+                    },
+                    customCss: [
+                        "@nu-appdev/northwestern-starlight-theme/src/styles/layers.css",
+                        "@nu-appdev/northwestern-starlight-theme/src/styles/variables.css",
+                        "@nu-appdev/northwestern-starlight-theme/src/styles/typography.css",
+                        "@nu-appdev/northwestern-starlight-theme/src/styles/theme.css",
+                        "@nu-appdev/northwestern-starlight-theme/src/styles/navigation.css",
+                        "@nu-appdev/northwestern-starlight-theme/src/styles/content.css",
+                        "@nu-appdev/northwestern-starlight-theme/src/styles/components/cards.css",
+                        "@nu-appdev/northwestern-starlight-theme/src/styles/components/utility-surfaces.css",
+                        "@nu-appdev/northwestern-starlight-theme/src/styles/components/steps.css",
+                        "@nu-appdev/northwestern-starlight-theme/src/styles/components/code.css",
+                        "@nu-appdev/northwestern-starlight-theme/src/styles/components/tabs.css",
+                        "@nu-appdev/northwestern-starlight-theme/src/styles/components/mermaid.css",
+                        "@nu-appdev/northwestern-starlight-theme/src/styles/mermaid-toolbar.css",
+                        "@nu-appdev/northwestern-starlight-theme/src/styles/openapi.css",
+                        ...(starlightConfig.customCss ?? []),
+                    ],
+                    expressiveCode: {
+                        themes: ["github-dark", "github-light"],
+                        useStarlightUiThemeColors: true,
+                        ...(typeof starlightConfig.expressiveCode === "object" ? starlightConfig.expressiveCode : {}),
+                    },
+                });
+
+                if (mermaidEnabled) {
+                    const { default: mermaidIntegration } = await import("astro-mermaid");
+                    const { defaultMermaidConfig } = await import("./mermaid.ts");
+
+                    const userOverrides = typeof mermaid === "object" ? (mermaid as Record<string, unknown>) : {};
+                    const mergedConfig = {
+                        ...defaultMermaidConfig,
+                        ...userOverrides,
+                        enableLog: false,
+                        mermaidConfig: {
+                            ...(defaultMermaidConfig.mermaidConfig ?? {}),
+                            ...((userOverrides.mermaidConfig as Record<string, unknown>) ?? {}),
+                            themeVariables: {
+                                ...((defaultMermaidConfig.mermaidConfig as Record<string, unknown>)?.themeVariables ??
+                                    {}),
+                                ...(((userOverrides.mermaidConfig as Record<string, unknown>)?.themeVariables as Record<
+                                    string,
+                                    unknown
+                                >) ?? {}),
+                            },
+                        },
+                    };
+
+                    addIntegration(mermaidIntegration(mergedConfig));
+                    logger.info("Mermaid support enabled");
+                }
+            },
+        },
+    };
+}

package/mermaid.ts

@@ -0,0 +1,376 @@
+import type { AstroIntegration } from "astro";
+import mermaid, { type AstroMermaidOptions } from "astro-mermaid";
+import { darken, isDark, lighten, mix, transparentize } from "khroma";
+
+export interface NorthwesternMermaidOptions extends AstroMermaidOptions {
+    toolbar?: boolean;
+}
+
+export type NorthwesternMermaidMode = "light" | "dark";
+
+type ThemeVariables = Record<string, unknown>;
+
+type BrandPalette = {
+    purple: string;
+    blue: string;
+    green: string;
+    yellow: string;
+    red: string;
+    teal: string;
+    orange: string;
+    white: string;
+    black: string;
+    canvas: string;
+    text: string;
+    textMuted: string;
+    surface: string;
+    surfaceAlt: string;
+    border: string;
+    edgeLabel: string;
+};
+
+const chartPalette = ["#4e2a84", "#836eaa", "#5091cd", "#008656", "#ffc520", "#ef553f", "#7fcecd", "#d85820"];
+
+function onColor(color: string, darkText = "#342f2e", lightText = "#fff") {
+    return isDark(color) ? lightText : darkText;
+}
+
+function createPalette(mode: NorthwesternMermaidMode): BrandPalette {
+    if (mode === "dark") {
+        const canvas = "#1c1c1f";
+        const purple = lighten("#4e2a84", 8);
+        const blue = lighten("#1168bd", 6);
+
+        return {
+            purple,
+            blue,
+            green: "#008656",
+            yellow: "#ffc520",
+            red: "#ef553f",
+            teal: "#7fcecd",
+            orange: "#d85820",
+            white: "#fff",
+            black: "#342f2e",
+            canvas,
+            text: "#f0f0f0",
+            textMuted: mix("#f0f0f0", canvas, 60),
+            surface: mix("#4e2a84", canvas, 18),
+            surfaceAlt: mix("#fff", canvas, 8),
+            border: mix("#b6acd1", canvas, 18),
+            edgeLabel: "#fff",
+        };
+    }
+
+    return {
+        purple: "#4e2a84",
+        blue: "#1168bd",
+        green: "#008656",
+        yellow: "#ffc520",
+        red: "#ef553f",
+        teal: "#7fcecd",
+        orange: "#d85820",
+        white: "#fff",
+        black: "#342f2e",
+        canvas: "#fff",
+        text: "#342f2e",
+        textMuted: mix("#342f2e", "#fff", 45),
+        surface: "#f3f0f7",
+        surfaceAlt: "#e4e0ee",
+        border: "#b6acd1",
+        edgeLabel: "#fff",
+    };
+}
+
+function createThemeVariables(mode: NorthwesternMermaidMode): ThemeVariables {
+    const palette = createPalette(mode);
+    const dark = mode === "dark";
+    const primary = palette.purple;
+    const primaryBorder = dark ? lighten(primary, 24) : darken(primary, 10);
+    const secondary = dark ? palette.surface : palette.surfaceAlt;
+    const tertiary = dark ? mix(palette.white, palette.canvas, 6) : palette.surface;
+    const noteBackground = dark ? mix(primary, palette.canvas, 16) : palette.surface;
+    const actorLine = dark ? primary : primary;
+    const activation = dark ? mix(primary, palette.canvas, 28) : palette.surfaceAlt;
+    const cluster = dark ? mix(primary, palette.canvas, 10) : lighten(palette.surface, 2);
+    const _externalSystem = dark ? mix(palette.white, palette.canvas, 38) : "#999";
+    const stateBackground = dark ? mix(palette.white, palette.canvas, 8) : tertiary;
+    const compositeBackground = dark ? mix(palette.white, palette.canvas, 5) : palette.white;
+    const compositeAltBackground = dark ? mix(palette.purple, palette.canvas, 22) : palette.surfaceAlt;
+    const stateTitleBackground = dark ? mix(primary, palette.canvas, 14) : tertiary;
+    const stateLabelColor = dark ? palette.white : palette.black;
+    const rowOdd = dark ? mix(primary, palette.canvas, 26) : palette.surface;
+    const rowEven = dark ? mix(palette.white, palette.canvas, 8) : palette.white;
+
+    return {
+        primaryColor: primary,
+        primaryTextColor: onColor(primary),
+        primaryBorderColor: primaryBorder,
+
+        secondaryColor: secondary,
+        secondaryTextColor: onColor(secondary),
+        secondaryBorderColor: palette.border,
+
+        tertiaryColor: tertiary,
+        tertiaryTextColor: onColor(tertiary),
+        tertiaryBorderColor: dark ? mix(palette.border, palette.canvas, 24) : lighten(palette.border, 8),
+
+        background: palette.canvas,
+        mainBkg: primary,
+        secondBkg: secondary,
+        tertiaryBkg: tertiary,
+
+        textColor: palette.text,
+        taskTextColor: palette.text,
+        taskTextLightColor: palette.white,
+        nodeTextColor: onColor(primary),
+        textColorStrong: palette.text,
+        mainContrastColor: palette.text,
+        darkTextColor: palette.black,
+        lineColor: dark ? lighten(primary, 28) : primary,
+        arrowheadColor: dark ? lighten(primary, 28) : primary,
+        defaultLinkColor: dark ? lighten(primary, 28) : primary,
+        fontFamily: '"Akkurat Pro", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
+        fontSize: "14px",
+
+        nodeBkg: primary,
+        nodeBorder: primaryBorder,
+        border1: palette.border,
+        border2: primaryBorder,
+        clusterBkg: cluster,
+        clusterBorder: palette.border,
+        edgeLabelBackground: palette.edgeLabel,
+        labelBackground: palette.edgeLabel,
+
+        titleColor: palette.text,
+        labelColor: palette.text,
+        labelTextColor: palette.text,
+        loopTextColor: palette.text,
+        transitionColor: dark ? lighten(primary, 28) : primary,
+        transitionLabelColor: palette.black,
+        stateLabelColor,
+        stateBkg: stateBackground,
+        labelBackgroundColor: palette.edgeLabel,
+        compositeBackground,
+        compositeTitleBackground: stateTitleBackground,
+        compositeBorder: palette.border,
+        innerEndBackground: compositeBackground,
+        specialStateColor: primary,
+
+        noteBkgColor: noteBackground,
+        noteBorderColor: palette.border,
+        noteTextColor: palette.text,
+
+        actorBkg: primary,
+        actorBorder: primaryBorder,
+        actorTextColor: onColor(primary),
+        actorLineColor: actorLine,
+        signalColor: palette.text,
+        signalTextColor: palette.text,
+        labelBoxBkgColor: noteBackground,
+        labelBoxBorderColor: palette.border,
+        activationBkgColor: activation,
+        activationBorderColor: actorLine,
+        sequenceNumberColor: dark ? palette.black : palette.white,
+
+        taskBorderColor: primaryBorder,
+        taskBkgColor: primary,
+        taskTextOutsideColor: palette.text,
+        taskTextClickableColor: dark ? lighten(primary, 32) : primary,
+        activeTaskBorderColor: dark ? lighten(primary, 20) : darken(primary, 10),
+        activeTaskBkgColor: dark ? lighten(primary, 12) : lighten(primary, 8),
+        gridColor: dark ? mix(palette.white, palette.canvas, 15) : "#ddd",
+        doneTaskBkgColor: dark ? mix(palette.green, palette.canvas, 30) : lighten(palette.green, 30),
+        doneTaskBorderColor: palette.green,
+        critBorderColor: palette.red,
+        critBkgColor: dark ? mix(palette.red, palette.canvas, 30) : lighten(palette.red, 30),
+        taskTextDarkColor: palette.text,
+        todayLineColor: palette.red,
+
+        errorBkgColor: dark ? mix(palette.red, palette.canvas, 30) : lighten(palette.red, 36),
+        errorTextColor: dark ? lighten(palette.red, 20) : palette.red,
+
+        requirementBackground: dark ? mix(primary, palette.canvas, 20) : palette.surface,
+        requirementBorderColor: palette.border,
+        requirementBorderSize: "1",
+        requirementTextColor: palette.text,
+        relationColor: dark ? lighten(primary, 28) : primary,
+        relationLabelBackground: palette.edgeLabel,
+        relationLabelColor: palette.text,
+
+        altBackground: secondary,
+        classText: palette.white,
+        fillType0: primary,
+        fillType1: secondary,
+        fillType2: mix("#8b1e5a", palette.canvas, dark ? 20 : 0),
+        fillType3: mix("#f1dfe8", palette.canvas, dark ? 65 : 0),
+        fillType4: mix("#0d5f90", palette.canvas, dark ? 10 : 0),
+        fillType5: mix("#d9eef6", palette.canvas, dark ? 65 : 0),
+        fillType6: mix("#8d4a00", palette.canvas, dark ? 10 : 0),
+        fillType7: mix("#f8e9d7", palette.canvas, dark ? 68 : 0),
+
+        rowOdd,
+        rowEven,
+        attributeBackgroundColorOdd: dark ? transparentize(primary, 0.76) : palette.surface,
+        attributeBackgroundColorEven: dark ? "#1f1f23" : palette.white,
+        sectionBkgColor: rowOdd,
+        altSectionBkgColor: rowEven,
+        sectionBkgColor2: compositeAltBackground,
+
+        git0: chartPalette[0],
+        git1: chartPalette[1],
+        git2: chartPalette[2],
+        git3: chartPalette[3],
+        git4: chartPalette[4],
+        git5: chartPalette[5],
+        git6: chartPalette[6],
+        git7: chartPalette[7],
+        gitBranchLabel0: onColor(chartPalette[0]),
+        gitBranchLabel1: onColor(chartPalette[1]),
+        gitBranchLabel2: onColor(chartPalette[2]),
+        gitBranchLabel3: onColor(chartPalette[3]),
+        gitBranchLabel4: onColor(chartPalette[4]),
+        gitBranchLabel5: onColor(chartPalette[5]),
+        gitBranchLabel6: onColor(chartPalette[6]),
+        gitBranchLabel7: onColor(chartPalette[7]),
+        gitInv0: palette.white,
+
+        pie1: chartPalette[0],
+        pie2: chartPalette[1],
+        pie3: chartPalette[2],
+        pie4: chartPalette[3],
+        pie5: chartPalette[4],
+        pie6: chartPalette[5],
+        pie7: chartPalette[6],
+        pie8: chartPalette[7],
+        pie9: dark ? lighten(chartPalette[0], 16) : darken(chartPalette[0], 10),
+        pie10: dark ? lighten(chartPalette[2], 16) : darken(chartPalette[2], 10),
+        pie11: dark ? lighten(chartPalette[3], 16) : darken(chartPalette[3], 10),
+        pie12: dark ? lighten(chartPalette[4], 10) : darken(chartPalette[4], 10),
+        pieStrokeColor: dark ? palette.canvas : palette.white,
+        pieSectionTextColor: palette.white,
+        pieSectionTextSize: "14px",
+        pieTitleTextColor: palette.text,
+        pieTitleTextSize: "16px",
+        pieLegendTextColor: palette.text,
+        pieLegendTextSize: "14px",
+        pieStrokeWidth: "2px",
+        pieOuterStrokeWidth: "1px",
+        pieOuterStrokeColor: dark ? palette.border : palette.border,
+        pieOpacity: "0.85",
+
+        cScale0: dark ? mix(primary, palette.canvas, 40) : primary,
+        cScale1: dark ? mix(palette.blue, palette.canvas, 40) : palette.blue,
+        cScale2: dark ? mix(palette.green, palette.canvas, 40) : palette.green,
+        cScale3: dark ? mix(palette.orange, palette.canvas, 35) : palette.orange,
+        cScale4: dark ? mix(palette.teal, palette.canvas, 35) : darken(palette.teal, 15),
+        cScale5: dark ? mix(palette.yellow, palette.canvas, 30) : darken(palette.yellow, 20),
+        cScale6: dark ? mix(palette.red, palette.canvas, 35) : palette.red,
+        cScale7: dark ? mix(primary, palette.canvas, 30) : lighten(primary, 10),
+
+        cScaleLabel0: palette.white,
+        cScaleLabel1: palette.white,
+        cScaleLabel2: palette.white,
+        cScaleLabel3: palette.white,
+        cScaleLabel4: dark ? palette.white : palette.black,
+        cScaleLabel5: palette.black,
+        cScaleLabel6: palette.white,
+        cScaleLabel7: palette.white,
+
+        quadrant1Fill: dark ? mix(primary, palette.canvas, 35) : mix(primary, palette.white, 25),
+        quadrant2Fill: dark ? mix(primary, palette.canvas, 28) : mix(primary, palette.white, 18),
+        quadrant3Fill: dark ? mix(primary, palette.canvas, 22) : mix(primary, palette.white, 12),
+        quadrant4Fill: dark ? mix(primary, palette.canvas, 15) : mix(primary, palette.white, 8),
+        quadrant1TextFill: onColor(dark ? mix(primary, palette.canvas, 35) : mix(primary, palette.white, 25)),
+        quadrant2TextFill: onColor(dark ? mix(primary, palette.canvas, 28) : mix(primary, palette.white, 18)),
+        quadrant3TextFill: onColor(dark ? mix(primary, palette.canvas, 22) : mix(primary, palette.white, 12)),
+        quadrant4TextFill: onColor(dark ? mix(primary, palette.canvas, 15) : mix(primary, palette.white, 8)),
+        quadrantPointFill: primary,
+        quadrantPointTextFill: dark ? palette.white : palette.black,
+        quadrantXAxisTextFill: palette.text,
+        quadrantYAxisTextFill: palette.text,
+        quadrantTitleFill: palette.text,
+        quadrantInternalBorderStrokeFill: dark ? palette.border : lighten(palette.border, 10),
+        quadrantExternalBorderStrokeFill: palette.border,
+
+        xyChart: {
+            plotColorPalette: chartPalette.join(","),
+            titleColor: dark ? "#342f2e" : palette.text,
+            xAxisLabelColor: dark ? "#342f2e" : palette.text,
+            yAxisLabelColor: dark ? "#342f2e" : palette.text,
+            xAxisTitleColor: dark ? "#342f2e" : palette.text,
+            yAxisTitleColor: dark ? "#342f2e" : palette.text,
+            xAxisLineColor: "#ccc",
+            yAxisLineColor: "#ccc",
+        },
+    };
+}
+
+export function createNorthwesternMermaidConfig(mode: NorthwesternMermaidMode): AstroMermaidOptions {
+    const palette = createPalette(mode);
+    return {
+        theme: "base",
+        autoTheme: false,
+        mermaidConfig: {
+            themeVariables: createThemeVariables(mode),
+            xyChart: {
+                plotColorPalette: chartPalette.join(","),
+                titleColor: mode === "dark" ? "#342f2e" : palette.text,
+                xAxisLabelColor: mode === "dark" ? "#342f2e" : palette.text,
+                yAxisLabelColor: mode === "dark" ? "#342f2e" : palette.text,
+                xAxisTitleColor: mode === "dark" ? "#342f2e" : palette.text,
+                yAxisTitleColor: mode === "dark" ? "#342f2e" : palette.text,
+                xAxisLineColor: "#ccc",
+                yAxisLineColor: "#ccc",
+            },
+        },
+    };
+}
+
+/**
+ * Northwestern-branded Mermaid configuration.
+ *
+ * The theme is derived from a small brand palette per mode instead of a large
+ * hand-authored variable table. Mermaid renders with a dedicated light or dark
+ * config, while CSS remains limited to structural SVG tweaks.
+ */
+export const defaultMermaidConfig: AstroMermaidOptions = createNorthwesternMermaidConfig("light");
+export const darkMermaidConfig: AstroMermaidOptions = createNorthwesternMermaidConfig("dark");
+
+export function northwesternMermaid(options: NorthwesternMermaidOptions = {}): AstroIntegration {
+    const { toolbar = true, ...overrides } = options;
+    const lightConfig = createNorthwesternMermaidConfig("light");
+    const darkConfig = createNorthwesternMermaidConfig("dark");
+
+    const mermaidIntegration = mermaid({
+        ...lightConfig,
+        ...overrides,
+        enableLog: false,
+        mermaidConfig: {
+            ...(lightConfig.mermaidConfig ?? {}),
+            ...(overrides.mermaidConfig ?? {}),
+            themeVariables: {
+                ...((lightConfig.mermaidConfig as Record<string, unknown>)?.themeVariables ?? {}),
+                ...((overrides.mermaidConfig as Record<string, unknown>)?.themeVariables ?? {}),
+            },
+        },
+    });
+
+    return {
+        name: "northwestern-mermaid",
+        hooks: {
+            "astro:config:setup"(params) {
+                mermaidIntegration.hooks["astro:config:setup"]?.(params);
+
+                params.injectScript(
+                    "page",
+                    `window.__NU_MERMAID_TOOLBAR__ = ${toolbar ? "true" : "false"}; window.__NU_MERMAID_CONFIGS__ = ${JSON.stringify(
+                        {
+                            light: lightConfig.mermaidConfig,
+                            dark: darkConfig.mermaidConfig,
+                        },
+                    )}; import "@nu-appdev/northwestern-starlight-theme/src/scripts/mermaid-toolbar.ts";`,
+                );
+            },
+        },
+    };
+}