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 have two places where the Node.js version is specified, and they must stay in sync. .tool-versions is used for local development with asdf and by GitHub Actions. .node-version is used by Cloudflare Pages and other hosts. If you change one, change the 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.

Releasing a version

1. Open the Prep release workflow, select Run workflow, and choose a patch, minor, or major version bump.
2. The workflow creates a branch and opens a draft pull request that:
   • bumps the version in package.json; and
   • changes the Unreleased heading in CHANGELOG.md to the new version and release date.
3. Review the generated changes, mark the pull request ready for review, and merge it into main.
4. Create a matching tag. The tag must start with v, for example v2.10.4. You can do this in either of these ways:

• Using the command line: pull the merged commit, then create and push the tag:

  git checkout main
  git pull
  git tag v2.10.4
  git push origin v2.10.4

• Using the GitHub UI:

  1. Open the new release page.
  2. Select Choose a tag and enter the new version, including the v prefix.
  3. Select Create new tag on publish.
  4. Confirm that the tag will target the main branch.

5. On the new release page, select the matching tag, generate the default release notes, and publish the release. If you chose to create the tag through the GitHub UI, publishing the release creates the tag at the same time.

Publishing the GitHub release triggers GitHub Actions to build the package and publish it to npm using npm Trusted Publishing. Releases do not require an NPM_TOKEN or NODE_AUTH_TOKEN repository secret.