Customising

You customise LO-TEK by setting CSS variables in your own CSS. The values that ship with the package are defaults, and yours win over them.

Three routes, in the order you should try them:

Route	For
Tokens	Colours, across the whole system
Component variables	Shape and size of one component
Ordinary rules	Everything else

Your own colours

There is one way in: your own CSS, loaded after tokens.css. Everything LO-TEK ships is in a cascade layer (@layer lotek), and CSS outside a layer always wins over CSS in a layer, whatever the specificity. You need neither !important nor long selectors.

The default is to leave it alone: LO-TEK’s own colours are checked against WCAG AA in both themes, and you do not need to write anything. If you want to change them, you choose how coarse a change to make.

You want to	Write
Change one colour	The cell, --lt-color-accent-fill
Change a whole family	The nine roles, --lt-color-accent-surface to --lt-color-accent-content
Give the whole system your organisation’s colours	Nothing. Make a theme, and the file is written for you

The generator is not a separate mechanism. It sets the same variables, for both themes. The file it writes goes in its own layer, lotek-theme, declared after lotek, so your own CSS outside a layer still wins over the theme. If you use Tailwind, the layer must be in the layer order, or it ends up after utilities and beats your classes.

If you write cells yourself, keeping the contrast promises is up to you. lotek check-theme theme.css tells you which cell fails and why.

The variables

:root {
  --lt-color-accent-fill: #7c3aed;
  --lt-color-accent-content: #ffffff;
}

Override a colour, and the contrast is yours to check

The colours in LO-TEK are checked against WCAG AA, in both themes. If you replace one of them, that guarantee no longer applies, and the pairs the colour is part of must be checked again. --lt-color-accent-fill, for example, is both the button background under --lt-color-accent-content and the border colour of a checked checkbox.

The tick in a checkbox is an image, not a colour, and does not follow --lt-color-accent-content by itself. If you make --lt-color-accent-fill light and --lt-color-accent-content dark, you must also set --lt-icon-check and --lt-icon-dash in the same colour, or the tick disappears. A theme from the theme generator does not need this: the roles have fixed lightness, so the tick keeps its contrast there.

Light and dark

Without you doing anything, the colours follow the system setting. Painting the page itself is up to you: LO-TEK sets no background on <html> or <body>, since the package may be a guest on someone else’s page. Give <body> the surface and the text colour, or you get light text on a white page when the system is in dark mode:

body {
  background: var(--lt-color-neutral-canvas);
  color: var(--lt-color-neutral-text);
}

A page that wants to decide the theme itself sets data-theme on <html>:

<html data-theme="light">

The attribute is a theme boundary

data-theme works on any element, not just the root. The element and everything below it get the theme, and the rest of the page is left untouched:

<div data-theme="dark">
  <button class="lt-button">This one is dark</button>
</div>

A theme can sit inside another, both ways. A light box in a dark section is as valid as the opposite.

The element with data-theme="light" or data-theme="dark" also gets the theme’s surface and text colour, so a dark section on a light page is not left transparent with light text on white. That does not apply to <html>, which is yours, or to lt-toast. The rule has zero specificity in @layer lotek, so a component that has data-theme on itself, like a card, keeps its own background, and so does your own style outside a layer or in a layer after lotek. If your style is in a layer before lotek, like base in the Tailwind setup, LO-TEK’s surface wins.

The focus ring and the colours for the disabled state also follow the boundary, because they are declared again in each theme block. If you override --lt-focus-ring, --lt-color-disabled-surface or --lt-color-disabled-text, write the override on [data-theme="light"] and [data-theme="dark"] too, or it only applies outside the theme boundaries.

An embedded component locks its own theme

If you put LO-TEK into someone else’s page, this is how to do it. Set the attribute on the component’s own root element, and it is light whatever the system is set to, and the host is not touched:

<div data-theme="light">
  <table class="lt-table">
    <caption class="lt-sr-only">Invoices</caption>
  </table>
</div>

Do not set data-theme on the host’s <html>. It is a global attribute that belongs to the page, not to you.

The host’s CSS stops at the boundary

The host often has rules outside any layer, like button { background: none; border: none } or a normalize. Rules outside a layer beat @layer lotek, so inside your component .lt-button loses its background and border. Set data-lt-boundary on the root element, next to data-theme:

