Variable Naming (I promise I'm not trying to bike shed!)

[wesruv]

So I don't want to be that guy, but I feel like PFE, PF, and what I've seen from hanging with @bennypowers and seeing work on this wonderful project have issues that create confusion.

General concerns:

• Cognitive load for folks trying to use the system
  • Intuitiveness and/or predictability
  • Understandable for folks that learned english as a second language
  • Any issues for devs/designers with low vision, color blindness, etc
• Extendable
  • We may get new shades/hues over the life of the system
  • Will it be difficult for folks to integrate it with their new or existing systems
• Other things folks want to add to the list?

What I see as issues with current PF4 & PFE variables:

• The logic for color naming feels opaque, meaning I have a hard time guessing what hue/saturation/value I will get from looking at the color var name. Is it documented somewhere?

  • In PF the higher the number gets, the darker the color. In Hex, RGB, HSL, etc it is the opposite. It feels like it would be more intuitive to follow suit with those in CSS.
  • Hue names in PF have "light blue" and "light green", but since each hue has different brightness variations we have the light "light blue" and the dark "light blue".
  • The numbers have 3 places, which feels unnecessary since we never use the 0-9, only 10's and 100's.

• Need for delineating terms in the variable name.

  • If we just use kebab-case it's hard to know what's a term, e.g. (made up example) rh-featured-font. Does featured belong to the rh as in rh-featured, or the font as in featured-font.
  • PFE is using BEM naming the way it's used for CSS class names means practically everything is a double dash, and using dashes to replace spaces makes a lot of visual noise that I find unhelpful.
  • Variable name length can get a bit pesky, but I'm ok with sacrificing that for human readability/less cognitive load
    • In PF specifically, I wonder about the value of some parts of variable names. e.g. in the Palette --pf-global--palette--black-900, is global necessary? I haven't seen a place where it's not that?

• Other things folks want to contribute as issues we might be able to improve with our current naming systems?

I'm going to leave potential ideas/solutions to the discussion thread.

[wesruv]

Working on a Drupal admin theme I've gotten a naming convention I like that addresses a lot of the issues I listed above.

Things I think this solves for:

• BEM-ish naming convention makes it clear what words are part of the same term
• camelCase is an easy convention that reduces on var name length and makes the __ and -- more recognizable and easier to parse
• I think this naming convention is a lot easier to infer what the intention is than the PF and PFE (your mileage may vary, aka YMMV)
• Significantly less dashes makes it easier on the eyes
  • In the context of CSS I think styles should be considered Elements and not Modifiers; since they are the subject that we're applying 'adjectives'/states/modifiers to.

///
// General settings for this project (Red Hat Drupal Admin Theme)
//
// Should never be overridden, only used as settings.
///

// Font Settings
--rhdat__font__size--xs:     14px;
--rhdat__font__size--sm:     16px;
--rhdat__font__size--md:     18px;
--rhdat__font__size--lg:     20px;
--rhdat__font__size--xl:     20px;
--rhdat__font__size--xxl:    24px;
--rhdat__font__size--xxxl:   26px;
--rhdat__font__size--xxxxl:  36px;


///
// Theme vars
//
// Never to be overridden, but provide standard colors for certain contexts by the function of the color, not it's appearance
///

// Default theme:
--rhdat__theme__background: var(--pf-global--palette--white, #fff);
--rhdat__theme__font__color: var(--pf-global--palette--black-900, #151515);

/* Button colors */
--rhdat__theme__button__color: var(--pf-global--palette--black-900, #151515);
--rhdat__theme__button__background: var(--pf-global--palette--black-200, #f0f0f0);
--rhdat__theme__button--hover__background: var(--pf-global--palette--black-300, #d2d2d2);
--rhdat__theme__button--active__background: var(--pf-global--palette--black-400, #b8bbbe);

// Light on dark theme
--rhdat__theme--lightOnDark__background: var(--pf-global--palette--black-900, #151515);
--rhdat__theme--lightOnDark__font__color: var(--pf-global--palette--white, #fff);

--rhdat__theme--lightOnDark__button__color: var(--pf-global--palette--white, #fff);
--rhdat__theme--lightOnDark__button__background: var(--pf-global--palette--black-800, #3c3f42);
--rhdat__theme--lightOnDark__button--hover__background: var(--pf-global--palette--black-700, #4f5255);
--rhdat__theme--lightOnDark__button--active__background: var(--pf-global--palette--black-800, #3c3f42);


///
// Current context
//
// Should be overridden to match the current context allowing text, link, button and other elements
// to use good colors for their current background/visual context.
// e.g. body could have the default dark on light context, and the header might be dark on light,
// the header wrapper should set these vars appropriately
///

// Using surface as generic name for "element that appears as a visual container because it has a bg, or border, etc)
--surface__background: var(--rhdat__theme__background, #fff);
--font__color: var(--rhdat__theme__font__color);

--button__color: var(--pf-global--palette--black-900, #151515);
--button__background: var(--pf-global--palette--black-200, #f0f0f0);
--button--hover__background: var(--pf-global--palette--black-300, #d2d2d2);
--button--active__background: var(--pf-global--palette--black-400, #b8bbbe);

For color variables, I have loved the following convention:

[project]__palette__[hueName]--[approximateLightnessAsPercent]

In PF we currently have:

  --pf-global--palette--light-blue-100: #beedf9;
  --pf-global--palette--light-blue-200: #7cdbf3;
  --pf-global--palette--light-blue-300: #35caed;
  --pf-global--palette--light-blue-400: #00b9e4;
  --pf-global--palette--light-blue-500: #008bad;
  --pf-global--palette--light-blue-600: #005c73;
  --pf-global--palette--light-blue-700: #002d39;

  --pf-global--palette--orange-100: #f4b678;
  --pf-global--palette--orange-200: #ef9234;
  --pf-global--palette--orange-300: #ec7a08;
  --pf-global--palette--orange-400: #c46100;
  --pf-global--palette--orange-500: #8f4700;
  --pf-global--palette--orange-600: #773d00;
  --pf-global--palette--orange-700: #3b1f00;

I would prefer:

--pf__palette__aqua--90: #beedf9;
--pf__palette__aqua--80: #7cdbf3;
--pf__palette__aqua--70: #35caed;
--pf__palette__aqua--60: #00b9e4;
--pf__palette__aqua--50: #008bad;
--pf__palette__aqua--40: #005c73;
--pf__palette__aqua--10: #002d39;

--pf__palette__orange--70: #f4b678;
--pf__palette__orange--60: #ef9234;
--pf__palette__orange--50: #ec7a08;
--pf__palette__orange--45: #c46100;
--pf__palette__orange--40: #8f4700;
--pf__palette__orange--30: #773d00;
--pf__palette__orange--10: #3b1f00;

• Shorter name and easier to parse (YMMV)
  • I doubt we're going to need 1000 shades of a color as vars, 1-100 should give us enough wiggle room for new shades being added
  • Removing the word 'global', I don't think we need multiple 'palettes', we want multiple 'themes' which ought to describe the function of the color more than it's appearance.
• The numeric value gets larger as the color gets lighter (closer to white if we made the image grayscale)
• The naming convention follows the same BEM-ish pattern as other vars
• The number gives the developer an idea of what the result is without seeing a swatch
• One thing the current system seems to do is the 500 level is always the most saturated version of the hue, and everything branches off of that
  • That predictability is nice in some ways, but some of the vars have numbers that don't make any sense when compared to similar ones, e.g.
    • 700 on some is practically black, on others it's 50% darkness (important for ensuring good contrast for a11y)
    • Similarly, 500 on gold is very light, while 500 on red is quite dark
    • The amount of numbers isn't entirely consistent, some have a 50, some do not

[bennypowers]

Heads: this discussion is important, and deserves top billing, so I moved it to the main design-system discussion board

[paceaux]

I would agree that for color variables especially, the current convention is too verbose:

• It's heavy on dashes (which is frustrating for typing, selection, and including in Jira tickets)
• It presents a lot of mental overhead.

I have opinions on Wes' proposals, but they're based on the ultimate intent of these variables.

If these variables absolutely aren't subject to change ever, I can support the convention: --<project>__<domain/feature>__<feature-element>--<variation>. So --pf__palette__orange--10 would make sense, so long as it's never going to change (i.e. a constant)

And that's because of specific questions I have about the color names:

How do we align the names we would use against the named colors?

What is the value of --pf__palette__orange? I would assume that means it is rgb(255 265 0) / hsl(38.8%, 100%, 50%). If it's not, how are we planning to reconcile "our orange" to someone else's? How does that help visually impaired developers who have no choice but to believe the variable name?

I would then assume that pf__palette__orange--10 is a case where one of the three HSL values has shifted. Now, based on present discussion, I'm guessing that the --10 is lightness. Does that mean that the value of pfl__palette__orange--10 is hsl(38.8%, 100%, 10%) (i.e. the --10 is an indicator of the applied lightness to an unchanged hue and saturation)?

If that is the case, then does this mean that --pf__palette__orange === --pf__palette__orange--50?

I'm ok with this approach, so long as

1. We are using the hue and saturation aligned with the W3C's named colors
2. The number is always the three digit representation of lightness
3. We don't add our own colornames

This would guarantee predictability for new developers. They'll know the colorspace they're working in, the purpose of that final modifier, and that every color they encounter is a variation on a globally known and understood color.

What if we want colors that aren't the W3C's named colors?

I would suggest a slightly different convention for working with colors that aren't in the named color list. I'm definitely on board for the --<project>__<domain/feature>__ pattern, but why not name the color in a way that won't make it a liar that misleads developers and doesn't align with the W3C?

what about --<project>__<domain/feature>__<warm/cool><er|est>--<light/dark><er|est>

e.g.

--pf__palette__warm: hsl(38.8, 100%, 50%)
--pf__palette__warmer: hsl(10, 100%, 50%)
--pf__palette__warmer--lighter: hsl(10, 100%, 75%);
--pf__palette__warmer--darker: hsl(10, 100%, 25%);
--pf__palette__warmest--darkest: hsl(290, 100%, 12%);

Colors break into warm and cool, so two distinct name groups. By adding 'er' and 'est', each group gets six total hues: warm, warmer, warmest, cool, cooler, coolest. Once we add a light|dark(er|est) to each, we've got 7 variations on each hue, which means a total of 42 colors we can attribute to each palette.

By using the modifier lighter/darker,

• we've actually got flexibility to change the variable (so long as it stays in a general 180degree range on the color wheel and doesn't overlap another on).
• We can communicate what the variable does without saying what it is (a huge problem when we start naming colors)
• We don't have any magic numbers in the naming convention (it's never immediately obvious to me what those numbers actually mean)
• We don't have to worry about our "red" not being the W3c's "red"

TL;DR

I definitely agree with Wes' points about a BEMish convention that's less verbose and gives the developer a predictable idea of what the result is.

My only points are:

1. using colors that overlap with W3C's could be confusing
2. I've not seen a design system that needed over 50 colors; it's ok to think smaller.

[wesruv]

I do really like your point about visually impairment and color choices, I hadn't thought of that.

I'm not sure I agree with the W3C naming issue since we have the qualifier of a 'project name' and 'palette'.

I strongly dislike witty color names like using "seafoam" instead of "green" I think more than butting up against W3C naming I'd optimize for cognitive load and ESL folks. If we try to avoid W3C color names, we're not left with many obvious names for particular hues.

When I think of how these names are used, it's usually a FED getting a design and being able to get the RGB/Hex/etc of the color, and if they're lucky the variable name we standardize on. Ideally the FED checks the design token system and is able to find a var (if the color is in palette) and can leverage that.

Benny showed a really good page that spits out all of the palette colors, the var names, and the RGB/Hex/whatever values, so I think if anyone has issues confusing the W3C orange with "Red Hat Design System Orange" that's the documentation to address that.

[paceaux]

Valid counterpoint with the fact that we're talking about project specifics; alignment / overlap with W3C may not matter.

I agree that "witty color names" are very unhelpful which is why I'd favor a system that wasn't overly dependent on it. My concern in general is that 8-10% of the population with some form of colorblindness that may not do well if you go too far beyond ROYGBIV with color names -- and ESL folks whose color words don't align with ours on the spectrum (e.g. Russian & dark/light blue, Japanese && green/blue).

In general, the less we have to force someone to read documentation, the better.

[bennypowers]

How much of that is a variable-naming/implementation problem vs a design system problem? What I mean is, we expect and hope that in the vast majority of uses, developers building apps or pages with @rhds/elements won't need to even know our css variable names.

[bennypowers]

A few things to consider:

1. We're not beholden to PF/PFE on this project, even if some RHDS components may be built on top of their PFE counterparts. subclasses don't have to inherit styles, either, so <rh-button> is not required to any of the same styles as <pfe-button>
2. The elements (and by extension, tokens) are intended to be used by page and app authors, preferably as drop-in components. We're interested in limiting our API surface, providing strongly opinionated components - this isn't meant to be a white-label component set - that being said we want to solve problems for teams as much as we can
3. We're able to define our own term heirarchy in our tokens using style-dictionary. That would allow us to generate docs that group across taxonomies, not just alphabetically (e.g. 'find me all the font-sizes' or 'show me all the on-dark colours')
4. We're specifically trying to avoid BEM, _, --, camelCase, and other naming tricks, to align with the broader web components community. a big part of readability is keeping our 'weirdness budget' in check. Prior art:
   • Vaadin
   • Google Material
   • Shoelace
   • Microsoft FAST
   • Open Props
   • US Govt (not wc, but still)
   • Clarity
   • Adobe Spectrum
   • IBM Carbon see also naming conventions
5. WRT term confusion (e.g. -backgroundColor- vs -background-color-), I don't think this is a serious risk, really. I just can't really imagine developers getting tripped up by -font-size-, and if any do, we can accommodate them in docs, see point 2.

[wesruv]

Great points.

Re: 5 I don't think it's a big speed bump, I'm saying I think it's more intuitive, meaning less cognitive load in understanding. So optimization that I enjoy, not a dire issue.

Re: 4 This certainly isn't my lawn to mow, so I'm giving my thoughts, not trying to force my opinions. But I'll say I specifically don't like what those systems are doing with naming.

To be clear, I'm not saying the variables in the design token system should follow this convention, I'm saying that I'd like the CSS vars to look like that, in case that's a worthy delineation that's more palatable.

I'm a big BEM fan, I'm not sure why we'd avoid it?

It solves a lot of issues of cognitive load (as a person with raging ADHD I've found BEM very helpful for my sub-par skimming ability), I think it communicates intention better, and it can help avoid naming collision.

BUT I don't want to bike shed, I think I've brought up my concerns well. Do what you think is best!

[bennypowers]

definitely food for thought

[heyMP]

Wow, this is an amazing discussion. To add, we are definitely going to have way less CSS variables exposed as public APIs now that Shadow Parts are here. Instead of exposing very specific CSS properties we can rely on Shadow Parts to give the user control. For instance, changing background colors.

// from
:root {
  --rh-theme__button__icon__backgroundColor: pink;
}

// to
rh-button::part(button) {
  background-color: pink;
}

I've been slowly phasing out BEM from my components since I've been doing web components. To me it was one of those things that we needed before we had style encapsulation. But that's just my bias, so wanted to lay that out there. :)

[wesruv]

That's awesome, thanks for the code example, I wasn't sure how that works yet.