Bringing Jig to an existing codebase

Getting started took you through one page, once. The loop taught you decide, spec, mockup, make, critique and tweak in depth, on any page or feature. This chapter is neither: it is your whole codebase, past that first page. It means reading a large codebase’s first check report without drowning in it, scoping adoption to the pages you are actually touching, and redesigning a page you already have on purpose, once you already know the loop this chapter keeps pointing you back to.

“Adopting Jig everywhere is not the price of using it anywhere.” Three cases follow from that, in this order: reading a large codebase’s first report, scoping adoption to new work, and redesigning a page deliberately.

Before you start

This chapter assumes Getting started and The loop are both already done on this project. If they are not, start there.

One switch here, Agent only, no Path switch: the agent you chose is already selected, and changing it here changes it on every chapter.

A large codebase

The first check --all on a big repo is a long list, and the list is not a to-do. Read it in this order:

1.
check --all --ci first: the mechanical bucket, errors only, an exit code fit for continuous integration (CI). It is the short list, and every line on it is decidable.
2.
Then warnings, by rule rather than by file: a rule firing forty times is one decision made once, not forty.
3.
Then one page at a time: check defaults to the files you changed, so once the first two passes are done it goes quiet and stays that way for everything except what you touch.

Nothing obliges you to reach zero. A check that is quiet on today’s diff is worth more than one that was quiet on the whole repo six months ago.

npx jig-ui@0.25.0 check --all --ci

Only the new pages

The rules apply to what you point them at:

New work follows the loop, already covered in depth in The loop, and the Stop hook holds it to that if you asked for the hook. A small change to a built page that its approved mockup does not show goes through tweak instead.
Old pages sit where they are. They are not rewritten, and the default check says nothing about a file you have not touched.
jig.config.json can exempt paths you have no intention of revisiting, and the report names every exemption on every run, so an exemption list cannot grow quietly. jig.config.json in full, every field it takes, is Tokens and modes’ own chapter.
The token layer works the same way for you. A page adopts a token when you edit it to use one; no page changes on its own.

Redesigning a page you already have

The opposite job, and the loop runs in its ordinary order. The difference is what the old page counts as: content and constraints, not a target.

1.
Measure the page as it is, first: probe --run <page> --save <slug> (--serve <build dir> for a built site). It records what the page does today at each width: whether it scrolls sideways, whether the menu opens, what order it reads in. Keeping it is the only way you can say afterwards whether the redesign improved anything or merely changed it. probe’s full set of flags belongs to The CLI, not to this chapter.
```
npx jig-ui@0.25.0 probe --run <page> --save <slug>
```
2.
decide, if you have not already.
3.
spec as normal, designing forward. Take the content from the old page: its copy, its real data, the questions its FAQ answers. Decide the structure from the rules, not from what the markup happens to do now. Anything that genuinely must survive is a constraint, so write it into the spec by name: a URL linked from elsewhere, a field order the back end depends on, wording someone signed off.
4.
mockup, low fidelity, reviewed before code. This is where a redesign is cheap for you to argue about.
5.
make builds it, and critique checks it against the spec, the mockup and your decisions.

You already know each of these five in depth from The loop; what this chapter says in full is only what a redesign specifically needs, above. The trap worth naming: carrying the old structure across because it is there. A page redesigned from its own markup ends up the same page with new colours. The old page is the brief’s content; the rules and the spec decide its shape.

Adopting Jig is additive. The pressure to move values into tokens arrives when you start using them, not on the day you install.