Design Tokens: Early Feedback

[ghost]

Hi there!

To make Clay more flexible and help components to be themed easily while avoiding initiatives such as Dialect and Stylebooks to build their own components (by repeating the current Lexicon/Clay workstream, multiplying redundancy, and increasing the technical / design debt).

The Lexicon team has built a taxonomy and nomenclature model for Design Tokens to create variables that respond to the required design logic, ordering and reducing the number of variables that currently exist and bringing the positions between product teams and development closer. This model aims to be a standard that helps facilitate communication between teams.

In LEXI-1204, you will find a high-level description of the purpose of the proposal. To begin with, we need to replace the color variables that currently exist with the variables that would respond to the color/interaction logic that we require.

The main goal is to change the current model where we paint components by following a series depending on the creator criteria and interpreted to be introduced in the system depending on the front-end team criteria for a model where we apply each color according to a guide. This guide is outlined in the name of the color token, responding to color/interaction logic with less room for doubt and design/technical debt.

Now that the variables addressed by this initiative will be able to store changing values, we need a better naming convention. The new tokens definition meets design needs and the goal for them is to be introduced into the system according to the following taxonomy groups.

(Keep in mind that at the moment, this is only for color, but other tokens such as typography, icons, spacing, border-radius, elevation, etc. will follow a similar logic.)

So far, we've managed to encapsulate the current color logic in a small number of Design Tokens that we think are easily identifiable. Initiatives such as Stylebooks and Dialect, which plan to customize these values with a different and broader logic, will create and group new variables for their customization purposes by following the proposed model, keeping the system clean until there is an agreement on the use of these variables overrides.

Above these local tokens, our intention is to batch changes to be made over several instances from global tokens. You can read more about global and local tokens at Adobe Spectrum DSL, although all the information you will need is both in our own Research and kick off document, Lexicon Design Tokens File and Definition Document WIP.

Before our alignment and before building the final definition, could you review the proposal for color variables and comment on your doubts in the same files or this thread?

Thanks a lot.

cc. @liferay-lexicon @drakonux

[pat270]

Colors and State

From the CSS framework perspective, I would like to see the colors primary, secondary, danger, success, warning, info renamed to blue, gray, red, green, orange, navy or something that describes the color. The problem with combining colors and state is that changing them causes unexpected output in the framework.

Take secondary for example, in Lexicon it's a shade of gray. We have the habit of using $secondary to style things like text color. In Dialect, the secondary color is orange. If we change $secondary to orange, all our text is now orange. The state names should specifically saved for component state colors, like btn-secondary, alert-info, etc.

I would also like to see the number of shades for each color be the same. Why does secondary / neutral have so many shades, but primary /blue doesn't? Why does primary / blue have more shades than danger / red? States can have a smaller range of colors, but each state should have the same number of colors. It makes it so much easier to swap states on components.

Global Variables and Component Sizes (small and large)

It would be nice to have global variables like border-radius, font-size, box-shadow, spacer map to base component sizes like btn. The large and small versions would map to btn-lg and btn-sm, respectively. In my mind, if I change the global --border-radius token I assume the border-radius for all base components would change to that value.

The other idea (this one is better) is to remove the size namespace in global variables and just use a range like colors.

--border-radius-0: 0;
--border-radius-1: 4px;
--border-radius-2: 6px;
--border-radius-3: 8px;
--border-radius-4: 12px;
--border-radius-5: 16px;
--border-radius-6: 24px;
--border-radius-7: 50%;

You can use these values where ever and how ever you want. There is no confusion in the naming since we have no component like btn-5.

[pat270]

The main goal is to change the current model where we paint components by following a series depending on the creator criteria and interpreted to be introduced in the system depending on the front-end team criteria for a model where we apply each color according to a guide.

I didn't answer the question. You can change the current model to the model you want. I'm pretty sure Clay CSS can accept most of it. Whatever doesn't quite fit, we can tweak Clay CSS to accept it. The one thing we can't do is integrate the model directly into Clay CSS by renaming the variables or changing CSS classes and markup to adhere to Dialect's standards. The reason is that it's a ~major~ massive breaking change.

Even if we were to implement this change in 8.0, I still don't think it's a good idea. Liferay Portal has so much markup that we probably won't complete it until 10.0 😆 . We're still supporting markup from 10 years ago, each breaking iteration gives us more technical debt and makes upgrading from one version to another much harder.

