Token structure

[sarahill]

A few of us started a conversation around token structure and naming conventions to align on a general approach. Continuing the discussion here.

The general proposal is to use a structure like:
group + subgroup + variants (variants will change based on group)

This formula should work in general but there are some cases where it will and should be modified to use more human language. For example, fonts-fontsize-100 can potentially be reduced to fonts-size-100.

The use of plurals is an ongoing topic that we still need to align on.

Jam file

For reference:

• https://open-props.style/#typography

[heyjoethomas]

The basic structure you mention above would work great imo. We end up with a readable and usable token architecture. Colors would also have a state label after variants. Some examples of what the above structure would get us:

• --p-color-text-interactive-hover
• --p-font-family-sans
• --p-space-3
• --p-motion-curve-linear
• --p-breakpoint-xl
• --p-z-index-2

I think the current shape group could likely be labeled. Right now it has border-width and border-radius subgroups. The shape title doesn't seem to really communicate this well. Maybe it's just called 'border`?

[sarahill]

Thoughts based on some patterns I'm seeing... this isn't perfect but just throwing it out there as a conversation point:

Use 1:1 if it doesn’t relate to size:
--p-duration-100 = 100ms
--p-z-100 = z-index: 100;
--p-border-width-4 = .25rem / 4px

Use a multiplier of 4 when it relates to size:
--p-border-radius-4 = 16px / 1rem
--p-space-4 = 16px / 1rem
--p-font-line-height-4 = 16px

Breaks logic:

• --p-font-size-100 = 14px (so no multiplier)

Potential solutions:

• --p-font-size-400 (4x4=16px), --p-font-size-350 (3.5*4=14px), etc.
• --p-font-size-4, --p-font-size-base (14px), --p-font-size-3 (12px)
• --p-font-size-base, --p-font-size-sm, --p-font-size-xs - does this get confusing when thinking about headingSm, headingMd, etc and how a tshirt size maps to a variant size?

[heyjoethomas]

I think we could simply use 100-900 when we are creating a simple scale. This is what color tokens are doing. 100-900 is just a scale of lightness but the actual lightness values are not being communicated. Just that 300 has more contrast than 100. So we then end up with 3 different patterns here:

1. Literal: --p-duration-100 = 100ms --p-z-100 = z-index: 100; --p-border-width-4 = .25rem / 4px although 4px is really a size so maybe that goes to the next category
2. Multiplier: --p-space-4 = 16px since 4x4
3. Scale: '--p-font-size-100' --p-blue-800

I don't think there is a one size fits all approach here. Then maybe t-shirt sizing is used for compound things such as type styles or shadows that mix both color and elevation. Seems like it may be a little messy no matter how we slice it.

[sam-b-rose]

Challenging thought, what if they where all scales {0-9} or similar 📏 🤔

Curious if the token naming convention is too tightly tied to the value, then the token seems less relevant other than that it is an "allowed" or guideline value (ex: --p-duration-100 exits because we allow 100ms). When styling, when would using --p-duration-100 over 100ms be more useful if that value will always be 100ms due to the naming.

Proposed scaled example

Took this from Open Props 😅 but I feel like it would be a simple base token system to then abstract semantic theming over in the future.

Color

--p-gray-{0-9}
--p-red-{0-9}
--p-blue-{0-9}
...

Font

--p-font-size-{00-9}     // 1 is the base of 1rem
--p-font-weight-{1-9}    // 1 = 100, 2 == 200, etc
--p-line-height-{00-5}   // 1 is the base of 1.25 
...

Transitions

--p-duration-{0-5}
--p-ease-{1-5}
...

Sizes

No px here, relative units all the way. 0s are unsafe but common negative values, while 1-N are safe.

--size-{000-15}
--size-fluid-{1-10}
--size-content-{1-3}
--size-header-{1-3}

Z Index

--layer-{1-5}
--layer-important: 2147483647;   // helps "prevent" z-index battles by setting a standard maximum

[heyjoethomas]

I think the one that suffers the most here is spacing. I think having multiplier values in spacing actually makes a good amount of sense. I think everything else would work with this approach. Now you have me thinking lol.

[sam-b-rose]

I hear you. We can make the value a multiplier if we'd like, but the scale part is what I find nice. No gaps in the values (ex: there is a --p-size-4 but then it skips to --p-size-8... that would throw me off)

This is the values open props uses, but we could adjust according to our own needs:

--size-000: -.5rem;
--size-00: -.25rem;
--size-1: .25rem;
--size-2: .5rem;
--size-3: 1rem;
--size-4: 1.25rem;
--size-5: 1.5rem;
--size-6: 1.75rem;
--size-7: 2rem;
--size-8: 3rem;
--size-9: 4rem;
--size-10: 5rem;
--size-11: 7.5rem;
--size-12: 10rem;
--size-13: 15rem;
--size-14: 20rem;
--size-15: 30rem;