> For AI agents: the complete documentation index is available at /next/llms.txt, the full documentation bundle is available at /next/llms-full.txt.

# Primitives and Themes

`lynx-ui` is an **unstyled** component library (also known as **headless**). Inspired by [Radix Primitives](https://www.radix-ui.com/primitives) and [Base UI](https://base-ui.com/), it splits each component into two layers:

- **Primitives** are the top-level components you import, such as `Switch`, `Popover`, or `Sheet`. Each primitive handles one interaction pattern end to end, but makes no decisions about appearance.
- **Parts** are the structural pieces that make up a primitive. A `Switch` is composed of `SwitchTrack` and `SwitchThumb`. Each part is a separate element you render and style independently.

Since primitives ship with no visual design, you control appearance through two mechanisms:

- **Styling** defines the appearance of a component instance: its size, spacing, transitions, and state-specific visuals.
- **Theming** defines reusable semantic tokens that many components consume, so a single change to the token layer propagates everywhere.

This guide walks through both in practice, using [LUNA](/next/ui/luna-themes-tokens.md) as the theme layer (you can bring your own) and a single `Switch` example that evolves from a bare composition into a reusable themed wrapper, in three steps:

1. [Styling the parts](#styling-the-parts)
2. [Consuming tokens](#consuming-tokens)
3. [Composing themed wrappers](#composing-themed-wrappers)

## Setup

For plain CSS, import LUNA styles so token variables are available as CSS variables at
runtime.

```css
@import '@lynx-js/luna-styles/index.css';
```

For Tailwind, use LUNA tailwind preset to further expose the same tokens
as utilities such as `bg-primary` and `text-content`. Tailwind on Lynx requires
`@lynx-js/tailwind-preset` for runtime compatibility.

```ts
// tailwind.config.ts
import { LunaPreset } from '@lynx-js/luna-tailwind';
import LynxPreset from '@lynx-js/tailwind-preset';
import type { Config } from 'tailwindcss';

const config: Config = {
  content: ['./src/**/*.{js,jsx,ts,tsx}'],
  presets: [LynxPreset, LunaPreset],
};

export default config;
```

:::note

Some Tailwind integrations can provide source scanning automatically, so the
`content` field may not be required in every setup. The examples in this guide
use an additional integration layer beyond the basic Tailwind setup.

:::

## Styling the Parts

Every part of a `lynx-ui` component is intended to be styled by the
application. You render the part and attach your own classes. There is no
hidden built-in visual to override.

Using `Switch`:

```tsx
import { Switch, SwitchThumb, SwitchTrack } from '@lynx-js/lynx-ui';

export function ExampleSwitch() {
  return (
    <Switch className="switch">
      <SwitchTrack className="switch-track" />
      <SwitchThumb className="switch-thumb" />
    </Switch>
  );
}
```

The primitive supplies interaction and state. Your code supplies the visual
rules: root size and layout, track and thumb appearance, and how the
component responds to its various states.

The same composition works equivalently with Tailwind utilities. The only
difference is where the styling rules live:

```tsx
<Switch className="flex items-center w-[48px] h-[28px] rounded-full overflow-hidden">
  <SwitchTrack className="w-full h-full" />
  <SwitchThumb className="absolute w-[22px] h-[22px] rounded-full" />
</Switch>
```

A note on platform props: when a primitive needs to expose lower-level
platform attributes, it does so through explicit props such as `switchProps`
rather than mixing them into the styling API. This keeps the className surface
predictable while still allowing platform-level customization where needed.

## Styling States

Stateful primitives expose styling hooks for component state. This serves the
same purpose as the `data-*` state attributes used by libraries such as Radix
UI and Headless UI, and the `data-*` variants commonly used in Tailwind. In
`lynx-ui`, these hooks are exposed as **UI Variants**, implemented as UI state
classes:

- `ui-checked`
- `ui-active`
- `ui-disabled`

This is what makes headless primitives easy to style without hardcoding design
inside the component implementation.

In plain CSS, you target these states with selectors:

```css
.switch.ui-disabled {
  opacity: 0.5;
}
.switch-track.ui-checked {
  background-color: var(--primary);
}
.switch-track.ui-active {
  background-color: var(--primary-2);
}
.switch-thumb.ui-checked {
  transform: translateX(23px);
}
.switch-thumb.ui-active {
  width: 33px;
}
.switch-thumb.ui-checked.ui-active {
  transform: translateX(12px);
}
```

In Tailwind, the same states are expressed with variant chains:

```tsx
<SwitchTrack
  className="bg-neutral-faint
    ui-checked:bg-primary
    ui-active:bg-primary-2"
/>
<SwitchThumb
  className="bg-primary-content
    ui-checked:transform-[translateX(23px)]
    ui-active:w-[33px]
    ui-checked:ui-active:transform-[translateX(12px)]"
/>
```

:::note

This guide uses `transform-[translateX(...)]` instead of `translate-x-[...]`
for transform values.

`@lynx-js/tailwind-preset` is currently built on top of Tailwind v3, but it
adds support for this transform syntax. `translate-x-[...]` relies on CSS
variables, which have known issues in lower-version Lynx runtimes when used
with transitions or animations.

:::

When multiple states can be active at the same time, such as `checked` and `pressed`, make priority explicit. The `ui-checked:ui-active:` chain above is
intentional: it overrides the plain `ui-checked` translation when both states
apply, so the visual stays coherent during interaction. Whether you use
selectors or utilities, treat overlapping states as a design decision rather
than something to leave to specificity.


**This is an example below: lynx-ui-switch**

**Entry:** `BasicTailwind`
**Bundle:** `dist/SwitchBasicTailwind.lynx.bundle` | Web: `dist/SwitchBasicTailwind.web.bundle`

```tsx
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { Switch, SwitchThumb, SwitchTrack } from '@lynx-js/lynx-ui'
import type { SwitchProps } from '@lynx-js/lynx-ui'
import { clsx } from 'clsx'

import { hitSlop } from '../shared/hitSlop'

export function StyledSwitch({
  checked,
  defaultChecked,
  disabled,
  onChange,
  className,
  style,
  switchProps,
}: SwitchProps) {
  return (
    <Switch
      className={clsx(
        'flex flex-row items-center w-[48px] h-[28px] rounded-full overflow-hidden',
        'ui-disabled:opacity-50',
        className,
      )}
      checked={checked}
      defaultChecked={defaultChecked}
      disabled={disabled}
      onChange={onChange}
      style={style}
      switchProps={{ ...hitSlop, ...switchProps }}
    >
      {/* Track */}
      <SwitchTrack
        className={clsx(
          'size-full',
          'transition-colors duration-150 ease-out',
          'bg-neutral-faint',
          'ui-checked:bg-primary',
          'ui-active:bg-primary-2',
          'ui-checked:ui-active:bg-primary-2',
        )}
      />

      {/* Thumb */}
      <SwitchThumb
        className={clsx(
          // positioned relative to Switch root
          'absolute size-[22px] rounded-full bg-primary-content shadow',
          'transition-all duration-150 ease-out',
          // base position
          'transform-[translateX(3px)]',
          // checked position
          'ui-checked:transform-[translateX(23px)]',
          // Jelly press
          'ui-active:w-[33px]',
          // checked position offset for jelly effect
          'ui-checked:ui-active:transform-[translateX(12px)]',
        )}
      />
    </Switch>
  )
}

```



## Consuming Tokens

Notice that the styles above never hard-code literal colors. Instead, they
reference semantic tokens such as `primary` and `content`.

Semantic tokens name the intent of a value in the interface, not the raw value
itself. For example, `primary` means “the main accent in the current theme”,
and `content` means “primary foreground content”.

In this guide, you will most often see those tokens consumed as CSS property
values (`var(--primary)` and `var(--content)`) or Tailwind utilities
(`bg-primary` and `text-content`). These forms all resolve to the same runtime
token values.

Semantic tokens matter for two reasons:

- **Consistency.** A `Button`, a `Switch`, and a `Checkbox` that all read from
  `primary` stay in sync automatically. Changing the token updates every
  surface that consumes it.
- **Themeability.** Components depend on roles such as `primary` and `content`,
  rather than concrete colors. A theme can change what those roles resolve to
  across light, dark, or brand variants without rewriting component styles.

In practice, this means the concrete values for these semantic roles are
provided by the active theme scope on an ancestor node, following the same ancestor-based
theme switching pattern described in the [custom theming guide](/next/guide/styling/custom-theming.md),
where a theme class is applied at the container level and descendant styles resolve against that
shared theme scope.

Instead of branching styles per theme:

```tsx
<Button className="bg-pink-500 dark:bg-pink-300 text-white dark:text-black" />
```


> **Prefer semantic tokens over color scales**
> 
> In Tailwind utilities, the prefix describes the CSS property, such as `bg-` for
> background color or `text-` for text color. The value after the prefix is what
> matters for theming.
> Values such as `pink-500` and `pink-300` may still come from a design scale,
> but that scale is usually global: `pink-500` means the same concrete color
> regardless of whether the current theme is light, dark, or brand-specific.
> This makes it less suitable for components that need to adapt across multiple
> themes.
> Semantic values such as `primary` and `primary-content` describe the role of a
> style instead. The active theme decides what those roles resolve to, so the
> same component style can stay stable while the visual result changes with the
> theme.
> 


Components should consume semantic tokens and stay visually stable:

```tsx
<Button className="bg-primary text-primary-content" />
```

Theme switching then happens at the container level:

```tsx
<view className="lunaris-dark">
  {/* themed subtree */}
  <Button className="bg-primary text-primary-content" />
  <Switch className="switch">
    <SwitchTrack className="switch-track" />
    <SwitchThumb className="switch-thumb" />
  </Switch>
</view>
```

Changing the ancestor theme class, for example from `lunaris-dark` to
`lunaris-light`, updates the token values for the entire subtree without
rewriting individual component styles.

In `lynx-ui`, this container-scoped theme model is implemented by LUNA, which
provides four built-in theme classes: `luna-light`, `luna-dark`,
`lunaris-light`, and `lunaris-dark`.

For token names, surface hierarchy, and theme overriding,
see the [LUNA Themes and Tokens](/next/ui/luna-themes-tokens.md) documentation.

## Composing Themed Wrappers

Once a styling pattern repeats, the next step is to compose a themed wrapper
on top of the primitive. This gives you a stable, product-facing API without
losing the flexibility of the underlying parts.

The pattern is to wrap each part separately, encode your defaults in those
wrappers, and export a convenience composition for the common case:

```tsx
import {
  Switch as SwitchPrimitive,
  SwitchThumb as SwitchThumbPrimitive,
  SwitchTrack as SwitchTrackPrimitive,
} from '@lynx-js/lynx-ui';
import type {
  SwitchProps,
  SwitchThumbProps,
  SwitchTrackProps,
} from '@lynx-js/lynx-ui';
import { clsx } from 'clsx';

export function ThemedSwitch(props: SwitchProps) {
  return (
    <ThemedSwitchRoot {...props}>
      <ThemedSwitchTrack />
      <ThemedSwitchThumb />
    </ThemedSwitchRoot>
  );
}

export function ThemedSwitchRoot({ className, ...props }: SwitchProps) {
  return (
    <SwitchPrimitive
      className={clsx(
        'flex flex-row items-center w-[48px] h-[28px] rounded-full overflow-hidden',
        'ui-disabled:opacity-50',
        className,
      )}
      {...props}
    />
  );
}

export function ThemedSwitchTrack({ className }: SwitchTrackProps) {
  return (
    <SwitchTrackPrimitive
      className={clsx(
        'size-full transition-colors duration-150 ease-out',
        'bg-neutral-faint ui-checked:bg-primary ui-active:bg-primary-2',
        className,
      )}
    />
  );
}

export function ThemedSwitchThumb({ className }: SwitchThumbProps) {
  return (
    <SwitchThumbPrimitive
      className={clsx(
        'absolute size-[22px] rounded-full bg-primary-content shadow',
        'transition-all duration-150 ease-out transform-[translateX(3px)]',
        'ui-checked:transform-[translateX(23px)]',
        'ui-active:w-[33px]',
        'ui-checked:ui-active:transform-[translateX(12px)]',
        className,
      )}
    />
  );
}
```

A few things to notice in this final form:

- Each part is wrapped individually, so consumers can still override any one
  of them without rebuilding the rest.
- The convenience `ThemedSwitch` covers the common case but does not block
  the part-level API.
- Defaults for sizing, transitions, and state visuals are encoded once and reused everywhere.
- The token layer (`bg-primary`, `bg-neutral-faint`, `bg-primary-content`)
  carries through unchanged; the wrapper adds defaults, not new colors.

This is a typical [shadcn/ui](https://ui.shadcn.com/)-style composition pattern: primitives stay public and composable, while themed components become the default product-facing implementation.

The example below applies the pattern in a real UI: a controlled switch drives container theme,
and nested surfaces can override theme independently. The same demo is embedded on the [`<Switch>`](/next/ui/components/switch.md) page.


**This is an example below: lynx-ui-switch**

**Entry:** `Themed`
**Bundle:** `dist/SwitchThemed.lynx.bundle` | Web: `dist/SwitchThemed.web.bundle`

```tsx
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useState } from '@lynx-js/react'

import { clsx } from 'clsx'

import {
  ThemedSwitch,
  ThemedSwitchRoot,
  ThemedSwitchThumb,
  ThemedSwitchTrack,
} from './themed-switch'
import './index.css'

function App() {
  const [outerDark, setOuterDark] = useState(true)
  const [innerLight, setInnerLight] = useState(false)

  return (
    <view
      className={clsx(
        'size-full flex flex-col justify-center px-[48px] py-[72px]',
        'luna-gradient-berry',
        outerDark ? 'lunaris-dark' : 'lunaris-light',
      )}
    >
      <view className='flex flex-col gap-[24px] px-[48px] py-[64px] rounded-[16px] overflow-hidden text-content bg-canvas'>
        <text className='text-lg text-content-2'>Theme Switching</text>

        {/* 1) Outer container theme toggle (uses composed component) */}
        <view className='flex flex-row items-center gap-[16px] w-full'>
          <ThemedSwitch checked={outerDark} onChange={setOuterDark} />
          <text className='text-base text-content-2'>
            {outerDark ? 'lunaris-dark' : 'lunaris-light'}
          </text>
        </view>

        <view
          className={clsx(
            'flex flex-col mt-[16px] gap-[10px] py-[16px] px-[16px] rounded-[16px] overflow-hidden bg-canvas border border-line',
            innerLight ? 'lunaris-light' : 'lunaris-dark',
          )}
        >
          {/* 3) Inner container theme toggle (uses themed Primitives)*/}
          <view className='flex flex-row items-center gap-[16px] w-full pt-[8px]'>
            <ThemedSwitchRoot
              defaultChecked={innerLight}
              onChange={setInnerLight}
            >
              <ThemedSwitchTrack />
              <ThemedSwitchThumb />
            </ThemedSwitchRoot>
            <text className='text-base text-content-2'>
              {innerLight ? 'lunaris-light' : 'lunaris-dark'}
            </text>
          </view>
          {/* 3) Inner disabled sample */}
          <view className='flex flex-row items-center gap-[16px] w-full pt-[8px]'>
            <ThemedSwitch disabled checked={innerLight} />
            <text className='text-base text-content-2 opacity-50'>
              Disabled
            </text>
          </view>
        </view>
        {/* 4) Outer disabled sample */}
        <view className='flex flex-row items-center gap-[16px] w-full pt-[8px]'>
          <ThemedSwitch disabled checked={outerDark} />
          <text className='text-base text-content-2 opacity-50'>Disabled</text>
        </view>
      </view>
    </view>
  )
}

root.render(<App />)
export default App

```



## Best Practices

- Keep primitives visually unopinionated. The application owns appearance.
- Style each rendered part explicitly rather than relying on hidden defaults.
- Prefer semantic tokens over literal colors, even early in development.
- Make state priority explicit when multiple states can overlap.
- Promote a styled pattern to a wrapper only after it repeats, not before.
- Treat theming as a shared vocabulary across surfaces, not as a color dump.

## Summary

`lynx-ui` primitives are unstyled: they give you full control over appearance without taking behavior away from you. Style the parts directly with plain CSS or Tailwind, consume semantic tokens from a layer like LUNA so visual decisions stay consistent, and compose themed wrappers when a pattern is ready to be reused.
