Theming

[matheusps]

Shoreline theming

Context

The current theming structure has several problems that make it hard to manage and scale. This RFC proposes a simple solution for theming Shoreline.

Problems

No multiple themes

Managing multiple themes in the same package is impossible since the script only looks for a single shoreline.config.ts configuration file.

Separate bundle steps

Bundling and Theming happens in different scripts. First, we need the theme script - that generates the __shoreline__ folder. Then, we need PostCSS to import the generated tokens.css and bundle with the rest of the CSS.

Solution

Use a non-standard at-rule called @theme to define the tokens on a CSS file. So the definition:

@theme example {
  --space-1: 1rem;
  --space-2: 2rem;
  --space-3: 3rem;
  --space-gap: var(--space-1);
}

will convert to:

/* shoreline/styles.css */

@layer sl-tokens {
  :root {
    --sl-space-1: 1rem;
    --sl-space-2: 2rem;
    --sl-space-3: 3rem;
    --sl-space-gap: var(--sl-space-1);
  }
}

Pros

Build speed

LighningCSS is pretty fast in both transform and bundle. You can check the benchmarks here: https://github.com/parcel-bundler/lightningcss#benchmarks.

Multiple themes

You can bundle as many as themes as you can in a single build. It also does not create a dirty file tree with parcial builds. So, the theme sunrise and sunset could be created in the same build and/or file:

@theme sunrise {
  :where(html)[data-theme="sunrise"] {
   --bg-body: #fff;
  }
}

@theme sunset {
  :where(html)[data-theme="sunset"] {
    --bg-body: #000;
  }
}

No JS

There is no need of a .js config, any .css is enough.

Tradeoffs

@theme is a non-standard syntax

Non-standard syntaxes can have a bad IntelliSense in some editors. Additional plugins may be necessary of a truly premium developer experience.

References

• Tailwind v4 Alpha
• LightningCSS Custom Transforms