Design System


A primitive component that can be used to create all block level styles in Paste

yarn add @twilio-paste/box — or — yarn add @twilio-paste/core


The Box component is one of the pillars of our system. It can be any HTML element and can receive many of our token values as props. We use Box to build most of our other components.

About Box#

All HTML elements can be considered as boxes. In CSS, the term "box model" is used when talking about design and layout. It consists of: margins, borders, padding, and the actual content.

The Box component is inspired from the “box model". It is a simple wrapper component that takes tokens instead of using CSS. The limited but scoped set of tokens allowed on Box act as guardrails. They provide quick and direct access to the Twilio design language while preventing any other value. We prevent other values to protect our product from inconsistent and inaccessible designs.

For this reason, we can use the Box component to build out most of the interfaces at Twilio. Using this component will make our products resilient to design changes and themeable.

The Box component takes original inspiration from RebassJs and is powered by Styled System. The psuedo class functionality was inspired by and mimics Chakra UI.


The Box component is an all purpose component. By default, it has no accessibility concerns. If you use the Box as a custom element, it is up to you to manage the resulting accessibility implications.

Be sure to use the as prop to select semantically meaningful HTML elements. By default the Box component renders as a div which doesn’t provide much meaning to the user.


Tokens as props#

Parent box on the hill side
nested box 1 made out of ticky tacky
Nested box 2 may look the same

Tokens as pseudo-class props#

To view the full list of pseudo-class props, check the props table.

Hover over me!

Composition Notes#

The Box component is used to compose other experiences. If you imagine everything on a webpage as a Box, you can see how they all come together. Let's assume we need to build a modal component: it has a header, a body and a footer. Here's how we’ll compose the modal using Box:

Header area
Body area
An inner box with margin and padding
Footer area

When to use Box#

The Paste component library aims to cover the widest range of base use-cases. Sometimes, product requirements are more specific than what is offered here. When no other component in Paste works, use the Box component to build new experiences.

Be wary of building slightly different versions of existing Paste components. If what you need is only a little different, try to constrain the design into one of our provided solutions. This will allow you to leverage more of our system and reduce your maintenance costs. On the surface our components may look simple or restrictive. They are often limited for very specific reasons, such as accessibility.


Use Box to build new components and experiences.


Use Box to build slightly different versions of existing Paste components.


Use Box to layout your page or to apply padding to your components.


Use inline CSS, the CSS Cascade, or classNames to add styles that Box can provide.


Use Box with an 'as' prop to style custom HTML elements with tokens.


Use HTML elements for functionality covered by the Box component.

Usage Guide#



yarn add @twilio-paste/box - or - yarn add @twilio-paste/core


