Skip to content

Theming ​

The library's CSS custom properties follow a surface-layer taxonomy. Each token points to a concrete visual layer, not to a specific component: if you override a layer, every component that uses it updates together.

Layers ​

LayerTokenVisual role
base--bgapp background, empty inputs
intermediate--bg-althover / pressed
elevated--bg-elevatedmodals, dropdowns, popovers
panel--bg-panelcards, accordions, side panels
border--bordersurface outlines
text--text / --text-mutedprimary / secondary text
accent--accenthover and selection
palette--color-primary …--color-dark9 semantic colors (Catppuccin)
typography--font-monomonospace stack
motion--cp-ease / --cp-ease-snapeasing curves

Example — sepia theme ​

css
1.sepia-card {2  --bg-panel: #fffaf0;3  --border: #c9a87c;4  --text: #3a2a1a;5  --color-primary: #8b4513;6}

It works because the card uses var(--bg-panel) for its background, var(--border) for its border, var(--text) for the text color, and var(--color-primary) for its accents. All those var() calls live in the component's scoped CSS and receive the normal cascade.

When to change one thing vs the whole theme ​

Change one thing when you want to adjust a specific detail:

css
1.my-section {2  --bg-elevated: #1e1e2e;   /* only changes modals */3}

That touches one variable. Only what uses it changes; the rest stays the same.

Change the whole theme when you want a new look from scratch (e.g. dark mode). Override the variables in :root:

css
1:root {2  --bg: #1e1e2e;3  --bg-alt: #2a2a3a;4  --bg-elevated: #333344;5  --bg-panel: #2d2d3d;6  --text: #e0e0e8;7  --text-muted: #a0a0b0;8  --border: #444455;9  --color-primary: #cba6f7;10  /* ... */11}

That replaces the whole theme of your app in one go.

How it's applied per component ​

Each component page has its own ## CSS Custom Properties section with the table of tokens that particular component uses, its actual default, and a short description. The layer is the same; the list is per component.

API conventions (props and slots) ​

Each content area of a component follows one of three patterns, chosen by what makes semantic sense. The rule makes the API predictable: if you know the pattern, you know how to invoke the component.

1. Replaceable content (prop + slot, slot wins) ​

Areas like the title, description, header, or footer of a card that accept plain text as a default value and rich markup when needed.

vue
1<h3 class="card-title">2  <slot name="title">{{ title }}</slot>3</h3>

Use:

vue
1<Card title="Plain" />                                  <!-- prop only -->2<Card><template #title>★ <em>rich</em></template></Card> <!-- slot only -->3<Card title="Fell"><template #title>Rich</template></Card> <!-- slot overrides prop -->

Rule: the slot wins. The prop is the fallback rendered when the slot is empty.

Components using this pattern: Card (title, description, header, footer), Modal (title, footer), Box (header, footer), Panel (header, footer), TreeNode (label), StatusBar (info).

2. Optional content (slot only, conditional render) ​

Areas like a footer of actions or an extra header block that do not have a reasonable default value — if there is no slot, the block is not rendered.

vue
1<footer v-if="$slots.footer" class="card-foot">2  <slot name="footer" />3</footer>

Use:

vue
1<Card><template #footer><Button>OK</Button></template></Card>2<!-- without a slot, the block does not appear -->

Components using this pattern: none in the current version — every area that used to be slot-only migrated to pattern 1 in LBDS-285. If you add a new area in the future, use this pattern when there is no reasonable default.

3. Visual / styling (prop only) ​

Colors, shadows, borders, typography variants. Slots do not make sense here because you want to apply a scalar value (an enum, a boolean), not markup.

vue
1<button :class="`color-${color}`">Click</button>

Use:

vue
1<Button color="primary" fill="solid" :border="false" />

Rule: if the only sensible value is a scalar, it is prop-only. Do not add a slot.

Components using this pattern: every visual boolean/enum (color, border, shadow, design, fill, icon, size, etc.) on any component.

How to choose between the three ​

  • Does a one-line default text value make sense? → Pattern 1 (prop + slot).
  • No reasonable default and the area is purely "extra"? → Pattern 2 (slot only).
  • Is it a scalar value that is not text? → Pattern 3 (prop only).