Skip to main content

css

Curated CSS value unions — colors, display, position, lengths, vars.

import type {
  CSSGlobal, CSSNamedColor, CSSSystemColor, CSSSpecialColor, CSSColor,
  CSSDisplay, CSSPosition,
  CSSFlexDirection, CSSJustifyContent, CSSAlignItems,
  CSSCursor, CSSLineStyle,
  CSSLengthUnit, CSSLength,
  CSSVar, CSSCustomProp,
} from '@gentleduck/ttest/css'

Curated CSS value unions sized to give autocomplete without blowing up the type-checker. Use for component props that want type-safe CSS-shaped strings; widen to string at the consumer boundary for esoteric values.

CSSGlobal

type CSSGlobal = 'inherit' | 'initial' | 'unset' | 'revert' | 'revert-layer'

The CSS-wide keyword values every property accepts.

CSSNamedColor

type CSSNamedColor = 'aliceblue' | 'antiquewhite' | ... | 'yellowgreen'

All 147 CSS named colors (level 4).

const accent: CSSNamedColor = 'rebeccapurple'  // ok
const bad:    CSSNamedColor = 'almostblue'     // Error

CSSSystemColor

type CSSSystemColor = 'Canvas' | 'CanvasText' | 'LinkText' | ...

Theme-aware system colors. Capitalized — these are reserved keywords.

CSSSpecialColor

type CSSSpecialColor = 'transparent' | 'currentColor'

CSSColor

type CSSColor =
  | CSSNamedColor | CSSSystemColor | CSSSpecialColor
  | `#${string}` | `rgb(${string})` | `rgba(${string})`
  | `hsl(${string})` | `hsla(${string})` | `oklch(${string})` | `color(${string})`

Union of every supported color form.

const a: CSSColor = 'rebeccapurple'                // named
const b: CSSColor = '#1a1a1a'                      // hex
const c: CSSColor = 'rgb(255, 0, 0)'               // rgb
const d: CSSColor = 'oklch(70% 0.15 200)'          // oklch

Edge case: hex shape is `#${string}`; the union does not enforce 3/6/8-digit hex syntax. Validate at runtime if shape matters.

CSSDisplay

type CSSDisplay = 'block' | 'inline' | 'inline-block' | 'flex' | 'grid' | 'flow-root' | ...

CSSPosition

type CSSPosition = 'static' | 'relative' | 'absolute' | 'fixed' | 'sticky'

CSSFlexDirection

type CSSFlexDirection = 'row' | 'row-reverse' | 'column' | 'column-reverse'

CSSJustifyContent

type CSSJustifyContent =
  | 'flex-start' | 'flex-end' | 'center'
  | 'space-between' | 'space-around' | 'space-evenly'
  | 'start' | 'end' | 'left' | 'right' | 'stretch' | 'normal'

CSSAlignItems

type CSSAlignItems =
  | 'flex-start' | 'flex-end' | 'center'
  | 'baseline' | 'first baseline' | 'last baseline'
  | 'stretch' | 'start' | 'end' | 'self-start' | 'self-end' | 'normal'

CSSCursor

type CSSCursor = 'auto' | 'pointer' | 'grab' | 'grabbing' | 'col-resize' | ...

CSSLineStyle

type CSSLineStyle = 'none' | 'hidden' | 'dotted' | 'dashed' | 'solid' | 'double' | 'groove' | 'ridge' | 'inset' | 'outset'

CSSLengthUnit

type CSSLengthUnit = 'px' | 'em' | 'rem' | '%' | 'vh' | 'vw' | 'ch' | 'pt' | 'svh' | 'dvw' | ...

Every absolute, relative, and viewport-relative length unit.

CSSLength

type CSSLength = `${number}${CSSLengthUnit}` | '0' | `calc(${string})`

A length expression: a number with a unit, the bare zero, or any calc(...) form.

const a: CSSLength = '1.5rem'
const b: CSSLength = '0'                          // bare zero
const c: CSSLength = 'calc(100% - 2px)'
const d: CSSLength = '24'                          // Error — bare numbers other than 0 are rejected

CSSVar

type CSSVar<Name extends string = string> = `var(--${Name})` | `var(--${Name}, ${string})`

A var(...) reference, optionally with a fallback.

const a: CSSVar<'fg'> = 'var(--fg)'
const b: CSSVar<'fg'> = 'var(--fg, white)'
const c: CSSVar       = 'var(--anything)'  // wildcard name

CSSCustomProp

type CSSCustomProp<Name extends string = string> = `--${Name}`

A CSS custom-property name.

const a: CSSCustomProp<'theme'> = '--theme'
const b: CSSCustomProp          = '--any-name'

Edge case: every union here is a curated subset. Refusing values outside the curated set is sometimes the goal, sometimes friction. When friction wins, widen to string at the consumer boundary.