Theme Variable Reference

Complete documentation for all 74 CSS custom properties that control the Refraction UI visual identity. Split into Essential (~19 variables, always needed) and Advanced (~55 additional variables, optional).

Config Editor/LLM Prompt Generator/Theme Playground

Essential

19 variables

These are the only variables you need for Simple mode. Set your brand colors, pick your fonts, choose a radius.

Brand Colors

Core colors that define your brand. All color values use HSL format without the hsl() wrapper: "hue saturation% lightness%".

Variable	Controls	Accepts	Default
--background	Page/app background color	HSL: H S% L%	0 0% 99%
--foreground	Default body text color	HSL: H S% L%	240 10% 10%
--primary	Primary brand color (buttons, links, active states)	HSL: H S% L%	250 50% 50%
--primary-foreground	Text on primary color	HSL: H S% L%	0 0% 100%
--secondary	Secondary actions and subdued surfaces	HSL: H S% L%	240 5% 96%
--secondary-foreground	Text on secondary color	HSL: H S% L%	240 4% 44%
--muted	Subdued backgrounds (disabled states, secondary surfaces)	HSL: H S% L%	240 5% 96%
--muted-foreground	Subdued text (placeholders, secondary labels)	HSL: H S% L%	240 4% 44%
--accent	Highlighted/hover backgrounds	HSL: H S% L%	250 30% 95%
--accent-foreground	Text on accent color	HSL: H S% L%	250 50% 40%
--destructive	Error and danger actions	HSL: H S% L%	0 84% 50%
--destructive-foreground	Text on destructive color	HSL: H S% L%	0 0% 100%
--border	Default border color for cards, dividers	HSL: H S% L%	240 6% 92%
--input	Input field border color	HSL: H S% L%	240 6% 92%
--ring	Focus ring color	HSL: H S% L%	250 50% 50%

Fonts

CSS font-family stacks for body text, headings, and monospace code.

Variable	Controls	Accepts	Default
--font-sans	Body/UI text font stack	CSS font-family string	'Inter', system-ui, sans-serif
--font-heading	Heading font stack (can differ from body for personality)	CSS font-family string	'Inter', system-ui, sans-serif
--font-mono	Code and monospace font stack	CSS font-family string	'JetBrains Mono', ui-monospace, monospace

Shape & Feel

The base border-radius that sets the overall shape language of your UI.

Variable	Controls	Accepts	Default
--radius	Base radius (used as the default across components)	rem/px value	0.375rem

Advanced

55 additional variables

Optional branding controls for designers who want to fine-tune every visual detail. These all have sensible defaults.

Extended Colors

Additional color tokens for cards, popovers, semantic states, sidebar, and data visualization.

Variable	Controls	Accepts	Default
--card	Card component background	HSL: H S% L%	0 0% 99%
--card-foreground	Card component text color	HSL: H S% L%	240 10% 10%
--popover	Popover/dropdown background	HSL: H S% L%	0 0% 100%
--popover-foreground	Popover/dropdown text color	HSL: H S% L%	240 10% 10%
--success	Success indicators and confirmations	HSL: H S% L%	142 71% 35%
--success-foreground	Text on success color	HSL: H S% L%	0 0% 100%
--warning	Warning indicators	HSL: H S% L%	38 92% 50%
--warning-foreground	Text on warning color	HSL: H S% L%	240 10% 10%
--sidebar-background	Sidebar background	HSL: H S% L%	0 0% 98%
--sidebar-foreground	Sidebar text color	HSL: H S% L%	240 10% 10%
--sidebar-primary	Sidebar active item highlight	HSL: H S% L%	250 50% 50%
--sidebar-primary-foreground	Text on sidebar active item	HSL: H S% L%	0 0% 100%
--sidebar-accent	Sidebar hover/subtle highlight	HSL: H S% L%	250 30% 95%
--sidebar-accent-foreground	Text on sidebar accent	HSL: H S% L%	250 50% 40%
--sidebar-border	Sidebar border color	HSL: H S% L%	240 6% 92%
--sidebar-ring	Sidebar focus ring	HSL: H S% L%	250 50% 50%
--chart-1	Primary chart color	HSL: H S% L%	250 50% 50%
--chart-2	Second chart color	HSL: H S% L%	173 80% 36%
--chart-3	Third chart color	HSL: H S% L%	38 92% 50%
--chart-4	Fourth chart color	HSL: H S% L%	330 65% 50%
--chart-5	Fifth chart color	HSL: H S% L%	201 96% 42%

