Getting started

Lit, Shadow DOM, and how to override styles

For deck authors who fear they must learn Lit: you write HTML, and this page shows the three ways to restyle a component without touching the framework.

Do I need to learn Lit?

No · a deck author never writes Lit. Lit is what we used to build the components. You write HTML tags such asdeck-cover, deck-feature, deck-code, and that is it. Lit is an implementation detail; you never write a class, never call a tagged template literal, never see a decorator.

You only meet Lit if you decide to write a component of your own, which means working from the TypeScript sources (seeContributing). Restyling what already ships is a different job and needs no Lit at all · the tokens inTheming cover it, and they work the same whether the deck loads the package from npm install rikiki-deck or from a copied folder. To write a deck, you stay in HTML-land.

What about Shadow DOM?

Every deck-* element renders inside its own Shadow DOM. That means the framework's internal CSS can't leak onto your page, and your page's stray CSS can't reach inside a component and break it.

In practice you can't use a regular CSS selector to retheme a component. A rule such as deck-cover h1 with a color in your stylesheet has no effect, because the heading lives in shadow.

That reads as a restriction, and it is · a deliberate one. Retheming goes through the hooks the components expose instead of through selectors that reach inside them. The three patterns below are those hooks.

Pattern 1 · Override one instance via tokens

Components that have something of their own to style declare CSS custom properties named after their tag, --deck-<tag>-* ·--deck-cover-bg on deck-cover,--deck-card-bg and --deck-card-radius ondeck-card, --deck-punch-color ondeck-punch. Each one falls back to a semantic--rik-* token, so an untouched component follows the theme. Some elements expose very little: deck-feature exposes only the shared--deck-eyebrow-* tokens, and the rest of its look comes from the semantic tokens. A few declare none at all · deck-fit,deck-metric-list, deck-tier-arrow anddeck-shortcut-list. Set a component token on the host and it crosses the shadow boundary.

inline override
<deck-cover style="--deck-cover-bg: navy;"><h1>Hello</h1></deck-cover>
Live preview · slide canvas

Pattern 2 · Override globally

Add a stylesheet after the theme link and override the--rik-* tokens at the document root or scoped to specific hosts.

local.css
:root { --rik-accent: #007acc; }

Pattern 3 · Pass content via slots (light DOM)

Anything you put as a direct child of a component is your HTML in light DOM. It is not shadowed, so your CSS reaches it normally. That is why text content, code, and custom HTML always work like you would expect.

slot example
<deck-feature><h1 slot="title">Hello</h1></deck-feature>
Live preview · slide canvas

The one-line rule

Override colors and shapes with the --rik-* and--deck-* tokens; don't try to write CSS selectors that reach inside a component.

Need a token that doesn't exist? Open an issue onthe tracker · missing hooks get added when the case is clear. Until then, putting your own HTML in a slot keeps that part in your CSS world.

Recap

  • Lit: the framework uses it, a deck author does not. You write HTML.
  • Shadow DOM is why your CSS can't accidentally break the framework. The tokens are the bridge.
  • Override tokens, not selectors. Either inline on a host, or globally on the document root.
  • Slot content stays in your CSS world. Anything you put inside a layout component can be styled normally.

Next