@guardian/interactive-component-library
v0.4.0
Published
A set of reusable components for use in interactive pages, written in Preact using [Atomic Design](https://bradfrost.com/blog/post/atomic-web-design/) principles.
Downloads
18,142
Keywords
Readme
@guardian/interactive-component-library
A set of reusable components for use in interactive pages, written in Preact using Atomic Design principles.
Install the component library in a new client project
npm install @guardian/interactive-component-library
Contributing to this repository
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
Atomic design
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.
Adding a new component
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 storiesdocs.mdx
(optional) additional documentation for the component in Storybook
Developing and testing locally
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
Publishing a new version
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
Scripts
Always prepending pnpm
:
dev
: Start Storybook for local developmentbuild
: Builds the static storybook projectbuild:lib
: Builds the component library into the dist folderbuild:lib:watch
: Same as previous command, but it watches/src
folder and rebuilds on changes
Testing for dark mode in Storybook
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.