<div data-lt-boundary data-theme="light">
  <button type="button" class="lt-button">Try again</button>
</div>

The boundary is in lotek.css, and as a separate file in @lo-tek/interfaces/boundary.css for those who import the stylesheets one by one. It is the only rule in the package outside the layer, and it does one thing: below the root element the browser ignores CSS outside a layer, within the specificity below, and LO-TEK’s layers apply again. Where no layer says anything, the browser’s own rules apply.

This is kept:

• The font and everything else that is inherited. Inheritance comes in through the root element, and the boundary does not touch it. LO-TEK inherits the font on purpose, so the component gets the host’s font.
• The --lt-* variables, both on the root element and on :root.
• Rules on the root element itself, including your own outside a layer.

What you need to know:

• Your own CSS inside the boundary must be in a layer after lotek, for example components or utilities in the layer order. CSS outside a layer disappears there just like the host’s. Tailwind classes are already in a layer.
• Elements without a LO-TEK class lose the host’s CSS outside a layer. A plain <p> loses the host’s margins, and a <button> without lt-button gets the browser’s button, unless a layer says otherwise.
• The boundary has specificity (0,2,0). It beats the host’s resets, like button:not(:disabled), a:hover and input[type="text"]. A rule from the host with the same specificity wins if it is loaded after the boundary, and one with more, like .app .content a, always wins. So does !important.
• The host’s layers are not stopped. The boundary only takes CSS outside a layer. A layer the host has declared after lotek wins over LO-TEK. A layer declared before, like Tailwind’s Preflight in base, applies where LO-TEK sets nothing.

Letting the user choose

lt-theme-control on a radio button makes value a theme choice, in plain CSS:

<label class="lt-toggle-group__option">
  <input class="lt-theme-control" type="radio" name="theme"
         value="dark" /> Dark
</label>

Three values mean something: auto, light and dark. light and dark win over data-theme on <html>, so the server can send the stored choice while a click takes effect at once. auto has no theme block, so there the server’s data-theme remains. The control stores nothing itself. See Let the user choose the theme for the whole pattern.

Colour scheme

color-scheme decides how the browser draws its own surfaces: scrollbars, the dropdown of a <select> and the calendar panel in a date field. LO-TEK sets it where someone has chosen a theme: on [data-theme="light"], on [data-theme="dark"] and on the three options of the theme picker. Bare :root never gets it.

The reason is that the property is inherited, so a value on the root applies to the whole document, including a host page that never asked for it. A child can opt out with color-scheme: normal, but that is a counter-rule the host should not have to write. If you want the browser’s surfaces to follow the system on the whole page, write one line yourself:

:root {
  color-scheme: light dark;
}

It is the same arrangement as for the layer order: one line each, and both are yours.

If you use the theme picker, do not write that line. Each of the three options sets color-scheme itself: light gives light, dark gives dark, and “Follow the system” gives light dark, that is, the message that the page works in both and the browser may choose by the system. If you write it anyway, outside a layer, the rule beats @layer lotek, and the browser’s surfaces are locked to the system while the user has chosen something else. Putting it in a layer before lotek does not help: the order is already established by tokens.css, which loads first, so a later @layer statement puts the layer last.

Per theme

The override under “Your own colours” applies to both themes. If you want different values, write your own rules:

:root {
  --lt-color-accent-fill: #7c3aed;
}

@media (prefers-color-scheme: dark) {
  :root:not([data-theme="light"]) {
    --lt-color-accent-fill: #c4b5fd;
  }
}

[data-theme="light"] {
  --lt-color-accent-fill: #7c3aed;
}

[data-theme="dark"] {
  --lt-color-accent-fill: #c4b5fd;
}

If you use the theme picker, the last two blocks need its selector next to them, as LO-TEK’s own have:

[data-theme="light"],
:root:has(.lt-theme-control[value="light"]:checked) {
  --lt-color-accent-fill: #7c3aed;
}

[data-theme="dark"],
:root:has(.lt-theme-control[value="dark"]:checked) {
  --lt-color-accent-fill: #c4b5fd;
}

The picker does not set data-theme, because CSS cannot write an attribute. Without the selector, none of your blocks matched when the user chose a theme, and LO-TEK’s own colour remained.

All four blocks are needed. The two data-theme blocks each declare their value directly on the element that carries the attribute, and a declaration on the element itself wins over a value it inherits, whatever layer the inherited value came from. If you leave out [data-theme="light"], LO-TEK’s own colour applies inside a light theme boundary while yours applies elsewhere on the page.

