Color Naming [PLEASE VOTE AT BOTTOM]

[cbeley]

The current names of our colors seem a bit awkward and not consistent. We use color-primary, which seems to imply how it is used, without being generically usable. But then we have a set of gray's which breaks that convention.

Instead of going into full details here, I'd recommend reading https://davidwalsh.name/sass-color-variables-dont-suck . For mobile-web-frontend, we adopted a similar approach, though ended up using color numbers (https://github.com/opentable/mobile-web-frontend/blob/develop/statics/scss/_colors.scss ...though, there shouldn't be so many greens and blues..that was not design approved).

TLDR: I'm a fan of David Walsh's approach to the problem (though, I'm not inherently opposed to the pattern mobile web took). We have tools to replace all colors of a certain type if need be and it's not very obvious when reading code what $colorPrimary is.

[matteofigus]

@cbeley I agree with you that a discussion about naming is needed.

In my opinion, the point of having a vetted set of colors by designers, should be that I, as engineer, shouldn't care to know what kind of grey or yellow I should put in a button. If that's a primary button, that should be primary, and design only should decide which color actually is that. In that perspective, I like the idea of having a color-primary. Now, when I see something like color-grey-primary I get a bit confused. If that is supposed to mark a different scenario (for instance, color-primary is for consumer and color-grey-primary is for Guest Center? I am really speculating here as I don't have too much context), then I believe color-grey-primary is not a good name.

So summarising, either we go full with abstract names (which I prefer), or with meaningful descriptors - but not a big fan of the mixed approach 👎

[nickbalestra]

Thanks @cbeley for the heads up. I've brought that up with @lastquestion before and totally agree. For example before primary and secondary where both reds and I found that super confusing.

From my understanding most of those naming (set aside legacy ottheme) are derived from the invisionapp documents produced by designers, therefore I think it will be good to have @mannionaco in the conversation to ask him where he's leading naming for the design-system.

[mannionaco]

@nickbalestra and @cbeley the current naming convention is somewhat arbitrary in that the intention is to make the naming generic (ie $color-primary = red #da3743) so that in the future if we change a hex value for a particular color (ie #da37343 to #XYZ) with the intention of it serving the same purpose (ie primary) we won't need to add a new color and modify changes within any respected components.

My goal with design systems is to best organize us to avoid future challenges and redundant dependencies. If there is an alternative approach that is suggested and allows design to modify design tokens without impact to development I'm all for it. Alternatively, if there is a strong case not to go with that direction or to take another approach I'm open to your collected direction on how to best move forward.

[karuto]

TL;DR: I suggest we have non-functional, pure color variables in aliases.xml and map them to "functional variables" such as color-button-hover at the token level.

This provides a very clear separation of abstraction levels: designs have flexibility in color world and devs have context in functional world.

---

Long version:

Wow. I wish I discovered this thread sooner. I wrote pretty much the same concern as @matteofigus in Frances' PR right here: https://github.com/opentable/design-tokens/pull/54#issuecomment-335885473 about functional variable namings vs the pure color ones.

I think we should have only "pure color variables" like the ones in @cbeley's example inside aliases.xml. The aliases.xml should have the as little amount of functional context as possible because its intention is to be flexible for any token to adopt its values.

However, I do see the pain point that @matteofigus mentioned where as a dev you shouldn't know about colors down to actual color level. It's natural to expect a button has a color-button and perhaps color-button-hover, color-button-disabled etc. The benefit is that variables names are consistent, predictable, matches the states of the UI and you worry about only the right level of abstraction.

I suggest we should consider map the "pure color variables" from aliases.xml to "functional variables" such as color-button-hover at the token level, as needed. This approach provides a very clear separation of concern, or separation of abstraction levels between tokens and aliases.xml.

I feel like mixed context / mixed abstraction level is the source of evil and what makes this confusing. So let's try to isolate them as much as we can?

As to David Walsh's complaint about this approach of "functional naming":

The problem is the variables aren't reusable. What happens when decide to use #292929 as the background color for your buttons?

My anwser is that the reusability is solved in React land, by the nature of React components + CSS modules. We only define this color in CSS once, ideally, so this is a non issue.

The other half of "reusability" comes when we have to batch change the values inside a token. I think that's a price I'm willing to pay because 1. that doesn't happen often at all; 2. token is much easier to change / publish than a fullstack consumer repo like start page.

Also, his complaint is based on a 100% functional naming approach where reuse is nonexistent. But I'm proposing a mixed NameThatColor (at aliases level) + functional naming (at token level) approach so I think it's a much more balanced way to go. Thoughts?

[cbeley]

My anwser is that the reusability is solved in React land, by the nature of React components + CSS modules. We only define this color in CSS once, ideally, so this is a non issue.

I'm not quite sure I follow. The issue isn't really about redefining the color once, but about dealing with the eventual issue of wanting to use the same color in multiple places.

I see functional color names as a bit of a maintenance nightmare. Instead of just being able to reference a color, people now need to go into this repo and add new functional names that are just aliases for every new component that gets added. It may sound nice on paper, when you're imagining just a few basic high-level components, but in practice, there's going to be some edge cases and probably more functional things to color that may not fit into the category of one of your previously defined functional names.

Also, perhaps I'm in the minority, but when writing CSS, I want to know whether two things have the same color. Otherwise I'm just writing CSS blind without understanding what I'm writing. It's a lot easier for me to visualize when I know both thing X and thing Y are the same color vs. different colors, which functional names would completely hide.

I think I may have opened up a bit of a can of worms with this discussion. Honestly, I think the only thing that needs to be done is use some consistent color names. If we're going to do color-secondary-gray, then we should do color-primary-red. Or, if we're going to do color-primary, we should just do color-secondary.

After talking with kellen more, I think color-secondary, color-primary, etc. is in line with how design is setting up their pallet, that I think we should just go for it. I'd prefer to tack on the color to those variables, but don't feel strongly one way or the other.

Finally, one last argument against functional names, is that doesn't seem to be how design is working. They have their pallet of colors and use those. They are not, to my knowledge, setting functional colors and setting those in their specs. I'd like us to stay as close to design as possible when naming this stuff.

TLDR: I'll be extremely sad if we start going down the functional color names route. I've seen it used in practice elsewhere and it wasn't a fun time.

[morewry]

I agree that functional color names are a nightmare. And if you read Salesforce/Theo's documentation, you'll find an explicit suggestion that a token never be used in a place different from its name.

For example: color-button should never be used on anything other than a button.

I was really excited to see aliases as a config option in the Theo design token system. An alias approach was what I was advocating in the eyeglass module exploration I presented to some of you a while back.

My preference would be that the colors have names that are only about what color they are. Perhaps we use the Pantone naming system, perhaps another, perhaps a combination--whether a particular shade of blue is called blueberry or bluejean or lightcerulean isn't the big deal--it needs to be something we can adopt vocabulary-wise, but it mainly just needs to have a static and unique name. @karuto and @cbeley both mentioned this same approach, and it's by far my favorite[1]. Basically the same as that article on David Walsh's site, only that approach PLUS aliases.

Then that color can be aliased with multiple function names. button-primary, selected-item, icon-selected, list-item-hover, and more can all point to bluejean. We can see that they're all bluejean. But within the context of a component, it's typically easier to use localized names that do suit function. But you either have to duplicate or alias to accomplish that without using colors in places that they don't sound like they belong.

A really cool thing about this in terms of the design token config is that you get some info just by looking at the tokens about all the various places they're used! I've never had the luxury of working that way before, but given my feelings on opening CSS preprocessor era framework _variables.scss files I have a feeling that would be awesome.

However, my initial explorations of design tokens made it seem like the aliases got compiled away and only the main names were present in the compiled token files. Which makes aliases useless, so I hope to loop back around to figure out why that was happening. I had to be doing something wrong.

150% agree that functional names are a bad, bad, bad, bad, bad idea except for aliases.

[1] I've done this two ways in the past, one with Sass maps and one with Sass variables. I've also done numbered colors before (e.g. blue01, blue02, blue03) and that's...well, it's okay if you can't get agreement on anything else, but more memorable names are better.

[mannionaco]

Logically the suggested proposal makes a lot of sense. Looking at the Salesforce's design token list, the items are granular and design wants to make sure that our naming of components and instances is in alignment to maintain a common language within our teams. I can foresee naming getting a bit out of hand, though I don't think it'll be a major problem, at the expense of having common naming for color where there is a control.

@francesyun and I are in alignment with this proposal and are wondering if @morewry @cbeley want to see an example list with naming to make sure we are all on the same page. Sound good?

[cbeley]

@mannionaco I think a quick example of what you are thinking would be great. Few different ideas bounced around in this issue.

[morewry]

@mannionaco Love to see it! Keeping in mind, of course, that no one has confirmed to me that restaurant will be using these same tokens. So in terms of diner's efforts, my opinion is less important--unless the decision made will also be directly relevant to restaurant.

[karuto]

This thread has been stale for a while. I will try to summarize everyone's opinion and provide voting options below.

If I'm understanding @morewry's long post above correctly, you are suggesting the same approach I had which is having "pure color variables" in the aliases and an option to map them to functional names at a per token level:

... Then that color can be aliased with multiple function names. button-primary, selected-item, icon-selected, list-item-hover, and more can all point to bluejean. ...within the context of a component, it's typically easier to use localized names that do suit function.

But you sound conflicted at the end as you found out the aliases get compiled away and only token-level variable names remains in the output file.

150% agree that functional names are a bad, bad, bad, bad, bad idea except for aliases.

I'm trying to find out if you are proposing a mixed "pure color names at aliases level + functional names at token level" approach or a "use pure color names all the way with no mapping" approach?

Also, if we are going towards this mixed approach, where should we put these functional names? Let's say some headings need to be color-chalkboard. Do we define the "functional name" - color-heading - in the otkit-colors token, or in its own functional token otkit-typography?

[mannionaco]

I've been meaning to create an example from the design team based off some of the input from everyone, sorry for the delay on our end. It's not groundbreaking by any means and after some light discussion with the design team (aka @francesyun):

We like Salesforce's structure: https://www.lightningdesignsystem.com/design-tokens/

Salesforce Token example: Token = $color-background-path-incomplete-hover

Color reference: rgb(221, 219, 218)

dddbda

PALETTE_GRAY_5

---

OT translation, token example: Token = $color-background-list-item-hover

Color reference: rgb (do we need this?)

f7f7f7

Utility Gray

---

I appreciate this direction. I like that it isolates design colors and creates a single source of truth that enables us to reflect changes across all sites/references if we were to introduce a color to test against.

My only hesitation is the amount of instances that are created on the token side. Who will come up with a naming convention? Is that a problem we need to solve for? Who is responsible for managing that?

[morewry]

@karuto, yes, I'm pretty sure we're advocating for the same (or at least almost the same) approach. However, the way aliases work within a Theo design tokens system is the opposite of what I expected.

An alias, in US English, means "a name someone is otherwise called or also known as, an additional name that a person sometimes uses." In people terms, an alias is not the legal or official name of the person--basically, it's not their canonical name within the social system.

So when I started experimenting, I approached it from that perspective:

colors.json 1 (alias intuition)

{
  "props": {
    "cloud-burst-blue": {
      "value": "#20315A"
    }
  },
  "aliases": {
    "table-row-selected-background": "cloud-burst-blue"
  }
}

My intention was to set up a canonical name for a color, e.g. cloud-burst-blue, within the design system. Then, I wished to create aliases for that color, alternative names by which that color might called at other times within implementations, e.g. table-row-selected-background.

The output I got was this:

:root {
  --cloud-burst-blue: #20315A;
}

No alias in the output, which was disconcerting. Can't use the alternative name if it's not present, after all. In trying to figure out what I did wrong, I began to get the impression that values, if I wish to reuse them under other names, have to be set up in the aliases--exactly the opposite way from my intuition and with a special syntax (mentioned in the docs, but not very clearly):

colors.json 2 (alias reality)

{
  "props": {
    "table-row-selected-background": {
      "value": "{!cloud-burst-blue}"
    }
  },
  "aliases": {
    "cloud-burst-blue": {
      "value": "#20315A"
    }
  }
}

Then the output I got was this:

:root {
  --table-row-selected-background: #20315A;
}

I only get one name in my result again. So I infer the alias feature is a preprocessor-style feature; it gets compiled away by Theo no matter the output format. (Which I also found somewhat unexpected, although for no particular reason.)

My new understanding of "aliases" is as a compile-time-only feature that allows an "alias" to be used to reference its own value in any file that has the alias defined or imported, what's already done in this OpenTable design tokens repo (although I overlooked it):

colors.json 3 (corrected)

{
  "aliases": {
    "cloud-burst-blue": {
      "value": "#20315A"
    }
  }
}

table.json

{
  "props": {
    "table-row-selected-background": {
      "value": "{!cloud-burst-blue}"
    }
  },
  "imports": [
    "./colors.json"
  ]
}

In contrast to what I expected, this means you basically have to define a new token file and set of props for every re-use of a value under different names. It will still enable roughly the same approach, but creates distributed repetition, which may be less desirable than something like this:

colors.json 4 (theoretical)

{
  "tokens": {
    "cloud-burst-blue": {
      "value": "#20315A"
    }
  },
  "aliases": {
    "cloud-burst-blue": [
      "table-row-selected-background", 
      "list-item-selected", 
      "button-primary"
    ]
  }
}

In our CSS Modules setup, unlike the browser-supported CSS custom properties I used in my examples, we will already be compiling away all the variables and their values will be replaced everywhere they are used, so colors.json 4 (theoretical) might have some theoretical advantages.

Instead, with Theo, we'll end up needing to create table.json, list.json, and button.json to accomplish the same result. I still think colors.json 3 (corrected) looks like a good approach, especially because it's similar to what Salesforce Lightening is doing. I think it is the best way to use Theo--it is clearly the approach that led to Theo's functionality.

With colors.json 3 (corrected) I think it might look desirable to share the "aliases" from this repo, but co-locate the "aliased" "props" with their component. I can't 100% guarantee that this would unavoidably compound any issues inherent in the pattern, but I've used that model with Sass and feel it can be improved upon, although I know with many projects you wouldn't run into any particular issue. For OT, it would be more risky with multi-repos and I'd say, "no way, please!" to that, although I concede it might amount to the same thing with a mono-repo. But because of that, if we see any advantages for us in keeping all the tokens here to be managed by design it would be the safest first approach.

[karuto]

@morewry Thanks for the detailed comment with code snippets. I see that your primary concern is Theo forces us to do distributed aliasing / repetition (your code sample 3) instead of a centralized approach (your code sample 4).

I agree with you that I think design token variables (aliases) in this repo should locate next to the component, so that it's easier for designers to contextualize.

Which means, for example, in otkit-typography, heading-large-font-size should have a heading-large-color: { value: {!color-chalkboard} } associated with it.

@mannionaco also speaks for design that design thinks functional color names make more sense to them, where each functional color name (Token = $color-background-list-item-hover) maps to a pure color name behind the scenes ($color-gray-utility: #f7f7f7).

---

Yes, functional color names may be "bad by principle" (?) but with the way Theo and CSS modules is integrated into our workflow, I personally believe the "pure color in aliases -> functional color in token" two pronged approach is better than using pure color all the way, in this specific scenario.

For the two pronged approach, if design wants to change the color of large headings, it's easy and clear that heading-large-color in otkit-typography needs to be changed, and that's it, all projects using design token should be updated.

For the pure color all the way approach, there is no way for design to easily do that. We as developers would have to search for all the @value some-pure-color-variable from 'otkit-colors/token.cssmodules.css' from the codebase, find out which color is used in the .heading-large CSS class, and change it from there. But that's only for a single microsite, so we have to herd everyone else: "hey please change your pure color reference inside your project so that we all have the new large heading color".

I thought this project's intention was to give autonomy to designers so that design decisions, such as color changes, can be abstracted away from engineers. It's clear which approach suits this mentality better IMO.

Maybe I'm understanding the "pure color" approach wrong, but that's what I can visualize. @cbeley feel free to correct me.

---

I also think this discussion thread has been going on for long enough and it's time to call a vote.

[morewry]

@karuto, agreed! At first when you said "with the component," I thought you might mean with a correlating UI component in ot-react-ui-component. The rest made it clear. 😄

[karuto]

Thumbs up if you prefer the "pure color names in aliases + functional color names in tokens" two-pronged approach:

• in aliases, use only pure color variables, such as color-chalkboard
• at the per-token level, map the pure color variable to a functional name; for example: heading-large-color: { value: {!color-chalkboard} }
• these functional color names should stay close to the "component" or UI element they serve; for example, heading-large-color should be next to other heading-large design token variables, such as heading-large-font-size and heading-large-line-height, etc.
• in your microsite that consumes design token, reference functional color names alongside other design token variables for the same grouping.

For example, with this approach, your CSS import for heading-large would look like:

@value 
heading-large-color, 
heading-large-font-size, 
heading-large-line-height from 'otkit-typography'

This poll closes in 7 days from now on.

[karuto]

Thumbs up if you prefer the "pure color all the way" approach:

• in aliases, use only pure color variables, such as color-chalkboard
• all pure color variables exist inside otkit-colors token as they are named
• do not define additional color variables inside other "functional tokens"
• in your microsite that consumes design token, reference the pure color variable separately from other "functional" design token variables.

For example, with this approach, your CSS import for heading-large would look like:

@value color-chalkboard from 'otkit-colors'
@value heading-large-font-size, heading-large-line-height from 'otkit-typography'

@cbeley let me know if I got your idea wrong; this is my personal interpretation on your pure color approach.

This poll closes in 7 days from now on.

[karuto]

@morewry @cbeley @matteofigus @nickbalestra @lastquestion @nikhilrao89 @ggauravr @ericz82 feel free to vote ^

@mannionaco @francesyun would love designers' input as well.

[mannionaco]

@karuto I have two goals for color:

1. Establish a control to reduce/eliminate deltas
2. Establish a system, that may be reliant on naming, to provide flexibility at scale when A/B testing

I want this to be easy to maintain and change. I want it to be easy to change color, like a switch, where multiple components across our experience will change without having to investigate what is used where.

I lightly understand the benefit of functional colors, however I don't have a strong preference of what direction we take, as long as it solves for my two goals. When I looked at Salesforce's naming structure, I thought it made sense, but I'm overall hesitant of managing that direction.

A problem I to run into in discussion is nomenclature. I've learned, with color on the design side, is to name with purpose. For OpenTable, naming colors based off natural things, like food ((i.e. green = lettuce), resonates well because it relates to our brand and business. It makes it easy to understand, gives it purpose, and is easy to talk to.

I can't speak for the development side, but @cbeley's article in the first post (https://davidwalsh.name/sass-color-variables-dont-suck), the solution presented at the end of the article directly relates to how the brand design team at OpenTable wants to name. If we can leverage this, it will make it easier to produce a common a language we can all talk to.

How this relates to development, I don't know, but if whatever we land on accomplishes the two goals I presented I'm happy with any direction. I most importantly, in our effort to create a design system, is to reduce churn, eliminate redundancies, and produce a flexible system that allows us to make smart decisions on the fly while doing our best to reduce future challenges.

[karuto]

@mannionaco Thanks for the insight, Kellen. I absolutely agree with your points and I understand that designers use a pure color naming system.

The thought process I have behind my proposal for the two-pronged functional color names is designer-centric. I'm trying to solve the exact problem you mentioned: if Kellen wants to change the color of all the heading-large few months down the road, how easy is it to do that from Kellen's perspective?

Here is what I think will happen in a functional naming world:

1. Kellen finds out which functional variable controls the color of that heading: heading-large-color.
   2. Kellen changes heading-large-color: { value: {!color-chalkboard} } to
      heading-large-color: { value: {!color-lettuce} }.
   3. Publish a new version of the token and done.

As you can see, we are still using the natural-based color names that designers understand at the core, so we are not doing things in a different direction. The functional color name, such as heading-large-color, is for developers to give designers an "interface" to tweak design details. You don't need to know how and where exactly heading-large-color is used in the real codebase; all you need to worry about is that it represents the single source of truth for the color of heading-large. You can make design decisions without developers getting in the way. Full autonomy.

Where as if we are using the pure color all the way approach, you will not be able to change colors without dev's help, because inside design-tokens you only see color-chalkboard but you have no visibility on where and how this color is being used, which elements uses this colors, how can you change it, etc. You have to ask each team that uses design-token and change it one at a time.

Hope you get where I'm coming from. My whole intention is to make designers life easier. Let me know if I can explain it more clearly.

[cbeley]

My big question is, if design isn't going to decide on the functional names, who is? Who is going to maintain this big list of functional names, that has to somehow conveniently work across all the teams using those names? Also, how fast are we going to be able to move, when, if we need to add something that doesn't quite fit into a current functional name, it now needs to be added to this repo and merged before another team can even really begin to use the new token. It's unfortunate to create a layer on top of design's system for engineering.

How I view it, is if design is going to think with functional names and maintain a strict set of them in their designs, it makes sense. If engineering is going to maintain this list of functional names, I see a potential mess down the road (which, is maybe where some of my bitterness lies, since I've had to deal with messes around this before).

All color changes should be going through QA anyway for teams switching colors. Being able to change a bunch of colors at once without an engineer understanding the full impact of that change for QA seems dangerous to me to begin with.

Anyway, this thread has gotten really long. If we're going to vote, maybe a new issue with voting at the top and a long, clear list of al the pros and cons of each approach to help summarize the arguments in one place.

TLDR: I honestly don't think think engineering should be deciding this. OTKit should be representative of however design wants to do things in my opinion.

[karuto]

Who is going to maintain this big list of functional names

The way I see it there's no a single person maintaining this. It should be a decentralized model. Of course all the changes should go through code review and obvious bad names should be caught that way.

Also I don't see any team using all of design tokens. For example in the near future I don't think anybody besides start page will be using otkit-desktop-typography, which will contain functional names, and that's fine because it doesn't stop other teams moving forward.

if we need to add something that doesn't quite fit into a current functional name, it now needs to be added to this repo and merged before another team can even really begin to use the new token.

I mean... yeah, that's the whole point of why we are doing design tokens, or ot-react-ui, or anything that's shared across teams. I will gladly accept "we move slower" rather than everything's isolated inside each team's codebase without much external visibility or shared decision making.

If the argument is "functional names are creating an extra layer that's hard for outsiders to understand" = bad, then wouldn't "let's keep design tokens as simple as possible and leave all the decisions inside each team's silo" = worse?

All color changes should be going through QA anyway for teams switching colors.

Sorry I am not following, shouldn't color switch be a design decision made by designers, so that they know the impact? Why is QA the decision maker?

OTKit should be representative of however design wants to do things in my opinion.

I think it should be a co-product of design and dev, I mean, that's the slogan of this repo, "design and engineers working together". I never excluded designers from this conversation and I think they should participate, comment, vote too.

[cbeley]

Sorry I am not following, shouldn't color switch be a design decision made by designers, so that they know the impact? Why is QA the decision maker?

How can we guarantee that a change is as design expects without verifying it? Say we change title_color from green to red. This may seem harmless, but maybe someone used it in an unexpected spot (which becomes even more likely, now that design isn't specifying functional names). The designer changes that value (or anyone really), pushes it out, and it causes something to look wrong or not be visible. As with any code change, we should be verifying that our changes have the intended effect. It becomes harder to verify that when we can make wide-spread sweeping changes by changing one variable.

EDIT: Now, this isn't to say that the same isn't true for changing a single color variable (like changing red to a slightly different red). Though, that also means, that if someone wants to change certain things from red to green, someone is explicitly making that change in their code and verifying that it matches the designer's specs, vs someone potentially blindly changing $title_color and then not auditing the scope of changes fully. You could do the same for functional names by searching the code base for all the uses of a particular name, sure. Though, things then get hairy if there's one spot where the functional name no longer makes since or matches design..what do you do? do we add another functional name? How do we deprecate these functional names when needed? How do we ensure we don't add too many highly-specific functional names?

If the argument is "functional names are creating an extra layer that's hard for outsiders to understand" = bad, then wouldn't "let's keep design tokens as simple as possible and leave all the decisions inside each team's silo" = worse?

The thing is, with functional names (if design is not using them as specs), it means I can't look at design's specs and directly compare it to code. To do the translation, I now have to look at the design, then look at design tokens, then figure out the correct name.

In a sense, this sort of comes down to where the single source of truth is, which I think we both want, but in different ways. I think the designer's specs should be the single source of truth, the thing I can look at and know how something should be and can directly use it to do an implementation. On the other hand, with functional names, the source of truth becomes a combination of the designer's spec, and how the functional names are written.

I don't think functional names are inherently bad, but I also think that, if left to a large group of people to maintain, they will grow out of hand. That's why, I think it's totally cool to go the functional design route if they will be used directly by design when they are specing things out. Otherwise, how am I going to be able to sit down with a designer and communicate design if we are both using different tokens (engineers using functional tokens and designers using the flat-out colors).

I think we're maybe at the point where I'm not sure there's much more to discuss. Lots of discussion above along with some excelent articles further documenting some of the pitfalls of possible decisions. I think we should just summarize as best we can everything and have people vote on their fate. I'll just end on this: I totally see the appeal of functional names and I was once on that bandwagon. But sadly, no matter how hard you try, code review doesn't catch everthing and people deviate in unexpected ways. Some possible ways to avoid that are to either strictly standardize with automated rule checking (I'm not sure how we could accomplish that with functional names) or limit the amount of people contributing (which is sort of in line with having designers always have the single source of truth for the spec).

[karuto]

Hi Chris. Yes, we both want to maintain a single source of truth. I agree with you.

I want to clarify that I never said engineers should decide on functional names alone. Designers should be involved in this process. Hope that makes you happier.

I think the designer's specs should be the single source of truth... On the other hand, with functional names, the source of truth becomes a combination of the designer's spec, and how the functional names are written.

I see what you are saying, but you are under the assumption that functional names are solely decided inside engineering silos. Sorry if I confused you before.

My argument is that the design spec I received for rest profile is already grouped by functional components. It doesn't live in a "pure color names" mentality, as in, the design spec isn't structured like this: "here's color-chalkboard, and here is a list of all the places / components it shows up: the heading, the title, the dtp prompt, the social proof text...".

I see the pure color approach originates from a CSS engineer's mindset, a product to solve an engineering problem in my opinion, but doesn't match with how our design specs are organized, and it leaves the decision-making scattered among code silos, which as I said I think is a bigger danger.

So I would argue that functional names take the minimum effort for both design and engineers, because all we need to do is just give these already-functionally-grouped values proper names.

If we

1. let designers decide the variable names (because I think they are perfectly capable),
2. collect these variable names in a centralized place (invision for now, live styleguide later perhaps),

will you feel better, since now we avoid the problem of "crowdsourcing functional names", which seems to be the no.1 concern of yours? ;)

I'll ask more designers and people affected by this to vote.

[karuto]

Closing this as we get enough votes and it has been over 7 days since the voting started. The community decided to go with functional approach.

[mannionaco]

@karuto now that we have picked a direction I want to come up with and document a strategy on how this will be maintained and who is responsible for what. This can be discussed in our Design Systems meeting.