If you want to understand how Clay CSS can work for you, I'll be happy to help.

[ghost]

Hey @pat270 , thanks for the quick reply; this way we will move faster with the definition.

Regarding the naming standard, we have studied the way to create groups of tokens (taxonomy) that respond to the same UI logic, to identify properties each one would be modifying quickly ( "--color-border-primary-default" affects first the token category: color, second the property: border, third: surface (not included yet, reserved to be Dialect/Stylebooks Theme override exceptions), and then the variants: primary-default).

Our goal is to provide a design tokens model for the design and development teams to know where each variable applies, considering any member is conscious of common interaction standards.

In other words, we are trying to align the different product and dev teams into standard naming rules to avoid continuing with the current work of interpretation that drives us to create more redundancies via design and technical debt.

Also, our (Lexicon) goal is to create the most significant number of general values ​​grouped in the fewer number of variables possible. Then, teams (Dialect/Stylebooks) would only need to create token exceptions that comply with a different logic than the offered by Lexicon (such as the Dialect and Stylebooks styles) as overrides.

We should start with the minimum number of variables we need (cleaning code in the process), order the (un)logic that currently exists, and create a scalable model that allows us to introduce new tokens in the future.

As long as there is an alignment above the different products, we could iterate by including exception-type tokens as general tokens into Lexicon/Clay.

To learn more about the proposed workflow, I think it would be best to start by reviewing the project's kick-off document we created, which I link here. And if you want to expand more knowledge about practices when generating design tokens, Amazon's Style Dictionary would be the key to understanding this model.

We have made an effort to adapt the maxims we aspire to have a viable model from the first iteration, so regarding the color gradients, we won't make changes at the moment because we do not want to alter the system until the new variable assignments have been implemented.

Our final goal is to leverage multi-theming starting from these initial variables. The secondary variable/token you refer to, which in Lexicon applies a shade value of gray, Dialect / Stylebooks should be able to change it to any color, depending on the brand/theme they are working on. We require to apply an interaction logic and a priority, not a color logic.

If we call the variables blue, red, green ... we would make it odd for those variables to contain a different value than the one mentioned, and when we aspire to change themes simply by modifying these values, this would not make much sense.

[pat270]

If I'm understanding correctly:

--color-text-button-primary-default
--color-text-button-primary-hover
--color-text-button-primary-focus
--color-text-button-primary-active
--color-text-button-primary-disabled

--color-background-button-primary-default
--color-background-button-primary-hover
--color-background-button-primary-focus
--color-background-button-primary-active
--color-background-button-primary-disabled

--color-border-button-primary-default
--color-border-button-primary-hover
--color-border-button-primary-focus
--color-border-button-primary-active
--color-border-button-primary-disabled

--color-box-shadow-button-primary-default
--color-box-shadow-button-primary-hover
--color-box-shadow-button-primary-focus
--color-box-shadow-button-primary-active
--color-box-shadow-button-primary-disabled

--color-text-button-secondary-default
--color-text-button-secondary-hover
--color-text-button-secondary-focus
--color-text-button-secondary-active
--color-text-button-secondary-disabled

--color-background-button-secondary-default
--color-background-button-secondary-hover
--color-background-button-secondary-focus
--color-background-button-secondary-active
--color-background-button-secondary-disabled

--color-border-button-secondary-default
--color-border-button-secondary-hover
--color-border-button-secondary-focus
--color-border-button-secondary-active
--color-border-button-secondary-disabled

--color-box-shadow-button-secondary-default
--color-box-shadow-button-secondary-hover
--color-box-shadow-button-secondary-focus
--color-box-shadow-button-secondary-active
--color-box-shadow-button-secondary-disabled

More complex component Card:

--color-text-card-default
--color-background-card-default
--color-border-card-default

--color-text-card-primary-default

--color-text-card-secondary-default

--color-text-card-link-primary-default
--color-text-card-link-primary-hover
--color-text-card-link-primary-focus
--color-text-card-link-primary-visited

--color-text-card-button-primary-default
--color-text-card-button-primary-hover
--color-text-card-button-primary-focus
--color-text-card-button-primary-active
--color-text-card-button-primary-disabled

--color-background-card-button-primary-default
--color-background-card-button-primary-hover
--color-background-card-button-primary-focus
--color-background-card-button-primary-active
--color-background-card-button-primary-disabled

