Package
For React apps, Storybook setups, sandboxes, and any project with its own build pipeline outside AEM, install the styleguide as an npm package.
Install
Section titled “Install”npm install --save-dev @tmedxp/styleguidepnpm add --save-dev @tmedxp/styleguideImport
Section titled “Import”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 tokensimport '@tmedxp/styleguide/lexus/styles.css'; // full styleguide + Lexus tokensimport '@tmedxp/styleguide/kinto/styles.css'; // full styleguide + Kinto tokens (preview)import '@tmedxp/styleguide/styles.css'; // full styleguide, no tokensChrome 120
Section titled “Chrome 120”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.
All exports
Section titled “All exports”| 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[]Load only what a page renders
Section titled “Load only what a page renders”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:
{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.{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-tokensdependency.
Single-brand SSR
Section titled “Single-brand SSR”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.
Multi-brand
Section titled “Multi-brand”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);Load order
Section titled “Load order”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.cssrenders unstyled — its semantic tokens are undefined. Always pair component entries with a theme.
Set the active brand
Section titled “Set the active brand”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.
Root font size
Section titled “Root font size”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.
Build-tool assets (preview)
Section titled “Build-tool assets (preview)”{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.
Storybook
Section titled “Storybook”Update your previewHead with the assets and styles for the brand you’re showing:
<link rel="stylesheet" href="/node_modules/@tmedxp/styleguide/toyota/assets.css"/><link rel="stylesheet" href="/node_modules/@tmedxp/styleguide/toyota/styles.css"/>React component library
Section titled “React component library”If you’re using React, we are exposing 2 packages
Plain react component
npm install --save-dev @tmedxp/react-componentspnpm add --save-dev @tmedxp/react-componentsAEM React component - made specificy on top of the react component for usage within AEM
npm install --save-dev @tmedxp/aem-react-componentspnpm add --save-dev @tmedxp/aem-react-componentsimport { PillButton } from '@tmedxp/react-components';
export const Component = () => <PillButton />;What else to know
Section titled “What else to know”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.