---
title: "Maintaining the system"
description: "This section is for work on Soul itself."
canonical: index.html
navigation-title: "Maintaining"
---

<a id="maintaining-the-system"></a>

# Maintaining the system

- [Start with the source](#start-with-the-source)
- [Ship packages](#ship-packages)
- [Demand visible evidence](#demand-visible-evidence)
- [Review the pixels](#review-the-pixels)
- [Test Storybook](#test-storybook)

This section is for work on Soul itself. Where the source is, and what a
task generates from it. How to change the repository without an edit to an
artefact the next build replaces.

The product rules stay with the surfaces they govern. Design decisions and
their reasons live under [Design system](../design-system/index.md). The frontend contract
lives under [As a standalone frontend](../frontend/index.md). The documentation renderer lives under
[As a Guides theme](../guides-theme/index.md). These pages describe how those sources connect
in this repository.

- [Source and output](source-and-output.md)
- [Package splits](package-splits.md)
- [Component evidence](component-evidence.md)
- [Visual review](visual-review.md)
- [Storybook tests](storybook-tests.md)

<a id="start-with-the-source"></a>

## Start with the source

Every artefact has one hand-written source. A generated file can be useful
evidence, and git can keep it for a consumer, but a change never starts
there. [Sources and generated output](source-and-output.md) maps each output back to the source and the
task that own it.

<a id="ship-packages"></a>

## Ship packages

The repository root is a workspace. Every directory under `packages/` has
to leave as something a project can install. [Package splits](package-splits.md) explains
how assembly, history replay and the consumer render keep that boundary
honest.

<a id="demand-visible-evidence"></a>

## Demand visible evidence

An element in source is not a maintained component. [Component evidence](component-evidence.md)
explains why stories, drawn classes and the Guides render catch different
failures, and how `make verify ARGS=coverage` keeps a temporary gap from
a permanent exemption.

<a id="review-the-pixels"></a>

## Review the pixels

A visual refactor needs a before image, an after image and an exact
comparison. [Visual review](visual-review.md) explains how the screenshot loop freezes
moving state, and why its comparison has no tolerance. And how to tell a
repeated change from the known drift in guideline cards.

<a id="test-storybook"></a>

## Test Storybook

Every story is a test, and the Storybook shell is a second surface a story
proves nothing about. [Testing Storybook](storybook-tests.md) explains which runner opens
which, and how the suite judges a story with axe.