Core props | Foundations

SWAN provides a set of core props that can be used on any component.

Many of them indicate that they have Responsive support—this means you can provide different values for different screen sizes. For more information, see Responsive System.

Color props

Color contains two categories of core props: text color and background color. Like other core props, the allowed values for these props align with tokens.

For more information, see Color.

<Box bgc="standard" textColor="standard">
  standard
</Box>

<Box bgc="standard" textColor="standard">
  standard
</Box>

Text color

The textColor prop is a core prop that can be used to change the color of text.

Ensure that text and background meet a 4.5:1 color contrast ratio.

<GridContainer>
  <Row fontSkin="title-subsection" mb={5}>
    <Column span={6}>Standard mode</Column>
    <Column span={6}>Dark mode</Column>
  </Row>
  <Row>
    <Column span={6}>
      <Box textColor="standard" standardMode>
        standard
      </Box>
    </Column>
    <Column span={6}>
      <Box textColor="standard" darkMode bgc="standard" px={3}>
        standard
      </Box>
    </Column>
  </Row>
  <Row>
    <Column span={6}>
      <Box textColor="subtle" standardMode>
        subtle
      </Box>
    </Column>
    <Column span={6}>
      <Box textColor="subtle" darkMode bgc="standard" px={3}>
        subtle
      </Box>
    </Column>
  </Row>
  <Row>
    <Column span={6}>
      <Box textColor="info" standardMode>
        info
      </Box>
    </Column>
    <Column span={6}>
      <Box textColor="info" darkMode bgc="standard" px={3}>
        info
      </Box>
    </Column>
  </Row>
  <Row>
    <Column span={6}>
      <Box textColor="accent" standardMode>
        accent
      </Box>
    </Column>
    <Column span={6}>
      <Box textColor="accent" darkMode bgc="standard" px={3}>
        accent
      </Box>
    </Column>
  </Row>
  <Row>
    <Column span={6}>
      <Box textColor="success" standardMode>
        success
      </Box>
    </Column>
    <Column span={6}>
      <Box textColor="success" darkMode bgc="standard" px={3}>
        success
      </Box>
    </Column>
  </Row>
  <Row>
    <Column span={6}>
      <Box textColor="warning" standardMode>
        warning
      </Box>
    </Column>
    <Column span={6}>
      <Box textColor="warning" darkMode bgc="standard" px={3}>
        warning
      </Box>
    </Column>
  </Row>
  <Row>
    <Column span={6}>
      <Box textColor="error" standardMode>
        error
      </Box>
    </Column>
    <Column span={6}>
      <Box textColor="error" darkMode bgc="standard" px={3}>
        error
      </Box>
    </Column>
  </Row>
  <Row>
    <Column span={6}>
      <Box textColor="promo" standardMode>
        promo
      </Box>
    </Column>
    <Column span={6}>
      <Box textColor="promo" darkMode bgc="standard" px={3}>
        promo
      </Box>
    </Column>
  </Row>
  <Row>
    <Column span={6}>
      <Box textColor="help" standardMode>
        help
      </Box>
    </Column>
    <Column span={6}>
      <Box textColor="help" darkMode bgc="standard" px={3}>
        help
      </Box>
    </Column>
  </Row>
</GridContainer>

<GridContainer>
  <Row fontSkin="title-subsection" mb={5}>
    <Column span={6}>Standard mode</Column>
    <Column span={6}>Dark mode</Column>
  </Row>
  <Row>
    <Column span={6}>
      <Box textColor="standard" standardMode>
        standard
      </Box>
    </Column>
    <Column span={6}>
      <Box textColor="standard" darkMode bgc="standard" px={3}>
        standard
      </Box>
    </Column>
  </Row>
  <Row>
    <Column span={6}>
      <Box textColor="subtle" standardMode>
        subtle
      </Box>
    </Column>
    <Column span={6}>
      <Box textColor="subtle" darkMode bgc="standard" px={3}>
        subtle
      </Box>
    </Column>
  </Row>
  <Row>
    <Column span={6}>
      <Box textColor="info" standardMode>
        info
      </Box>
    </Column>
    <Column span={6}>
      <Box textColor="info" darkMode bgc="standard" px={3}>
        info
      </Box>
    </Column>
  </Row>
  <Row>
    <Column span={6}>
      <Box textColor="accent" standardMode>
        accent
      </Box>
    </Column>
    <Column span={6}>
      <Box textColor="accent" darkMode bgc="standard" px={3}>
        accent
      </Box>
    </Column>
  </Row>
  <Row>
    <Column span={6}>
      <Box textColor="success" standardMode>
        success
      </Box>
    </Column>
    <Column span={6}>
      <Box textColor="success" darkMode bgc="standard" px={3}>
        success
      </Box>
    </Column>
  </Row>
  <Row>
    <Column span={6}>
      <Box textColor="warning" standardMode>
        warning
      </Box>
    </Column>
    <Column span={6}>
      <Box textColor="warning" darkMode bgc="standard" px={3}>
        warning
      </Box>
    </Column>
  </Row>
  <Row>
    <Column span={6}>
      <Box textColor="error" standardMode>
        error
      </Box>
    </Column>
    <Column span={6}>
      <Box textColor="error" darkMode bgc="standard" px={3}>
        error
      </Box>
    </Column>
  </Row>
  <Row>
    <Column span={6}>
      <Box textColor="promo" standardMode>
        promo
      </Box>
    </Column>
    <Column span={6}>
      <Box textColor="promo" darkMode bgc="standard" px={3}>
        promo
      </Box>
    </Column>
  </Row>
  <Row>
    <Column span={6}>
      <Box textColor="help" standardMode>
        help
      </Box>
    </Column>
    <Column span={6}>
      <Box textColor="help" darkMode bgc="standard" px={3}>
        help
      </Box>
    </Column>
  </Row>
