Styleguide dependancies on tokens

[Riaan-ZA]

I'm having a bit of a problem in that there are styles in the styleguide that are dependant on tokens set for the normal front end. For example, there are colors set in src/tokens/color.yml eg color_silver which break the site if you remove them, because those variables are being used in the docs eg /docs/components/tokens/Color.vue

Not sure if I'm doing something wrong, but this doesn't seem like good behaviour to me

[arielsalminen]

@PlatinumSeed Sorry to hear you’re having troubles using the tool. First of all, I don’t think you’re doing anything wrong. The documentation does use tokens from the design system and if you change the names you currently have to change the names used in the docs as well.

While I don’t really want to stop using design tokens in the docs (as you’d lose both the ability to theme docs and the connection to design system itself), I do understand the issue you’re having and I think this functionality can be improved.

I’m suggesting introducing Sass !default values for all design tokens inside docs. So for example docs.styles.scss could have something this defined:

$color-white: #fff !default;
$color-rich-black: #000 !default;
// etc…

These defaults would only get used in case the global tokens aren’t already assigned. What do you think about this kind of approach?

The benefit of this would be that you could tweak the tokens in the design system and app side how you like and the docs wouldn’t break while doing this (they would just switch on to using Vue Design System’s default values).

[Riaan-ZA]

@viljamis Well personally first choice for me would be to keep theming of the docs completely separate from the design system, but I can appreciate that there are other requirements and use cases to take into account. Your solution makes sense though and would solve my problem.

I did have a look and there doesn't seem to be a global scss file under docs that gets loaded before everything else. I had to add $color-white: #fff !default; to docs/styleguide.styles.scss as well as in /docs/components/tokens.All.vue before it would work

[arielsalminen]

@PlatinumSeed I understand. If I can open up my thinking a little bit:

The reasoning behind this comes from my experience working with clients’ design systems where the case more or less always has been that they’ve wanted the public facing docs/style guide to use the same design tokens as their other websites and products. I think this makes a lot of sense if you’re building “a central source of truth for design & dev” anyway, but I agree that it might slow things down in the beginning too much. Especially if you’re immediately required to start touching the style guides base styles as well.

Let me think through this and propose a few changes/improvements in the form of a pull request later on this week.

[ryanberg]

@viljamis

the case more or less always has been that they’ve wanted the public facing docs/style guide to use the same design tokens as their other websites and products. I think this makes a lot of sense if you’re building “a central source of truth for design & dev” anyway, but I agree that it might slow things down in the beginning too much. Especially if you’re immediately required to start touching the style guides base styles as well.

That has definitely been the case for me over the last week. I've been replacing many of the current tokens (for font size and spacing so far, about to start with colors as well) with the names/values that we'll be using. Using find/replace has made updating the scss and any other references a little less tedious.

I've found it helpful to make more use of the "LOCAL TOKENS" section in docs.styles.scss. So instead of:

div[class^="rsg--wrapper"] > h1[class^="rsg--heading"] a {
  color: $color-oxford-blue;
}

specify a local token, then reference below:

$docs-color-heading: $color-oxford-blue;

div[class^="rsg--wrapper"] > h1[class^="rsg--heading"] a {
  color: $docs-color-heading;
}

Then once I have our customized color palette established, I'll have one easy place to update.

Perhaps it'd be appropriate to go one step further and manage these in a docs.yml tokens file.

[arielsalminen]

Fixed in 2.1.3 which adds local defaults for global tokens (for docs/style guide).