Persist a master design system with page-specific overrides

These files, merge rules and outputs are independently authored teaching materials, not upstream runtime results or measured model results.

Use case

Implement a checkout page using shared typography, text color and button spacing, with larger button padding on this page. Future sessions should retrieve both the shared baseline and this exception rather than guess which complete copy is current.

Two files exist under the teaching project root. design-system/shop/MASTER.md contains shared rules:

button.padding=12px
text.color=#0F172A
body.font_size=16px

design-system/shop/pages/checkout.md contains only the checkout deviation:

button.padding=16px

Teaching convention: merge by complete field name. Named page fields take precedence; unmentioned fields inherit the master. This fills in the example’s merge semantics, not an upstream implementation guarantee.

Mechanism

1. Establish the project root and page name checkout, then read the master. If it is missing, report that the shared baseline is unavailable and stop generating a design from it.
2. Locate the page file. If absent, use the master alone. If present but unreadable, report the error rather than treating read failure as absence of overrides.
3. Apply the field-level convention: replace only explicitly named page fields and retain other master values.
4. List effective rules and the origin of each value, then implement. Update shared rules in the master; maintain only necessary exceptions in page files.

Bad example

Implement checkout with the same supplied files:

Copy all of MASTER.md into checkout.md and edit each page independently from now on. Read only checkout.md during implementation; choose unspecified shared fields yourself and do not record where values came from.

Complete copies allow shared fields to drift independently. Reading only a sparse page file also mistakes an unlisted field for an unconstrained field.

Good example

Implement checkout. Resolve all paths from the project root.
Read design-system/shop/MASTER.md, then look for design-system/shop/pages/checkout.md.
Teaching merge rule: named page fields override matching master fields; unmentioned fields inherit the master.
If the page file is absent, use the master alone. If the master is missing or an existing file cannot be read, report the missing/read error and do not invent defaults.
First return effective button.padding, text.color and body.font_size with their origins, then implement using them.
Do not copy all shared fields into the page override file.

Replace the project directory, page name and managed fields, and state your own override convention. The supplied material yields this illustrative result:

Why the change matters

One master holds the shared baseline while page files express only deviations. Explicit merge granularity identifies replacement and inheritance. Recording origins lets a later session reconstruct the same effective rules instead of guessing values from appearance.

Observable expectation

Check the three effective values against the files. Remove the page file: expect the master’s 12px, #0F172A and 16px. Change only the master’s text color: checkout inherits it while retaining 16px button padding. A missing master must produce a missing-baseline report.

If code has been generated, inspect its actual styles against these values. Reading files and listing effective rules demonstrates merging, not runtime style compliance.

Limits

The upstream material proposes master-plus-page overrides without fully specifying field-level merging versus whole-file replacement. Define that convention before use. Project rules must separately define duplicate and deleted fields where relevant. Persisting files does not guarantee retrieval in later sessions or validate spacing, colors or accessibility.