</GridContainer>

Background color

The backgroundColor (or bgc) prop is a core prop that can be used to change the color of the background.

Ensure that text and background meet a 4.5:1 color contrast ratio. The BACKGROUND_WITH_MODE object can be used to dynamically set Dark mode to ensure the correct contrast.

<GridContainer>
  <Row fontSkin="title-subsection" mb={5}>
    <Column span={6}>Standard mode</Column>
    <Column span={6}>Dark mode</Column>
  </Row>
  <Row>
    <Column span={6}>
      <Box bgc="standard" standardMode p={3}>
        standard
      </Box>
    </Column>
    <Column span={6}>
      <Box bgc="standard" darkMode p={3}>
        standard
      </Box>
    </Column>
  </Row>
  <Row>
    <Column span={6}>
      <Box bgc="strong" standardMode p={3}>
        strong
      </Box>
    </Column>
    <Column span={6}>
      <Box bgc="strong" darkMode p={3}>
        strong
      </Box>
    </Column>
  </Row>
  <Row>
    <Column span={6}>
      <Box bgc="black" standardMode p={3}>
        black
      </Box>
    </Column>
    <Column span={6}>
      <Box bgc="black" darkMode p={3}>
        black
      </Box>
    </Column>
  </Row>
  <Row>
    <Column span={6}>
      <Box bgc="transparent" standardMode p={3}>
        transparent
      </Box>
    </Column>
    <Column span={6}>
      <Box bgc="transparent" darkMode p={3}>
        transparent
      </Box>
    </Column>
  </Row>
  <Row fontWeight="bold" fontSkin="title-item" mt={5} mb={3}>
    <Column span={6}>Semantic colors</Column>
    <Column span={6}></Column>
  </Row>
  <Row>
    <Column span={6}>
      <Box bgc="info" standardMode p={3}>
        info
      </Box>
    </Column>
    <Column span={6}>
      <Box bgc="info" darkMode p={3}>
        info
      </Box>
    </Column>
  </Row>
  <Row>
    <Column span={6}>
      <Box bgc="accent" standardMode p={3}>
        accent
      </Box>
    </Column>
    <Column span={6}>
      <Box bgc="accent" darkMode p={3}>
        accent
      </Box>
    </Column>
  </Row>
  <Row>
    <Column span={6}>
      <Box bgc="success" standardMode p={3}>
        success
      </Box>
    </Column>
    <Column span={6}>
      <Box bgc="success" darkMode p={3}>
        success
      </Box>
    </Column>
  </Row>
  <Row>
    <Column span={6}>
      <Box bgc="warning" standardMode p={3}>
        warning
      </Box>
    </Column>
    <Column span={6}>
      <Box bgc="warning" darkMode p={3}>
        warning
      </Box>
    </Column>
  </Row>
  <Row>
    <Column span={6}>
      <Box bgc="error" standardMode p={3}>
        error
      </Box>
    </Column>
    <Column span={6}>
      <Box bgc="error" darkMode p={3}>
        error
      </Box>
    </Column>
  </Row>
  <Row>
    <Column span={6}>
      <Box bgc="promo" standardMode p={3}>
        promo
      </Box>
    </Column>
    <Column span={6}>
      <Box bgc="promo" darkMode p={3}>
        promo
      </Box>
    </Column>
  </Row>
  <Row>
    <Column span={6}>
      <Box bgc="help" standardMode p={3}>
        help
      </Box>
    </Column>
    <Column span={6}>
      <Box bgc="help" darkMode p={3}>
        help
      </Box>
    </Column>
  </Row>
  <Row fontWeight="bold" fontSkin="title-item" mt={5} mb={3}>
    <Column span={6}>Brand colors</Column>
    <Column span={6}></Column>
  </Row>
  <Row>
    <Column span={6}>
      <Box bgc="warm-white" standardMode p={3}>
        warm-white
      </Box>
    </Column>
    <Column span={6}>
      <Box bgc="warm-white" darkMode p={3}>
        warm-white
      </Box>
    </Column>
  </Row>
  <Row>
    <Column span={6}>
      <Box bgc="midnight" standardMode p={3}>
        midnight
      </Box>
    </Column>
    <Column span={6}>
      <Box bgc="midnight" darkMode p={3}>
        midnight
      </Box>
    </Column>
  </Row>
