css-in-props

css-in-props

CSS properties as component props for DOMQL elements. Transforms design-system-aware props into CSS classes via the atomic CSS engine (@symbo.ls/css).

What it does

• Transforms component props (theme, color, background, border, shadow, etc.) into resolved CSS
• Resolves design system tokens (colors, spacing, typography, themes) from @symbo.ls/scratch
• Handles media queries (@dark, @mobileS, etc.) and pseudo selectors (:hover, :focus) as prop prefixes
• Generates atomic CSS classes for optimized rendering (one class per property-value pair)

Theme prop

The theme prop resolves theme definitions into CSS variables. Theme switching is handled entirely by CSS — no DOMQL re-renders needed.

const Card = {
  theme: 'primary',           // uses --theme-primary-* CSS vars
  // themeModifier: 'dark',   // optional: force a specific scheme on this component
}

When globalTheme is 'auto' (default), CSS variables switch automatically via prefers-color-scheme media queries and [data-theme] selectors.

Props reference

Category	Props
Theme	theme, color, background, backgroundColor, borderColor
Border	border, borderLeft, borderTop, borderRight, borderBottom, outline
Shadow	shadow, boxShadow, textShadow
Text	textStroke
Image	backgroundImage
Layout	outlineOffset

Media and selector props

Props can be prefixed with media queries or selectors:

const Button = {
  background: 'blue',
  ':hover': { background: 'darkblue' },
  '@mobileS': { padding: 'A' },
  '.active': { background: 'green' }
}

transformersByPrefix

The prefix-to-handler registry that powers media queries, selectors, conditionals, and variables. Each key is a single-character prefix that triggers a specific transformer when found at the start of a prop key:

Prefix	Handler	Example
@	Media query	@mobileS, @dark, @print
:	Pseudo selector	:hover, :focus, :first-child
[	Attribute selector	[disabled], [data-active]
>	Child combinator	> .child
&	Self selector	&.active
$	Global case (from context.cases)	$isSafari
.	Truthy conditional (props/state, then context.cases)	.visible
!	Falsy conditional (props/state, then context.cases)	!hidden
-	CSS variable	--my-var
*, +, ~	CSS combinators	* div, + .sibling, ~ .general

import { transformersByPrefix } from 'css-in-props'

Interaction with the define system

The $ prefix is used both by css-in-props ($isActive case conditional) and by the define system (e.g. $router). The framework resolves this by checking for define handlers before applying prefix rules. Keys with matching define handlers stay at the element root; only $-prefixed keys without define handlers are processed by css-in-props.

In v3.14, properties go directly on the element (no props: wrapper). The CSS engine processes design token properties internally.

Global Cases

Cases are defined in symbols/cases.js and added to context.cases (not designSystem). Case functions receive the element as this and as the first argument, but must also work without element context (arrow functions).

// symbols/cases.js
export default {
  isSafari: () => /Safari/.test(navigator.userAgent) && !/Chrome/.test(navigator.userAgent),
  isGeorgian () { return this?.state?.root?.language === 'ka' },
  isMobile: () => window.innerWidth < 768
}

// symbols/context.js
import cases from './cases.js'
export default { cases, /* ...other context */ }

Resolution order

• $ prefix: Checks context.cases[key] first (call if function, check truthiness if value). Falls back to element[key].
• . prefix: Checks element[key] / element.state[key] first. Falls back to context.cases[key].
• ! prefix: Same as . but inverted — applies when condition is falsy.

const Button = {
  padding: 'A',
  '$isSafari': { padding: 'B' },           // global case
  '.isActive': { background: 'blue' },      // props/state, then cases
  '!isMobile': { maxWidth: '1200px' }       // inverted
}

CSS Variable Resolution

String values starting with -- are automatically wrapped in var() for all CSS properties:

const Box = {
  padding: '--my-gap',      // → var(--my-gap)
  fontSize: '--base-size',  // → var(--base-size)
}