Tonic UI Sx

Tonic UI: sx vs __sx

All docs/ and packages/ paths are relative to the repository root. Component paths such as button/Button.js are relative to packages/react/src/. Read composition and verification when implementing a wrapper, transition, multi-feature prop getter, or regression check. Its worked examples and verification cases supplement the core rules below.

When to Use

Use this skill for component base styles, useXxxStyle() hooks, Box style routing, incoming __sx folds, wrappers overriding children, and headless-library prop getters such as react-table's getRowProps() / getHeaderProps(). It applies to any package rendering Tonic UI Box-based components, including external data-grid integrations. Also use it to investigate dropped wrapper styles or consumer overrides that lose.

Current Integration Status

Full __sx integration is not complete in this Tonic UI checkout. The helper, Box channel, and useSlot composition exist, and some components use them; the examples below describe the target styling convention, not proof that every component already follows it. Inspect the affected implementation before relying on it, and do not expand a task into full styling integration without a user request.

The one rule that governs everything: precedence-by-origin

A component's base styling always loses to a consumer override, regardless of which CSS property each touches. A wrapper's child-override beats the child's base but still loses to the end consumer. To make that true structurally (not by convention), Tonic UI routes who wrote the style to a fixed channel — and the channel decides precedence.

So the question is never "what does this style do?" but "who is writing it?"

• You are the component author, styling your own Box → __sx (lowest tier).
• You are a wrapper, overriding a child component you render → also __sx (folded into the child's incoming __sx).
• You are the consumer (app developer) → sx (highest tier), or style props / pseudo props.

A component never writes its own styling to sx. sx is the consumer's escape hatch.

"Writing it" isn't limited to a component's own render body. A higher-order component wrapping a child, or a headless-library plugin contributing props via a getter function (e.g. react-table's getRowProps()/getHeaderProps(), composed across features by a shallow merge), is just as much "the component author" for this purpose as a render body is — the same hand-built-style-object, hand-merged-via-ensureArray-or-object-spread failure shows up there too, just one layer removed from JSX.

The four channels of Box

Box concatenates four ordered channels into one Emotion class. For declarations of the same property at the same selector specificity, a later channel wins.

__sx and sx accept the identical authoring format: flat declarations, nested selectors ('& svg', '&:hover'), pseudo shortcuts (_hover), theme => … functions, design tokens, responsive arrays. They differ only in tier (who they belong to), not in what they can express.

Why __sx exists (the problem it solves)

Before __sx, base styling was authored as style props (tier 1) + pseudo props (tier 3). That made precedence a function of which kind of prop a value is — not who wrote it. Two failures followed:

• A component that needed nested selectors or pseudo-elements (which flat style props can't express) had to author base styling via sx — but then the component's sx outranked the consumer's style props and sx (single shared slot), so the consumer could no longer override. Backwards.
• Wrappers overriding a child had to squat on the consumer's sx channel and hand-merge the consumer's sx back on top (sx={[ownSx, ...ensureArray(sx)]}) — done inconsistently across the codebase, silently dropping overrides when an author forgot the spread.

__sx is a dedicated lowest-priority channel that reuses the sx transform. Base styling goes there; consumer style props and sx sit above it and override it. Precedence-by-kind becomes precedence-by-origin, with no per-author merge bets.

How to author base styling: the uniform fold

Every base-styling component follows the same call site. You cannot predict which components a future wrapper will inject __sx into, so apply this uniformly — don't pick and choose:

import { composeSx } from '@tonic-ui/utils/internal';

const MyComponent = forwardRef((inProps, ref) => {
  const {
    // ...component props...
    __sx: __sxProp,                 // destructure incoming __sx OUT of rest
    ...rest
  } = useDefaultProps({ props: inProps, name: 'MyComponent' });

  const styleProps = useMyComponentStyle(/* state */); // the COMPLETE base: flat + pseudo + nested

  return (
    <Box
      ref={ref}
      {...rest}
      __sx={composeSx(styleProps, __sxProp)}   // own base first, incoming __sx folded last
    />
  );
});

Why each part matters:

• __sx is destructured out of rest so it is not applied twice (once via the spread, once via the explicit prop).
• composeSx(styleProps, __sxProp) is placed after {...rest} so the explicit __sx wins the spread, and the incoming __sx (already folded) lands after the component's own base → an injected override beats the component's base, while the consumer's sx (tier 4) still beats everything.
• useXxxStyle() returns the component's complete base — flat layout, pseudo rules, and nested selectors in one value (an object, or an array when conditional/order-sensitive parts must compose). There is no separate get*Sx function; it was folded into useXxxStyle.

Destructure __sx: __sxProp (and ...rest) directly from useDefaultProps — in one line. Do not capture the whole bag as const props = useDefaultProps(...). You need two things the opaque bag can't give you cleanly: the incoming __sx pulled out (so it isn't applied twice) and a ...rest that no longer contains it (so the explicit __sx={composeSx(...)} after the spread wins). The one-line destructure is the canonical form:

// ✅ canonical — destructure inline
const { __sx: __sxProp, ...rest } = useDefaultProps({ props: inProps, name: 'X' });
const styleProps = useXxxStyle(...);
return <Child {...rest} __sx={composeSx(styleProps, __sxProp)} />;

// ❌ opaque bag — can't fold cleanly; `{...props}` carries an unfolded `__sx`,
//    and adding `__sx={...}` alongside it double-applies or collides
const props = useDefaultProps({ props: inProps, name: 'X' });
return <Child {...props} __sx={composeSx(styleProps, props.__sx)} />;

// ❌ two-step — works, but re-destructuring from a captured bag is noise; inline it
const props = useDefaultProps({ props: inProps, name: 'X' });
const { __sx: __sxProp, ...rest } = props;

composeSx: array composition, never object merge

const composeSx = (...values) => values.flatMap((value) => ensureArray(value));
// import { composeSx } from '@tonic-ui/utils/internal';   (internal — not the public barrel)

composeSx is variadic — pass any number of sx-values (composeSx(base, a, b)); arrays are flattened and undefined is skipped. It returns an array for the __sx/sx prop. Do not spread it as props.

If you author the element through useSlot, you don't fold __sx yourself. useSlot composes both ref (via useMergeRefs) and __sx (via composeSx) across props and slotProps internally — put the base in props.__sx, pass the consumer's slot props as slotProps, and the base stays below the slot's __sx. Do not strip __sx out of the slot props or hand-merge it; that's the hook's job (mirrors how it merges ref):

const [Slot, slotProps] = useSlot({
  props: { ref: combinedRef, __sx: baseStyle },  // base — useSlot keeps it below slotProps.__sx
  slot: slots.x ?? Default,
  slotProps: resolvedSlotProps,                   // consumer ref + __sx merged by useSlot
});

This is the single most important pitfall. Combining two sx-objects must use array composition ([a, b]), not object merge ({...a, ...b}):

• Array → both objects are emitted; source order resolves conflicts per declaration. An incoming &:hover partially overrides the base &:hover (changes color, keeps the base background).
• Object merge → a nested key like &:hover from b replaces a's &:hover entirely. The base hover styling is discarded. This is the wrong behavior and a common bug.

When there is no incoming value to fold (e.g. a sub-element whose style has no consumer __sx slot), pass the style object directly — composeSx adds nothing:

// Folding an incoming __sx → use composeSx:
<Box {...rest} __sx={composeSx(styleProps, __sxProp)} />

// No incoming __sx → pass directly:
return { ref, onMouseDown, __sx: trackStyleProps };