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 enable
to enable pnpm - Install dependencies with
pnpm i
- Run
pnpm dev
to start the local Storybook server
The component library is structured according to Atomic Design principles, using the bottom three levels.
- Particles (renamed from
atoms
for 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.jsx
containing the code for the actual component -
[component-name].stories.jsx
containing 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/src
folder 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-scheme
CSS media feature. If your component usesprefers-color-scheme
directly, you will also need to change your system or browser setting to see that styling take effect.