#LUNA Themes and Tokens

LUNA is the theme foundation used across the lynx-ui examples. It provides a small, semantic token system that can be consumed through CSS variables, Tailwind utilities, or themed wrapper components.

Use LUNA when you want a shared visual language across screens without hard-coding colors into every component. Instead of styling a button, sheet, or switch with one-off hex values, you style it with semantic roles such as paper, content, primary, and line. Those roles remain stable even when the visual expression changes between themes.

LUNA currently ships four built-in themes:

• luna is the neutral foundation for product UI.
• lunaris is the signature gradient expression for more branded surfaces.
• light and dark preserve the same semantic token contract, so components can keep the same styling logic across modes.

This page includes LUNA Studio, an interactive preview of the theme contract described in this guide: theme variants, token groups, and the recommended override surface.

#Core Token Groups

LUNA contains more tokens than most applications need on day one, but a small set of core groups covers most product surfaces. If you are styling lynx-ui components or generating UI with AI, start with these groups first.

#Surface

Surface tokens define the background layers of the interface.

Use surface tokens to establish hierarchy before adding accent color. In most layouts, canvas defines the page environment, paper defines where content lives, and paper-clear lifts above paper for floating surfaces such as popovers and sheets.

#Content

Content tokens define text and icon presence.

When in doubt, start with content for main text and content-2 or content-muted for supporting copy.

#Primary

Primary tokens define high-emphasis actions and active states.

Use primary for action emphasis, not as a replacement for every surface in the interface.

#Neutral

Neutral tokens provide structural contrast and low-emphasis fills.

In practice, neutral-faint is one of the most useful tokens for form controls, tracks, and supporting UI chrome.

#Lines and Backdrop

These tokens handle separation and screen-level overlays.

Use line to outline a component, and rule to separate one region from another. The distinction is about role, not weight.

#Gradient

Gradients are optional, but they can make container-heavy lynx-ui examples more comprehensible by giving surfaces a clear visual identity.

Gradient tokens define the signature Lunaris expression.

If you are building neutral product UI, you may not need these tokens often. If you are building branded or expressive surfaces, these are the first tokens to reach for.

#Suggested Starting Set

If you want a small token contract for examples, product UI, or AI prompts, start with this subset:

• Surfaces: canvas, paper, paper-clear
• Text: content, content-2, content-muted
• Actions: primary, primary-2, primary-content
• Structure: neutral-faint, line, rule
• Overlays: backdrop, backdrop-heavy

This set is intentionally small. It is enough to build a coherent UI without forcing every use case to choose from the full token inventory.

#Token Usage

You can consume the same tokens in different ways depending on your stack.

#CSS Variables

.card {
  color: var(--content);
  background-color: var(--paper);
  border: 1px solid var(--line);
}

.card-title {
  color: var(--content);
}

.card-description {
  color: var(--content-muted);
}

#Tailwind Utilities

<view className="bg-paper text-content border border-line">
  <text className="text-content">Card title</text>
  <text className="text-content-muted">Supporting description</text>
</view>

The semantic roles stay the same even if you switch from luna-light to lunaris-dark.

#Overriding Tokens

LUNA is designed to make branding start at the token layer. Instead of rewriting component styles, define a product theme by overriding the semantic tokens those components consume.

#Apply a Built-In Theme As-Is

When you are using a built-in theme without modification, apply its class directly:

<view className="lunaris-dark">{/* themed content */}</view>

#Define Your Own Theme

Once you start overriding tokens, give your theme its own name. Treat it as a peer of the built-in themes, not a modifier layered on top of one:

.my-brand-dark {
  --primary: #ff4f8b;
  --primary-2: #ff2f73;
  --primary-content: #ffffff;
  --paper: #141414;
  --content: #f8f8f8;
  /* inherit remaining tokens from a built-in theme of your choice */
}

<view className="my-brand-dark">{/* branded content */}</view>

This keeps the className surface honest: a single class name corresponds to a single, fully-defined theme. Light and dark are properties of your brand, not borrowed from a built-in theme at the markup layer.

#Override Principles

• Prefer overriding semantic tokens over rewriting component classes.
• Start with a small set of brand-defining tokens such as primary, paper, and content.
• Keep foreground and background pairs aligned, such as primary with primary-content.
• Preserve the same token names across light and dark modes whenever possible.

#AI Gen UI Guidelines

If you are using LUNA as the visual contract for AI-generated UI, keep the instructions simple and semantic. The goal is not to expose every available token. The goal is to give the model a stable vocabulary that maps cleanly to real theme variables.

#Do and Don't

#Token Vocabulary

For most generated UI, this set is enough:

• Surfaces: canvas, paper, paper-clear
• Text: content, content-2, content-muted
• Actions: primary, primary-2, primary-content
• Structure: neutral-faint, line
• Overlays: backdrop

Map intent to tokens directly:

#Recommended Prompt Guidance