3M Global Design System

Decision 1: Two token tiers, with brand, device and color mode as variable modes

My first model was a chain of JSON files. A 3M palette file fed one file per brand (SIBG, AAD), which fed light and dark files, which fed a component file.

Figure 4.0. The first token model. Each file aliases the one before it.

Dark mode exposed a gap in that chain. It did not say which values change between light and dark and which stay fixed. The next diagram pairs each text token with the surface it sits on. Dynamic tokens change with the mode. Static tokens, such as white text on a brand-40 fill, do not.

Figure 4.1. Brand files in light and dark (left). Dynamic and static text tokens (right).

The shipped version uses Figma Variables in two tiers. Foundation tokens include color ramps with steps from 10 to 110 and a matching dark ramp. Each step lists hex, lightness, chroma, hue, a CSS name and a TypeScript name. —mmm-color-red-60 is #EB0029, for example.

Figure 4.2. The variable visualization page in the Foundation file, cropped to the maroon and red ramps.

Semantic token names follow one pattern: property, role, then emphasis. The properties are text, icon, border and bg. The roles are neutral, brand, accent, negative, warning, positive and alt. The emphasis levels are low-emphasis, emphasis, high-emphasis and press, so a developer can guess bg-brand-high-emphasis before looking it up. A -fixed-dark suffix marks the value meant for fixed dark surfaces. In light mode, text-default is #151518 and text-default-fixed-dark is #f2f2f5.

Brand, device and color mode are Figma variable modes. The build resolves one file per combination. In the SIBG package —layout-padding is 24 on desktop and 16 on mobile, and —button-height-standard is 40 on desktop and 44 on mobile. Each SIBG build contains 278 tokens.

Decision 2: Fail the build when Figma’s structure changes

Designers edit variables at any time, and the build locates modes by collection and mode name. A renamed mode would otherwise publish a package that silently lacks a device or a theme.

The contract check (npm run contract:check) calls /v1/files/:key/variables/local and fails if the payload is missing variable collections or contains zero variables. It also fails if the desktop or mobile device mode or the light or dark color mode is missing. A missing brand mode logs a warning. The fetch and build steps run only after the check passes.

Decision 3: Build on the Material libraries teams already used

The JUMBO monorepo (Nx with npm workspaces) turns Figma tokens into a framework-neutral core, then into three adapters:

• @3m-cloud/jumbo-mui exports createJumboMuiTheme(), which returns an MUI v7 theme.
• @3m-cloud/jumbo-angular generates SCSS themes for Angular Material v12 and for v17 and later.
• Jumbo.MaterialBlazor provides Razor components that wrap Material.Blazor v5.

The design system constitution gives engineers three ways in, and none is required. They can clone a model-home repository as a starter, copy a component or theme into an existing project, or build from the Theme Configurator’s CSS and HTML output and the Figma files. The design team owns the Figma libraries and the configurator. Engineering is invited to send pull requests to the model homes, so the system works like an internal open source project.

Figure 4.3. The layers drawn as a kitchen analogy. Corporate is the store, the 3M design system is the basket, SIBG adds a cutting board to prepare JUMBO, and an application such as RepairStack is the finished dish.

Decision 4: Contribute pull requests instead of handing off specifications

I joined a new monorepo that was rebuilding several acquired applications into one Angular codebase. Instead of writing specifications for the other engineers to implement, I opened component pull requests:

• Replaced custom HTML placeholder components with production components built on Angular Material.
• Installed the token packages and configured them to drive the Angular Material styling layer.
• Used the tokenized components in live application features alongside the core engineering team.

The difference shows up in a single rule. The first block is an illustrative example of hand-matching a Figma frame to a stock Angular Material color. The second uses token names and values from the published SIBG package.

// Before: values copied from a Figma frame
.save-button {
  background: #3f51b5;
  color: #fff;
  height: 36px;
  border-radius: 4px;
}

// After: values from @3m-cloud/sibg-jumbo-tokens
@use "@3m-cloud/sibg-jumbo-tokens/dist/sibg/desktop/light/scss/variables" as t;

.save-button {
  background: t.$bg-brand-emphasis;          // #3373e0
  color: t.$text-on-color;                   // #ffffff
  height: t.$button-height-standard * 1px;   // 40
  border-radius: t.$button-radius * 1px;     // 2
}

Decision 5: Write for AI coding assistants as well as for people

Engineers on these teams used AI coding assistants, and an assistant with no token source guesses values. I added a machine-readable component manifest (manifest.md) to the monorepo. It lists token names, component parameters and layout rules. Developers wrote custom agent skills that point at it, so their assistants read token variables from the npm packages and produced layouts that matched the brand without styling errors.

The JUMBO repository applies the same idea at larger scale. A generator produces these files, and no one edits them by hand:

• MANIFEST.md and llms.txt as entry points.
• components.json, which covers 30 components. Each entry lists the per-framework import, props with allowed values, the tokens used, do and don’t guidance and copy-paste recipes.
• tokens.json, with 30 resolved sets: 5 brands, 2 themes and 3 devices.
• A 9-section DESIGN.md contract for each brand.
• An MCP server that serves the same data, and three agent skills for consuming the system, auditing a design against it and keeping the manifest current.

Two rules lead the consumption guide. Never hardcode a color, radius or size, and resolve each from a token. Match the brand’s look and feel, not only its values.