Page Comparison

...

This document defines the format for creating new design tokens that will be most effective for administration in Theme Designer as well as the locations that the tokens are required to provide similar theme control as TDv1. The words CSS Custom Property and Design Token are used interchangeably in this document and refer to the same thing, “named entities that represent atomic design values, and convey design decisions though their structure”.

...

1. Reusability - abstraction that allows for property reuse.

2. Intuitive scoping - the scoping should be intuitive and easily extendable.

3. Standardization - the naming should follow a well established industry standard.

4. Design system adaptability - the naming should be abstracted enough to be easily adapted to a design system

5. Coverage for existing themes - the properties should give coverage to be able to adequately reproduce existing themes during a theme migration.

2. CSS Custom

...

Property Scoping

...

A. Scoping to :root

All CSS vars that you want to expose in a theme must be scoped to :root. This is very important. :root is a psuedo that refers to the page document itself. Any properties that are scoped to a level other than root will have a higher priority than :root and will override any values applied by Theme Designer. It is fine to scope private variables properties (those not using --ads), but be aware that Theme Designer will not have control over them.

3.

...

Creating new CSS Property Names

A. Property Naming Requirements

The format varies slightly between vars that are scoped to DOM elements and those that are general theme properties. These formats are aligned with (Block, Element, Modifier) model and industry recommendations[1][2][4]. Adopting this standard ensures we are not reinventing the wheel. At a high level, these groups are defined as:

...

Namespaces (--ads, --adx, etc) are prepended first.

...

Block levels (*-input, *-page, *-brand, etc) come after the namespace. See Section E of this guide for available block level names to use.

...

Element levels (*-title, *-border, *-button, *-plp, *-checkout) are a backbone in the middle. Levels within Elements vary based on preferences for hierarchical strictness, for example, a page name, or a specific category that a var applies to.

...

Modifiers (*-active, *-error, *-hover) are applied before the property type and are optional.

...

A. Naming Requirements

...

Keep token names as concise as possible

...

Scope them to the top level tokens defined in section E of this document!

• In order to limit the amount of top level accordions (categories) in TD, DO NOT add any additional top level categories beyond those defined in section E of this document

...

Make your var names make relational sense. When users open TD, we want them to intuitively know that if they need to find the setting for the Card Header Color on the PDP page, in TD they should go to Page → PDP → Card → Header. And so the prop name for that is --ads-page-pdp-card-header-color. That relationship in TD is defined by your variable name!

...

Use full words to describe the elements (-button- instead of -btn- for example)

...

All tokens (CSS Custom vars) that you want Theme Designer to consume must be prefixed with --ads

• Props that you dont want exposed to TD, prefix with --adx instead

...

It is recommended to not nest your token names more than 4-5 levels deep or you will create “accordion hell” for your users in the TD interface when trying to drill down to the controls.

...

Try to focus on reusability of token names by avoiding high levels of specificity whenever possible.

• When you do need a high level of specificity, place vars that are scoped to specific pages under --ads-page-<name of page>-*

...

Property types must be the last element in the token and those that are multi-word must be lower case concatenated.

...

Test your variable name in TD when you are done to make sure it works and appears in the proper category.

...

• background-color → backgroundcolor

• flex-direction → flexdirection

• font-family → fontfamily

• text-align → textalign

• text-decoration → textdecoration

• min-height → minheight

B. Token Names Determine the Control Type

...

• Keep token names as concise as possible

• Scope them to the top level tokens defined in section E of this document!

  • In order to limit the amount of top level accordions (categories) in TD, DO NOT add any additional top level categories beyond those defined in section E of this document

• Make your var names make relational sense. When users open TD, we want them to intuitively know that if they need to find the setting for the Card Header Color on the PDP page, in TD they should go to Page → PDP → Card → Header. And so the prop name for that is --ads-page-pdp-card-header-color. That relationship in TD is defined by your property name!

• Use full words to describe the elements (-button- instead of -btn- for example)

• It is recommended to not nest your property names more than 4-5 levels deep or you will create “accordion hell” for your users in the TD interface when trying to drill down to the controls.

• Try to focus on reusability of property names by avoiding high levels of specificity whenever possible.

  • When you do need a high level of specificity, place vars that are scoped to specific pages under --ads-page-<name of page>-*

