Better support for theming using CSS global vars

[mcoker]

Taking the learnings from dark theme, let's examine the current global variables and see where we can make improvements specifically for theming. A couple of examples are:

• --pf-global--BackgroundColor--300 - same as our primary background color, but used on elements that float on top of other elements. This ends up being useful to uniquely set a different background color for elements that float against the primary background in other themes.
• --pf-global--BorderColor--400 - bottom border for form control elements.
• --pf-global--primary-color--100/300 - different primary color backgrounds for elements with and without text.

As close we can, a user should be able to go in and tweak a global variable to theme some concept and it change - to the best of our ability - that thing. If we use --pf-global--disabled-color--400 for text, backgrounds, and borders, and a user wants to theme --pf-global--disabled-color--400 for use in one context, it's probably going to change a bunch of stuff they don't want in other contexts.

As part of this, I think we should be able to document the intended use of every global variable so there is no confusion as to when to use what var for what purpose, and if a user wants to theme their app, that documentation can be their reference guide.

Then we should audit each component and make sure they are referencing the correct global vars, which can be a follow up task/epic.

cc @mceledonia @mmenestr @mcarrano

---

Other ideas:

Status colors

• The pf-color-name-50 colors we use as the background for statuses should be global vars
• Make it clear what --100, --200, etc are for, or give those more meaningful names as text, icons, backgrounds, hover/focus backgrounds, etc
• We should probably have a generic scale for the existing status colors that are not tied to status names, as they don't always have to be used for a particular status - labels and banners as an example - Colors - PF colors for severity levels patternfly-design#1219
  • Would we want to have both status names and the generic scale? I would say so:
    • Users can theme their "red" (but not danger) component things uniquely from their "danger" component things
    • We could probably get rid of the "default" status and make it part of the generic scale? Or do we want a "default" status that can be themed separately from a "cyan" status? We probably need to rename that regardless since it's causing a namespace conflict in react components - Potential namespace conflict with "default" in status prop enums #5175

Icons

• Sort out icon color and icon font size global vars - the color should likely be whatever the text color is by default, as in it should probably inherit it so they stay in sync, but maintain separate vars for theming.

Spacers

• Provide more meaningful description for the form spacer
• Introduce spacers for shared concepts. eg,
  • helper text
  • icon + text
  • document blocks/gaps for things like stacked components or content like paragraph + paragraph + list + heading + paragraph (seen in the content component)
  • gutters and insets - both block (vertical) and inline (horiz)
• Consider logical property names where appropriate - like the form spacer. It's block (vertical) padding for a form element. Or text/content's heading - there is a unique block-start and block-end

  patternfly/src/patternfly/components/Content/content.scss

  Lines 15 to 16 in 2e3c6ae

  	--pf-c-content--h1--MarginTop: var(--pf-global--spacer--lg);
  	--pf-c-content--h1--MarginBottom: var(--pf-global--spacer--sm);

• Consider global var for form element height (it's currently 36px) - or look at removing this,

  patternfly/src/patternfly/components/FormControl/form-control.scss

  Line 41 in 8427be1

  --pf-c-form-control--Height: calc(var(--pf-c-form-control--FontSize) * var(--pf-c-form-control--LineHeight) + var(--pf-c-form-control--BorderWidth) * 2 + var(--pf-c-form-control--PaddingTop) + var(--pf-c-form-control--PaddingBottom)); // Needed for various browsers that compute height of form elements differently

Borders

• Have more robust and well-documented border and disabled colors. We often get a color from design to use for, say, a disabled box's border, and we just use whatever global var is available - that may be a text color, a global disabled color, or one of the border colors.

Box shadows

• Consider variations for shadows that are inset vs go outside of their container.

Backgrounds

• Different backgrounds for elevation - Dark theme - surface colors that represent elevation patternfly-design#1204

Colors

• HSLa - more intuitive, better for theming and generating palettes in general, support for the alpha channel*
  • * we can add support for that now with hex colors using #RRGGBBAA, which I think we should add if we don't use HSLa with this update.

[mcarrano]

@mcoker @srambach Just doing some housekeeping. Do we need to keep this issue open?

[srambach]

Looks to me like it could be closed and we'll open more specific issues around tokens and theming, but I'll defer to @mcoker - there's a lot of good info here.

[mcoker]

Agree, some of this is already done in the penta work, but everything I see here is already being considered. Closing for now and we can reference if needed.