Patterns and principles
Stacks UI is built with a few things in mind: accessibility, 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.
Basic concepts
Components and props
The majority of what @stacks/ui exports are components. Components are encapsulated bits
of UI that serve some function. They let you split UI into small, independent, reusable pieces.
This allows you to work on them in isolation, and allows for composition. Components are the
highest level API in @stacks/ui, and they all take some kind of props: arbitrary inputs
that affect the component in some way.
You can read more about Components, Props, & React here.
System props
All of the components are styled and built with System Props, via styled-system. Any 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,
Flex, Grid, or Text. Read more here.
Base primitives
All components are built from one of the base primitive components: Box,
Flex, Grid, or Text. If you
have worked within something like React Native before, 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.
Composition
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.
Accessibility
When creating a component, keep accessibility top of mind. This includes keyboard navigation, focus management,
color contrast, and the correct aria-* attributes.
Naming
Generally, ensure a prop name is indicative of what it does. Boolean props should be named using verbs such
as does, has, is and should. For example, Button uses isDisabled, isLoading, and Stack uses isInline.