Patterns and principles

Blockstack UI is built with a few things in mind: consistency, composability, easy of use, and extensibility. These components aren't meant to be highly complex instances of specific UI elements; rather they are meant to be primitive components that you can use to build anything you want.

System props

All component styles can be extended or overwritten via system props to reduce the use of css or creating new styled() wrapper components. Compose new components from one of the base primitives: Box, PseudoBox, Flex, Grid, or Text. Read more here.

Base primitives

All components are built from one or many of the base primitive components: Box, PseudoBox, Flex, Grid, or Text. If you have worked within something like React Native, concepts of primitive components should be a bit familiar. Box is not unlike View. Rather than thinking in divs, try to think in primitives. Do I need my parent wrapper to have display: flex?, then I should use Flex as the base component to extend from.


Break down components into smaller parts with minimal props to keep complexity low, and compose them together. This will ensure that the styles and functionality are flexible and extensible.


When creating a component, keep accessibility top of mind. This includes keyboard navigation, focus management, color contrast, voice over, and the correct aria-* attributes.


Generally, ensure a prop name is indicative of what it does. Boolean props should be named using auxilliary verbs such as does, has, is and should. For example, Button uses isDisabled, isLoading, etc.