import {Box} from '@twilio-paste/box';
const Component = () => (
backgroundColor: "colorBackgroundPrimary"
padding: "space70"


All the regular HTML attributes (role, aria-*, type, and so on) including the following custom props:

backgroundColor?ResponsiveValue<keyof ThemeShape['backgroundColors']>
width?`ResponsiveValue<keyof ThemeShape['widths']'100%'>`
minWidth?ResponsiveValue<keyof ThemeShape['minWidths']>
maxWidth?ResponsiveValue<keyof ThemeShape['maxWidths']>
height?ResponsiveValue<keyof ThemeShape['heights']>
minHeight?ResponsiveValue<keyof ThemeShape['minHeights']>
maxHeight?ResponsiveValue<keyof ThemeShape['maxHeights']>
margin?ResponsiveValue<keyof ThemeShape['space']>
marginTop?ResponsiveValue<keyof ThemeShape['space']>
marginRight?ResponsiveValue<keyof ThemeShape['space']>
marginBottom?ResponsiveValue<keyof ThemeShape['space']>
marginLeft?ResponsiveValue<keyof ThemeShape['space']>
padding?ResponsiveValue<keyof ThemeShape['space']>
paddingTop?ResponsiveValue<keyof ThemeShape['space']>
paddingRight?ResponsiveValue<keyof ThemeShape['space']>
paddingBottom?ResponsiveValue<keyof ThemeShape['space']>
paddingLeft?ResponsiveValue<keyof ThemeShape['space']>
borderRadius?ResponsiveValue<keyof ThemeShape['radii']>
borderTopLeftRadius?ResponsiveValue<keyof ThemeShape['radii']>
borderTopRightRadius?ResponsiveValue<keyof ThemeShape['radii']>
borderBottomRightRadius?ResponsiveValue<keyof ThemeShape['radii']>
borderBottomLeftRadius?ResponsiveValue<keyof ThemeShape['radii']>
borderWidth?ResponsiveValue<keyof ThemeShape['borderWidths']>
borderTopWidth?ResponsiveValue<keyof ThemeShape['borderWidths']>
borderRightWidth?ResponsiveValue<keyof ThemeShape['borderWidths']>
borderBottomWidth?ResponsiveValue<keyof ThemeShape['borderWidths']>
borderLeftWidth?ResponsiveValue<keyof ThemeShape['borderWidths']>
borderColor?ResponsiveValue<keyof ThemeShape['borderColors']>
borderTopColor?ResponsiveValue<keyof ThemeShape['borderColors']>
borderRightColor?ResponsiveValue<keyof ThemeShape['borderColors']>
borderBottomColor?ResponsiveValue<keyof ThemeShape['borderColors']>
borderLeftColor?ResponsiveValue<keyof ThemeShape['borderColors']>
boxshadow?ResponsiveValue<keyof ThemeShape['shadows']>
zIndex?ResponsiveValue<keyof ThemeShape['zIndices']>

Change Log

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

2.4.6 (2020-05-27)

Bug Fixes#

  • box: allow text-decoration style prop (50aac91)

2.4.5 (2020-05-20)

Bug Fixes#

  • box: allow ref on the interface of a box (5853b39)

2.4.4 (2020-05-07)

Note: Version bump only for package @twilio-paste/box

2.4.3 (2020-05-07)

Note: Version bump only for package @twilio-paste/box

2.4.2 (2020-05-04)

Bug Fixes#

  • box: switch to new spacing prop validators (045625e)

2.4.1 (2020-05-01)

Note: Version bump only for package @twilio-paste/box

2.4.0 (2020-04-25)


  • box: export interface prevent undefined pseudo selectors (7e6363e)

2.3.1 (2020-04-22)

Note: Version bump only for package @twilio-paste/box

2.3.0 (2020-04-17)


  • components: promote text components, spinner and primitive to prod (5605adc)

2.2.10 (2020-04-15)

Note: Version bump only for package @twilio-paste/box

2.2.9 (2020-04-08)

Bug Fixes#

  • box: package dependencies updated to be correct (87f302a)

2.2.8 (2020-04-07)

Note: Version bump only for package @twilio-paste/box

2.2.7 (2020-04-07)

Bug Fixes#

  • box: add missing invalid, indeterminate, checked pseudo selectors (a2d1f28)

2.2.6 (2020-04-02)

Note: Version bump only for package @twilio-paste/box

2.2.5 (2020-03-28)

Bug Fixes#

  • box: remove min-width:0 as a default (7b8e55b)

2.2.4 (2020-03-24)

Bug Fixes#

  • box: switch from theme-tokens to theme package dep (071e77a)

2.2.3 (2020-03-17)

Note: Version bump only for package @twilio-paste/box

2.2.2 (2020-03-17)

Note: Version bump only for package @twilio-paste/box

2.2.1 (2020-03-11)

Note: Version bump only for package @twilio-paste/box

2.2.0 (2020-03-06)

Bug Fixes#

  • add missing transitive peerDep on '@styled-system/css' (fdbb813)


  • box: add pseudo-class props and missing props (9463ddd)

2.1.12 (2020-03-02)

Note: Version bump only for package @twilio-paste/box

2.1.11 (2020-02-28)

Note: Version bump only for package @twilio-paste/box

2.1.10 (2020-02-26)

Bug Fixes#

  • package dependencies and deprecation warnings (#334) (0e88338)

2.1.9 (2020-02-14)

Bug Fixes#

  • box: add missing peer deps (2281923)

2.1.8 (2020-02-13)

Note: Version bump only for package @twilio-paste/box

2.1.7 (2020-02-11)

Note: Version bump only for package @twilio-paste/box

2.1.6 (2020-02-11)

Note: Version bump only for package @twilio-paste/box

2.1.5 (2020-02-11)

Note: Version bump only for package @twilio-paste/box

2.1.4 (2020-02-03)

Note: Version bump only for package @twilio-paste/box

2.1.3 (2020-01-24)

Note: Version bump only for package @twilio-paste/box

2.1.2 (2020-01-17)

Note: Version bump only for package @twilio-paste/box

2.1.1 (2019-12-20)

Note: Version bump only for package @twilio-paste/box

2.1.0 (2019-12-19)


  • box: use style-props package, create method to safelySpreadProps (dc9f7fb)

2.0.4 (2019-12-05)

Note: Version bump only for package @twilio-paste/box

2.0.3 (2019-11-20)

Note: Version bump only for package @twilio-paste/box

2.0.2 (2019-11-18)

Bug Fixes#

  • design-tokens: update some blues, reds, and focus shadow (#185) (98d70cc)
  • website: remove vague anchor do dont (#177) (8530c56)

2.0.1 (2019-11-12)

Bug Fixes#

  • prettier updated, updating formatting (8644831)

2.0.0 (2019-11-11)


  • icons: delete old icons, add new streamline icons (#129) (571791d)
  • enable theme switching on the docsite (#124) (df797e5)


  • icons: removed all the inherited icons since we're moving to a new system

  • chore(icons): update icon list for storybook

  • fix(spinner): use new icon

  • fix(storybook): use new icon for story

  • fix(story): button icons should be 24px

  • fix: adjust icon size tokens

  • feat: add iconSizes as separate key in theme-tokens

  • feat(icons): icons package to use tokens and update icons

  • fix(spinner): update to use tokens and new icons

  • fix(button): use correct spinner size

  • fix(icons): major icons package fixes

  • huge overhaul to build process
  • now uses rollup
  • builds into cjs and esm directories
  • made the package publishable to npm
  • moved svg folder out of src, now src only holds react stuff
  • updated scripts to use new paths and cleaned up the code
  • programmatically generates rollup config from the icon-list command
  • chore: add new icons dist folders to gitignore

  • fix: spinner and button icon usage

  • feat(icons): add rollup icon list cache file

  • fix(core-bundle): sort packages for consistent builds

  • chore: use esm instead of es in rollup for correctness

  • chore: yarn.lock

  • fix(spinner): lint error

  • chore(icons): move rollup icon list

  • chore(spinner): use types package in story

  • fix(spinner): swap out destructured props for explicit props

1.1.0 (2019-10-31)


  • update types package to styled-system v5 format (#154) (117c41e)

1.0.0 (2019-10-29)



  • box: many Box API changes

  • fix(theme-tokens): add sizes key for styled-system responsiveness

  • fix(absolute): update to newer Box

  • fix(types): allow for responsive values via array

  • fix(box): update story and light tweaks to OverflowProps

  • chore: update yarn.lock file

  • fix(types): many more types fixes

refactor: moved ValueOf into types package

  • fix(box): eslint error in story

  • fix(box): using the correct BorderProps definition

fix: we shouldn't allow users to pass the border shorthand, it circumvents tokens

  • fix: lint errors

  • fix(website): update box docs

  • fix(storybook): use theme breakpoints

0.3.1 (2019-09-16)

Note: Version bump only for package @twilio-paste/box

0.3.0 (2019-08-15)

Bug Fixes#


  • ComponentHeader component, component overview fixes, more (#20) (875e124)
  • website: Add the tokens page (#19) (878d3c5)


If you need support, please open a new issue in our GitHub repository. Please try to provide as much detail as possible in your issue.


The Paste design system is open source and contributions are welcome. Check out the project on GitHub to learn more about contributing.

Copyright © 2020 Twilio, Inc.