Naming convention for design tokens

[andij]

Outcome

An understandable and predictable naming convention for design tokens.

Scope

• [x] Agree a suitable naming convention
• [ ] Document the naming convention and technique
• [ ] Writing description for each token and see if the name makes sense
• [ ] Implement any changes to existing tokens
• [ ] Ensure all new tokens conform to agreed convention

Resources

• https://medium.com/eightshapes-llc/naming-tokens-in-design-systems-9e86c7444676
• https://medium.com/@NateBaldwin/component-and-token-naming-in-design-systems-366bad54843f
• https://spectrum.adobe.com/page/design-tokens/
• https://www.duetds.com/naming/

Notes

Name appropriately according to the context, increasing context the closer it gets to the component.

Principles

• What it does not what it is (disabled, not grey or warning, not red or large, not 120px-space)
• Simple - common, short and uncomplicated (Reflect CSS structure, use only single words in JSON)
• Scalable - allow for associated names
• Don't use prefixes to name tokens

Approach

NEEDS REVIEWING (below is more from a brand perspective)

• Lowest = #b0b0b0
• Base = grey-500
• Theme = theme-color-disabled
• Component = inputter-disabled-background-color

[andij]

It would be useful to identify names that can be used for common concepts.

One example is decoration. This name can be used for the specifying the pretty things. The word decoration can be applied to any component to specify a facet that is applied to visual effect. Specifically something that is not essential to the understanding of the content.

For example: image, icon, illustration, shape, mask, etc.

Used in combination with a component theme. This name can be used for specifying the colour or meaning of a component. Every component has a theme. By default the component's theme will be inherited from the global theme of the user preference set in their operating system and browser. And subsequently each component can have a theme applied to infer a design feature or a meaningful purpose.

For example: dark mode, contrast item, colour emphasis, category, meaning.

• Dark mode is a site-wide user specified configuration affecting the entire site.
• Contrast item can be a component which stands out against the site's theme.
• Colour emphasis layering colourful branding emphasis.
• Category using a theme to categorise products, services, rewards, offers etc.
• Meaning provide meaning to a component like error, warning, success, information.

Using decoration and theme in conjunction with each other can provide a multitude of options.

Consider layout components (e.g. a panel) that can have a theme applied to it. Then all components within this panel inheriting the relevant appearance.

Additionally a component within can have it's own theme which may contrast from it's parent's theme to help make it stand out.

[PtitBen]

That made me think of something that could (or maybe not) be useful. Because words like the ones you mention (theme, decoration, illustration, etc...) can have different meanings across the industry (both in design, and engineering), how about we create a glossary/dictionary as part of the docs?

Maybe a dumb idea :D

[andij]

It's certainly a good idea to document the meaning of the name in each of the contexts it's used. I'd like to suggest that the description of the token is the best starting point for this information.

If it doesn't explain it well enough, then we can either include more information within the description and we can include additional supporting documentation if necessary.

[andij]

I've added some initial documentation for the tokens in our handbook: https://github.com/centrica-engineering/nucleus-internal-handbook/pull/9

[andij]

Design tokens naming convention proposal

Outlined within this proposal is a suggestion on the principles and approach on how to name the design tokens within Muon.

Principles

Each word within a token should describe something meaningful.

• What it does not what it is
  • For example disabled not grey, warning not red, large not 120px.
• Simple
  • Common, short and uncomplicated
• Scalable
  • Allow for associated names

Structure

The structure of a token takes the form of:

stateDiagram-v2
    Component --> card
    Group --> content
    Property --> padding
    Property --> block
    Value --> value

Which produces this token: CARD_CONTENT_PADDING_BLOCK

Do's and Don'ts

Don't hyphenate words

Do:

{
  "this": {
    "thing": {
      "value": "is okay"
    }
  }
}

Don't:

{
  "this-thing": {
    "value": "is not okay"
  }
}

Don't use acronyms or initialisms

Do:

{
  "this": {
    "background": {
      "color": {
        "value": "lovely"
      }
    }
  }
}

Don't:

{
  "this": {
    "bg": {
      "color": {
        "value": "ugly"
      }
    }
  }
}

Don't overcomplicate

Do:

{
  "this": {
    "thing": {
      "color": {
        "value": "nice and easy to understand"
      }
    }
  }
}

Don't:

{
  "verbose": {
    "disfigured": {
      "undesirable": {
        "explanation": {
          "value": "rather complicated"
        }
      }
    }
  }
}

