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:
- The component's own props (
variant,size, ...). Always first. - System style props (
m,p,display,w, ...). Token-backed, responsive. sxfor 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.