Typography Details

Controls the visual treatment of headings and base text size.

Variable	Controls	Accepts	Default
--heading-weight	Font weight for headings	100-900	600
--heading-letter-spacing	Letter spacing for headings (negative = tighter)	em value	-0.02em
--heading-line-height	Line height for headings	unitless ratio	1.2
--font-size-base	Base body text size	rem/px value	1rem

Per-Component Radius

Override the border-radius for individual component types.

Variable	Controls	Accepts	Default
--avatar-radius	Avatar border radius	rem/px/9999px	9999px
--badge-radius	Badge border radius	rem/px/9999px	9999px
--button-radius	Button border radius	rem/px value	0.375rem
--card-radius	Card border radius	rem/px value	0.5rem

Depth -- Shadows

Shadow scale and per-component shadow overrides.

Variable	Controls	Accepts	Default
--shadow-sm	Small shadow (subtle elevation)	CSS box-shadow	0 1px 2px 0 rgb(0 0 0 / 0.03)
--shadow-md	Medium shadow (cards, dropdowns)	CSS box-shadow	0 2px 4px -1px rgb(0 0 0 / 0.04), 0 1px 2px -1px rgb(0 0 0 / 0.03)
--shadow-lg	Large shadow (modals, popovers)	CSS box-shadow	0 6px 10px -2px rgb(0 0 0 / 0.05), 0 2px 4px -2px rgb(0 0 0 / 0.03)
--card-shadow	Card component shadow	CSS box-shadow or none	0 1px 2px 0 rgb(0 0 0 / 0.03)
--button-shadow	Button shadow (often none)	CSS box-shadow or none	none

Transparency & Glass

Controls for overlay darkness, blur effects, and glassmorphism.

Variable	Controls	Accepts	Default
--overlay-opacity	Backdrop overlay darkness (dialogs, drawers)	0-1	0.5
--backdrop-blur	Backdrop blur amount	px value	8px
--glass-bg	Glass effect background color	rgba() value	rgba(252, 252, 253, 0.8)

Density

Controls how compact or spacious the UI feels.

Variable	Controls	Accepts	Default
--spacing-scale	Global spacing multiplier (affects all spacing)	0.85-1.2	1
--card-padding	Internal padding of card components	rem value	1.5rem
--input-height	Height of input fields	rem value	2.5rem
--container-max-width	Max width of the main content container	px value	1280px

Borders

Border width control.

Variable	Controls	Accepts	Default
--border-width	Default border width for all bordered elements	px value	1px

Component Styles

Behavioral keywords that control component appearance.

Variable	Controls	Accepts	Default
--input-style	Input visual style	bordered \| filled \| underline	bordered
--button-style	Default button visual style	filled \| outline \| ghost-default	filled
--hover-effect	What happens on hover	darken \| lighten \| shadow-lift \| scale	darken
--disabled-opacity	Opacity of disabled elements	0-1	0.5
--link-style	How links are visually distinguished	color-only \| underline \| underline-on-hover	color-only
--focus-ring-style	Focus indicator style	ring \| outline \| shadow	ring
--icon-style	Icon set style	outlined \| filled \| duotone	outlined
--icon-stroke-width	Stroke width for outlined icons	number (1-3)	1.5
--tooltip-style	Tooltip color scheme	dark \| light \| primary	dark
--table-style	Table row treatment	clean \| striped \| bordered	clean
--scrollbar-style	Scrollbar visibility and width	thin \| hidden \| default	thin

Selection Highlight

Controls the color of text when selected with the cursor.

Variable	Controls	Accepts	Default
--selection-background	Background color of selected text	HSL: H S% L%	250 50% 90%
--selection-foreground	Text color of selected text	HSL: H S% L%	240 10% 10%

Usage Tips

HSL format: Color values use raw HSL values without the hsl() wrapper. Write 250 50% 50% not hsl(250, 50%, 50%).
Contrast: All foreground/background pairs should meet WCAG AA contrast (4.5:1 for text, 3:1 for large text).
Simple mode: Start with just the Essential variables. The Advanced controls all have good defaults and can be added later.
Density: The --spacing-scale acts as a global multiplier. Values below 1 make the UI denser, above 1 make it more spacious.