This proposal is incomplete..

[andij]

Here's an explanation of the naming for Muon colour tokens within the discussion related to Nucleus Baseline Foundations: https://github.com/centrica-engineering/nucleus/discussions/138#discussioncomment-3169659

My understanding of the concept behind the naming of the colour tokens in Muon is to provide a set of colours that are essential for creating a user interface (without using specific colour names).

These colours can be mapped to a brand colour. E.g. for British Gas; the darkest colour will map to slate.

Any additional brand colours can be added to the brands color.json, and consumed by the brand as required.

Here's the Muon colour palette:

PURPLE = "#644BED"; // maps to THEME_COLOR_PRIMARY
ORANGE = "orange"; // maps to THEME_COLOR_SECONDARY
WHITE = "#FFFFFF"; // maps to THEME_COLOR_LIGHTEST
BLACK = "#000000"; // maps to THEME_COLOR_DARKEST
ACTION = "#1565C0"; // maps to THEME_COLOR_ACTION
DANGER = "#EB002F"; // maps to THEME_COLOR_DANGER
WARNING = "#E3660E"; // maps to THEME_COLOR_WARNING
SUCCESS = "#23D160"; // maps to THEME_COLOR_SUCCESS
INFORMATION = "#209CEE"; // maps to THEME_COLOR_INFORMATION

Here's the list of colour tokens that are generated with the Muon colour palette:

THEME_COLOR_PRIMARY = "#644BED";
THEME_COLOR_SECONDARY = "orange";
THEME_COLOR_FOCUS = "#b28bff";
THEME_COLOR_DISABLED = "#b0b0b0";
THEME_COLOR_PLACEHOLDER = "#b0b0b0";
THEME_COLOR_TRANSPARENT = "transparent";
THEME_COLOR_CURRENT = "currentColor";
THEME_COLOR_LIGHTEST = "#FFFFFF";
THEME_COLOR_DARKEST = "#000000";
THEME_COLOR_BASE_BACKGROUND = "#FFFFFF";
THEME_COLOR_TEXT_LIGHT = "#FFFFFF";
THEME_COLOR_TEXT_DARK = "#404040";
THEME_COLOR_NEUTRAL_LIGHT_50 = "#e5e5e5";
THEME_COLOR_NEUTRAL_LIGHT_100 = "#cccccc";
THEME_COLOR_NEUTRAL_LIGHT_150 = "#b3b3b3";
THEME_COLOR_NEUTRAL_LIGHT_200 = "#9b9b9b";
THEME_COLOR_NEUTRAL_LIGHT_250 = "#848484";
THEME_COLOR_NEUTRAL_LIGHT_300 = "#6d6d6d";
THEME_COLOR_NEUTRAL_LIGHT_350 = "#575757";
THEME_COLOR_NEUTRAL_LIGHT_400 = "#424242";
THEME_COLOR_NEUTRAL_LIGHT_450 = "#2e2e2e";
THEME_COLOR_NEUTRAL_LIGHT_500 = "#1b1b1b";
THEME_COLOR_NEUTRAL_DARK_50 = "#191919";
THEME_COLOR_NEUTRAL_DARK_100 = "#2c2c2c";
THEME_COLOR_NEUTRAL_DARK_150 = "#404040";
THEME_COLOR_NEUTRAL_DARK_200 = "#555555";
THEME_COLOR_NEUTRAL_DARK_250 = "#6a6a6a";
THEME_COLOR_NEUTRAL_DARK_300 = "#818181";
THEME_COLOR_NEUTRAL_DARK_350 = "#989898";
THEME_COLOR_NEUTRAL_DARK_400 = "#b0b0b0";
THEME_COLOR_NEUTRAL_DARK_450 = "#c9c9c9";
THEME_COLOR_NEUTRAL_DARK_500 = "#e2e2e2";
THEME_COLOR_ACTION_500 = "#95c2ff";
THEME_COLOR_ACTION = "#1565C0";
THEME_COLOR_DANGER_500 = "#ff8e86";
THEME_COLOR_DANGER = "#EB002F";
THEME_COLOR_WARNING_500 = "#ffc873";
THEME_COLOR_WARNING = "#E3660E";
THEME_COLOR_SUCCESS_500 = "#a3ffc1";
THEME_COLOR_SUCCESS = "#23D160";
THEME_COLOR_INFORMATION_500 = "#ffffff";
THEME_COLOR_INFORMATION = "#209CEE";