Author a custom theme

Use this when the bundled light and dark themes don't fit your brand and you need to ship a third one: global, dark-mode, or user-selectable.

1. Decide how the theme activates

The factory mixin supports three triggers, used alone or together:

  • $is-default: true: emits unconditionally on :root. Pick this for the one theme that's always-on.
  • $root-when: 'prefers-color-scheme: dark': emits inside a @media query. Pick this for OS-driven dark mode.
  • $modifier-class: '.theme-sunset': emits under that selector. Pick this for explicit user overrides.

The bundled dark.scss uses both $root-when and $modifier-class so OS preference and a manual toggle both work.

2. Write the theme file

Create a SCSS file under your theme directory of choice. Pass a $variables map of scalar tokens keyed by short-name (the factory adds the --kc- prefix), plus a $combinations map of (bg, fg) tuples — one per entry in $color-combinations.

// src/theme/sunset.scss
@use '../variables';
@use 'create';

$variables: (
  bg:            #1b0f17,
  fg:            #f7e9d7,
  link:          #f26b1d,
  link-hover:    #ffb27a,
  border-radius: variables.$global-border-radius,
  card-bg:       #2a1822,
  card-fg:       #f7e9d7,
  focus-ring:    #f26b1d,
) !default;

$combinations: (
  default: (#2a1822, #f7e9d7),
  primary: (#f26b1d, #1b0f17),
  warning: (#ecf241, #1b0f17),
  danger:  (#c0392b, #fff),
  success: (#6b7530, #f4f6e6),
) !default;

@include create.theme(
  $name: 'sunset',
  $variables: $variables,
  $combinations: $combinations,
  $is-default: false,
  $modifier-class: '.theme-sunset',
);

To override only a couple of combinations and inherit the rest of the default palette, merge over variables.$color-combinations:

$combinations: map.merge(
  variables.$color-combinations,
  (primary: (#f26b1d, #1b0f17), warning: (#ecf241, #1b0f17)),
);

3. Wire it into your stylesheet

Use the forwards-only entry (which skips the bundled themes), then @use exactly the themes you want emitted:

// app.scss: bring your own theme
@use '@adnap/krysalicss';
@use './theme/sunset';     // emits .theme-sunset { --kc-* } block

4. Activate at runtime

For class-modifier themes, toggle the class on <html>:

<script>
  const root = document.documentElement;
  const saved = localStorage.getItem('theme');
  if (saved) root.classList.add('theme-' + saved);

  document.querySelector('#theme-sunset').addEventListener('click', () => {
    root.classList.remove('theme-dark');
    root.classList.add('theme-sunset');
    localStorage.setItem('theme', 'sunset');
  });
</script>