Shape and size

Colours are not the only thing you can change. Each component has its own variables for shape and size:

:root {
  --lt-button-radius: 9999px;
  --lt-input-radius: 0;
}

Where you set it decides how far it reaches

The variables are inherited, like all CSS variables. Where you write the declaration is therefore the only thing that decides its reach, and you need no separate mechanism to limit it.

On :root it applies to the whole app, as in the example above. If you write it on your own class instead, it applies to that element and everything inside it:

Example

Plain HTML

<div class="lt-card">
<h3 class="lt-heading" data-size="s">Default</h3>
<p class="lt-paragraph">The values that ship with the package.</p>
<button class="lt-button">Open the case</button>
</div>

<div class="lt-card compact-panel">
<h3 class="lt-heading" data-size="s">Compact panel</h3>
<p class="lt-paragraph">Same markup, one more class.</p>
<button class="lt-button">Open the case</button>
</div>

.compact-panel {
--lt-card-padding: var(--lt-spacing-2);
--lt-card-radius: 0;
--lt-button-padding: var(--lt-spacing-1) var(--lt-spacing-3);
}

The markup is the same in both. The only difference is the class compact-panel, and it is yours, not ours. The button inside gets narrower without you touching the button: it inherits the variable from the card.

That gives you three scopes with the same mechanism:

Where you write it	How far it reaches
:root	The whole app
Your own class on a container	Everything inside that container
Your own class on the component	Just that one

The table below is a reference of every variable there is. What each one does, and an example that shows it, is on the component’s own page.

