RPF Design System - React

The React implementation of the Raspberry Pi Foundation Design System

Design System links:

Usage

Using yarn:

yarn add @raspberrypifoundation/design-system-react

Import the package stylesheet once in your app entrypoint. This stylesheet includes the component CSS and the Material Symbols Google Fonts imports used by icon-based components.

import "@raspberrypifoundation/design-system-react/styles.css";
import { Button } from "@raspberrypifoundation/design-system-react";

Development

Dependencies:

• asdf (https://asdf-vm.com/)

Note: The Node.js version is specified in both .tool-versions (for local development with asdf) and .node-version (for Cloudflare Pages deployments). Cloudflare Pages does not use .tool-versions for Node.js version resolution, so .node-version is required to ensure the correct version is used in builds. Keep both files in sync when updating the Node.js version.

asdf install

Enable corepack, which adds the yarn binary to your path

corepack enable

Install packages:

yarn

Run Storybook:

yarn run storybook

Linting & Formatting

We use ESLint for linting and Prettier for formatting.

Learn more here and here.

In short:

• Formatting is faster and simpler with Prettier.
• Seperation of concerns for code quality and bug catching (ESLint) and code formatting (Prettier).
• It is recommended by ESLint maintainers to run a dedicated source code formatter - such as Prettier.

For both we are using the default recommend configurations to avoid bike-shedding. Prettier uses purposely opinionated options for example.

Linting

You are manually run ESLint with:

yarn lint

To automatically fix issues where possible:

yarn lint --fix

Formatting

The .prettierrc file lets lets editors and other tools know we're are using Prettier.

To get the most out of Prettier, it’s recommended to run it from your editor.

If you just want to run the formatting manually:

yarn format

Testing

Run the tests with yarn run test.

Working with a local version of design-system-core

Sometimes you may want to work on design-system-core and design-system-react at the same time. You can do this by working with your local version of core using yarn link.

1. In your design-system-react repo and tell the application to use your local version of design-system-core. In this command ../design-system-core should be replaced with the path to your copy of design-system-core.

yarn link ../design-system-core

The output should look include something like

➤ YN0000: ┌ Resolution step
➤ YN0085: │ + @raspberrypifoundation/design-system-core@portal:/Users/testy.mctestface/path/to/design-system-core::locator=%40raspberrypifoundation%2Fdesign-system-react%40workspace%3A.
➤ YN0085: │ - @raspberrypifoundation/design-system-core@npm:1.4.0
➤ YN0000: └ Completed

2. Set NODE_OPTIONS=--preserve-symlinks, to make sure the local version of design-system-core is being used.

export NODE_OPTIONS="$NODE_OPTIONS --preserve-symlinks"

3. Re-start storybook

yarn run storybook

Troubleshooting

If you are experiencing issues and believe design-system-react is not using your local version of design-system-core, or if you are running into issues running yarn link, try the following:

• Check that design-system-react and design-system-core are both using the same nodejs version in .tool_versions. If they are not, update the node version(s) in .tool_versions locally and retry the steps above. If this was the issues / the nodejs versions are not the same, consider creating a PR to bring them in-line.

• Make sure the NODE_OPTIONS=--preserve-symlinks is set in the same terminal (i.e. shell instance) as Storybook, and that Storybook has been restarted.

• Ask in the design-system Slack channel.

Node versions

We've two places where the NodeJS version is specified, and we should keep these in-sync. The .tool-versions is used for local development, installed via asdf. The .nvmrc is used in the CI/publish Github action, and the Cloudflare pages build process. If you change one, please change t'other.

TypeScript and PropTypes

This package is gradually migrating from PropTypes to TypeScript for type checking. PropTypes were deprecated in 2017 and will not be supported by React 19.

To get the best type experience:

• TypeScript consumers

  • You’ll get full static type information when using the TS-enabled components (any component using the .tsx file extension).
  • Props are defined with TypeScript interfaces/types instead of propTypes.
  • No runtime validation is performed — errors are caught at compile time.

• JavaScript consumers

  • Components continue to work exactly the same.
  • However, you will no longer see runtime warnings in the console when passing incorrect props to components that use TypeScript instead of propTypes.
  • Refer to the Storybook docs or the component’s TypeScript definition for prop typing details.
  • Consider moving to Typescript to get the most out of type definitions.

During the migration period you may see a mix of propTypes and TypeScript in different components.

Deployment

Create a new release:

• Use yarn version -i minor to increment the version in package.json. You can also use major or patch instead of minor here.
• Update the changelog
• Commit and push to a branch, and open a PR for review.

Make a cuppa while a peer reviews the release.

• Once approved, merge your PR to main
• Click 'Draft a new release'
• Type the version in the dropdown and click 'Create new tag'
• Add a title and some notes about what the release contains
• Click 'Publish release' (leave 'Set as latest release' checked) and a build will be kicked off

Once published

• Add new version to package.json in your app

Using Docker

TODO