shading #

fuz_css offers a shading model built on adaptive style variables that respond to the color-scheme. Adaptive means the underlying values change between light and dark modes to maintain consistent prominence -- low numbers stay subtle, high numbers stay strong. Each theme can implement light mode, dark mode, or both.

Light mode's starting point is plain white documents (like paper) where we subtract light to create contrast and shape. Black shadows on white make natural sense; white glows are near invisible.

Dark mode's starting point is a lightless void where we add light. Elements emit light to fill the darkness. White glows make natural sense; black shadows are near invisible.

The shade scale
#

The shade scale is the primary system for backgrounds and surfaces. All numbered shades (shade_00 through shade_100) are tinted using the theme's tint_hue and tint_saturation for visual cohesion. The scale also includes two untinted extremes (shade_min and shade_max) for maximum contrast needs.

Key values
#

shade_min: untinted surface-side extreme -- white in light mode, black in dark mode; used for input backgrounds
shade_00: the base background
shade_05: very subtle: hover states on surface
shade_10: subtle elevation: panels, cards, aside, blockquote, code
shade_20: more elevated: active/pressed states
shade_30: default border intensity
shade_100: maximum tinted contrast
shade_max: untinted contrast-side extreme: black in light mode, white in dark mode; rarely needed

Adaptive alpha overlays (fg/bg)
#

The fg and bg variables provide alpha-based overlays that adapt to the color scheme. Unlike the opaque shade scale, these stack when nested and are used by composites like .panel and .chip.

fg_NN (foreground direction) - darkens in light mode, lightens in dark mode; use for elevated surfaces like panels, cards, and hover states
bg_NN (background direction) - lightens in light mode, darkens in dark mode; use for surfaces that blend toward the background

In light mode, fg is the same as darken and bg is the same as lighten. In dark mode, they're swapped.

fg (toward foreground)
#

Adaptive alpha overlays that add contrast with the surface.

bg (toward background)
#

Adaptive alpha overlays that reduce contrast with the surface.

Stacking behavior
#

Unlike the opaque shade scale, alpha overlays stack when nested. Each layer adds more contrast:

<div class="fg_10 p_sm">
	<div class="fg_10 p_sm">
		<div class="fg_10 p_sm">
			<div class="fg_10 p_sm">
				...
			</div>
		</div>
	</div>
</div>

fg_10

nested fg_10

triple nested

quadruple nested

This is useful for nested UI elements like cards within cards, or hover states inside elevated containers. Composites like .panel, .chip, and .menu_item use fg_10 for this stacking behavior.

Darken/lighten alpha overlays
#

The non-adaptive darken_NN and lighten_NN variables provide consistent darkening or lightening regardless of color scheme. These are the underlying primitives that fg and bg reference.

Darken
#

Alpha overlays that always add black.

Lighten
#

Alpha overlays that always add white.

Visual balance
#

Both scales are tuned for visual balance, not mathematical spacing: 0%, 3%, 6%, 12%, 21%, 32%, 45%, 65%, 80%, 89%, 96%, 98%, 100%. This provides visually even steps across the range.

When to use which
#

Use fg_NN when you need stacking behavior or are building nested UI:

/* elevated panel (stacks when nested) */
background-color: var(--fg_10);

/* hover state (stacks on any background) */
background-color: var(--fg_10);

/* active/pressed state */
background-color: var(--fg_20);

Use shade_NN when you need explicit, predictable opaque surfaces:

/* base page background */
background-color: var(--shade_00);

/* opaque border */
border-color: var(--shade_30);

/* input backgrounds (untinted for contrast) */
background-color: var(--shade_min);

The composites (.panel, .chip, .menu_item) use fg_NN for stacking. The page background uses shade_00 as the opaque base.

Text colors
#

For text colors, see the text scale (text_00 through text_100). Both scales use the same "prominence" semantics for light and dark modes: low numbers are subtle, high numbers are strong. They're separate scales because text and backgrounds have different contrast requirements.