Theming
Fuji appearance is shaped by three global settings on FujiProvider: a theme, a radius, and an elevation. Set them once and every component follows, because each reads the same design tokens rather than branching on the theme in JavaScript. This page covers all three settings plus the colors, tokens, shadows, and glass surfaces they drive.
Themes
There are exactly three themes: light (default), dark, and glass. Set the theme once, globally. There is no per-component theme prop and no nested-provider requirement.
import { FujiProvider } from "@fujiui/react";
<FujiProvider persist defaultTheme="glass" defaultRadius="soft" defaultElevation="floating">
<App />
</FujiProvider>Each of the three settings can be controlled or uncontrolled on the provider, and all three are exposed through useFujiConfig(). The provider persists them together as one preference, so a choice survives navigation, opening a new tab, and refresh, with no default-theme flash on load. The glass theme is a dark, atmospheric backdrop with white text and translucent white-glass surfaces; overlays stay translucent so the background remains visible behind them.
These swatches read the active theme live
Every swatch reads its color directly from the active theme. Use the theme switcher in the header to watch them change without a page reload.
Background
--fuji-background
Background (subtle)
--fuji-background-subtle
Surface (subtle)
--fuji-surface-subtle
Surface
--fuji-surface
Surface (strong)
--fuji-surface-strong
Surface (overlay)
--fuji-surface-overlay
Foreground
--fuji-foreground
Foreground (muted)
--fuji-foreground-muted
Foreground (subtle)
--fuji-foreground-subtle
Default
--fuji-default
Earth
--fuji-earth
Border
--fuji-border
How theme switching works
FujiProvider stamps data-fuji-theme, data-fuji-radius, and data-fuji-elevation on its root element and mirrors them onto <html> for native form control and color-scheme support. Every token is scoped under those attributes, so flipping one re-resolves every affected value in a single paint, with no remount and no React state threaded through the tree. Overlays such as dialogs, menus, popovers, and tooltips render in a portal outside the provider subtree; each Fuji overlay re-stamps the theme and radius attributes on its portalled root, so overlay content always matches the active theme.
Radius
Radius is the second global axis: cornered (default) or soft. It controls three scoped tokens (control, panel, and overlay radius), so every button, card, and dialog stays visually consistent with each other.
<FujiProvider radius="soft">
<App />
</FujiProvider>Cornered
control 8px · panel 12px · overlay 14px
Soft
control 13px · panel 18px · overlay 22px
Circular elements stay circular. Avatars, radio dots, switches, and status dots use rounded-full directly; radius tokens only apply to rectangular controls, panels, and overlays, never to semantically circular shapes.
Elevation
Elevation is the third global axis: regular (default) or floating. regular keeps the restrained shadows shown below. floating swaps in deeper, softly layered shadows plus a small inset highlight at meaningful boundaries such as cards, panels, menus, and overlays. It changes shadow depth only; it never adds scale or hover motion to static surfaces. In dark mode, floating uses deeper, darker layered shadows with a subtle inset highlight so raised surfaces still read against the near black canvas. Both modes drive the same shadow tokens, so every elevated component follows the mode automatically.
control floating
card floating
panel floating
overlay floating
Colors and tokens
Every color is a CSS custom property prefixed --fuji-, scoped per theme in the package stylesheet. Components reference these tokens, never raw hex values, through matching Tailwind utilities such as bg-fuji-surface-strong.
Surface hierarchy
Four surface levels express depth without relying on shadow alone: subtle for hover areas and inactive tabs, the base surface for cards and panels, strong for inputs and selected states, and overlay for dialogs, drawers, menus, popovers, and tooltips. Shadow depth is the separate elevation setting described above.
ComponentTone vs. StatusTone
Fuji has two separate tone vocabularies, and they are not interchangeable. ComponentTone (default | earth | fire | water | forest | sun) is purely decorative - it powers Button, IconButton, ButtonGroup, Badge, Icon, Slider, Rating, Avatar, and similar visual-only tone props. Choosing tone="fire" on a Badge says nothing about status - it is a look, the same as picking a color swatch.
StatusTone (default | success | warning | danger | info) is semantic - the value itself carries meaning for accessibility, and it never changes regardless of the decorative palette in use. It is used by Alert, Toast, Result, StatusIndicator, Progress, CircularProgress, and Timeline, always through a variant prop rather than tone. Each status name maps internally onto one decorative token purely for styling: success → forest, warning → sun, danger → fire, info → water.
Decorative - ComponentTone
<Badge tone="fire">fire</Badge>Semantic - StatusTone
<StatusIndicator variant="danger" label="danger" />Semantic colors
Success, warning, danger, and info are deliberately muted, never neon, and keep the same hue in every theme so meaning never depends on which theme is active.
Success
--fuji-forest
Warning
--fuji-sun
Danger
--fuji-fire
Info
--fuji-water
A note on the old ‘primary’ tone
Fuji's native visual language treats default as the main action color. Earlier versions also shipped a primary tone that was a pure alias of default - both resolved to the same token (--fuji-primary aliased --fuji-default) in every theme. primary has since been removed in favor of a single canonical default tone. The default and contained combination still adapts automatically per theme: black on light, warm off-white on dark, and a translucent near-black on glass. If a distinct accent hue is introduced later, only the token aliases change.
Shadows and glass
Shadows are layered (two stacked box-shadows per level) and soft, never a single flat drop shadow, and grow stronger from control to overlay. Not every element gets a visible shadow; subtle surfaces and ghost buttons intentionally have none.
control
Buttons, inputs, small controls
card
Cards, standard panels
panel
Elevated panels, dropdowns
overlay
Dialogs, drawers, popovers, menus
The glass theme
The glass theme layers white-glass surfaces at four distinct opacities over a dark, atmospheric gradient background, so panels never look uniformly transparent. Foreground text is white. Ordinary cards, fields, and controls stay translucent but unblurred — backdrop-filter is deliberately reserved for opened overlays (dialogs, drawers, menus, popovers, toasts), since blurring every card and field on the page would mean compositing dozens of expensive blur layers during scroll for little visible benefit on an already-translucent surface. Inputs lean on a reflective border and focus ring for definition, and overlays keep the page atmosphere visible behind them rather than replacing it.
Fallbacks and accessibility
When backdrop-filter is unsupported, or the user has prefers-reduced-transparency: reduce set, glass surfaces fall back to opaque cool-neutral panels instead of a blurred effect; readability always wins over the visual effect. Print styles similarly flatten every theme to plain black on white.