I'm struggling with setting up the library

[angelikatyborska]

I am trying to add bitstyles to a new project without changing any configuration. It is difficult.

I would like to just write:

@use '~bitstyles/scss/bitstyles';

and be able to use the library without any configuration but that's not possible.

Here are my problems:

1. The library tries to load custom font files

The first errors I see is this (truncated):

✘ [ERROR] Could not resolve "../assets/fonts/poppins-v20-latin-400.woff2"

    css/app.scss:749:11:
      749 │   src: url("../assets/fonts/poppins-v20-latin-400.woff2") format(...
          ╵            ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

✘ [ERROR] Could not resolve "../assets/fonts/poppins-v20-latin-400.woff"

    css/app.scss:749:79:
      749 │ ...f2"), url("../assets/fonts/poppins-v20-latin-400.woff") format...
          ╵              ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

etc...

The instructions on https://bitcrowd.github.io/bitstyles/?path=/story/introduction-getting-started--page do not mention that I need to do to anything special to make fonts work. They mention:

You may need to provide your sass installation with the path for bitstyles’ sass. This should be:

But doing that does not resolve the font problems.

I don't want to have any fancy fonts at this stage of the project, I would be happy with a basic system-built in font. So I would like to overwrite the bitstyles config and not have to provide any custom font files.

2. Customization examples from docs doesn't work

When I want to start customizing the bitstyles config to change the font, I copy-paste this example from https://bitcrowd.github.io/bitstyles/?path=/story/introduction-getting-started--page :

@use '~bitstyles/scss/bitstyles/settings';
@use '~bitstyles/scss/bitstyles/design-tokens' with (
  $color-palette-text: #fff,
  $layout-size-base: 1.2rem
  /* lots of other options here */
);
@use '~bitstyles/scss/bitstyles/generic';
@use '~bitstyles/scss/bitstyles/base';
@use '~bitstyles/scss/bitstyles/atoms';
@use '~bitstyles/scss/bitstyles/organisms';
@use '~bitstyles/scss/bitstyles/utilities' with (
  $margin-breakpoints: (
    'l',
    'l3',
  )
);

This example gives me this error:

✘ [ERROR] Can't find stylesheet to import.
  ╷
2 │ ┌ @use '~bitstyles/scss/bitstyles/design-tokens' with (
3 │ │   $color-palette-text: #fff,
4 │ │   $layout-size-base: 1.2rem
5 │ │   /* lots of other options here */
6 │ │ );
  │ └─^
  ╵
  - 2:1  root stylesheet [plugin sass-plugin]

1 error
[watch] build finished, watching for changes...

I can figure out by looking at the source code that there are two main design-token files, "primary" and "secondary" so I change it to:

@use '~bitstyles/scss/bitstyles/settings';
@use '~bitstyles/scss/bitstyles/design-tokens/primary' with (
  $color-palette-text: #fff,
  $layout-size-base: 1.2rem
  /* lots of other options here */
);
@use '~bitstyles/scss/bitstyles/design-tokens/secondary';
@use '~bitstyles/scss/bitstyles/generic';
@use '~bitstyles/scss/bitstyles/base';
@use '~bitstyles/scss/bitstyles/atoms';
@use '~bitstyles/scss/bitstyles/organisms';
@use '~bitstyles/scss/bitstyles/utilities' with (
  $margin-breakpoints: (
    'l',
    'l3',
  )
);

Which then produces a new error:

✘ [ERROR] This variable was not declared with !default in the @used module.
  ╷
3 │   $color-palette-text: #fff,
  │   ^^^^^^^^^^^^^^^^^^^^^^^^^
  ╵
  - 3:3  root stylesheet [plugin sass-plugin]

So I remove that variable from the file, which then produces this error:

✘ [ERROR] "Oops! Breakpoint ‘l3’ does not exist."
   ╷
63 │     @include media-query.get($breakpoint) {
   │     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   ╵
  node_modules/bitstyles/scss/bitstyles/tools/_properties.scss 63:5       output-directional()
  node_modules/bitstyles/scss/bitstyles/utilities/margin/_index.scss 6:1  @forward
  node_modules/bitstyles/scss/bitstyles/utilities/_index.scss 24:1        @use
  - 8:1                                                                   root stylesheet [plugin sass-plugin]

Which leaves me with this code with no overriding any variables:

@use '~bitstyles/scss/bitstyles/settings';
@use '~bitstyles/scss/bitstyles/design-tokens/primary';
@use '~bitstyles/scss/bitstyles/design-tokens/secondary';
@use '~bitstyles/scss/bitstyles/generic';
@use '~bitstyles/scss/bitstyles/base';
@use '~bitstyles/scss/bitstyles/atoms';
@use '~bitstyles/scss/bitstyles/organisms';
@use '~bitstyles/scss/bitstyles/utilities';

3. How exactly do I customize bitstyles to stop importing a font file?

I had to read the source code to know that I can override $webfont-family-name to change thedefault font family and $webfont-variants to an empty array to stop any font files from getting imported. At first I tried to do:

@use '~bitstyles/scss/bitstyles/design-tokens/primary' with (
  $webfont-family-name: 'Arial',
  $webfont-variants: (),
);

Which doesn't work. I am forced to copy-paste the whole "primary" file into my bitstyles configuration in order to overwrite the fonts.

TL;DR: the simplest bitstyles configuration that compiles for me was this:

// bitstyles/scss/bitstyles.scss split into parts:
@use '~bitstyles/scss/bitstyles/settings';

// bitstyles/scss/bitstyles/design-tokens/primary.scss split into parts:
@use '~bitstyles/scss/bitstyles/design-tokens/animation';
@use '~bitstyles/scss/bitstyles/design-tokens/base-colors';
@use '~bitstyles/scss/bitstyles/design-tokens/base-palette';
@use '~bitstyles/scss/bitstyles/design-tokens/breakpoints';
@use '~bitstyles/scss/bitstyles/design-tokens/color-palette';
@use '~bitstyles/scss/bitstyles/design-tokens/layout';
@use '~bitstyles/scss/bitstyles/design-tokens/shadows';
@use '~bitstyles/scss/bitstyles/design-tokens/typography' with (
  $webfont-family-name: 'Arial',
  $webfont-variants: (),
);

@use '~bitstyles/scss/bitstyles/design-tokens/secondary';
@use '~bitstyles/scss/bitstyles/generic';
@use '~bitstyles/scss/bitstyles/base';
@use '~bitstyles/scss/bitstyles/atoms';
@use '~bitstyles/scss/bitstyles/organisms';
@use '~bitstyles/scss/bitstyles/utilities';

This process is not really obvious. It would be great to have public docs explaining how to approach creating config overrides.

[planktonic]

Thanks for taking notes! 🙏

Yes some of the process can be painful still, sorry for that. It’s clear we’ve never quite struck the right balance for the use cases we’re trying to cover. I think many issues come from just a few sources (probably there are more!):

• There’s conflict between giving a simple start with useful defaults, and providing a totally customizable design system and component library.
• Managing Sass variables and making them overridable when using Sass modules is convoluted and hard.
• Assets like fonts & icons are difficult to provide, because when you build the Sass in a project such things are filesystem and build system dependent.
• We only have one configuration. It’s used for every new project, testing, and the internal storybook. Perhaps multiple configs could help cover usecases with fewer headaches

Taking your issues one by one here, let me know what you think:

1. The library tries to load custom font files

A description of what is currently needed to get the build green should at least be added to the documentation.

We want a custom font to applied consistently for some projects such as admin interfaces — those ideally all have matching branding by default — and to the storybook here. Ideally I think the out-of-the-box results should match what’s shown in our storybook, anything else I would find confusing.

For many projects (the public-facing apps, mainly) changing the webfoot is the first thing that’s done — that’s very much part of the initial setup, along with all the other design tokens. But that doesn’t mean we should be proscriptive and require that of course.

• Perhaps the path to the webfonts can be handled better, so that it works on a clean install
• Readme should be updated so at the end of the installation process, the build works
• is this the right repo to apply/provide a webfont, or should that be done elsewhere?

2. Customization examples from docs doesn't work

Yes, simplest case would be that we update any references to importing design-tokens directly, and break it into the primary & secondary layers.

It is possible to use the current single import, but it means knowing Sass modules (or we add it to our documentation so that users know about it). Each module in Sass adds its own name to the variable that it forwards/exports. So your example from number 3, which didn’t work for you:

@use '~bitstyles/scss/bitstyles/design-tokens/primary' with (
  $webfont-family-name: 'Arial',
  $webfont-variants: (),
);

It didn’t work because each of the modules that are forwarded by primary add their name to the start of the variable name. So this would work:

@use '~bitstyles/scss/bitstyles/design-tokens/primary' with (
  $typography-webfont-family-name: 'Arial',
  $typography-webfont-variants: (),
);

That’s because the Sass module forwarded by design-tokens/primary is called typography. I don’t think it’s the job of bitstyles to teach how Sass modules works, but clearly there should be more documentation on this — perhaps a very reduced subset of possibilities that we can suggest as good methods of configuration.

I had to read the source code to know that I can override $webfont-family-name to change thedefault font family and $webfont-variants to an empty array to stop any font files from getting imported.

Those variables are covered in Design Tokens/Typography/Overview, but there’s no explicit mention that you can set them to empty string & list to avoid fonts. That seems like a common enough use that we should add that to the docs there 👍

---

I’ll have to come back and finish off tomorrow, I hope that’s ok :)

[planktonic]

Continued…

✘ [ERROR] Can't find stylesheet to import.

@use '~bitstyles/scss/bitstyles/design-tokens' with

// ...

This error could also be fixed if we added a default import file i.e. design-tokens/_index.scss that @forwards the primary and secondary files. It could be convenient in some cases, and would mean the variables in both those imports could still be overridden by prepending primary or secondary to the variable name (see previous comment on how sass modules exposes variables). But we would still need to fix the documentation to show a working method, so maybe not useful, just a thought.

✘ [ERROR] "Oops! Breakpoint ‘l3’ does not exist."
   ╷
63 │     @include media-query.get($breakpoint) {

This is a bug that was introduced when changing the naming of the spacing scale — there is no breakpoint l3, it’s xl

I think the final remaining problem you described is another example of out-of-date documentation:

@use '~bitstyles/scss/bitstyles/design-tokens/primary' with (
  $color-palette-text: #fff,
  $layout-size-base: 1.2rem
  /* lots of other options here */
);

✘ [ERROR] This variable was not declared with !default in the @used module.
  ╷
3 │   $color-palette-text: #fff,
  │   ^^^^^^^^^^^^^^^^^^^^^^^^^

The error is correct, and this isn’t a case of needing to add a module-name prefix, the variable doesn’t exist. Text color and background-color are now handled in the default theme. I would suggest updating the example in the documentation to override a different variable from the base design tokens would be the best solution.

---

There’s a lot here to cover, but I think many of these issues can be fixed with a couple of changes (a couple of PRs, at least). Feedback and thoughts on all this are totally welcome — I would prefer to do this slowly and correctly rather than rush to make changes. Your input on any changes to the documentation would also be great, to make sure it’s clear and doesn’t assume too much domain knowledge.