Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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”.

Info

The CSS Custom Variable you Propertyyou create should tokenize the association between a customizable value in the UI and the overarching Aspenware Design System.

1. Considerations

Multiple considerations were taken into account when determining both the properties to include and the format of the property names. The primary considerations include:

  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.

...

panelIconIdatlassian-info
panelIcon:info:
bgColor#DEEBFF

Creating new CSS Property Names

A. Property Naming Requirements

Info

Our theme based CSS vars MUST be prefixed with --ads for name spacing purposes. Vars without that prefix will not be exposed by TD. For Aspenware design system properties that you do not want exposed by Theme Designer, use the prefix --adx.

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

Info

Theme Designer has internal mappings to convert the concatenated prop type for all common CSS properties back into delimited formats for an optimized user experience whenever the prop names are used in the UI.

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

Info

Theme Designer has internal mappings to convert the concatenated prop type for all common CSS properties back into delimited formats for an optimized user experience whenever the prop names are used in the UI.

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.

...

For this CSS property…

Use this element property type…

And this input type will be displayed [with menu options]

Brand (--ads-brand-*) – ONLY THESE PROP TYPES WILL DISPLAY IN THE BRAND SECTION

Color

*-color

Color Picker Widget

Favicon

*-favicon

Image Upload Widget

Font Family

*-fontfamily

Font Configuration Widget

Non-Brand (--ads-*)

Align Content

*-aligncontent

Flex Align Content Menu ['stretch', 'flex-start', 'flex-end', 'center', 'space-between', 'space-around']

Align Items

*-alignitems

Flex Align Items Menu ['stretch', 'flex-start', 'flex-end', 'center', 'baseline']

Aspect Ratio

*-aspectratio

Image aspect ratio text input with the label of “Aspect ratio”

Background Image

*-image or *-backgroundimage

Image Upload Widget

Border Color

*-bordercolor

*-bordercolorp

Color Widget (Color picker / Swatches)

Color Picker toggled for *-bordercolorp

Background Color

*-backgroundcolor

*-backgroundcolorp

Color Widget (Color picker / Swatches)

Color Picker toggled for *-backgroundcolorp

Color (Text Color)

*-color or *-colorp

*-textcolor or *-textcolorp

Color Widget (Color picker / Swatches)

Color Picker toggled for *-colorp or *-textcolorp

Display

*-display

Display Menu ['flex', 'block', 'inline', 'none', 'unset']

Flex Direction

*-flexdirection

Flex Direction Menu ['row', 'row-reverse', 'column', 'column-reverse']

Flex Wrap

*-flexwrap

Flex Wrap Menu ['nowrap', 'wrap', 'wrap-reverse']

Font Family

*-fontfamily

Font Selection Menu

Font Style

*-fontstyle

Font Style Menu ['normal', 'italic', 'oblique', 'initial', 'inherit']Font Weight

Justify Content

*-fontweight

Font Weight Menu ['400', '700']

Justify Content

*-justifycontent

Flex Justify Content justifycontent

Flex Justify Content Menu ['flex-start', 'flex-end', 'center', 'space-between', 'space-around']

Position

*-position

Position Menu ['static', 'relative', 'absolute', 'fixed', 'sticky']

Text Align

*-textalign

Text Align Menu ['left', 'center', 'right']

Text Justify

*-textjustify

Text Justify Menu ['auto', 'inter-word', 'none', 'initial', 'inherit']

Text Transform

*-texttransform

Text Transform Style Menu ['capitalize', 'uppercase', 'lowercase', 'none']

Visible

*-visible

Visibility Menu ['visible', 'hidden', 'initial', 'inherit']

Vertical Align

*-verticalalign

Vertical Align Menu ['visible', 'hidden', 'initial', 'inherit']

All Others

*-* (all other types)

Text Input Field

...

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

...

', 'initial', 'inherit']

Vertical Align

*-verticalalign

Vertical Align Menu ['visible', 'hidden', 'initial', 'inherit']

All Others

*-* (all other types)

Text Input Field

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!

List of currently mapped labels that are available to use:

cssNameMap: { alignitems: 'align items', aspectratio: 'aspect ratio', bordercolor: 'border color', bordercolorp: 'border color', bordertop: 'border top', borderbottom: 'border bottom', borderleft: 'border left', borderright: 'border right', borderradius: 'border radius', borderwidth: 'border width', backgroundimage: 'background image', backgroundcolor: 'background color', backgroundcolorp: 'background color', brandfooter: 'brand footer', colorp: 'color', dropshadow: 'drop shadow', boxshadow: 'drop shadow', flexdirection: 'flex direction', fontfamily: 'font family', fontsize: 'font size', fontstyle: 'font style', fontweight: 'font weight', groupmembers: 'group members', herodisplay: 'display', heroheight: 'height', justifycontent: 'justify content', lineheight: 'line height', minheight: 'min height', maxheight: 'max height', minwidth: 'min width', maxwidth: 'max width', marginleft: 'margin left', marginright: 'margin right', margintop: 'margin top', marginbottom: 'margin bottom', paddingleft: 'padding left', paddingright: 'padding right', paddingtop: 'padding top', paddingbottom: 'padding bottom', pdp: 'PDP', plp: 'PLP', positiontop: 'position top', positionbottom: 'position bottom', positionleft: 'position left', positionright: 'position right', publicui: 'public ui', simpleheader: 'simple header', simplefooter: 'simple footer', textcolor: 'text-color', textcolorp: 'text-color', textalign: 'text align', textdecoration: 'text decoration', textjustify: 'text justify', textoverflow: 'text overflow', texttransform: 'text transform', verticalalign: 'vertical align' },


4. References

[1]. https://www.imarc.com/blog/block-property-modifier-a-bem-like-css-custom-properties-methodology

...