--color-border-card-button-primary-default
--color-border-card-button-primary-hover
--color-border-card-button-primary-focus
--color-border-card-button-primary-active
--color-border-card-button-primary-disabled

--color-text-card-button-secondary-default
--color-text-card-button-secondary-hover
--color-text-card-button-secondary-focus
--color-text-card-button-secondary-active
--color-text-card-button-secondary-disabled

--color-background-card-button-secondary-default
--color-background-card-button-secondary-hover
--color-background-card-button-secondary-focus
--color-background-card-button-secondary-active
--color-background-card-button-secondary-disabled

--color-border-card-button-secondary-default
--color-border-card-button-secondary-hover
--color-border-card-button-secondary-focus
--color-border-card-button-secondary-active
--color-border-card-button-secondary-disabled

This will work, since the colors can be changed at the component level. Doing it this way, colors, state, global variables don't matter. This is exactly what Clay CSS does and the reason I am so confident about taking on Dialect's token model. I will be happy to plug this into Clay if this is what you want to do at the Liferay Portal theme level not inside this repo.

[marcoscv-work]

I just want to remember that the custom properties are not like the SASS variables. SASS variables do not add weight to the framework, they only exist during the build process, instead, doing an export of hundreds (potentially thousands) of custom properties would increase the weight considerably. Adding them "just in case someone wants to use them" is a bit too much haha, so yeah, my vote for adding this at Dialect/or theme level and deactivate parts if needed.

I think could be good to consider adding the most essential ones or a base of common custom properties in the theme and this base could be modified or extended at theme/design-pack/custom-stylebook level

I remember another critical topic we are fighting within frontend-infra is optimization, we should be really worried about the number of lines we are planning to add :-D

[victorvalle]

From my understanding, cases as complex as the one that @pat270 states here "--color-border-card-button-primary-default" would not exist. The button is defined at button level and the card needs one of several buttons.

I understand the point of view from @marcoscv-work , but do you have an estimated weight of that extra definition? it is just to support the argument. Of course, I would like to make the things as light as possible and maybe for that, we need to place some complexity in its right place.

[marcoscv-work]

We don't have an estimated weight to save or a specific limit. if something is needed will be there but a simple decision can make a big impact, for example, if we decide we can add buttons, we will re-write all the buttons, but if we decide to make buttons configurable for each component we will multiplicate the number of variables.

I think we could try to find out the minimal number of variables for the framework, in order to keep it simple and light, and then, the rest of super-specific variables could be added at the site/theme/stylebook level

[pat270]

@victorvalle my estimate for 1000 variables is around 40kb un-compressed. If the server sets up compression it should be a lot lower. 1000 variables should be ~7kb-10kb.

[ethib137]

From the CSS framework perspective, I would like to see the colors primary, secondary, danger, success, warning, info renamed to blue, gray, red, green, orange, navy or something that describes the color. The problem with combining colors and state is that changing them causes unexpected output in the framework.

Take secondary for example, in Lexicon it's a shade of gray. We have the habit of using $secondary to style things like text color. In Dialect, the secondary color is orange. If we change $secondary to orange, all our text is now orange. The state names should specifically saved for component state colors, like btn-secondary, alert-info, etc. -- @pat270

Our final goal is to leverage multi-theming starting from these initial variables. The secondary variable/token you refer to, which in Lexicon applies a shade value of gray, Dialect / Stylebooks should be able to change it to any color, depending on the brand/theme they are working on. We require to apply an interaction logic and a priority, not a color logic.

If we call the variables blue, red, green ... we would make it odd for those variables to contain a different value than the one mentioned, and when we aspire to change themes simply by modifying these values, this would not make much sense. -- @hold-shift

I really appreciate @pat270's example of the difficulty we have when we use $secondary to style text. I want to propose an alternative solution for the problem he raises. I don't think we need to rename the colors "primary, secondary, danger, success, warning, info", I think we need to add a color token layer at a higher level.

For the sake of reusability, it would be helpful to have a set of tokens whose names describe the color not the use: red, orange, yellow, green, blue, indigo, violet, neutral. Let's call these literal-color-tokens. At this layer of tokens it should be possible for customers to provide custom tokens when they need a color that we don't provide. This will be technically possible with "Design Packs", a new feature that echo is working on that will allow the contribution of frontend token definitions without needing to create a theme. I think this would handle @hold-shift's objection?

