Welcome to Origami!

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

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

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

The Origami website, served at https://origami.ft.com.

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

Origami Design System documentation and usage guides.

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

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

Scripts for maintenance of the repository itself

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

Tools used to build and test Origami components

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

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

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

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 is used in the component watch command for watching files

brew install entr

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

brew install rg

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/for-everyone-website/

Follow the quick start guide to get started developing components.

Storybook can be run locally with the storybook command.

npm run storybook

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

ORIGAMI_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.

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.

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

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

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

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

npm run test -w components/o-example

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

• 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

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