Design scales: color

[timglorioso]

Objective

• Establish a single source of truth for Mirlo design scales
• Establish a single source of truth for tokens, currently spread across CSS custom properties and Emotion theme
• Prepare to facilitate future visual changes by embedding design thinking in the frontend code

Solution

Consolidate the following styling resources:

• Javascript tokens from theme.ts
• CSS tokens and styles from styles.ts
• CSS styles from index.css

Part of this consolidation involves converting all CSS custom properties to Javascript theme tokens.

Example

// mirloDesignScales.ts
export const color = {
  black: "#3E363F",
  white: "#FFEEDB"
}

// theme.ts
import { color } from "./mirloDesignScales"

const dark = {
  background: color.black
}

const light = {
  background: color.white
}

export default { dark, light }

Tasks

• [x] Establish Mirlo design scales, starting with color
• [x] Use color scales to populate Emotion themes for dark/light modes
• [x] Listen for dark/light mode changes from window.matchMedia
• [x] Replace CSS custom properties with Emotion theme tokens
• [x] Fix Button regressions
• [ ] Reconsider theme tokens
• [ ] Replace color literals with theme tokens
• [ ] Basic documentation for scales, tokens, themes

[timglorioso]

@simonv3 I'd appreciate your thoughts on the Solution here, make sure I'm not moving in a wrong direction from your perspective

[timglorioso]

As I face some Button regressions, I'm now reconsidering whether theme tokens are a useful abstraction layer. It feels better to keep component-specific color usages within the component styles where they're contextualized. Solution would be to add color scales to the themes and replace tokens with scale values.

[simonv3]

@timglorioso sorry I didn't see your question from earlier. Honestly it feels like you have more experience and thoughts on this than I do! I'm happy with whatever you think works best.

I think you're right in that consolidating things into one spot is the right move. I was moving towards using var(--mi-variable) but if you think it's best to use themes than that works.

I think the main thing to flag and keep in mind as it gets designed (and I think you are minding it!) is the desire to ultimately let musicians define their own page styles. How I was envisioning solving that with the var(--mi-variable) stuff was basically to just inject a style on artist pages that sets those variables and overrides them from default.

[timglorioso]

Thanks @simonv3. For artist pages customization, it feels like nested theme will be a cleaner solution based on my understanding/imagining of those pages. I may need to handle that in the related PR to ensure the theme approach will work as I'm hoping.

[timglorioso]

Braindumping implications for themes with or without tokens

Scenario

we have dark and light themes they automatically toggle based on system setting they manually toggle based on user site setting

Internal mechanisms

we have a Button component, which has a few variants the Secondary variant changes based on whether we're in a dark or light theme

With tokens

• the Secondary Button doesn't need to know anything about colors
• the Secondary Button doesn't need to know what theme we're in
• the theme needs to know about component internals

Without tokens

• the Secondary Button needs to know which colors to use
• the Secondary Button needs to know what theme we're in
• the theme needs to know about what theme we're in (so that components can then know)

In summary, tokens result in components knowing less about the theme, and themes knowing more about the components. No tokens result in components knowing more about the theme, and themes self-describing what they are to components.

To me, without tokens feels ideal when looking at internal mechanisms—I don't like the feeling of the theme needing to know about how components are rendering themselves.

External mechanisms

In practice, what do each of these feel like as an API when styling an application and its constituent parts?

With tokens

• color usages are centralized—changing a token's color changes it everywhere
• useful when themes apply to entire UI
• useful when components are universal

Without tokens

• color usages are distributed across component definitions—changing brand color from Red to Green means refactoring all Red usages (this is probably rare, or never happens)
• useful when themes apply to UI verticals
• useful when components are distinct to UI verticals

[timglorioso]

Thinking we will want to use tokens, but keep Mirlo and Artist tokens separate... TBD. Is it possible with Typescript Emotion to have two different theme types feeding the same Provider instance? I guess if you make things optional?

[simonv3]

@timglorioso Sorry if this is explained elsewhere but what are tokens?

[timglorioso]

A token is an applied scale value. Many tokens will be the same between Mirlo and Artist themes, but lumping them together is a knot that we want to avoid. For example, Mirlo theme might have tokens for Button variants that don't map to anything meaningful in Artist theme (i.e. such Button variant isn't in the Artist design language).

// color scales
const color = {

  // color scale
  gray: {
    ...,
    900: "#111111" // color scale value
  }
}

const darkTheme = {
  color: {
    ...,
    backgroundColor: color.gray[900] // token
    ...,
  }
}

[timglorioso]

Worth also mentioning that a design scale is a way of constraining options from near-infinite amount to at most a few dozen, to reduce decision fatigue and improve consistency.