Align Styles Package Structure and Documentation with Tokens?

[oliverschuerch]

The tokens package defines tree main output files for the component layer:

• elements.scss (contains sass maps for elments body, paragraph, etc.)
• components.scss (contains sass maps for components .accordion, .lead, .badge, etc.)
• utilities.scss (contains sass maps for utilities spacing, font-size, font-weight, etc.)

The first question we want to ask ourself is, if we should align the folder structure in the styles package accordingly?

styles/src/elements/body.scss
...
styles/src/components/tabs.scss
...
styles/src/utilities/spacing.scss
...

The second question is, if we should also align the navigation structure in the storybook documentation?

• elements/body
• ...
• components/accordion
• ...
• utilities/spacing
• ...

Please add your thoughts and make your choice below.

[gfellerph]

@oliverschuerch would you put CSS resets like the ones proposed under #3533 in one file or distribute them across different base element files?

[oliverschuerch]

I would like the approach to have them in different base element files.
So everything is where it belongs. It would also match with the tokens strategy.

[gfellerph]

This would create a bit of clutter

button {
  font: inherit;
}

input {
  font: inherit;
}

but that would be fine with me I guess. Then there'd only be the generic star selector (*) resets in a global resets file.

[oliverschuerch]

This would create a bit of clutter

button {
  font: inherit;
}

input {
  font: inherit;
}

but that would be fine with me I guess. Then there'd only be the generic star selector (*) resets in a global resets file.

Something like this would only be necessary on several elements, and this is what other reset css tools need to do as well.
But I would also not have a problem if something like font inheritance would be done in a general typo file, like:

// elements/typo.scss
*, *::before, *::after {
  fon-family: inherit;
  font-size: inherit;
  font-style: inherit;
  font-stretch: inherit;
  font-weight: inherit;
  font-variant: inherit;
  line-height: inherit;
  letter-spacing: inherit;
  color: inherit;
}

But we could also use a sass placeholder or a mixin to do this in every elements file, where it is necessary.

[oliverschuerch]

Beside this poll, we decided to align the styles package structure with the tokens.json output like so:

• elements
• components
• utilities
• shared

We want to co-locate styles, functions, mixins and placeholder, where they are used.
If something like this is used in multiple places, we move it to the folder shared/{functions|mixins|placeholders}.

The documentation package on the other side will be aligned with the Figma structure like so:

• Foundations
• Components
• Layout
• ...