Particle

A CSS framework and React component library for building dscout user interfaces. Visit the documentation site to learn more.

Usage

Install particle using yarn or npm:

$ yarn add @dscout/particle
$ npm install --save @dscout/particle

React Version Support

Particle supports both React 18.x and React 19.x applications. No code changes are required when upgrading between React versions. Note that Particle is built using React 18.x, so usage with React 19.x should be done with this in mind and developers should validate components behave as expected.

# React 18 applications
yarn add @dscout/particle react@^18.0.0 react-dom@^18.0.0

# React 19 applications
yarn add @dscout/particle react@^19.0.0 react-dom@^19.0.0

Peer dependencies

Particle requires the implementing application install React and React Router. Optionally the implementing application can also install lodash and @floating-ui/dom. These optional peer dependencies are required when using the tooltip or dropdown components from Particle, but can be omitted if those are not used.

Importing

Everything is a named export on the namespace "@dscout/particle," for example:

import React from 'react';
import { Container, Heading } from '@dscout/particle';

export default function Announcement() {
  return (
    <Container>
      <Heading level="2">Important!</Heading>
      <p>Make sure to eat your vegetables.</p>
    </Container>
  );
}

Stylesheets

Stylesheets are included in two formats: css and scss.

Pre-compiled stylesheets are located in the lib directory of the build output. To import into a plain CSS file:

@import 'node_modules/@dscout/particle/lib/stylesheets/particle.css';
@import 'node_modules/@dscout/particle/lib/stylesheets/particle.min.css';

The source scss file is located in the styles directory. You can import it into your own scss file like so:

@import '@dscout/particle/styles/particle.scss';

Developing with Storybook

Storybook provides an isolated development environment for Particle components as well as a published static site that serves as a playground and documentation.

Install dependencies

Particle uses asdf to manage the node dependencies. To develop locally first install asdf with:

brew install asdf

Then install nodejs. If you don't already have nodejs set up on your machine you may first need install its dependencies and OpenPGP keys:

brew install coreutils
brew install gpg
bash ~/.asdf/plugins/nodejs/bin/import-release-team-keyring

Install asdf dependencies

asdf install

Install NPM dependencies with yarn:

yarn install

Start Storybook

Run Storybook locally:

yarn start

Scripts

A variety of scripts are provided for running common tasks.

Lint with ESLint and run typechecker:

yarn lint

Start the Vitest test runner in watch mode:

Note: Before testing, you will need to run yarn playwright install to ensure the local test runner can properly spin up the necessary browser environment.

yarn test

Contributing

See the wiki for details on how to contribute to Particle.

Releasing a new version

Instructions for preparing a new release and submitting it to npm can be found here.