m3-tokens-react

Material 3 design tokens, a React ThemeProvider, and components (Button, Card, Chip) generated 1:1 from a Figma Material 3 design kit token export. Every token keeps its original Figma name and carries a figmaPath so you can always trace a value back to the design file.

Install

npm install m3-tokens-react

React 18 or newer is required (it's a peer dependency).

Quick start

Wrap your app in the theme provider. It puts every token on the page as a CSS custom property (like --md-sys-color-primary) and handles light/dark switching:

Import the stylesheet once (for example in your app entry file), then wrap your app in the theme provider:

import "m3-tokens-react/styles.css";
import { M3ThemeProvider } from "m3-tokens-react";

export default function App() {
  return (
    <M3ThemeProvider defaultScheme="light">
      <YourApp />
    </M3ThemeProvider>
  );
}

Use the components

import { M3Button, M3Card, M3Chip } from "m3-tokens-react";

<M3Button variant="filled" onClick={save}>Save</M3Button>
<M3Card variant="elevated">Card content</M3Card>
<M3Chip variant="filter" selected>Popular</M3Chip>

The components load Roboto sizes and weights from the type scale tokens, so add Roboto to your page (for example via Google Fonts) for faithful rendering.

Use the tokens directly

In CSS, reference any token as a variable — these update automatically when the scheme changes:

.banner {
  background: var(--md-sys-color-primary-container);
  color: var(--md-sys-color-on-primary-container);
  box-shadow: var(--md-sys-elevation-level1);
}

In React, read tokens and control the scheme with the hook:

import { useM3Theme, m3Tokens } from "m3-tokens-react";

function SchemeToggle() {
  const { scheme, toggleScheme } = useM3Theme();
  return <M3Button variant="outlined" onClick={toggleScheme}>
    Switch to {scheme === "light" ? "dark" : "light"}
  </M3Button>;
}

// The full token tree is also available as data:
m3Tokens.schemes.light.colors["md-sys-color-primary"].value; // "#6750a4ff"
m3Tokens.typescale["md-sys-typescale-body-large"].fontSize;  // 16

What's inside

• System colors — md-sys-color-* for light and dark, plus elevation surface tints
• State layers — md-sys-state-layers-<name>-opacity-<percent> for hover/press states
• Reference palettes — six tonal palettes (md-ref-palette-primary40, ...)
• Type scale — 15 styles (md-sys-typescale-display-large, ...) with full metrics
• Elevation — five levels as ready-to-use box-shadow values per scheme
• Every token has a figmaPath tracing it to the original Figma export

Regenerating from Figma

Token data is generated from the Figma token export by scripts/generate.mjs. To pick up a new export, replace the source JSON and run:

npm run generate
npm run build

The generator validates that every token name is a legal CSS custom property name and fails loudly if an export would break the theme.