Maintaining the system
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. The frontend contract lives under As a standalone frontend. The documentation renderer lives under As a Guides theme. These pages describe how those sources connect in this repository.
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 maps each output back to the source and the task that own it.
Ship packages#
The repository root is a workspace. Every directory under packages/ has
to leave as something a project can install. Package splits explains
how assembly, history replay and the consumer render keep that boundary
honest.
Demand visible evidence#
An element in source is not a maintained component. Component evidence
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.
Review the pixels#
A visual refactor needs a before image, an after image and an exact comparison. Visual review 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.
Test Storybook#
Every story is a test, and the Storybook shell is a second surface a story proves nothing about. Testing Storybook explains which runner opens which, and how the suite judges a story with axe.