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.

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

Where to put your styles

HTML5 Components

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 — read the table above 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

External widgets

Third-party widgets (e.g. chatbot, survey, or consent tools) often inject their own unlayered styles into the page. These can 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).