ADR-0143 The Figma library is three files
Amends: ADR-0142
#Context
Section 9 names four Figma files so consumers subscribe to what they need: Foundations, Components, Specifications and Proof. ADR-0142 generated the library into one file and listed the split as not yet done. One file mixes what a product binds to with what explains it, and a product file enabling it receives both.
#Decision
One plugin, one command per file. tools/figma-sync offers Sync Foundations, Sync Components and Sync Specifications, and keeps the single-file run as a fourth command.
| File | Made by its command | Published |
|---|---|---|
| Foundations | the variables, Getting started and the Foundations sheets | yes, as the library every other file binds to |
| Components | every drawn component, bound to the Foundations library's variables | yes, as the component library |
| Specifications | the composition matrix from the contracts, the intensity ladder from the components' legal pairs, and a table of every component token | no |
Components imports its variables; it makes none. A Components run imports the Foundations library's variables by name, so a product file has one set of variables however many libraries it enables. The Component collection is therefore published. Its tokens keep empty scopes, so none of them appears in a picker.
Values resolve from the repo's data. A drawing reads a token's value through the build's own definitions rather than through Figma, which does not expose an imported variable's modes the way it does a local one.
Specifications places published components by key. A Components run saves each set's and variant's key on the machine that ran it, and Specifications imports from those keys. It can only run after Components is published.
Proof is not a Figma file; the live example is Watchtower. Section 9's fourth file was built once, as a supervisor queue assembled from library instances, and it was not good enough to show. The example is Watchtower Overseer instead, live at https://www.davidpaterni.com/portfolio/case-studies/watchtower/prototypes/overseer.html: a running supervision app that embeds Wolf-Rayet's generated token sheets and paints with its roles. apps/proof/app/watchtower carries Watchtower's consent case in this repository, painted from the token files each time it is served. A Figma copy of it would be a second, weaker drawing of a screen that already runs on the system.
#Rejected options
Draw the components again in Specifications. It needs no publishing order. It lost because a component drawn in two files is two components.
Keep one file and use pages for the split. It is what ADR-0142 shipped. It lost because a product file that enables it receives the specifications along with the components.
#Consequences
No code changed and no scene moved. The order of first setup is fixed: Foundations is published before Components runs, and Components is published before Specifications runs. Each Specifications run imports from the machine that last ran Components.