MINT Design System

A lightweight, white-labelable React + Tailwind v4 design system for GHG / carbon-inventory (ESM) reports. Components are organised by atomic design (atoms → molecules → organisms → templates) and documented in Storybook.

Built to reproduce the ESM Prototype MINT report, but re-skinnable to any company's brand by overriding a handful of CSS variables — no rebuild required.

Install

npm install mint-design-system

Peer dependencies: react and react-dom (>= 18).

Usage

Import the compiled stylesheet once at your app root, then use components:

import "mint-design-system/styles.css";
import { ReportPage, Section, StatGrid } from "mint-design-system";

export function Summary() {
  return (
    <ReportPage title="Executive Summary" page="PAGE 06">
      <Section eyebrow="SECTION 6" title="Executive Summary">
        <StatGrid
          columns={4}
          items={[
            { label: "TOTAL GHG INVENTORY", value: "1693.79", unit: "tCO2e" },
            { label: "SCOPE 1", value: "370.61", unit: "tCO2e" },
            { label: "SCOPE 2", value: "385.96", unit: "tCO2e" },
            { label: "SCOPE 3", value: "937.22", unit: "tCO2e" },
          ]}
        />
      </Section>
    </ReportPage>
  );
}

You do not need Tailwind in your app — the shipped styles.css already contains every utility the components use.

Branding / white-label

Every color and font is a CSS custom property. Rebrand in either of two ways.

1 — CSS override (global): set the tokens in your own stylesheet.

:root {
  --color-brand-400: #f59e0b; /* accent bars / rules       */
  --color-brand-600: #b45309; /* links / emphasis / arrows */
  --color-brand-800: #78350f; /* eyebrows / dark accents   */
  --font-display: "Georgia", serif;
}

2 — <BrandProvider> (scoped / multi-tenant, runtime): wrap any subtree. The default (MINT) palette is always the fallback; provide overrides to reskin.

import { BrandProvider } from "mint-design-system";

// Simplest: one brand color, expanded to a full 50–900 scale automatically.
<BrandProvider seed="#6366f1">
  <ReportPage title="…">…</ReportPage>
</BrandProvider>;

// Or a precise palette + fonts (explicit stops win over the seed):
<BrandProvider
  brand={{
    seed: "#6366f1",
    brand: { 400: "#818cf8", 600: "#4f46e5", 800: "#3730a3" },
    fontDisplay: "'Newsreader', serif",
  }}
>
  <ReportPage title="…">…</ReportPage>
</BrandProvider>;

For a user-driven picker (company admin chooses a color at runtime), feed the value straight into seed — see the Palette Playground story. You can also generate a scale yourself with brandScale("#6366f1").

See the 0 · White-label story and the toolbar Brand switcher in Storybook for a live comparison.

Token reference

| Token group | Variables | Used for | | ---------------- | ------------------------------------ | ------------------------------ | | Brand scale | --color-brand-50 … 900 | all accent colouring | | Semantic accents | --color-accent, --color-primary | bars/rules, links, arrows | | Ink | --color-ink* | text at 4 emphasis levels | | Surfaces / lines | --color-surface*, --color-line* | cards, backgrounds, borders | | Note | --color-note* | the amber "prototype data" box | | Type | --font-display, --font-sans | headings vs. body/labels |

Component map (atomic design)

• Atoms — Wordmark, Eyebrow, Heading, Text, Badge, Divider, AccentBar, Metric
• Molecules — StatCard, InfoCard, Callout, PriorityCard, DistributionBar, ProcessSteps, ValueRow, TocRow
• Organisms — PageHeader, PageFooter, DataTable, StatGrid, TableOfContents, Section, HotspotList, CoverHero
• Templates — ReportPage, CoverPage

Develop

npm install
npm run storybook     # http://localhost:6006
npm run build         # emits dist/ (JS + types + mint.css)
npm run typecheck

License

MIT