The protocol-ui library is our component library and custom theme that customizes and extends Chakra UI. The initial focus of this is on the functional components we used to build v1 such as form elements, modal wrappers, and the custom theme that overrides Chakra's base component styles.
Our components are built with [React](https://reactjs.org/ and TypeScript. This library also includes a Storybook instance.
This library was generated with Nx.
As of now, protocol-ui is for internal use within the monorepo (as opposed to it being published on npm as a standalone library). As this is the case you'll need to access it via @govrn/protocol-ui when working within the monorepo.
The Protocol Frontend is already set up to use protocol-ui and the theme provider, but if you're using this in another frontend app within the monorepo you'll need to wrap the app with Chakra's Theme Provider, passing in our GovrnTheme:
// main.tsx
import { GovrnTheme } from '@govrn/protocol-ui';
<ChakraProvider theme={GovrnTheme}>
<App />
</ChakraProvider>;Wrapping the app and passing in GovrnTheme provides access to the custom component styles leveraged in the library
Each component can be imported directly from the @govrn/protocol-ui package:
// ExampleForm.tsx
import { Input } from `@govrn/protocol-ui`;The form components require some additional scaffolding as they're designed to work with React Hook Form. This is covered in the Components section below.
This library roughly follows Atomic Design principles. The components are intended to be composable.
-
Components: We roughly follow Atomic Design principles so our components are organized as Atoms, and Molecules. As of now, we don't include Organisms as we're focusing on establishing foundational building blocks. The Organism and Page Level layouts are intentionally handled by each app.
-
Atoms
- These are the smallest components that are used to build up a larger component. Each Atom is typically a single UI element such as a
<Label>component. - Atoms can be used on their own or combined together to form Molecules.
- These are the smallest components that are used to build up a larger component. Each Atom is typically a single UI element such as a
-
Molecules
- Molecules are composed of Atoms and other Molecules. Molecules are typically used to build up a larger component. An example is an
<Toast/>component as it composes other Atoms.
- Molecules are composed of Atoms and other Molecules. Molecules are typically used to build up a larger component. An example is an
-
Theme
- This folder contains our
themeand the customized styles for several Chakra components in thecomponentsfolder. - We have a
GovrnThemethat composes and scaffolds core theme elements. This theme leverages Chakra's theme provider, so if you want to use it you'll need to pass it into theChakraProviderwrapping your app. - We currently use the default Chakra design tokens and have extended the
colors.tsby adding in a color scheme based on the primary Govrn brand color. Since this includes values ranging from 50 - 900, you can pass this into Chakra'scolorSchemeprop such as `colorScheme="brand.primary". - If we update or customize these they'll be included in this section as well.
- This folder contains our
We're in the process of adding our stories and deploying our Storybook. We'll continue to update the README with our progress and deployment details. Each component contains a Story that powers the Storybook. The Story demonstrates the basic functionality for the component and also any style variants, props, and controls that the component supports.
Our stories folder structure matches the component structure. You can find the story for each component in this folder.
Note: We're in the process of adding these Stories to previously created components.
You can check the available commands in the project.json file in the protocol-ui library.
nx run protocol-ui:storybook-- serves the Storybook locally onlocalhost:4400nx run protocol-ui:lint-- runs the linter. Useful to check for errors in components before opening a PRnx run protocol-ui:build-- builds the frontend. Useful to check for build serrors before opening a PR
Run nx test protocol-ui to execute the unit tests via Jest.
We'll be adding additional tests via Cypress in the future.