citizensadvice · davidrapson · Aug 3, 2026
@@ -9,9 +9,9 @@ Running the project locally requires the following language ependencies to be in
 - **Ruby** — We include a `.ruby-version` file in the root of the project with the required version so if you are using a version manager like [rvm](https://rvm.io/) or [rbenv](https://github.com/rbenv/rbenv) it should pick this up.
 - **Node** — We include a `.nvmrc` file in the root of the project with the required version so if you are using [nvm](https://github.com/nvm-sh/nvm) it should pick this up.
 
-## Using just commands
+## Using just recipies
 
-The design system codebase is made up of different languages and components which all have their own tools for running commands. To help manage this we provide a `justfile` which allows running commands via `just` from within any directory. Throughout the guides we'll reference these commands.
+The design system codebase is made up of different languages and components which all have their own tools for running recipies. To help manage this we provide a `justfile` which allows running recipies via `just` from within any directory. Throughout the guides we'll reference these recipies.
 
 You can install this with:
 
@@ -21,7 +21,7 @@ brew install just
 
 ## Setting up the project
 
-We provide a top-level setup script which handles the following:
+We provide a top-level setup recipe which handles the following:
 
 1. Setting up and building the top-level npm package
 2. Installing the Rails engine gem dependencies

@@ -16,133 +16,76 @@ We have a number of different layers of tests:
 
 For development purposes we provide a top-level script to run all checks:
 
-```
-just check-all
-```
-
-This can take a while to run so is most useful to check your local environment and to run once you've finished developing a new feature. The rest of this guide covers the each type of check in more detail and how to run them individually.
-
-## Formatting
-
-We provide a just command for formatting the codebase:
-
 ```sh
-just format
-```
-
-You can check the formatting without making changes with `just format-check`
-
-### Prettier, Stylelint, Oxlint, and Jest
-
-The repository is centred around a node module which is managed by the `package.json` at the top-level of the repository. This provides commands for running prettier against the project as well as linting (oxlint) and unit tests (jest) for client-side code.
-
-All top-level package commands can be run using `npm run`:
-
-| Command       | Description                                           |
-| ------------- | ----------------------------------------------------- |
-| `test`        | Runs all jest tests                                   |
-| `lint`        | Runs all linting checks (prettier, oxlint, stylelint) |
-| `lint:css`    | Runs only `stylelint` on the project code             |
-| `lint:js`     | Runs only `oxlint` on the project code                |
-| `lint:format` | Run `prettier --check` on the project code            |
-| `format`      | Auto-format all eligible code with prettier           |
-
-### RuboCop
-
-For ruby code we run `rubocop` checks against our `engine`, `demo`, and `website` directories. From any of these directories run:
-
-```sh
-rake rubocop
+just check-all
 ```
 
-You can also run `rake rubocop:autocorrect` or `rake rubocop:autocorrect_all` to handle auto-corrections.
+This can take a while to run so is most useful to check your local environment and to run once you've finished developing a new feature.
 
-### ERB Lint
-
-We run `erb_lint` as templating lint check against our `engine` directory. From the `engine` directory run:
+To run just the quick checks use:
 
 ```sh
-rake erb_lint
-```
-
-### RSpec
-
-We run a suite of RSpec tests against our `engine` directory. From the `engine` directory run:
-
-```
-rake spec
+just check-quick
 ```
 
-We use Appraisal for managing different gemfiles for older Rails versions as well as for testing new ViewComponent versions. You can run appraisals using:
+The rest of this guide covers the each type of check in more detail and how to run them individually.
 
-```sh
-bundle exec appraisal install
-```
+## Formatting
 
-Followed by:
+We provide a just recipe for formatting the codebase using Prettier:
 
 ```sh
-bundle exec appraisal rake spec
+just fmt
 ```
 
-See the [Appraisal docs](https://github.com/thoughtbot/appraisal) for a full list of commands.
+You can check the formatting without making changes with `just lint-fmt`
 
-### Cypress
+## Linting
 
-We use [Cypress](https://www.cypress.io/) for two main things:
+Each component of the design system runs lint checks depending on the environment:
 
-1. To run accessibility checks against every component example using [`cypress-axe`](https://github.com/component-driven/cypress-axe)
-2. For behavioural tests against any interactive components (e.g. targeted content) as well as end-to-end tests for the design system form builder.
+- The top-level package runs lint checks using Stylelint and Oxlint
+- The engine and demo apps run lint checks using RuboCop and ERB_Lint
 
-You can run both from within the `demo` directory by either running:
+You can run them all with:
 
 ```sh
-./bin/rails cypress:open
+just lint
 ```
 
-Which will open the Cypress UI for interactive testing, or by running:
+Or on a per-component level with e.g. `just lint-engine`
 
-```sh
-./bin/rails cypress:run
-```
-
-Which will run all tests in a headless browser.
+## Unit tests
 
-### BackstopJS
+Similar to lint checks, each component of the design system runs unit tests depending on the environment:
 
-We use [BackstopJS](https://github.com/garris/BackstopJS) to automate visual regression testing of components by comparing DOM screenshots over time. The tests are run inside of Docker to ensure rendering consistency across different environments.
+- The top-level package runs unit tests using Vites
+- The engine and demo apps run unit tests using RSpec
 
-Firstly, run the demo app using:
+You can run them all with:
 
 ```sh
-./bin/rails server -e test
+just test
 ```
 
-With the demo app running, you can start the backstop tests using:
+Or `just t` for short; or on a per-component level with e.g. `just test-engine`.
 
-```sh
-npm run backstop
-```
+Specifically for engine checks, we use Appraisal for managing different gemfiles for older Rails versions. The Just recipe will run all versions. For details on working with individual appraisals see the [related engine guide](../demo/README.md).
 
-After a test run is complete you can run view the report in a browser using:
+## Browser tests
 
-```sh
-npm run backstop:report
-```
-
-If the test you ran looks good, then go ahead and approve it. Approving changes will update your reference files with the results from your last test. Future tests are compared against your most recent approved test screenshots.
+We use the `demo` app to run a series of browser tests, specifically:
 
-```sh
-npm run backstop:approve
-```
+- Cypress for component and accesibility testing; and
+- BackstopJS for visual regression testing
 
-You can run tests for a specific set of scenarios by passing a filter to the backstop command where `Example` is the search term you want to filter by.
+You can run these tests using:
 
 ```sh
-npm run backstop -- --filter=Example
+just test-demo
 ```
 
-For more details see the [BackstopJS Github page](https://github.com/garris/BackstopJS)
+They also form part of the slower `test-all` and `check-all` commands. If you are looking to work directly with the tests themselves as part of development see the [related demo guide](../demo/README.md).
 
 ## Testing with your application
 

@@ -18,37 +18,7 @@ An alternative to makefiles is [just](https://just.systems/man/en/introduction.h
 
 ## Decision
 
-Use [just](https://just.systems/man/en/introduction.html) for project specific commands. We will start with an initial list of recipes and expand over time:
-
-```sh
-Available recipes:
-    adr title     # Generate a new ADR
-    check-all     # Run all checks
-    format        # Run formatters [alias: fmt]
-    format-check  # Check format only
-    help          # List available recipes
-    setup         # Setup project
-
-    [demo]
-    demo-check    # Check demo app only
-    demo-dev      # Run a dev server for the demo app
-    demo-setup    # Setup demo app only
-
-    [engine]
-    engine-check  # Check engine only
-    engine-setup  # Setup engine only
-    engine-sync   # Sync fonts between npm source and engine
-
-    [package]
-    package-check # Check npm package only
-    package-setup # Setup npm package only
-
-    [website]
-    website-build # Build a static copy of the website
-    website-check # Check website only
-    website-dev   # Run a dev server for the website
-    website-setup # Setup website only
-```
+Use [just](https://just.systems/man/en/introduction.html) for project specific commands. We will start with an initial list of recipes and expand over time.
 
 ## Consequences
 

@@ -15,12 +15,12 @@ This app:
 Following this you should be able to run the dev server with:
 
 ```sh
-just demo-dev
+bin/dev
 ```
 
 The engine code bundles a set of component previews which can be seen at `http://localhost:3000/rails/view_components`.
 
-## Running cypress tests
+## Working with Cypress tests
 
 We use [Cypress](https://www.cypress.io/) for two main things:
 
@@ -33,15 +33,9 @@ You can run both from within the `demo` directory by either running:
 ./bin/rails cypress:open
 ```
 
-Which will open the Cypress UI for interactive testing, or by running:
+When running Cypress this way you'll need a copy of the demo app running with `bin/dev`.
 
-```sh
-./bin/rails cypress:run
-```
-
-Which will run all tests in a headless browser.
-
-## Running visual regression tests
+## Working with visual regression tests
 
 We use [BackstopJS](https://github.com/garris/BackstopJS) to automate visual regression testing of components by comparing DOM screenshots over time. The tests are run inside of Docker to ensure rendering consistency across different environments.
 

@@ -7,10 +7,12 @@ A Rails Engine packaged as a gem which provides a set of [view components](https
 Run tests with via just or, within the `engine` directory directly via `rake`:
 
 ```sh
-just engine-check
+just lint-engine test-engine
 ```
 
-By default this will run all rspec, rubocop, and erb-lint checks. You can view all available tasks with `rake -T`.
+This will run all rspec, rubocop, and erb-lint checks. You can view all available tasks with `rake -T`.
+
+## Working with Appraisal
 
 We use Appraisal for managing different gemfiles for older Rails versions as well as for testing new ViewComponent versions. By default the just recipe above will run all appraisal specs, you can run appraisals using:
 
@@ -27,5 +29,5 @@ We provide some additional utility tasks for developing the engine.
 Font files can be synced between the package and the engine with:
 
 ```sh
-just engine-sync
+rake sync_fonts
 ```