</GridContainer>

<GridContainer>
  <Row fontSkin="title-subsection" mb={5}>
    <Column span={6}>Standard mode</Column>
    <Column span={6}>Dark mode</Column>
  </Row>
  <Row>
    <Column span={6}>
      <Box bgc="standard" standardMode p={3}>
        standard
      </Box>
    </Column>
    <Column span={6}>
      <Box bgc="standard" darkMode p={3}>
        standard
      </Box>
    </Column>
  </Row>
  <Row>
    <Column span={6}>
      <Box bgc="strong" standardMode p={3}>
        strong
      </Box>
    </Column>
    <Column span={6}>
      <Box bgc="strong" darkMode p={3}>
        strong
      </Box>
    </Column>
  </Row>
  <Row>
    <Column span={6}>
      <Box bgc="black" standardMode p={3}>
        black
      </Box>
    </Column>
    <Column span={6}>
      <Box bgc="black" darkMode p={3}>
        black
      </Box>
    </Column>
  </Row>
  <Row>
    <Column span={6}>
      <Box bgc="transparent" standardMode p={3}>
        transparent
      </Box>
    </Column>
    <Column span={6}>
      <Box bgc="transparent" darkMode p={3}>
        transparent
      </Box>
    </Column>
  </Row>
  <Row fontWeight="bold" fontSkin="title-item" mt={5} mb={3}>
    <Column span={6}>Semantic colors</Column>
    <Column span={6}></Column>
  </Row>
  <Row>
    <Column span={6}>
      <Box bgc="info" standardMode p={3}>
        info
      </Box>
    </Column>
    <Column span={6}>
      <Box bgc="info" darkMode p={3}>
        info
      </Box>
    </Column>
  </Row>
  <Row>
    <Column span={6}>
      <Box bgc="accent" standardMode p={3}>
        accent
      </Box>
    </Column>
    <Column span={6}>
      <Box bgc="accent" darkMode p={3}>
        accent
      </Box>
    </Column>
  </Row>
  <Row>
    <Column span={6}>
      <Box bgc="success" standardMode p={3}>
        success
      </Box>
    </Column>
    <Column span={6}>
      <Box bgc="success" darkMode p={3}>
        success
      </Box>
    </Column>
  </Row>
  <Row>
    <Column span={6}>
      <Box bgc="warning" standardMode p={3}>
        warning
      </Box>
    </Column>
    <Column span={6}>
      <Box bgc="warning" darkMode p={3}>
        warning
      </Box>
    </Column>
  </Row>
  <Row>
    <Column span={6}>
      <Box bgc="error" standardMode p={3}>
        error
      </Box>
    </Column>
    <Column span={6}>
      <Box bgc="error" darkMode p={3}>
        error
      </Box>
    </Column>
  </Row>
  <Row>
    <Column span={6}>
      <Box bgc="promo" standardMode p={3}>
        promo
      </Box>
    </Column>
    <Column span={6}>
      <Box bgc="promo" darkMode p={3}>
        promo
      </Box>
    </Column>
  </Row>
  <Row>
    <Column span={6}>
      <Box bgc="help" standardMode p={3}>
        help
      </Box>
    </Column>
    <Column span={6}>
      <Box bgc="help" darkMode p={3}>
        help
      </Box>
    </Column>
  </Row>
  <Row fontWeight="bold" fontSkin="title-item" mt={5} mb={3}>
    <Column span={6}>Brand colors</Column>
    <Column span={6}></Column>
  </Row>
  <Row>
    <Column span={6}>
      <Box bgc="warm-white" standardMode p={3}>
        warm-white
      </Box>
    </Column>
    <Column span={6}>
      <Box bgc="warm-white" darkMode p={3}>
        warm-white
      </Box>
    </Column>
  </Row>
  <Row>
    <Column span={6}>
      <Box bgc="midnight" standardMode p={3}>
        midnight
      </Box>
    </Column>
    <Column span={6}>
      <Box bgc="midnight" darkMode p={3}>
        midnight
      </Box>
    </Column>
  </Row>
