Forma 36 React Components

A React component library for the Forma 36 design system created by Contentful.

Table of contents

- Forma 36 React Components
- Table of contents
- Installing package
- Usage
- Import desired component into your project
- Development
- Storybook
- Example component directory structure
- Code Style Guide
- Component principles
- Adding documentation for component
- Testing
- Run tests
- Building
- Create a build of the library
- Commits

Installing package

``bash
yarn add @contentful/f36-components
`

Or

`bash
npm install @contentful/f36-components
`

Usage

$3

`js
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.

$3

We use Storybook to create a development environment for our component library. To start it locally run:

`bash
npm run-script storybook
`

When creating new component, before you start, please have a look at our contribution model for Forma 36.

$3

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

$3

Our code style guide

$3

We follow a number of principles when creating our components:

1. 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:

- Box
- Flex
- Grid
- Stack

$3

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:

1. A short summary of the component.
2. Import - provide example how to import component.
3. Examples - try to add couple of examples, both basic and more advanced, where component is used in the context with other components.
4. Props (API reference) - Overview of properties
5. Content guideliness - try to describe in best practices around content for your component
6. 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.

$3

`bash
npm run-script test
`

It is recommended to run tests in development with the optional --watch flag.

`bash
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)

$3

`bash
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

`bash
npm run-script commit
``