Origami Component System

Welcome to Origami!

This is the repository for the Origami components, libraries, and apps that make up the Origami Component System.

Proposals

If you'd like to make a proposal for a new component or anything else, go ahead and open an issue.

Projects in this repository

This repository houses many projects of different kinds. Most of them have READMEs of their own where you can learn more about them.

apps/storybook

Origami's storybook, served at https://origami.ft.com/storybook/.

apps/website

Origami Design System documentation and usage guides.

components and libraries

Components and libraries that implement the FT's design system for the web.

presets

Presets for development tools that make it easier to build consistent components.

scripts

Scripts for maintenance of the repository itself

scripts/components

Default scripts used in component package.jsons for building and testing components.

tools

Tools used to build and test Origami components

Running Origami locally

Requirements

There is some software you'll need on your computer in order to work with this repo.

volta

We use volta to make sure everyone is using the same versions of node and npm.

curl https://get.volta.sh | bash

git-lfs

To keep the repo speedy, we use git-lfs to store binary files like the images on the website.

brew install git-lfs
git lfs install

entr

entr is used in the component watch command for watching files

brew install entr

rg

ripgrep is used in the component watch command for quickly choosing the files to watch for changes.

brew install rg

Quick start

1. First, clone the repo

   git clone [email protected]:Financial-Times/origami.git
   cd origami

2. Then npm install. This will install all the components into the root node_modules, allows all the components to find one another.

   npm install

3. Choose the appropriate command based on the project:

   • For Origami's o2 components storybook, run the following command:

     npm run storybook

   • For Origami's o3 components storybook, run the following commands:

     npm run build-storybook -w apps/o3-storybook/
     npm run storybook -w apps/o3-storybook/

   • For Origami Design System website, run the following command:

     npm run dev -w apps/website

Developing components

Setup

Follow the quick start guide to get started developing components.

Preview demos

Storybook

Storybook can be run locally with the storybook command.

npm run storybook

To view components in other brands in Storybook, set the STORYBOOK_BRAND environment variable with the brand.

STORYBOOK_BRAND=internal npm run storybook

Some demos in Storybook are embedded through the Build Service, meaning that local changes will not appear on Storybook. This can be verified by inspecting the *.story.ts file for a component and seeing if the root element is an iframe. Local development for these components can still be achieved by using legacy demos instead.

Legacy

Component demos formerly on the Origami Registry have now been migrated to Storybook.

The legacy demos may be useful for development purposes where a demo in Storybook is sourced from Build Service as mentioned in the previous section. You can view these using the build and start commands:

npm run build -w components/o-example
npm run start -w components/o-example

This will generate demos for all brands that the component is configured to be a part of.

Watch demos

To serve the demos, and have them automatically rebuild when the code changes you can use the watch command.

npm run watch -w components/o-example

Setting brands

Some components you create may only be part of one brand. We recommend you follow these guidelines when contributing branded components:

Storybook

Storybook component demos can be branded by introducing a brand sub-directory within the stories folder, and placing brand-specific stories within it. e.g:

o-labels/
    demos/
    src/
    stories/
       core/
           // Core brand stories go in this directory.
           labels.stories.tsx
           labels.scss
       //Unbranded stories can be placed in the root of stories/
       labels.stories.tsx
       labels.scss

o-labels provides a good example of this.

Legacy

Legacy Origami Registry component demos are branded through the origami.json manifest in the component's root directory. You can find how to use this file in the Origami documentation.

Test

Run tests for a given component with the npm test script.

npm run test -w components/o-example

Run tests for all components with the npm test script.

npm run test -w components

Note: This will take a good amount of time when running on localhost.

Run JavaScript tests in a browser using the debug:js script.

npm run debug:js -w components/o-example

Lint the code of a given component with the npm lint script.

npm run lint -w components/o-example

Run linting for all components with the npm test script.

npm run lint -w components

Note: This will take a good amount of time when running on localhost.

Tips

• If you're working on the storybook configuration and it starts acting weird and not working, try running it without the cache: npm run storybook -- --no-manager-cache

Chromatic

Origami implements visual regression tests for o3 components with Chromatic.

More details on how Chromatic can test Pull Requests can be found in the Contribution notes.

Billing

Chromatic usage is calculated in snapshots. You can check on the current consumption of our monthly allowance by:

• Logging into Chromatic
• Click Billing in the left side menu

Here you can see the current billing periods usage as well historical periods.

Notifications

An alert has been set for when the snapshot usage reaches 42,500 (50% of the current 85,000 total).

The alert sends an email to the #origami-notifcation channel.

Contributing

If you want to contribute, check out CONTRIBUTING.md.