</GridContainer>

MARKETING_COLORS deprecated in SWAN v3.2

Import the object from @vp/marketing-colors instead. Find more information and migration documentation in the Deprecation roadmap.

For marketing-specific background colors, the MARKETING_COLORS object offers a set of approved marketing-only background colors for use in Contentful/Builder. These can be used with whitelisted SWAN components (such as Banner) through the --swan-public-marketing-background CSS Custom Property.

Vanilla

In the vanilla API, the text color CSS class is swan-text-color-[color], e.g. swan-text-color-error.

In the vanilla API, the background color CSS class is swan-bgc-[color], e.g. swan-bgc-error.)

Text props

To apply text styling on any component it strongly recommended to use the fontSkin prop. This props adds all styling required to match the semantically grouped font styles.

If that doesn't suit you can then use other typography props to change things individually like font size, weight, family, color, capitalization, and alignment.

All of these props except fontSkin, fontSize and fontFamily have Responsive support. The fontSkin and fontSize props inherently adjust based on the screen size.

For more information, see Typography.

<SwanComponent
  fontSize="x1"
  // other than fontSize, you can handle these props responsively
  textAlign={{ xs: 'left', sm: 'right' }}
  textColor={{ sm: 'alert', lg: 'black' }}
  fontWeight={{ xs: 'normal', md: 'bold' }}
  textAllCaps={{ sm: true, lg: false }}
/>

<SwanComponent
  fontSize="x1"
  // other than fontSize, you can handle these props responsively
  textAlign={{ xs: 'left', sm: 'right' }}
  textColor={{ sm: 'alert', lg: 'black' }}
  fontWeight={{ xs: 'normal', md: 'bold' }}
  textAllCaps={{ sm: true, lg: false }}
/>

Space props

Space contains two categories of core props: margin and padding. Like other core props, the allowed values for these props align with tokens. Both named semantic and numeric semantic values can be used.

Space can be set in 1, 2, or 4 dimensions, similar to their shorthand CSS equivalents. Multiple props can be added to the same component, but setting multiple props that change the same dimension is not advised.

Refer to Space for more information on how space props should be used.

<Box px="4" mb="between-sections" />

<Box px="4" mb="between-sections" />

Margin and padding

In the table below, "x" sets the x-axis (both left and right), while "y" sets the y-axis (both top and bottom).

Prop	Allowed values
margin / m	1-12, auto
marginX / mx	1-12, auto, between-actions, to-actions
marginY / my	1-12, auto, between-sections, between-subsections, between-actions, to-actions
marginTop / mt	1-12, auto, between-sections, between-subsections, between-actions, to-actions
marginRight / mr	1-12, auto, between-actions, to-actions, between-icon-and-text
marginBottom / mb	1-12, auto, between-sections, between-subsections, between-actions, to-actions
marginLeft / ml	1-12, auto, between-actions, to-actions, between-icon-and-text
padding / p	1-12
paddingX / px	1-12
paddingY / py	1-12
paddingTop / pt	1-12
paddingRight / pr	1-12
paddingBottom / pb	1-12
paddingLeft / pl	1-12

Responsive

All props support responsive values, allowing for different values on different screen sizes.

<Box px={{ xs: 3, sm: 4, md: 5 }} py={{ xs: 4, md: 6, lg: 4, xl: 7 }} />

<Box px={{ xs: 3, sm: 4, md: 5 }} py={{ xs: 4, md: 6, lg: 4, xl: 7 }} />

Vanilla

The Vanilla API follows the format of swan-[shorthand property]-[size], e.g. swan-mt-2.

Mode props

You can change the appearance of UI via modes. Modes can be activated through their respective core prop, e.g. darkMode. Different modes can be used together as needed, e.g. darkMode and compactMode. Modes can also be nested. To reset to the default token values, standardMode can be applied to overwrite all other modes.

For more information, See Modes.

Render props

You can change which HTML element a SWAN React component renders. For instance, maybe you want an Icon to be a <button> tag, or want your tile to be an <a> tag.