These literal-color-tokens would then be mapped to the other layers: primary=blue, secondary=neutral, danger=red, success=green, warning=orange, info=blue or (light-blue new color defined by customer). This will allow us to have a high degree of reusability and help us to avoid the issue @pat270 mentioned. For instance text can now use the neutral literal-color-token.

Another example of this is regarding the required reference mark on a form input label. We often style this using a red or an orange that is the same color as our color-warning or color-error tokens. But, this really isn't an error or warning state. We would be better off mapping it to an orange or red literal-color-token so as not to call something state related that isn't.

When applying a new theme to the tokens it would be possible to start at the highest level of abstraction and work down as necessary. First defining the token values for red, orange, yellow, green, blue, indigo, violet, neutral. Possibly creating some additional color tokens if the theme requires it. Then likely mapping those tokens to color-primary and color-secondary tokens. It often wouldn't be necessary to remap color-danger or other state based tokens since the literal-color associated with a state usually doesn't change. Then more specific mappings could be done to the components using the state-colors only when the usage calls for it and the literal-color-tokens when it's a branding choice or aesthetic choice.

Would this be helpful? What issues or drawbacks might it have?

[matuzalemsteles]

Having literal color tokens can make feeling like a "ready to use" color pack as a rule of thumb not to change the literal color to another one but just changing the shades of blue for example might make sense. I think the biggest downside is just the nested token codependencies and maybe a slight increase in the number of tokens.

I really like the idea of starting with global tokens that are reflected in components, changing spacing or font-size for example in global, seems to achieve a certain visual symmetry as opposed to defining specific tokens for each component, I think the biggest problem is what level of granularity we will reach. Starting with globals and then defining the specifics seems to be a great strategy to know what we need to deliver at the component level unless we are already sure they will be needed.

I'm still wondering if this should only live on DXP/theme, couldn't this live on Clay? what problems would we have, I don't necessarily want us to change everything but we would do the same as we do in theme but only here, available inside a sass file for example.

[pat270]

@matuzalemsteles This could live in Clay, it just has to be generic and extendable enough to satisfy designers. We would need to clearly document that these color variables only exist to enforce consistent color values across the framework.

On the other hand, completely removing colors from Clay is pretty enticing. This gives designers and developers complete freedom in choosing color palettes and variable names for their theme. What I mean is that we would remove $gray, $white, $black, $blue, $red, etc and replace uses of $gray-900 with #212529 or a $generic-text-color variable. Theme designers/developers can create their color palette and variables without unknowingly changing a color somewhere in the framework.

The only place in Clay where that would happen globally is through $primary, $secondary, ..., $dark states. These variables are descriptive enough to communicate that changing these will ripple through all the components.

[marcoscv-work]

I personally think that if the product strategy is that we are going to orient the design edition to the token modification interface, what really matters is the name of the tokens themselves and not how they work or the technical name we decide to use in development layers. Don't misunderstand me, it is important but I think we don't need to rename everything just because we are trying to add an extra tokens layer.

Literal names can be a good option for final users and the "ready to use" concept so probably that can be applied there, in the final interface :-P

[drakonux]

Hey guys,

Officially, I take Ruben's task from now. I would like to close the first iteration next week.

Thanks for your feedback here in the thread and in the definition document, I really appreciate it 💓.

I talked with the Dialect team, echo-team, and some of you, and I would like to share some thoughts and decisions I would like to take:

Naming Going with pure agnostic naming will cause problems for front-end developers and designers because they will have to review twice what they would like to do. So, in my opinion, the best option is to choose a hybrid solution. Therefore we will change the naming, trying a more usable approach.

Besides, @pat270 pointed out that Clay custom properties would live together with SASS variables. So, our clients and support team would not appreciate inconsistencies between both, so we should try to name as similar as possible with the current Clay naming.

Component Custom Properties If we create new 1000 variables, that decision potentially could impact the experience using the UI of DXP Stylebooks when a user tries to map a property with a token, overall if they finally decide to expose all the tokens we have.

Our goal here must be to provide the infrastructure for DXP to decide if they expose component properties using stylebooks.

Do we need to create a custom property for each exposed property of a component? For example, as a DXP user, I would like to change the value of a property set with a hardcoded value o a mapped value. Further on, I will decide to break the mapping or tokenize a hardcoded value if I want, but I don't need a choosable token of that property.

