Design tokens > Token naming refinement and todos

After the initial naming convention was completed in #1602 (closed) there are some remaining details and action items to keep track of in this issue.

Naming…

Naming

1. ✅ Confirm that naming consistency that aligns with intent. For example, even though a box shadow or outline might be used, the design intent is to create a border. Naming aligns with intent and not a 1:1 with a CSS property.
2. ✅ Determine when to use default, and if default is the right term. We'll use default when necessary, especially when multiple states are available.
3. ✅ Determine if constant is a necessary prefix for constants. This will not be used in Figma, and would be less than ideal in code, so the decision is to not prefix constants.
4. ✅ Determine if component color tokens should reference both semantic and constant tokens, or only constants?
   • Determine if every use of color in a component should have a token. For example, if the color matched a semantic token, should there be a component-level token created to reference it? See #1816 (comment 1879716852) and #1816 (comment 1879715211).
5. ✅ Should illustration color constants be included now (unsure when any illustration effort from Paper Cuts or elsewhere might commence)? Not included now.
   • ✅ If yes, should illus in the constants be fully spelled out to illustration? Spell it out if/when included for consistency.
6. ✅ What separator are we using to reference tokens in documentation? For example, dot or dash. Dot notation to separate depth/chaining, and dash for composite terms. For example, action.danger-primary.background.color.default.
7. ✅ Are we good with all lowercase and delimiters only as a naming format? Yes, see previous question.
8. ✅ More clarity around our scales and where and when we should be generic vs. specific and use different types of scales. We're aligned on the type of scales and where to use.
   • Nominal - No particular hierarchy or order. For example, shadow-modal, shadow-drawer, shadow-dropdown, shadow-popover.
   • Ordinal - Ordered, but not clear the space between, also has finite options. For example, text-color-default, text-color-subtle, text-color-strong.
   • Interval - Clear progression, potentially infinite options. For example, color-neutral-0, color-neutral-100, color-neutral-200, color-neutral-300.
9. ✅ Align on a shared scale for background, border, and text. (For example, default, subtle, strong). It would be great to run a few tests on this naming, but at some level it will require documentation and training.
10. What it means to have bounded contexts, and what are the ones we have. This isn't a topic we need to cover as part of this effort.

Documentation…

Documentation

1. Documenting color patterns. e.g., icon color is one step lighter (light UI) in the color ramp from its text counterpart to aid with optical balance (opposite is true in dark mode). Border color should never be stronger than the main enabled content color within. And more!
2. ✅ Document how to read tokens. Covered in !3823 (merged)
3. Token matching. Does naming infer pairing and how to document token matching patterns. e.g., A designer might ask, should background-color-default have to be paired with border-color-default? The answer is maybe, but why? Does text-color-disabled have to rest on background-color-disabled? Again, the answer is maybe, but how do I reliably know when to choose what? Are there things that should always pair? e.g., text-color-default and icon-color-default
4. Clarify what is a choice (more for authors, like choosing what color constant to use) vs. what is a decision (what is the intent or purpose I’m using this token for). The documentation covers this in a few ways.
5. Document the concept that “the token IS the manual for how to use it,” and when this works or not. Steering away from additional abstract concepts.
6. ✅ Starting an MR in the Pajamas project to update the current design tokens page with more user-facing guidance. See !3823 (merged).

Other…

Other

1. Getting the naming test cleaned up and work through more moderated sessions. Timing isn't going to allow for specific testing. We'll continue to monitor for learning.

Outcome

Complete the token inventory spreadsheet →