Better theming support

[davestewart]

Problem

Having done the (initial) hierarchical sidebar, I've been thinking about the best way to override styles.

My personal feeling is that folks are not going to want to heavily (or granularly) restyle the app, as long as it's fairly neutral and lets them work easily with their components.

As such, the current approach of creating and overriding CSS variables seems like an increasing maintenance burden and a constraint on any styling implementation.

Proposal

In Histoire, every component had a class name we could target, and it worked well.

So I propose two things going forwards:

Targetable classes

In the hierarchy branch, I added bt--prefixed classes to all Nav* elements:

bt-nav-root

bt-nav-folder
bt-nav-folder-title
bt-nav-folder-container

bt-nav-item
bt-nav-item-link
bt-nav-item-title
bt-nav-item-variants

bt-active
bt-icon

It's:

• easy to read and write
• unlikely to clash with user stories
• would be a simple way for users to target bedtime-specific styles

Resets and overrides

And the nice thing about moving away from variables is you basically design so that a user can modify any property, or even reset all properties for targeted elements using the all property:

// override root, or any child
.bt-nav-root *:not(svg) {
  all: revert-layer; // there are various options here; see link
}

// target elements
.bt-nav-root .bt-nav-folder-title {
  color: red;
}


// increase specificity (if needed)
.bt-nav-root .bt-nav-folder .bt-nav-item-variants {
  color: blue;
}

Before:

After:

Going in this direction would eliminate the need to maintain an ever-increasing list of variables, and would let anyone override or replace any styling decision.

[timhanlon]

Yeah, the CSS variables were the "least worst" option I could think of to ship something quickly without a Tailwind dep, I'm not attached to them at all.

Things to keep in mind:

1. There's Tailwind Variants slots on the Story/Variant components (see: Story.vue) which would, ideally, be on everything, with sane defaults available
2. It'd be good to have a cleaner way to opt-out of the default CSS

[davestewart]

I had a thought this morning about theming, based on how VuePress works with ejecting its theme.

As I understand variants (for stories and variants only) are configured in runtime config, so is effectively a) CSS in JS and b) Tailwind-only.

This is in addition to:

• a raft of CSS variables
• the option to override CSS rules anyway
• initial support for "theming" via runtime config and custom CSS

The problem as I see it is we now have 4 ways to apply styles, and the theming override [data-bedtime-theme] introduces specificity issues with classes that want to override the base theme.

Something that would fix all of this would be

• a single CSS file with rules and base variables for things like theme colors
• which could be "ejected" from the module and edited in any consuming project
• and could either replace or augment the core stylesheet

So, something like:

bedtime eject-theme src/assets

Provides this stylesheet:

/* theme */
:root {
    --bt-text: #222;
    --bt-bg: #FFF;
    --bt-item-bg: #AAA;
    ...
}

@media (prefers-color-scheme: dark) {
    :root {
        ...
    }
}

/* sidebar */
.bt-sidebar { ... }
.bt-sidebar-container { ... }
.bt-sidebar-options { ... }
...

/* nav */
.bt-nav { ... }
...

/* main */
.bt-main { ... }
...

/* stories */
.bt-story { .. }
...

/* variants */
.bt-variant { .. }
...

Which:

• has everything in one place
• provides rules for all elements (can delete if not using)
• has much simplified variables (color only)
• has no specificity issues
• is fully-customisable

Runtime config is super simple too:

export default defineNuxtConfig({
  extends: layers.extends(),
  modules: ['nuxt-bedtime'],
  bedtime: {
    theme: {
      stylesheet: '/bedtime.css', // or maybe `false` and they just compile as part of the app?
      replace: true,
    }
  },
})

We would need to move all component styles to a single stylesheet, but that would be good as well, as it would:

• enforce logical component naming
• show the user in one place what our component structure looks like

Thoughts?

[timhanlon]

As I understand variants (for stories and variants only) are configured in runtime config

They can be passed directly into the Story/Variant components using the classes prop as well, which could no doubt be renamed to something better.

I'd like the Tailwind Variants slots to stick around, I think the escape hatch of being able to use the Story/Variant components with a completely custom viewer UI is worth keeping.

Everything else looks sound, thanks.