Nice. This basically how our logic in DCR looks. We check for display first and then use a switch to branch on Design.

At a later stage this could extend to a nested switch statement if the number of use cases grows but with this model that's a simple refactor

This. It's funny how it looks so simple when you see it here now but I guess the solutions that seem simple are the best ones!

One nitpick, I wouldn't name the function the same as the property it is setting, I normally go for some kind of prefix like decideHeadlineBackground() or getHeadlineBackground() but that's maybe because I lean a lot on using CMD+D to select similar text when editing. Defo not a blocker.

I find the more complex the code that I write gets, the less comfortable I am that it's the best way of doing it 🙂

I suspect DCR might make use of this (with a theme), and AR might make use of the individual functions/CSS declarations.

One nitpick

Yeah we should discuss the API, this is a draft PR for a reason 🙂. On this, I try to make function names as simple as I can because I find the longer they are a) there's more brainpower required to parse them, and b) longer names can muddy what the function is actually doing. I think ideally the type should be able to work in tandem with the name to tell you a function's purpose. This is subjective, happy to be told otherwise.

This might be a bit restrictive for DCR. I don't have a specific example but my feeling is we often stray outside the bounds of 'neat'...

I am assuming this is for dark mode?

I am assuming this is for dark mode?

Yep, many colours have a dark mode variant, the most prominent examples being the article background and body copy colour.

Minor: I might suggest headlineText for better consistency with Source.

Good idea! Updated.

It's worth spending a bit of time thinking about how the naming system will scale. I know @oliverlloyd has pointed to the potential problem with the Colour abstraction defining a light and a dark mode. This could become a bit verbose or restrictive for DCR that only has a light mode. There might be ways for DCR to abstract this away in their application, but it's worth bearing in mind.

I'll give you a peek at Source's colour token naming system:

[theme][property].[component][variant][state][mode]

• theme: the colour theme to which this token applies
• property: the style property for which this token is intended
• component: the design system component to which this token is applied
• variant: there are sometimes multiple variants of each token. For example, text in a component may be primary or supporting
• state: user interaction that may have affected the appearance, such as hover or checked
• mode: the colour mode (i.e. inverse represents dark mode)

Note that in most cases, not all of these parts will be present.

Examples:

text.primary

This is a text colour, for primary text. There is no theme specified, so we assume it’s for the default theme. Note that it’s not for a specific component. “Primary” is the variant, telling us it should be applied to the most important or core text. There is no state, so we assume there has been no user interaction. There is no mode, so we assume the default colour mode ("light mode")

brandBackground.cardArticleHover

This is a background colour on brand theme, for the article card, in the hover state.

This is very thorough, thanks!

Two questions:

1. What does the dot signify in the hierarchy (I know it represents a method or property lookup, but why at that level)?
2. How would you define the property for text in a headline? Would it be headlineText.primary? Or do you see headline styles coming as a bundle so that it would be something like: headline.text.primary?

const headline = {
    text: ...,
    background: ...,
    brandAltText: ...,
    brandAltBackground: ...,
};

The position of the dot was my best guess at where to split the palette to make it more treeshakable. It's likely that most applications won't be using multiple themes on one page, and those that used multiple themes might not want all the colours for each theme. I think you can ignore this consideration for your purpose.

In your example text is the property... it represents the CSS property to which this token will be applied (well, technically it's the CSS color property, but color is a bit vague!)

I think headlineText is a good name. Abstracted it's [component][property] whereas Source goes with [property][component] but I don't think it matters too much.

There's only one headline per article, so you won't have variants like "primary headline" and "supporting headline".

It's worth taking a look at other design systems to see how they name their tokens. Then write down what your system is, so you can (attempt to!) keep it consistent:

• Salesforce
• Adobe
• Duet

Oh sorry, yes that's also an API we'd want. With the above I was asking which one of those four we should go with for individual colour lookups. I think we'd want the palette API to exist in addition to that?

My preference would be option 1. It's similar to Source and I kinda like the ergonomics. Also there's some value in consistency as people would be able to switch between the Source palette and the Editorial palette without having to think too much.

Ok, sounds good, I'm happy with the API.

My only concern is that we'd be generating a lot of unused colours with every call to the text function. For example, if we use it in the Headline component, we're only going to pull out one or two colours. We could solve this with memoisation, or by dependency injecting the full palette as DCR are planning to do.

I wonder if a fifth option that looks a lot like (1) would be preferable:

text.headlinePrimary(format)

That way we're doing the minimum amount of work at each call site, just enough to derive a single colour.

Oh gosh, yes. More performant and preserves the ergonomics. I'm on board 🚢

Ok, I've updated the code to use this new API.

Do you intend to move border to editorialStyles also?

I wasn't planning to move it 🤔, but we could generate CSS declarations for it there as well. Would have to be border-color specifically rather than border I think?

Now that you've flagged this it occurs to me we could also name it something more generic in the palette module, like line?

Would have to be border-color specifically rather than border I think

Yeah, maybe. I was gonna suggest dropping colour or color from names because colour is implied by the fact it's in the editorial palette. It's up to you though, maybe there will be non-colour tokens here also (spacing, border radiuses)? In which case, specific is better.

we could also name it something more generic in the palette module, like line

I think there's a distinction between border and line. Borders border elements, lines divide elements. Borders are encapsulated within a component, lines are defined at the layout level. I don't think we should conflate these concepts.

I was gonna suggest dropping colour or color from names because colour is implied by the fact it's in the editorial palette

Sorry, I was probably unclear there. I was thinking something along these lines:

1. The editorialPalette module would contain a colour token, called either border or line, which is just a hex colour.

2. The editorialStyles module could contain a CSS declaration of the form:

const border = css`
  border-color: ${palette.border};
`;

When I said border-color I meant the CSS property rather than the name for the variable in our code 🙂. I think you're right, this is just for colours.

Borders border elements, lines divide elements

Ok, we have a semantic distinction between them so we should provide different names to avoid confusion, sounds good 👍.

Right, yeah, me got confused there! Only 3 cups of tea this morning. You makes a lot of sense 👍