Look out! from my non-technical view (and talking with @pat270), if we create in Clay something like this:

.card {
--background-color: var(--color-secondary-00, #fff);
--border-radius: var(--border-radius-01, 4px);
--border-color: var(--color-secondary-02, #F00);
--border-width: var(--border-size-01, 1px);

background-color: var(--background-color);
border-radius: var(--border-radius);
border-color: var(---border-color)
border-width: var(--border-style);
}

We would have generic custom properties defined within each component and mapped with global custom properties.

Colors Following the previous reasoning, I've removed the background, text, and border colors because they would be mapped with the global color tokens. So, in the end, they are global tokens just used in a property. Besides, we have neither a need from DXP to wrap all those properties to be exposed.

About literal colors, yes, Clay keeps bootstrap colors ($blue, $red, etc.), but we are not defining them in Clay. Since they have no impact on components, could be something we could rely on the theme layer. For example, allowing Dialect and Classic to provide a wide color range of tokens by default.

If we finally decide to add Lexicon chart colors as new custom properties, they should be named agnostic because a client could choose to not use the default values we proposed because, for example, they would like to have a range of red colors for their charts instead so $blue would be set with a red color which doesn't make sense.

Tooling FYI. One of the requests will be to create a tool to allow users to play with the tokens and theme Clay as you made time ago @pat270

Typography For now, we will go with the same decisions Clay currently has. But we need to study responsive typography and type scale, Abel from Dialect will explore what should be interesting to have in the short term.

Reasoning section I've added a QA section within the definition document to write down questions we are continuously answering. Please be my guest to add more information there or things you would like to have clarified.

Delivery date of the doc I want to close the new definition document the following week on Thursday. After that, I will create a new request for the Clay team, and it would be great if you could work on PoC's and give us feedback to adjust definition details.

Thank you for your patience.

[pat270]

Look out! from my non-technical view (and talking with @pat270), if we create in Clay something like this: ... We would have generic custom properties defined within each component and mapped with global custom properties.

I'm going to clarify a little bit more so no one is confused:

DXP Theme's _clay_variables.scss

$card: (
    background-color: var(--background-color, #fff),
    border-radius: var(--border-radius, 4px),
    border-color: var(---border-color, #f00),
    border-width: var(--border-width, 1px),
);

clay.css will contain

.card {
    background-color: var(--background-color, #fff);
    border-radius: var(--border-radius, 4px);
    border-color: var(---border-color, #f00);
    border-width: var(--border-width, 1px);
}

When you change card tokens in Stylebooks, it needs to output

<style>
.card {
    --background-color: var(--color-secondary-00);
    --border-radius: var(--border-radius-01);
    --border-color: var(--color-secondary-02);
    --border-width: var(--border-size-01);
}
</style>

Edit: If this is something we would like to do, we need Team Echo's blessing. They will have to implement the last part 😺 .

Edit 2: I'd like to note that this pattern is not much different from overwriting CSS the traditional way. We aren't saving much space in terms of file size. The one benefit or downfall is that it will bypass CSS specificity. If we have two types of cards:

.card {
    background-color: var(--background-color, #fff);
    border-radius: var(--border-radius, 4px);
    border-color: var(--border-color, #222);
    border-width: var(--border-width, 1px);
}

.dark .card {
    background-color: var(--background-color, #222);
    border-radius: var(--border-radius, 4px);
    border-color: var(--border-color, #fff);
    border-width: var(--border-width, 2px);
}

and Stylebooks adds:

<style>
.card {
    --background-color: red;
    --border-radius: 0;
    --border-color: green;
    --border-width: 10px;
}
</style>

every .card will change.

[drakonux]

Sorry, this is the last time I write CSS, not my business bad idea 😞 . Thanks, Patrick.

At least, what I would like to clarify it's if we implement custom properties in Clay if the token-definition of the theme is going to redefine Clay custom properties and exposed on the UI or both of them (the ones the theme defines and exposes) and the ones Clay defines are going to be available to be mapped from the UI. I will try to explain this better next week.

cc\ @marcoscv-work

[pat270]

@drakonux you should keep writing, we are still trying to figure out the best way to go about this. It's better to hash everything out now than implementing something not thought out.

[drakonux]

Based on your feedback, we've changed the proposal to be more aligned with your needs. Please continue the discussion using the new request #4282

@brunofernandezg could you close this question, please?