() => {
  return (
    <Accordion fullBleed>
      <BasicCollapsible collapsibleId="as" heading="as / component">
        <Card bordered as="a" href="#url">
          Card as an &lt;a&gt; tag.
        </Card>
        <P>
          <strong>Acceptable values:</strong> Any valid HTMLElement
        </P>
        <P>
          We also provide <code>component</code> as an alias for <code>as</code>
          .
        </P>
      </BasicCollapsible>
      <BasicCollapsible collapsibleId="render" heading="render">
        <TextInputWithButtonInset>
          <TextInput placeholder="Search..." type="search" />
          <Icon
            render={props => (
              <Button tabIndex={-1}>
                <img {...props} />
              </Button>
            )}
            iconType="search"
          />
        </TextInputWithButtonInset>
        <P>
          <strong>Acceptable values:</strong> A function that accepts props
          object and returns a ReactNode
        </P>
      </BasicCollapsible>
    </Accordion>
  )
}

() => {
  return (
    <Accordion fullBleed>
      <BasicCollapsible collapsibleId="as" heading="as / component">
        <Card bordered as="a" href="#url">
          Card as an &lt;a&gt; tag.
        </Card>
        <P>
          <strong>Acceptable values:</strong> Any valid HTMLElement
        </P>
        <P>
          We also provide <code>component</code> as an alias for <code>as</code>
          .
        </P>
      </BasicCollapsible>
      <BasicCollapsible collapsibleId="render" heading="render">
        <TextInputWithButtonInset>
          <TextInput placeholder="Search..." type="search" />
          <Icon
            render={props => (
              <Button tabIndex={-1}>
                <img {...props} />
              </Button>
            )}
            iconType="search"
          />
        </TextInputWithButtonInset>
        <P>
          <strong>Acceptable values:</strong> A function that accepts props
          object and returns a ReactNode
        </P>
      </BasicCollapsible>
    </Accordion>
  )
}

<>
  // using `as` prop
  <Card as="a" href="#">
    Some text
  </Card>
  // using `render` prop
  <TextInputWithButtonInset>
    <TextInput placeholder="Search..." type="search" />
    <Icon
      render={props => (
        <Button tabIndex={-1}>
          <img {...props} />
        </Button>
      )}
      iconType="search"
    />
  </TextInputWithButtonInset>
</>

<>
  // using `as` prop
  <Card as="a" href="#">
    Some text
  </Card>
  // using `render` prop
  <TextInputWithButtonInset>
    <TextInput placeholder="Search..." type="search" />
    <Icon
      render={props => (
        <Button tabIndex={-1}>
          <img {...props} />
        </Button>
      )}
      iconType="search"
    />
  </TextInputWithButtonInset>
</>

display

The display prop sets the CSS display property, specifying the display behavior (the type of rendering box) of an element.

The prop also supports the Responsive system.

Acceptable values: any value in SWAN’s TypeScript type StyleDisplay, which covers most of the possible CSS values for display.

overflow

The overflow prop sets the CSS overflow property. This prop has Responsive support.

Acceptable values: any value in SWAN’s TypeScript type StyleOverflow, which covers the possible CSS values for overflow.

visuallyHidden

The visuallyHidden prop is used for accessibility support, making content hidden from screens but still available to users on assistive technologies such as screen readers.

It is useful for adding additional explanatory text that sighted users might not need, but which will make the UI better understood by users on assistive technologies. This prop has Responsive support.

Acceptable values: boolean

swanStyle

You can group together any of the above props (p, m, bgc, visuallyHidden, etc) into a single prop called swanStyle. This prop has Responsive support.

<Box bgc="black">
  <Card
    swanStyle={{
      m: { xs: 4, md: 5, lg: 7 },
      p: { xs: 4, sm: 7 },
      display: 'inline-block',
      bgc: 'green-100',
      textAllCaps: true,
      textAlign: 'right',
      textColor: 'dark-grey',
      fontSize: 4,
    }}
  >
    Some content in card
  </Card>
</Box>

<Box bgc="black">
  <Card
    swanStyle={{
      m: { xs: 4, md: 5, lg: 7 },
      p: { xs: 4, sm: 7 },
      display: 'inline-block',
      bgc: 'green-100',
      textAllCaps: true,
      textAlign: 'right',
      textColor: 'dark-grey',
      fontSize: 4,
    }}
  >
    Some content in card
  </Card>
</Box>

loadingShimmer

The loadingShimmer is for sections of pages that are currently loading, such as skeleton screens. Typically a section with this prop will not have any content inside of it.

<Card loadingShimmer>Loading Shimmer</Card>

<Card loadingShimmer>Loading Shimmer</Card>