Getting started

Lit, Shadow DOM, and how to override styles

Two minutes.

Do I need to learn Lit?

No. Lit is what we used to build the components. You write HTML tags such as deck-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 your own component (see Contributing). For 100 percent of decks, 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 sounds scary the first time. It is not · we exposed the right hooks so you don't need to break Shadow DOM to retheme anything. There are exactly three patterns.

Pattern 1 · Override one instance via tokens

Every component declares CSS custom properties named with the --deck-TAG-* convention. Set them on the host and they cross the shadow boundary.

inline override
<deck-cover style="--deck-cover-bg: navy;"><h1>Hello</h1></deck-cover>

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>

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, we add them when it's reasonable. Until then, you can always wrap your custom HTML in a slot.

Recap

  • Lit: we use it, you don't. 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.