Variable	Default
--lt-button-padding	var(--lt-spacing-2) var(--lt-spacing-4)
--lt-button-radius	var(--lt-spacing-1)
--lt-button-border-width	1px
--lt-button-font-weight	var(--lt-font-weight-medium)
--lt-button-line-height	var(--lt-line-height-default)
--lt-heading-font-weight	var(--lt-font-weight-bold)
--lt-heading-line-height	var(--lt-line-height-heading)
--lt-paragraph-line-height	var(--lt-line-height-article)
--lt-badge-padding	var(--lt-spacing-0-5) var(--lt-spacing-2)
--lt-badge-radius	var(--lt-spacing-4)
--lt-alert-padding	var(--lt-spacing-3) var(--lt-spacing-4)
--lt-alert-radius	var(--lt-spacing-1)
--lt-alert-accent	var(--lt-spacing-1)
--lt-card-padding	var(--lt-spacing-4)
--lt-card-radius	var(--lt-spacing-2)
--lt-divider-space	var(--lt-spacing-4)
--lt-spinner-size	var(--lt-spacing-6)
--lt-spinner-thickness	2px
--lt-table-cell-padding	var(--lt-spacing-2) var(--lt-spacing-3)
--lt-list-gap	var(--lt-spacing-1), but var(--lt-spacing-2) in divided
--lt-tag-padding	var(--lt-spacing-0-5) var(--lt-spacing-2)
--lt-tag-radius	var(--lt-spacing-1)
--lt-avatar-size	var(--lt-spacing-10)
--lt-avatar-radius	var(--lt-spacing-1)
--lt-skeleton-height	var(--lt-spacing-4), but var(--lt-spacing-10) in circle
--lt-skeleton-radius	var(--lt-spacing-1), but var(--lt-spacing-0-5) in text
--lt-breadcrumbs-gap	var(--lt-spacing-2)
--lt-pagination-gap	var(--lt-spacing-1)
--lt-pagination-size	var(--lt-spacing-10)
--lt-pagination-radius	var(--lt-spacing-1)
--lt-progress-fill	var(--lt-color-accent-fill), and data-color changes it
--lt-progress-track	var(--lt-color-neutral-surface)
--lt-progress-border	var(--lt-color-neutral-border), the border around the track. Set it to transparent to remove it
--lt-progress-height	var(--lt-spacing-2)
--lt-progress-radius	var(--lt-spacing-1)
--lt-skip-link-padding	var(--lt-spacing-2) var(--lt-spacing-4)
--lt-skip-link-radius	var(--lt-spacing-1)
--lt-accordion-radius	var(--lt-spacing-1)
--lt-accordion-padding	var(--lt-spacing-3) var(--lt-accordion-padding-inline), the spacing in the heading
--lt-accordion-padding-inline	var(--lt-spacing-4), the spacing at the sides, in the heading and the content
--lt-dialog-width	min(32rem, 100%, calc(100vw - var(--lt-spacing-8)))
--lt-dialog-padding	var(--lt-spacing-5)
--lt-dialog-layer	40
--lt-dialog-radius	var(--lt-spacing-2)
--lt-tooltip-width	16rem
--lt-tooltip-padding	var(--lt-spacing-1) var(--lt-spacing-2)
--lt-tooltip-radius	var(--lt-spacing-1)
--lt-paragraph-width	70ch
--lt-paragraph-gap	var(--lt-spacing-3)
--lt-tabs-gap	var(--lt-spacing-1)
--lt-tabs-padding	var(--lt-spacing-2) var(--lt-spacing-4)
--lt-tabs-panel-space	var(--lt-spacing-4)
--lt-error-summary-padding	var(--lt-spacing-4)
--lt-error-summary-radius	var(--lt-spacing-1)
--lt-file-upload-padding	var(--lt-spacing-2)
--lt-file-upload-radius	var(--lt-spacing-1)
--lt-avatar-stack-overlap	calc(var(--lt-spacing-2) * -1)
--lt-popover-width	min(20rem, calc(100vw - var(--lt-spacing-8)))
--lt-popover-padding	var(--lt-spacing-3)
--lt-popover-radius	var(--lt-spacing-1)
--lt-popover-top	set by the component
--lt-popover-left	set by the component
--lt-toast-space	var(--lt-spacing-4)
--lt-toast-width	min(24rem, calc(100vw - var(--lt-spacing-8)))
--lt-toast-padding	var(--lt-spacing-3) var(--lt-spacing-4)
--lt-toast-radius	var(--lt-spacing-1)
--lt-toast-layer	60
--lt-suggestion-max-height	calc(var(--lt-spacing-10) * 4)
--lt-suggestion-radius	var(--lt-spacing-1)
--lt-suggestion-top	set by the component
--lt-suggestion-left	set by the component
--lt-suggestion-width	set by the component
--lt-suggestion-option-padding	var(--lt-spacing-2) var(--lt-spacing-3)
--lt-input-width	100%
--lt-input-padding	var(--lt-spacing-2) var(--lt-spacing-3)
--lt-input-radius	var(--lt-spacing-1)
--lt-textarea-min-height	calc(var(--lt-spacing-4) * 5)
--lt-textarea-padding	var(--lt-spacing-2) var(--lt-spacing-3)
--lt-textarea-radius	var(--lt-spacing-1)
--lt-select-width	100%
--lt-select-padding	var(--lt-spacing-2) var(--lt-spacing-3)
--lt-select-radius	var(--lt-spacing-1)
--lt-select-option-padding	var(--lt-spacing-2) var(--lt-spacing-3)
--lt-select-viewport-margin	var(--lt-spacing-2)
--lt-checkbox-size	var(--lt-spacing-5)
--lt-checkbox-radius	var(--lt-spacing-1)
--lt-radio-size	var(--lt-spacing-5)
--lt-switch-width	var(--lt-spacing-10)
--lt-switch-height	var(--lt-spacing-6)
--lt-fieldset-gap	var(--lt-spacing-2)
--lt-label-required-symbol	" *"
--lt-label-required-text	" (required)"
--lt-label-optional-text	" (optional)"
--lt-search-icon-space	var(--lt-spacing-10)
--lt-search-icon-size	var(--lt-spacing-5)
--lt-toggle-group-radius	var(--lt-spacing-1)
--lt-toggle-group-height	var(--lt-spacing-10)
--lt-toggle-group-padding	0 var(--lt-spacing-4)
--lt-session-timeout-width	26rem
--lt-session-timeout-padding	var(--lt-spacing-5)
--lt-session-timeout-radius	var(--lt-spacing-1)
--lt-connection-status-layer	1000
--lt-connection-status-padding	var(--lt-spacing-2) var(--lt-spacing-4)

The defaults point at the --lt-spacing-* scale. If you rewrite the scale, step by step, the components follow. If you set the variable, your value applies only to that component.

When the variable is not enough

Tokens and component CSS are in @layer lotek. CSS outside a layer always wins over CSS in a layer, whatever the specificity. So you can override anything with a simple selector:

