Skip to content

Package

For React apps, Storybook setups, sandboxes, and any project with its own build pipeline outside AEM, install the styleguide as an npm package.

Terminal window
npm install --save-dev @tmedxp/styleguide

Pick the entry that matches your needs. The branded entries bundle a brand’s tokens with the full styleguide — the simplest setup. The brand-neutral styles.css ships every component without tokens, for hosts that apply brand tokens at runtime (it’s what the multi-brand setup below uses).

import '@tmedxp/styleguide/toyota/styles.css'; // full styleguide + Toyota tokens
import '@tmedxp/styleguide/lexus/styles.css'; // full styleguide + Lexus tokens
import '@tmedxp/styleguide/kinto/styles.css'; // full styleguide + Kinto tokens (preview)
import '@tmedxp/styleguide/styles.css'; // full styleguide, no tokens

The entries above target current browsers. A host that must still run on Chrome 120, such as retailer screens, imports the same entry under compat/ instead — identical styles, lowered for Chrome 120 and so somewhat larger:

import '@tmedxp/styleguide/compat/toyota/styles.css';

Every CSS entry has a compat/ twin. Load one build or the other on a page, never both. What Chrome 120 support covers, and what degrades, is on Browser support.

Entry Contents
@tmedxp/styleguide Global consts and brand namespaces
@tmedxp/styleguide/assets.css Styleguide assets
@tmedxp/styleguide/styles.css Full styleguide, all components, no brand tokens
@tmedxp/styleguide/compat/*.css Any CSS entry above, lowered for Chrome 120
@tmedxp/styleguide/kinto Kinto namespace (preview)
@tmedxp/styleguide/kinto/assets.css Styleguide and Kinto brand assets
@tmedxp/styleguide/kinto/density.css Opt-in coarse density for Kinto
@tmedxp/styleguide/kinto/theme.css Branded foundation + Kinto tokens, no components
@tmedxp/styleguide/kinto/styles.css Full styleguide with Kinto tokens
@tmedxp/styleguide/kinto/components/*.css One self-contained Kinto component, e.g. kinto/components/button.css
@tmedxp/styleguide/kinto/forms/*.css One self-contained Kinto form component, e.g. kinto/forms/stepper.css
@tmedxp/styleguide/kinto/cards/*.css One self-contained Kinto card component, e.g. kinto/cards/model-card.css
@tmedxp/styleguide/lexus Lexus namespace
@tmedxp/styleguide/lexus/assets.css Styleguide and Lexus brand assets
@tmedxp/styleguide/lexus/density.css Opt-in coarse density for Lexus
@tmedxp/styleguide/lexus/theme.css Branded foundation + Lexus tokens, no components
@tmedxp/styleguide/lexus/styles.css Full styleguide with Lexus tokens
@tmedxp/styleguide/lexus/components/*.css One self-contained Lexus component, e.g. lexus/components/button.css
@tmedxp/styleguide/lexus/forms/*.css One self-contained Lexus form component, e.g. lexus/forms/stepper.css
@tmedxp/styleguide/lexus/cards/*.css One self-contained Lexus card component, e.g. lexus/cards/model-card.css
@tmedxp/styleguide/toyota Toyota namespace
@tmedxp/styleguide/toyota/assets.css Styleguide and Toyota brand assets
@tmedxp/styleguide/toyota/density.css Opt-in coarse density for Toyota
@tmedxp/styleguide/toyota/theme.css Branded foundation + Toyota tokens, no components
@tmedxp/styleguide/toyota/styles.css Full styleguide with Toyota tokens
@tmedxp/styleguide/toyota/components/*.css One self-contained Toyota component, e.g. toyota/components/button.css
@tmedxp/styleguide/toyota/forms/*.css One self-contained Toyota form component, e.g. toyota/forms/stepper.css
@tmedxp/styleguide/toyota/cards/*.css One self-contained Toyota card component, e.g. toyota/cards/model-card.css
@tmedxp/styleguide/rfc-assets/* Build-tool assets, preview

The package also exposes brand namespaces from its JS entry:

import { Toyota } from '@tmedxp/styleguide';
import * as Toyota from '@tmedxp/styleguide/toyota';
Toyota.ICONS; // Toyota.Icon[]

The full {brand}/styles.css bundle carries every component on every page. A consumer that can tie CSS loading to component rendering — an SSR server emitting <link>s, or a bundler that code-splits CSS per component — can instead load a brand theme plus only the per-component entries a page actually uses. A page rendering a handful of components ships markedly less CSS this way.

Two pieces make up a chunked page:

  1. {brand}/theme.css — the branded foundation: reset, foundations, layouts, utilities, plus the brand’s semantic + primitive tokens. No component CSS, no component tokens. Load once per page.
  2. {brand}/components/{name}.css (and {brand}/forms/, {brand}/cards/) — one self-contained component each, mirroring the styleguide source dirs. Each entry already has that brand’s component tokens inlined, so it works the moment it’s loaded next to the theme — no separate token chunks, no @tmedxp/figma-tokens dependency.

A server that knows the brand per route emits the theme and the component entries the page renders. Nothing else — each component entry carries its own brand tokens:

<link rel="stylesheet" href="@tmedxp/styleguide/toyota/theme.css" />
<link rel="stylesheet" href="@tmedxp/styleguide/toyota/components/button.css" />
<link
rel="stylesheet"
href="@tmedxp/styleguide/toyota/components/notification.css"
/>

Each entry only ever carries its own brand’s tokens, so a Toyota build never ships Lexus tokens (and vice versa). Components compose freely: a notification that renders a link picks up the link’s colours from toyota/components/link.css when that entry is present.

Hosts that render several brands on one page — kept apart by data-brand — load the brand-neutral aggregate once, then each brand’s tokens side by side. This is what the DX Playbook and the visual-test harness do: they render every component, so chunking buys them nothing, and they stay on the aggregate.

@import url('@tmedxp/styleguide/styles.css'); /* base + ALL components, no tokens */
@import url('@tmedxp/styleguide/kinto/assets.css');
@import url('@tmedxp/styleguide/lexus/assets.css');
@import url('@tmedxp/styleguide/toyota/assets.css');
@import url('@tmedxp/figma-tokens/kinto.css') layer(tng.foundations);
@import url('@tmedxp/figma-tokens/lexus.css') layer(tng.foundations);
@import url('@tmedxp/figma-tokens/toyota.css') layer(tng.foundations);

