A set of reusable components for use in interactive pages, written in Preact using Atomic Design principles.
npm install @guardian/interactive-component-library
Building the project requires Node v16.18.1 or higher.
- Clone this repository
- Run
corepack enableto enable pnpm - Install dependencies with
pnpm i - Run
pnpm devto start the local Storybook server
The component library is structured according to Atomic Design principles, using the bottom three levels.
- Particles (renamed from
atomsfor obvious reasons) - Molecules
- Organisms
Particles are the lowest level components that form the building blocks for everything else, e.g. a Button. Molecules represent more complex components (e.g. a Table) and often depend on particle components. Organisms combine the previous two levels into distinct sections of an interactive page, e.g. KeySeats.
Folders use the same naming structure, with particles, molecules and organisms folders in src/lib/components, to distinguish between the three different levels.
Create a folder for your new component in the appropriate directory. The name of the folder should be the name of your component in Kebab case, i.e. src/lib/components/particles/my-new-component.
The folder should contain the following:
-
index.jsxcontaining the code for the actual component -
[component-name].stories.jsxcontaining examples of how to use the component, written as Storybook stories -
docs.mdx(optional) additional documentation for the component in Storybook
During development, you'll often want to see how a component looks in the interactive page that you're working on, without rebuilding and publishing a new version of the component library. To facilitate this workflow, we use npm-link.
Here's how to set that up:
cd ~/projects/interactive-component-library # go into the package directory
npm link # creates global link
cd ~/projects/interactive-project # go into your project directory
npm link @guardian/interactive-component-library # link-install the package
After you've done that, run pnpm build:lib:watch to package the library and rebuild on file changes.
To revert back to the version specified in your project‘s package.json:
npm uninstall --no-save @guardian/interactive-component-library && npm install
To publish a new version of the component library, follow these steps:
- Create a new release on GitHub (don't forget to write some release notes)
- Publishing the release triggers a workflow to package the library and publish it to the NPM registry. If the publish actions fails, you can also trigger it manually
- The publish action also creates a pull request to bump the version number. Merge the pull request to finish the release
Always prepending pnpm:
-
dev: Start Storybook for local development -
build: Builds the static storybook project -
build:lib: Builds the component library into the dist folder -
build:lib:watch: Same as previous command, but it watches/srcfolder and rebuilds on changes
Use the sun/moon button in the toolbar to switch between light and dark mode.
Enabling dark mode applies .ios and .dark-mode classes to the <body> element, which in turn renders the story preview with dark mode colours (this behaviour can be customised in .storybook/preview.scss).
Note that enabling dark mode using this button does not affect the
prefers-color-schemeCSS media feature. If your component usesprefers-color-schemedirectly, you will also need to change your system or browser setting to see that styling take effect.