Styling

Every @hub/ds-components component mixes in the same token-backed style props, plus an sx escape hatch, and forwards standard DOM attributes. So you rarely need style={{ ... }} or a wrapper <div> for spacing and layout.

There are three layers, in order of preference:

  1. The component's own props (variant, size, ...). Always first.
  2. System style props (m, p, display, w, ...). Token-backed, responsive.
  3. sx for anything without a dedicated prop (border, background, pseudo-states).

System style props

Spacing props take a step on the token spacing scale, never a raw pixel value. The step maps to a @hub/ds-tokens value (2 to Spacing2 to 8px; 0.5 to 2px). Valid steps: 0, 0.5, 1, 2, 3, 4, 5, 6, 8, 10, 12, 16, 20, 24.

import { Button, Box } from '@hub/ds-components';

<Button mt={4} mb={2}>Save</Button>
<Box p={4} px={6}>Padded 16px, 24px inline</Box>

| Group | Props | | --- | --- | | Margin | m, mt, mr, mb, ml, mx, my | | Padding | p, pt, pr, pb, pl, px, py | | Size | w, h ('full' / 'auto' / 'fit') | | Layout | display, alignSelf, justifySelf, grow, shrink |

mx/my/px/py are the axis shorthands. w="full" is 100%, w="fit" is fit-content.

Flex-container props (Box and Stack)

Container controls live on Box (and mirror Stack), since they only mean something on a flex parent. Combine with display="flex".

<Box display="flex" align="center" justify="end" gap={2} w="full">
  <Button variant="outlined">Cancel</Button>
  <Button>Save</Button>
</Box>

| Prop | CSS | | --- | --- | | align | align-items (start / center / end / stretch / baseline) | | justify | justify-content (start / center / end / between / around / evenly) | | direction | flex-direction (row / column / row-reverse / column-reverse) | | wrap | flex-wrap (boolean) | | gap | gap on the spacing scale |

Responsive values

Every style prop also accepts a mobile-first map keyed by breakpoint. Missing breakpoints inherit the next-smaller value.

<Box
  direction={{ mobile: 'column', desktop: 'row' }}
  gap={{ mobile: 2, desktop: 4 }}
  p={{ mobile: 2, desktop: 6 }}
/>

Breakpoints: mobile (< 768px), tablet (768 to 1023px), desktop (>= 1024px). Single values apply at every breakpoint; responsive maps emit a scoped stylesheet with the tablet/desktop media queries (an inline style could not be overridden by a media query, so maps have to be a stylesheet).

sx: the escape hatch

For styles with no dedicated prop (border, background, box-shadow, pseudo-classes), use sx. It is token-aware: numeric spacing values resolve against the scale, other numbers become px, and you can nest selectors (&:hover, ::placeholder) and pass responsive maps.

import { Box } from '@hub/ds-components';
import { ColorOtherOutlinedBorder, BorderRadiusMd } from '@hub/ds-tokens';

<Box
  p={4}
  sx={{
    border: `1px solid ${ColorOtherOutlinedBorder}`,
    borderRadius: BorderRadiusMd,
    transition: 'background-color 120ms',
    '&:hover': { backgroundColor: 'var(--color-background-paper)' },
  }}
>
  hover me
</Box>

Prefer the dedicated props for spacing and layout; reach for sx only for the rest.

Limitation. A :hover or responsive sx override cannot beat a property the component sets on its own root inline style (an inline style always wins over a generated class rule). Flat sx overrides fine; for a pseudo or breakpoint override of such a property, use the dedicated prop instead.

Custom attributes

Components forward standard DOM attributes to the underlying element, so id, data-*, aria-*, and event handlers work as expected.

<Button data-testid="save" aria-label="Save" onClick={save}>Save</Button>
<Box id="panel" data-section="settings">...</Box>

Style props are stripped before the spread, so m/p/sx never leak to the DOM as invalid attributes.

Precedence

A raw style={{ ... }} on a component wins over the equivalent system prop (inline beats the generated rule):

<Box mt={8} style={{ marginTop: 0 }} /> // renders with no top margin

Use this only as a deliberate override. For token-safe styling, stick to the props and sx.