Cascade layers keep load order robust. The theme declares the layer order; component entries (and the brand tokens they inline) import under tng.components, while the theme’s semantic + primitive tokens resolve under tng.foundations. Order the tags theme → components for readability, but the layers — not source order — fix the cascade. Override styleguide rules from the unlayered tng.userstyles layer.

A component entry loaded without {brand}/theme.css renders unstyled — its semantic tokens are undefined. Always pair component entries with a theme.

The active brand is selected via a data-brand attribute on the <html> element. Set it once at the host level — your app, your Storybook preview, your sandbox — and every token resolves accordingly.

<html data-brand="lexus">
...
</html>

See Brands for how the attribute drives token resolution.

The styleguide sets the 62.5% root font size its tokens are sized against. Leave font-size on html and :root unset in your app, Storybook preview, or sandbox, or every CDS dimension renders at the wrong size. See Root font size.

The brand fonts ship with the package. For a quick drop-in, reference the font-face stylesheet the styleguide exposes; the Storybook section below shows where to load it.

{brand}/assets.css inlines every icon as a data URI, so every page downloads all of them. A host with a bundler can import the rfc-assets/ twin instead: the same rules, each icon a real .svg file, plus the brand fonts pre-split into unicode-range subsets so a page only fetches the scripts it renders.

@import url('@tmedxp/styleguide/rfc-assets/toyota/assets.css'); /* instead of toyota/assets.css */
@import url('@tmedxp/styleguide/rfc-assets/toyota/fonts.css');
File Contents
rfc-assets/{brand}/assets.css {brand}/assets.css with url()s to the files below
rfc-assets/{brand}/icons/*.svg One file per icon, named after its .icon-* class
rfc-assets/{brand}/platform-badges/*.svg Platform badge artwork
rfc-assets/{brand}/fonts.css The brand’s @font-face rules, one per subset
rfc-assets/fonts/*.woff2 The subset font files

Your bundler resolves the relative url()s and copies the files. Vite inlines any asset under 4 KB back into the CSS by default — set build.assetsInlineLimit to 0 to keep them as files.

The rfc-assets/ paths are a preview: they may move before they’re promoted.

Update your previewHead with the assets and styles for the brand you’re showing:

preview-head.html
<link
rel="stylesheet"
href="/node_modules/@tmedxp/styleguide/toyota/assets.css"
/>
<link
rel="stylesheet"
href="/node_modules/@tmedxp/styleguide/toyota/styles.css"
/>

If you’re using React, we are exposing 2 packages

Plain react component

Terminal window
npm install --save-dev @tmedxp/react-components

AEM React component - made specificy on top of the react component for usage within AEM

Terminal window
npm install --save-dev @tmedxp/aem-react-components
import { PillButton } from '@tmedxp/react-components';
export const Component = () => <PillButton />;

The runtime concepts in Architecture — CSS layers, the root reset, brand switching, and how drafts work — apply once the styleguide is loaded, regardless of how you installed it.