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
Section titled “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
Section titled “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. However, there are important caveats to be aware of:
- HTML5 Component — When adding an HTML5 component to the website, any styles included in that component that are not wrapped in a
@layerwill automatically be wrapped in@layer aemglobal {}. If you want to override styleguide CSS you will have to include the styles in@layer tng.userstyles {}. If your HTML5 component contains any@layerrules, we won’t wrap the styles in@layer aemglobal {}and you will have to make sure to include your styles in the correct layer yourself. - 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).
These are all available layers.
legacyaemglobaltngtng.resettng.foundationstng.layoutstng.componentstng.userstylestng.utilities
AEM Usage
Section titled “AEM Usage”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 Usage
Section titled “External Usage”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 install --save-dev @tmedxp/styleguidepnpm add --save-dev @tmedxp/styleguideDepending on your needs we provide these potential imports for you.
@tmedxp/styleguide— import the global consts and brand namespaces@tmedxp/styleguide/lexus— import the lexus namespace@tmedxp/styleguide/lexus/no-icons.css— import the styleguide with lexus design tokens@tmedxp/styleguide/lexus/styles.css— import the styleguide with lexus design tokens and icons@tmedxp/styleguide/toyota— import the toyota namespace@tmedxp/styleguide/toyota/no-icons.css— import the styleguide with toyota design tokens@tmedxp/styleguide/toyota/styles.css— import the styleguide with toyota design tokens and icons
import { Toyota } from '@tmedxp/styleguide';import * as Toyota from '@tmedxp/styleguide/toyota';let Toyota.ICONS: Toyota.Icon[];For some changes to be correctly 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>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
Section titled “Storybook”Update your previewHead config with your desired CSS.
<link rel="stylesheet" href="/node_modules/@tmedxp/styleguide/toyota.css" />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>Embedding Legacy Components
Section titled “Embedding Legacy Components”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.