@nu-appdev/northwestern-starlight-theme 1.1.1 → 1.3.0

package/CHANGELOG.md

@@ -7,6 +7,75 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.3.0] - 2026-03-26
+
+### Added
+
+- **Property Table component suite**: `<PropertyTable>`, `<Property>`, `<PropertyGroup>`, `<Expandable>`.
+  - See the [documentation](https://starlight-theme.entapp.northwestern.edu/components/property-table) for more information.
+- **Tooltip component suite**: `<Tooltip>`, `<Glossary>`, `<Term>`.
+  - See the [documentation](https://starlight-theme.entapp.northwestern.edu/components/tooltip) for more information.
+- **Keyboard component**: `<Kbd>`.
+  - See the [documentation](https://starlight-theme.entapp.northwestern.edu/components/kbd) for more information.
+- Fullscreen Mermaid overlay: scale animation, dot grid background, pan momentum on drag release, toast notifications on copy.
+- `@media (prefers-contrast: more)`: heavier borders, system colors for focus rings.
+- `@media (prefers-reduced-transparency: reduce)`: solid surfaces replace translucent backgrounds.
+- `CONTRIBUTING.md` with development setup, conventions, and PR process.
+- JSDoc comments on public TypeScript interfaces.
+
+### Fixed
+
+- Code block line numbers in dark mode had 2.85:1 contrast. Bumped from `#6e6e6e` to `#999` (4.6:1).
+- Code block copy button icon in dark mode used `--nu-purple-100` on hover. Switched to `--nu-purple-40`.
+- Wide tables overflowed into the sidebar. A [rehype](https://github.com/rehypejs/rehype) plugin now wraps each `<table>` in a scrollable `<div>` at build time.
+- Reopening the fullscreen viewer after Escape showed a blue focus ring around the entire viewport.
+- Mermaid hover toolbar sat unevenly relative to the diagram container border.
+- Fullscreen close button used `rgb(255 255 255 / 20%)` while the theme toggle used `15%`. Both use `15%` now.
+- Mobile sidebar: theme toggle and GitHub icon were white-on-white in light mode.
+- Mobile sidebar: theme toggle was taller than wide; GitHub icon sat below it.
+- Copy buttons did nothing on HTTP (insecure contexts). Added `document.execCommand("copy")` fallback.
+- Clicking copy twice during the success animation duplicated the check icon. Debounced per button.
+- iOS Safari toggled the URL bar when copying in the fullscreen viewer. The fallback textarea now appends inside the overlay.
+- Mouse-opening the fullscreen viewer put a focus ring on the first control. Keyboard opens focus the first button; mouse opens focus the overlay container (no visible ring, Tab still works).
+- Zoom in/out/reset buttons hidden on mobile (pinch-to-zoom covers it).
+- Mermaid user overrides dropped on client-side theme toggle. Runtime configs now include merged user config.
+- Mermaid lazy-rendered diagrams used stale theme after toggle. Observer callback now reads live theme mode.
+- Mermaid pinch-to-zoom anchored to viewport center instead of pinch midpoint.
+- Mermaid `MutationObservers` accumulated on view transitions. Previous observer now disconnected before creating a new one.
+- Mermaid render race on rapid theme toggles. Per-container version tracking discards stale async completions.
+- Mermaid fullscreen close could fire twice during animation. Added guard against double-close.
+- Mermaid `diagramSources` `Map` leaked detached DOM nodes across view transitions. Switched to `WeakMap`.
+- Tooltip event listeners duplicated on Astro view transitions. Added `WeakSet` idempotency guard.
+- Tooltip Popover API called without feature detection. Added fallback for unsupported browsers.
+- Tooltip positioning drifted on scroll. Now repositions via scroll listener while visible.
+- Sidebar active item border shifted text. All sidebar links now reserve space with a transparent left border.
+- Search modal focus ring used browser default blue. Now uses `--nu-focus-ring`.
+- Site title clipped on mobile. Added fluid font sizing with `clamp()` and ellipsis overflow.
+
+### Changed
+
+- Fullscreen controls bar uses Starlight's `--sl-nav-pad-x` and `--sl-menu-button-size` so the close button aligns with the hamburger menu on mobile.
+- Removed right padding on active sidebar headings that broke nested heading alignment.
+
+## [1.2.0] - 2026-03-25
+
+### Added
+
+- Fullscreen Mermaid viewer: wheel zoom and double-click zoom anchor to the pointer position.
+- Zoom level badge (e.g. `84%`) in the fullscreen viewer.
+- GFM footnote styles: superscript `[n]` reference markers, footnotes section with separator, styled `↩︎` back-references.
+
+### Fixed
+
+- Mermaid diagrams sometimes breaking on Firefox and Safari. The toolbar script read `textContent` after `astro-mermaid` had already rendered SVG into the element. Reads `data-diagram` first now.
+- Horizontal rules in dark mode used `--nu-purple-140`, which was invisible against the background. Switched to `--nu-border-color`.
+
+### Accessibility
+
+- Fullscreen Mermaid overlay: `role="dialog"`, `aria-modal`, focus trap, focus restore on close.
+- White focus rings on overlay controls, theme toggle, and menu button (all sit on dark backgrounds where the purple ring was invisible).
+- Inline Mermaid toolbar buttons use a solid accent outline on focus instead of the near-invisible shadow ring.
+
 ## [1.1.1] - 2026-03-25
 
 ### Fixed
@@ -21,7 +90,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- Fullscreen mermaid viewer supports touch: one-finger pan, pinch-to-zoom, two-finger pan.
+- Fullscreen Mermaid viewer supports touch: one-finger pan, pinch-to-zoom, two-finger pan.
 - Mermaid toolbar stays visible on touch devices (`hover: none`) since hover is unavailable.
 - SVG downloads use descriptive filenames derived from the site title, page slug, and diagram type (e.g., `northwestern-starlight-theme_examples-mermaid-flowchart.svg`).
 
@@ -52,7 +121,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - OpenAPI plugin compatibility with method badge preservation
 - Reduced motion support for transitions
 
-[Unreleased]: https://github.com/NIT-Administrative-Systems/northwestern-starlight-theme/compare/v1.1.1...HEAD
+[Unreleased]: https://github.com/NIT-Administrative-Systems/northwestern-starlight-theme/compare/v1.3.0...HEAD
+[1.3.0]: https://github.com/NIT-Administrative-Systems/northwestern-starlight-theme/compare/v1.2.0...v1.3.0
+[1.2.0]: https://github.com/NIT-Administrative-Systems/northwestern-starlight-theme/compare/v1.1.1...v1.2.0
 [1.1.1]: https://github.com/NIT-Administrative-Systems/northwestern-starlight-theme/compare/v1.1.0...v1.1.1
 [1.1.0]: https://github.com/NIT-Administrative-Systems/northwestern-starlight-theme/compare/v1.0.0...v1.1.0
 [1.0.0]: https://github.com/NIT-Administrative-Systems/northwestern-starlight-theme/releases/tag/v1.0.0

package/index.ts

@@ -3,7 +3,25 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import type { StarlightPlugin } from "@astrojs/starlight/types";
+import rehypeTableScroll from "./src/rehype-table-scroll.ts";
 
+/**
+ * Configuration for the homepage hero section.
+ *
+ * Controls hero layout, title visibility, and image sizing. Passed as the
+ * `homepage` property of {@link NorthwesternThemeConfig}.
+ *
+ * @example
+ * ```ts
+ * northwesternTheme({
+ *     homepage: {
+ *         layout: "split",
+ *         showTitle: false,
+ *         imageWidth: "750px",
+ *     },
+ * })
+ * ```
+ */
 export interface NorthwesternHomepageConfig {
     /**
      * Hero layout style.
@@ -32,19 +50,46 @@ export interface NorthwesternHomepageConfig {
     imageWidth?: string;
 }
 
+/**
+ * Top-level configuration for the Northwestern Starlight theme plugin.
+ *
+ * Pass to {@link northwesternTheme} when registering the plugin in your
+ * Starlight config. All properties are optional and have sensible defaults.
+ *
+ * @example
+ * ```ts
+ * // astro.config.ts
+ * import northwesternTheme from "@nu-appdev/northwestern-starlight-theme";
+ *
+ * export default defineConfig({
+ *     integrations: [
+ *         starlight({
+ *             plugins: [northwesternTheme({ homepage: { layout: "split" } })],
+ *         }),
+ *     ],
+ * });
+ * ```
+ *
+ * @see {@link NorthwesternHomepageConfig} for homepage hero options
+ */
 export interface NorthwesternThemeConfig {
     /**
      * Homepage hero layout configuration.
+     *
+     * @see {@link NorthwesternHomepageConfig}
      */
     homepage?: NorthwesternHomepageConfig;
 
     /**
      * Mermaid diagram support.
      *
-     * - `true` (default) — auto-detect: enables mermaid if `astro-mermaid` and `mermaid`
+     * - `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)
+     * - `false` — disables Mermaid entirely
+     * - `object` — enables Mermaid with custom {@link https://mermaid.js.org/config/schema-docs/config.html | MermaidConfig}
+     *   merged with Northwestern defaults
+     *
+     * @default true
      */
     mermaid?: boolean | Record<string, unknown>;
 }
@@ -64,6 +109,33 @@ async function canResolve(id: string): Promise<boolean> {
 const VIRTUAL_MODULE_ID = "virtual:northwestern-theme/config";
 const RESOLVED_VIRTUAL_MODULE_ID = `\0${VIRTUAL_MODULE_ID}`;
 
+/**
+ * Create a Northwestern-branded Starlight theme plugin.
+ *
+ * Registers Northwestern typography (Akkurat Pro, Poppins), purple color palette,
+ * component overrides (Hero, ThemeToggle, EditLink), and optional Mermaid diagram
+ * support with branded color schemes.
+ *
+ * @param config - Theme configuration. All properties optional.
+ * @returns A Starlight plugin to pass to `plugins` in your Starlight config.
+ *
+ * @example Basic usage (all defaults)
+ * ```ts
+ * starlight({ plugins: [northwesternTheme()] })
+ * ```
+ *
+ * @example Split hero with Mermaid disabled
+ * ```ts
+ * starlight({
+ *     plugins: [
+ *         northwesternTheme({
+ *             homepage: { layout: "split", showTitle: false },
+ *             mermaid: false,
+ *         }),
+ *     ],
+ * })
+ * ```
+ */
 export default function northwesternTheme(config: NorthwesternThemeConfig = {}): StarlightPlugin {
     const { homepage = {}, mermaid = true } = config;
     const themeConfig = {
@@ -92,6 +164,9 @@ export default function northwesternTheme(config: NorthwesternThemeConfig = {}):
                     hooks: {
                         "astro:config:setup": ({ updateConfig: updateAstroConfig }) => {
                             updateAstroConfig({
+                                markdown: {
+                                    rehypePlugins: [rehypeTableScroll],
+                                },
                                 vite: {
                                     plugins: [
                                         {
@@ -151,7 +226,7 @@ export default function northwesternTheme(config: NorthwesternThemeConfig = {}):
                         },
                     },
                 });
-                // Detect mermaid availability
+                // Detect Mermaid availability
                 let mermaidEnabled = mermaid;
 
                 if (mermaidEnabled) {
@@ -159,7 +234,7 @@ export default function northwesternTheme(config: NorthwesternThemeConfig = {}):
 
                     if (!hasMermaid) {
                         if (typeof mermaid === "object") {
-                            // User explicitly configured mermaid but it's not installed
+                            // 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",
@@ -190,6 +265,9 @@ export default function northwesternTheme(config: NorthwesternThemeConfig = {}):
                         "@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/blockquotes.css",
+                        "@nu-appdev/northwestern-starlight-theme/src/styles/components/footnotes.css",
+                        "@nu-appdev/northwestern-starlight-theme/src/styles/components/tables.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",
@@ -198,6 +276,7 @@ export default function northwesternTheme(config: NorthwesternThemeConfig = {}):
                         "@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",
+                        "@nu-appdev/northwestern-starlight-theme/src/styles/a11y.css",
                         ...(starlightConfig.customCss ?? []),
                     ],
                     expressiveCode: {

package/mermaid.ts

@@ -2,14 +2,41 @@ import type { AstroIntegration } from "astro";
 import mermaid, { type AstroMermaidOptions } from "astro-mermaid";
 import { darken, isDark, lighten, mix, transparentize } from "khroma";
 
+/**
+ * Configuration options for the Northwestern Mermaid integration.
+ *
+ * Extends `astro-mermaid` options with a `toolbar` toggle that controls
+ * the hover toolbar (fullscreen, download, copy) on rendered diagrams.
+ *
+ * @see {@link northwesternMermaid} for the integration factory
+ */
 export interface NorthwesternMermaidOptions extends AstroMermaidOptions {
+    /**
+     * Show the hover toolbar (fullscreen, download SVG, copy source) on diagrams.
+     *
+     * @default true
+     */
     toolbar?: boolean;
 }
 
+/**
+ * Theme mode for Mermaid color palette generation.
+ *
+ * Maps to the `data-theme` attribute on `<html>`: `"light"` for the default
+ * palette, `"dark"` for the inverted palette with lighter primary colors
+ * and darker canvas backgrounds.
+ */
 export type NorthwesternMermaidMode = "light" | "dark";
 
+/** Flat key-value map passed to Mermaid's `themeVariables`. */
 type ThemeVariables = Record<string, unknown>;
 
+/**
+ * Resolved brand palette for a single theme mode.
+ *
+ * All values are hex strings. Derived from Northwestern's brand primaries
+ * with light/dark adjustments via `khroma`.
+ */
 type BrandPalette = {
     purple: string;
     blue: string;
@@ -31,6 +58,15 @@ type BrandPalette = {
 
 const chartPalette = ["#4e2a84", "#836eaa", "#5091cd", "#008656", "#ffc520", "#ef553f", "#7fcecd", "#d85820"];
 
+/** Generate `{ prefix0: fn(0), prefix1: fn(1), ... }` from an array. */
+function indexedVars(prefix: string, values: string[], startAt = 0): ThemeVariables {
+    const out: ThemeVariables = {};
+    for (let i = 0; i < values.length; i++) {
+        out[`${prefix}${i + startAt}`] = values[i];
+    }
+    return out;
+}
+
 function onColor(color: string, darkText = "#342f2e", lightText = "#fff") {
     return isDark(color) ? lightText : darkText;
 }
@@ -216,32 +252,16 @@ function createThemeVariables(mode: NorthwesternMermaidMode): ThemeVariables {
         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]),
+        // Git graph — one color per branch from the chart palette
+        ...indexedVars("git", chartPalette),
+        ...indexedVars(
+            "gitBranchLabel",
+            chartPalette.map((c) => onColor(c)),
+        ),
         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],
+        // Pie chart — 8 base slices + 4 extended with tint shift
+        ...indexedVars("pie", chartPalette, 1),
         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),
@@ -255,35 +275,64 @@ function createThemeVariables(mode: NorthwesternMermaidMode): ThemeVariables {
         pieLegendTextSize: "14px",
         pieStrokeWidth: "2px",
         pieOuterStrokeWidth: "1px",
-        pieOuterStrokeColor: dark ? palette.border : palette.border,
+        pieOuterStrokeColor: 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)),
+        // C4/journey scale — each color mixed toward canvas in dark mode
+        ...(() => {
+            const colors = [
+                primary,
+                palette.blue,
+                palette.green,
+                palette.orange,
+                palette.teal,
+                palette.yellow,
+                palette.red,
+                primary,
+            ];
+            const darkMix = [40, 40, 40, 35, 35, 30, 35, 30];
+            const lightFallback = [
+                primary,
+                palette.blue,
+                palette.green,
+                palette.orange,
+                darken(palette.teal, 15),
+                darken(palette.yellow, 20),
+                palette.red,
+                lighten(primary, 10),
+            ];
+            return indexedVars(
+                "cScale",
+                colors.map((c, i) => (dark ? mix(c, palette.canvas, darkMix[i]) : lightFallback[i])),
+            );
+        })(),
+        ...indexedVars("cScaleLabel", [
+            palette.white,
+            palette.white,
+            palette.white,
+            palette.white,
+            dark ? palette.white : palette.black,
+            palette.black,
+            palette.white,
+            palette.white,
+        ]),
+
+        // Quadrant chart — progressive primary tints
+        ...(() => {
+            const darkRatios = [35, 28, 22, 15];
+            const lightRatios = [25, 18, 12, 8];
+            const fills = darkRatios.map((dr, i) =>
+                dark ? mix(primary, palette.canvas, dr) : mix(primary, palette.white, lightRatios[i]),
+            );
+            return {
+                ...indexedVars("quadrantFill", fills, 1),
+                ...indexedVars(
+                    "quadrantTextFill",
+                    fills.map((f) => onColor(f)),
+                    1,
+                ),
+            };
+        })(),
         quadrantPointFill: primary,
         quadrantPointTextFill: dark ? palette.white : palette.black,
         quadrantXAxisTextFill: palette.text,
@@ -294,17 +343,36 @@ function createThemeVariables(mode: NorthwesternMermaidMode): ThemeVariables {
 
         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",
+            titleColor: palette.text,
+            xAxisLabelColor: palette.text,
+            yAxisLabelColor: palette.text,
+            xAxisTitleColor: palette.text,
+            yAxisTitleColor: palette.text,
+            xAxisLineColor: dark ? palette.border : "#ccc",
+            yAxisLineColor: dark ? palette.border : "#ccc",
         },
     };
 }
 
+/**
+ * Generate a complete `astro-mermaid` config with Northwestern-branded colors
+ * for the given theme mode.
+ *
+ * Builds a Mermaid `themeVariables` object from the Northwestern brand palette,
+ * deriving all node, edge, label, chart, and diagram-specific colors from a
+ * small set of brand primaries via `khroma` color manipulation.
+ *
+ * @param mode - `"light"` or `"dark"`. Controls canvas, text, and primary color values.
+ * @returns A complete `AstroMermaidOptions` object ready to pass to `astro-mermaid`.
+ *
+ * @example
+ * ```ts
+ * import { createNorthwesternMermaidConfig } from "@nu-appdev/northwestern-starlight-theme/mermaid";
+ *
+ * const darkConfig = createNorthwesternMermaidConfig("dark");
+ * // darkConfig.mermaidConfig.themeVariables contains all colors
+ * ```
+ */
 export function createNorthwesternMermaidConfig(mode: NorthwesternMermaidMode): AstroMermaidOptions {
     const palette = createPalette(mode);
     return {
@@ -314,45 +382,93 @@ export function createNorthwesternMermaidConfig(mode: NorthwesternMermaidMode):
             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",
+                titleColor: palette.text,
+                xAxisLabelColor: palette.text,
+                yAxisLabelColor: palette.text,
+                xAxisTitleColor: palette.text,
+                yAxisTitleColor: palette.text,
+                xAxisLineColor: mode === "dark" ? palette.border : "#ccc",
+                yAxisLineColor: mode === "dark" ? palette.border : "#ccc",
             },
         },
     };
 }
 
 /**
- * Northwestern-branded Mermaid configuration.
+ * Pre-built light-mode Mermaid config with Northwestern brand colors.
  *
- * 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.
+ * Used as the default when Mermaid is auto-detected. Override individual
+ * `themeVariables` by passing a `mermaid` object to {@link northwesternTheme}
+ * in `index.ts`, or use {@link createNorthwesternMermaidConfig} for full control.
  */
 export const defaultMermaidConfig: AstroMermaidOptions = createNorthwesternMermaidConfig("light");
+
+/**
+ * Pre-built dark-mode Mermaid config with Northwestern brand colors.
+ *
+ * Applied at runtime when the user switches to dark mode. The toolbar script
+ * re-renders diagrams with this config via `window.__NU_MERMAID_CONFIGS__.dark`.
+ */
 export const darkMermaidConfig: AstroMermaidOptions = createNorthwesternMermaidConfig("dark");
 
+/**
+ * Create an Astro integration that registers Northwestern-branded Mermaid diagrams.
+ *
+ * Wraps `astro-mermaid` with Northwestern color palettes for both light and dark
+ * modes, and injects the toolbar script (fullscreen viewer, download, copy).
+ *
+ * **Must be added before `starlight()` in the `integrations` array.** The
+ * `astro-mermaid` remark plugin needs to register before Starlight's rehype
+ * processing, and Astro processes integrations in order. Placing it after
+ * `starlight()` causes Mermaid code blocks to be treated as plain code.
+ *
+ * @param options - Merged with Northwestern defaults. Set `toolbar: false` to
+ *   disable the hover toolbar.
+ * @returns An Astro integration to add to `integrations` in your Astro config.
+ *
+ * @example
+ * ```ts
+ * import { northwesternMermaid } from "@nu-appdev/northwestern-starlight-theme/mermaid";
+ * import northwesternTheme from "@nu-appdev/northwestern-starlight-theme";
+ *
+ * export default defineConfig({
+ *     integrations: [
+ *         northwesternMermaid(), // Must come before starlight()
+ *         starlight({
+ *             plugins: [northwesternTheme()],
+ *             title: "My Docs",
+ *         }),
+ *     ],
+ * });
+ * ```
+ */
 export function northwesternMermaid(options: NorthwesternMermaidOptions = {}): AstroIntegration {
     const { toolbar = true, ...overrides } = options;
     const lightConfig = createNorthwesternMermaidConfig("light");
     const darkConfig = createNorthwesternMermaidConfig("dark");
 
+    const userMermaidConfig = overrides.mermaidConfig ?? {};
+    const userThemeVars = (userMermaidConfig as Record<string, unknown>)?.themeVariables ?? {};
+
+    function mergeWithOverrides(base: Record<string, unknown>): Record<string, unknown> {
+        return {
+            ...base,
+            ...userMermaidConfig,
+            themeVariables: {
+                ...(base.themeVariables ?? {}),
+                ...userThemeVars,
+            },
+        };
+    }
+
+    const mergedLightMermaidConfig = mergeWithOverrides(lightConfig.mermaidConfig as Record<string, unknown>);
+    const mergedDarkMermaidConfig = mergeWithOverrides(darkConfig.mermaidConfig as Record<string, unknown>);
+
     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 ?? {}),
-            },
-        },
+        mermaidConfig: mergedLightMermaidConfig,
     });
 
     return {
@@ -365,10 +481,10 @@ export function northwesternMermaid(options: NorthwesternMermaidOptions = {}): A
                     "page",
                     `window.__NU_MERMAID_TOOLBAR__ = ${toolbar ? "true" : "false"}; window.__NU_MERMAID_CONFIGS__ = ${JSON.stringify(
                         {
-                            light: lightConfig.mermaidConfig,
-                            dark: darkConfig.mermaidConfig,
+                            light: mergedLightMermaidConfig,
+                            dark: mergedDarkMermaidConfig,
                         },
-                    )}; import "@nu-appdev/northwestern-starlight-theme/src/scripts/mermaid-toolbar.ts";`,
+                    )}; import "@nu-appdev/northwestern-starlight-theme/src/scripts/mermaid/toolbar.ts";`,
                 );
             },
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nu-appdev/northwestern-starlight-theme",
-  "version": "1.1.1",
+  "version": "1.3.0",
   "description": "A Northwestern-branded theme for Astro Starlight",
   "license": "MIT",
   "author": "Danny Foster <danny@northwestern.edu>",
@@ -27,9 +27,21 @@
     "provenance": true
   },
   "exports": {
-    ".": "./index.ts",
-    "./expressive-code": "./expressive-code.mjs",
-    "./mermaid": "./mermaid.ts",
+    ".": {
+      "types": "./index.ts",
+      "import": "./index.ts"
+    },
+    "./expressive-code": {
+      "import": "./expressive-code.mjs"
+    },
+    "./mermaid": {
+      "types": "./mermaid.ts",
+      "import": "./mermaid.ts"
+    },
+    "./components": {
+      "types": "./src/components/index.ts",
+      "import": "./src/components/index.ts"
+    },
     "./src/styles/components/*": "./src/styles/components/*",
     "./src/components/*": "./src/components/*",
     "./src/scripts/*": "./src/scripts/*",
@@ -59,5 +71,8 @@
     "mermaid": {
       "optional": true
     }
+  },
+  "devDependencies": {
+    "@types/hast": "^3.0.4"
   }
 }