.lt-button {
  letter-spacing: 0.02em;
}

Without the layer you would have had to beat selectors like .lt-button[data-variant="danger"]:hover, or resort to !important.

Under data-lt-boundary the rule must be in a layer, see The host’s CSS stops at the boundary.

!important reverses the order

For declarations with !important the cascade goes the other way: then CSS inside a layer wins over CSS outside. If you write !important to be safe, you get the opposite. You do not need it, so leave it out.

display on the dialog

There is one exception, and it comes from the browser, not from us. A <dialog> without open is hidden by the browser’s own stylesheet, and layers only sort within one origin, so any author rule with display beats that hiding. If you set display on .lt-dialog, a closed dialog stays on the page like a card. Then include the rule yourself, at least as specific as your own:

dialog.lt-dialog:not([open]):not(:is(:popover-open)) {
  display: none;
}

LO-TEK itself sets display: flex when .lt-dialog__body is a direct child, so that the body can scroll, and has that rule next to it.

Tailwind and the layer order

If you use Tailwind, our layer has to be placed. Layers count in the order they are first mentioned, and the last one wins whatever the specificity. Set the order on the first line of your CSS:

@layer theme, base, lotek, lotek-theme, components, utilities;

@import "tailwindcss";
@import "@lo-tek/interfaces/tokens.css";
@import "@lo-tek/interfaces/tailwind.css";

Without that line you get one of the problems in the table. The first two depend on which import comes first, the third comes the day you add a generated theme:

Order	What happens
lotek before base	Tailwind’s Preflight resets the components. The background disappears from the button.
lotek after utilities	The components beat your Tailwind classes. p-6 on an .lt-button does nothing.
lotek-theme after utilities	A generated theme beats your Tailwind classes. The layer must be in the line even if you have no theme yet.
base, lotek, lotek-theme, utilities	Everything works

The failure cases are tested, not assumed: customising.browser.test.ts builds each of them in its own document and checks what the button and the root element actually get.

LO-TEK’s own theme for Tailwind is in @lo-tek/interfaces/tailwind.css. It is an ordinary CSS file, so the package has no dependency on Tailwind, and your version is the only one in use. See Design tokens.

No shadow DOM

No component in LO-TEK uses shadow DOM any more. <lt-calendar> was the only one, and it has been removed in favour of the browser’s own date picker. See Dates in a form.

That means your CSS reaches everywhere. You need neither ::part() nor a way into a shadow root.

When CSS is not enough

Variables and the layer cover the appearance. They do not cover making the component do something other than what it does. Then you can take over the source code of that one component:

npx @lo-tek/interfaces takeover button --out=src/ui

The command copies the component’s files into your project, gives the copy its own name, and rewrites the references out of the folder, so that the copy works where it ends up:

Copied button to src/ui/button/
  button.css
  button.ts
  lotek-manifest.json

The component is now yours. Updates to @lo-tek/interfaces do not touch it.

The copy is called app-button, and can sit next to the original.
Switch to the new name in the markup where the copy is to be used. The variables
from the theme (--lt-*) are the same.

References out of the folder now point at the package:
  ../shared.js → @lo-tek/interfaces/shared

These imports load the original, and can be removed when nothing uses it:
  @lo-tek/interfaces/button
  @lo-tek/interfaces/button.css

Check the markup for the copy with:
  lotek check --manifest=src/ui/button/lotek-manifest.json <files…>

The copy is called app-button in the classes, the tags and the selectors, so it and the original can be used side by side without the order of the stylesheets deciding which one wins. The variables from the theme keep their names, so the copy follows your theme.

lotek-manifest.json holds the classes, the elements and the valid values of the copy, under the new name. If you give it to check with --manifest, the markup for the copy is checked as strictly as the rest of LO-TEK. If you add a variant to the copy, write it into the fragment too. See takeover.

What you give up is the updates. Fixes and improvements in the package do not reach the copy, and from then on maintaining it is up to you. Use the command on the one component that needs it, not on all of them.

Accessibility becomes your responsibility. Our tests run against the package, not against your copy, so an accessibility statement that refers to the design system does not cover a component you have taken over and changed.

npx @lo-tek/interfaces takeover without a name lists the components. The copy is not overwritten if the folder already exists, unless you add --overwrite=yes.