Usage

The DXP Connected Design System is designed to be used in various contexts, including but not limited to AEM. The output of the styleguide is CSS only as is meant to be used with semantic HTML.

Development

Because we are actively developing this styleguide we will document the current status per component / part. This helps us to keep track of what’s ready or not to be used.

Pages marked Draft document features still in development. The implementation may be incomplete or the design not yet reviewed by the Design Team. Pages without a status label are stable and ready for use.

In terms of semver draft pages may include breaking changes without major version bumps, so be sure to check the changelog for updates when using draft features.

CSS layers

The Design System uses CSS Cascade layers to manage specificity. The current website styles are wrapped in @layer legacy {} and will gradually be replaced by the Design System. This layered setup allows the new design tokens and component styles to coexist predictably with the legacy CSS during the transition.

These are all available layers.

Layer	Description
legacy	Existing website styles being gradually replaced by the Design System
aemglobal	Any non-legacy styles that are meant to exist outside of the Design System.
tng	Design System base layer
tng.reset	Resets default HTML element styles for CDS components
tng.foundations	Core design tokens and typography
tng.layouts	Layout systems
tng.components	Component-specific styles
tng.userstyles	Override layer for custom component styles
tng.utilities	Utility classes for common styling needs

However, there are important caveats to be aware of:

• HTML5 Component — When adding an HTML5 Component its styles will automatically be wrapped in @layer aemglobal {}, unless the styles contain any @layer rules. When you go with the latter, make sure to understand what styles you are setting and why. Please read the above table carefully to understand the goals of using the different layers.

  The most common layers you’d want to be using are these.

  • legacy — for patching legacy styles
  • aemglobal — for styles that are meant to be used outside of the Design System, for example in AEM components that are not part of the CDS
  • tng.userstyles — for styles that are meant to be used inside the Design System, for example in CDS components that need to override the base styles

  Caution

  We recommend to use the legacy layer for patching legacy styles because how !important rules work across layers. Spoiler alert, it’s not what you expect.

• External widgets — Third-party widgets (e.g. chatbot, survey, or consent tools) often inject their own unlayered styles into the page. These can similarly override layered styles and cause visual conflicts. Because you typically don’t control the CSS of these vendors, consider isolating them using a Shadow DOM wrapper, or coordinate with the vendor to scope their styles more tightly (e.g. using a unique prefix or container selector).

AEM

The styles will be made available globally automatically as part of DXP Headless build setup. This means the code should never be included as part of your team’s build pipeline, at least not for components that are meant to be part of our AEM sites.

External

In many cases you’ll still want to be able to use these styles outside of AEM, for example in Storybook or other sandbox tools. In these cases you can include the CSS directly in your project. The CSS is available as a package on npm, so you can install it with:

npm

npm install --save-dev @tmedxp/styleguide

pnpm

pnpm add --save-dev @tmedxp/styleguide

Exports

Depending on your needs we provide these export.

• @tmedxp/styleguide — global consts and brand namespaces
• @tmedxp/styleguide/assets.css — styleguide assets
• @tmedxp/styleguide/styles.css — styleguide styles without brand tokens
• @tmedxp/styleguide/lexus — lexus namespace
• @tmedxp/styleguide/lexus/assets.css — styleguide and brand assets
• @tmedxp/styleguide/lexus/styles.css — styleguide styles with lexus tokens
• @tmedxp/styleguide/toyota — toyota namespace
• @tmedxp/styleguide/toyota/assets.css — styleguide and brand assets
• @tmedxp/styleguide/toyota/styles.css — styleguide styles with toyota tokens

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

Brands

For tokens and some specific styles to be applied between different brands we need to know which brand is currently active. This is done by adding a data-brand attribute to the html element.

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

Fonts

When you are not using the shared component library or not working within the DXP AEM environment, you will need to configure the font face. Check out this reference for more details.

Storybook

Update your previewHead config with your desired CSS.

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"
/>

Reset

Because the styleguide will be used side-by-side with existing component styles we have to apply a reset on the root of each new component. This reset is necessary because the current styles apply a lot of styles directly to HTML elements.

<div class="tng-root">…</div>

Revert reset

When a legacy component is placed inside a tng-root container, the CDS reset will strip its expected styles. To restore the legacy styles for that component, wrap its root element with the tng-legacy-apply class.

<div class="tng-root">
  <!-- CDS components render normally -->
  <div class="tng-legacy-apply">
    <!-- Legacy component with legacy styles restored -->
  </div>
</div>

This is useful when you need to embed an existing legacy component within a new CDS layout and want it to retain its original styling.