Forma 36 React Components
A React component library for the Forma 36 design system created by Contentful.
Table of contents
Installing package
yarn add @contentful/f36-components
Or
npm install @contentful/f36-components
Usage
Import desired component into your project
import { Button } from '@contentful/f36-components';
Development
For local development, in the root of the repo run npm i
to install all dependencies and then npm run-script build
to build all packages.
This package depends on several other Forma 36 packages so you will need to build all of them.
Storybook
We use Storybook to create a development environment for our component library. To start it locally run:
npm run-script storybook
When creating new component, before you start, please have a look at our contribution model for Forma 36.
Example component directory structure
A component's directory should resemble the following:
/my-component
/examples
/src
index.ts // A file for exporting your component
MyComponent.tsx // Your React component
MyComponent.test.tsx // Component tests
MyComponent.styles.ts // Component styles
/stories
# stories for storybook of each component inside the package
README.mdx
package.json
For more detailes you can have a look in document that describes folder structure in details.
If you use npm run-script generate
in the root of the repo, this structure will be created automatically for you
Code Style Guide
Our code style guide
Component principles
We follow a number of principles when creating our components:
- A component is responsible for only its internal spacing
Component should only be responsible for its own internal spacing - never external spacing. This means that we're flexible in where our components can be used without having to override margins.
The only outlier from this rule are typography components - they can manage their own margins. To handle margins and layout you can use our core components, like:
Adding documentation for component
We would like to make sure that every component contains a README file with recommendations and guidelines.
Make sure that your documentation for the component contains following parts:
- A short summary of the component.
- Import - provide example how to import component.
- Examples - try to add couple of examples, both basic and more advanced, where component is used in the context with other components.
- Props (API reference) - Overview of properties
- Content guideliness - try to describe in best practices around content for your component
- Accessibility - If possible, we strongly recommend providing accessibility guidelines.
Testing
We are using Jest and Testing Library to test our components.
Tests are kept next to their components and use the .test.js
file extension.
Run tests
npm run-script test
It is recommended to run tests in development with the optional --watch
flag.
npm run-script test --watch
Building
We are using tsup and esbuild together with Microbundle to build our component library.
Each component builds to its own dist
directory with:
index.d.ts
– TypeScript type declaration file
index.js
– CJS (CommonJS)
index.modern.mjs
– Modern output (work in all modern browsers)
index.module.js
– legacy ESM (ES Modules) output (for bundlers)
index.umd.js
– legacy UMD (Universal Module Definition) output (for Node & CDN use)
Create a build of the library
npm run-script build
Commits
This project uses the Angular JS Commit Message Conventions, via semantic-release. See the semantic-release Default Commit Message Format section for more details.
You can commit the changes by running
npm run-script commit