Maintaining the system
This section is for work on Soul itself: finding the authoritative source, understanding what a task generates from it, and changing the repository without editing an artefact that will be replaced on the next build.
The product-facing 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 are wired together in this repository.
Start with the source#
Every maintained artefact has one hand-written source. A generated file can be useful evidence and may be committed for a consumer, but it is never the place where a change begins. Sources and generated output maps each output back to the source and task that own it.
Ship packages#
The repository root is a workspace, while every directory under packages/
must leave as something a project can install. Package splits
explains how assembly, history replay and the consumer render keep that
publication boundary honest.
Require visible evidence#
An element in source is not enough to make it a maintained component.
Component evidence explains why stories, drawn classes and the Guides
render catch different failures, and how make verify ARGS=coverage keeps
temporary gaps from becoming permanent exemptions.
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, why its comparison has no tolerance and how to distinguish a repeated change from the known drift in guideline cards.
Test Storybook#
The component preview and the Storybook shell are separate browser surfaces, and the accessibility panel shares axe with the test suite. Testing Storybook explains how the shipped build keeps those paths from testing around one another.