• Property types must be the last element in the property and those that are multi-word must be lower case concatenated.

• Test your Propertyname in TD when you are done to make sure it works and appears in the proper category.

• Read the Spec for additional syntax requirements.
  
  For example:

  • background-color → backgroundcolor

  • flex-direction → flexdirection

  • font-family → fontfamily

  • text-align → textalign

  • text-decoration → textdecoration

  • min-height → minheight

B. Property Format Requirements

Properties specific to a nested element may include both component name and element name, much like the BEM CSS methodology[6]. The double dash before the property suffix is used for parsing control types to display in Theme Designer.

Format:

--ads-{block type}-{element prefix(optional)}-{element type}-{modifier/state(optional)}-{property}

Example:

--ads-card-action-button-hover-backgroundcolor

Breakout:

--ads -card -action -button -hover -backgroundcolor

namespace | block-type | el-prefix | element-type | modifier | property

C. Property Names Determine the Control Type

The last element in the CSS property name determines the prop that will be displayed when consumed by Theme Designer. The following table defines that relationship. Note that “brand” scoped vars use different components than non “brand” vars.

...

...

Tokens specific to a nested element may include both component name and element name, much like the BEM CSS methodology[6]. The double dash before the property suffix is used for parsing control types to display in Theme Designer.

Format:

--ads-{block type}-{element prefix(optional)}-{element type}-{modifier/state(optional)}-{property}

Example:

--ads-card-action-button-hover-backgroundcolor

Breakout:

--ads -card -action -button -hover -backgroundcolor

namespace | block-type | el-prefix | element-type | modifier | property

...

D. Property Names Generate Field and Accordion Labels

The token property names are also used to generate the field and accordion labels in TD, so keep this in mind when creating the CSS Prop names. In general, the last segment of the prop/token property name is used to generate the input label and the previous segments are used to generate the nested accordion labels. As previously mentioned in this document, concatenated prop types will be automatically formatted (spaces inserted and capitalized) for readability in the Theme Designer UI.

E. Existing Top Level CSS

...

Property Parts

In order to keep TD usable and free of dozens of top level options, DO NOT add any additional top level vars without team vetting. Try to place vars under existing categories. For example, if its an attribute that applies to a specific page, put it under --ads-page-<name of page>-*

--ads-border-*: Used for vars that style global border related properties (width, color, radius, etc). These are globals. You can also have scoped ones in your “--ads-page-<name of page>-*” vars that inherit from these global border styles.
--ads-brand-*: Used for global brand vars (DO NOT ADD ANY ADDITIONAL BRAND PROPS)
--ads-breadcrumbs-*: Used to for vars assigned to the PUI breadcrumbs
--ads-calendar-*: Used for vars assigned to the PUI calendar
--ads-font-*: Used for global font vars. These are globals. You can also have scoped ones in your “--ads-page-<name of page>-*” vars that inherit from these global font styles.
--ads-footer-*: Used for vars assigned to the global page footer (simple footer).
--ads-headings-*: Used for vars that style H1-H6 Headings. These are globals. You can also have scoped ones in your “--ads-page-<name of page>-*” vars that inherit from these global heading styles.
--ads-header-*: Used for vars assigned to the PUI Header
--ads-hero-*: Used for vars assigned to the NOP PLP hero
--ads-input-*: Used for vars assigned to global input components
--ads-loader-*: Used for vars assigned to the NOP page loader
--ads-page-* : Used for vars assigned to individual pages (must be followed by the page name)
--ads-plugins-*: Used for vars assigned to styling Various NOP plugins
--ads-sidebar-*: Used for vars assigned to the PUI Sidebar
--ads-tabs-*: Used for vars assigned to styling the category tabs on NOP PLPs

F. Label Map

Token Property parts can be formatted to appear a specific way in the TD application. This is configured in the TD Application Environment File src/environment/index.ts.

For example you want to add a CSS variable property named --ads-page-somepage-title-fontsize and you want the label for the somepage section to display as Some Page in the TD Application. All you need to do is add the CSS variable p name to your CSS and we can add the label format to the label map in Theme Designer app for the next TD release. Just create a card for the Platform Team and we will get it added!

...