atoms

The atoms function provides low-level access to Braid’s reusable atomic classes within your vanilla‑extract stylesheets.

CSS utilities

The atoms function provides a suite of common CSS utility props. Styles that regularly differ across screen sizes can also be expressed as responsive values, e.g. atoms({ justifyContent: { mobile: 'center', tablet: 'flexStart' }})These utilities are recommended where possible to reduce the amount of custom CSS in your application.

// styles.css.ts
import { atoms } from 'braid-design-system/css';

export const className = atoms({
  display: 'flex',
  justifyContent: {
    mobile: 'center',
    tablet: 'flexStart',
  },
  position: 'absolute',
  top: 0,
  left: 0,
  width: 'full',
  height: 'full',
});

display (Responsive)"block", "flex", "inline", "inlineBlock", "none"

position (Responsive)"absolute", "fixed", "relative", "sticky"

borderRadius (Responsive)"full", "large", "none", "small", "standard", "xlarge"

gap (Responsive)"gutter", "large", "medium", "none", "small", "xlarge", "xsmall", "xxlarge", "xxsmall", "xxxlarge"

paddingTop (Responsive)"gutter", "large", "medium", "none", "small", "xlarge", "xsmall", "xxlarge", "xxsmall", "xxxlarge"

paddingBottom (Responsive)"gutter", "large", "medium", "none", "small", "xlarge", "xsmall", "xxlarge", "xxsmall", "xxxlarge"

paddingRight (Responsive)"gutter", "large", "medium", "none", "small", "xlarge", "xsmall", "xxlarge", "xxsmall", "xxxlarge"

paddingLeft (Responsive)"gutter", "large", "medium", "none", "small", "xlarge", "xsmall", "xxlarge", "xxsmall", "xxxlarge"

marginTop (Responsive)"gutter", "large", "medium", "none", "small", "xlarge", "xsmall", "xxlarge", "xxsmall", "xxxlarge"

marginBottom (Responsive)"gutter", "large", "medium", "none", "small", "xlarge", "xsmall", "xxlarge", "xxsmall", "xxxlarge"

marginRight (Responsive)"gutter", "large", "medium", "none", "small", "xlarge", "xsmall", "xxlarge", "xxsmall", "xxxlarge"

marginLeft (Responsive)"gutter", "large", "medium", "none", "small", "xlarge", "xsmall", "xxlarge", "xxsmall", "xxxlarge"

alignItems (Responsive)"center", "flexEnd", "flexStart"

justifyContent (Responsive)"center", "flexEnd", "flexStart", "spaceBetween"

flexDirection (Responsive)"column", "columnReverse", "row", "rowReverse"

flexWrap (Responsive)"nowrap", "wrap"

flexShrink (Responsive)0

flexGrow (Responsive)0, 1

textAlign (Responsive)"center", "left", "right"

transform (Pseudo)"touchable"

overflow"auto", "hidden", "scroll", "visible"

userSelect"none"

outline"focus", "none"

opacity0

zIndex0, 1, 2, "dropdown", "dropdownBackdrop", "modal", "modalBackdrop", "notification", "sticky"

cursor"default", "pointer"

pointerEvents"none"

top0

bottom0

left0

right0

height"full", "touchable"

width"full", "touchable"

minWidth0

maxWidth"content", "large", "medium", "small", "xsmall"

transition"fast", "touchable"

Padding and margins

Padding can be applied in all directions using our space scale. Margin is also supported with the same syntax, but padding is recommended over margin in most cases to avoid issues with collapsing margins.

// styles.css.ts
import { atoms } from 'braid-design-system/css';

export const className = atoms({ paddingX: 'gutter', paddingY: 'large' });

padding

paddingX

paddingY

paddingTop

paddingRight

paddingBottom

paddingLeft

Responsive padding and margins

Padding and margins can also differ across screen sizes by providing responsive values, e.g. padding={{ mobile: 'small', tablet: 'medium', desktop: 'large', wide: 'xlarge' }}

// styles.css.ts
import { atoms } from 'braid-design-system/css';

export const className = atoms({
  padding: {
    mobile: 'small',
    tablet: 'medium',
    desktop: 'large',
    wide: 'xlarge',
  },
});

Responsive padding

Shadows and borders

The atoms function provides a series of boxShadow values that handle a wide variety of use cases. Note that box shadows are also used for borders so that their presence doesn’t alter the dimensions of the element.

// styles.css.ts
import { atoms } from 'braid-design-system/css';

export const className = atoms({ boxShadow: 'large' });

These box shadows are likely to change over time, so it’s important that you only use them within the semantic context they were designed for, e.g. only using “borderField” for actual field borders. If you choose semantic box shadows based solely on their appearance, your application’s colours may change in unexpected ways when upgrading Braid.

smallUsed for small shadows.

mediumUsed for medium shadows.

largeUsed for large shadows.

borderNeutralUsed for neutral element borders.

borderNeutralLargeUsed for large neutral element borders.

borderNeutralInvertedUsed for neutral borders on dark backgrounds.

borderNeutralInvertedLargeUsed for large neutral borders on dark backgrounds.

borderNeutralLightUsed for light neutral element borders.

borderFieldUsed for borders around form fields.

outlineFocusUsed for focus states of interactive elements.

borderFormAccentUsed for borders around prominent interactive elements.

borderFormAccentLargeUsed for large borders around prominent interactive elements.

borderFormAccentLightUsed for borders around prominent interactive elements in a dark context.

borderFormAccentLightLargeUsed for large borders around prominent interactive elements in a dark context.

borderBrandAccentUsed for borders around branded elements.

borderBrandAccentLargeUsed for large borders around branded elements.

borderBrandAccentLightUsed for borders around branded elements in a dark context.

borderBrandAccentLightLargeUsed for large borders around branded elements in a dark context.

borderPositiveUsed for borders around “positive” elements.

borderPositiveLightUsed for borders around “positiveLight” elements.

borderCriticalUsed for borders around “critical” elements.

borderCriticalLargeUsed for large borders around “critical” elements.

borderCriticalLightUsed for borders around “criticalLight” elements.

borderCriticalLightLargeUsed for large borders around “criticalLight” elements.

borderCautionUsed for borders around “caution” elements.

borderCautionLightUsed for borders around “cautionLight” elements.

borderInfoUsed for borders around “info” elements.

borderInfoLightUsed for borders around “infoLight” elements.

borderPromoteUsed for borders around “promote” elements.

borderPromoteLightUsed for borders around “promoteLight” elements.

CSS reset

Braid uses locally-scoped classes to manage CSS resets. This is managed automatically when using Box elements, but if you’re targeting native non-Braid elements, you can manually apply a CSS reset via the reset option which accepts a native element type.

// styles.css.ts
import { atoms } from 'braid-design-system/css';

export const className = atoms({
  reset: 'span',
});

Focus outlines

As part of the CSS reset, Braid will automatically style the focus ring outline when specifying an interactive element in the reset property, i.e. “button”, “a”, “input”, etc.

// styles.css.ts
import { atoms } from 'braid-design-system/css';

export const className = atoms({
  reset: 'button',
});

When styling a non-interactive element, i.e. “div”, “span”, etc., or when not using a reset, it is necessary to opt in to the focus ring outline using outline: ‘focus’.

// styles.css.ts
import { atoms } from 'braid-design-system/css';

export const className = atoms({
  outline: 'focus'
});

To apply the focus outline to an element based on the focus of another element, see outlineStyle.