Forking dawn-design

Every client project starts from a fork of dawn-design. The fork keeps DS3's structure and architecture intact while letting you set your own token values. This page covers how forking works and how to tell the difference between an intended customization and an actual deviation from DS3.

Why forking works this way

DS3 uses a 3-tier token architecture: core, semantic, and component. The names of the tokens are what's mapped in code, not the values. Because of that, you can change a value freely without touching a single line of dev code, as long as the token name and its place in the architecture stay the same.

This is also why forking is safe by design. Your fork can look completely different from another project's fork while both stay fully compatible with the Template App.

Forking your project repo

What counts as a deviation

Not every difference between your fork and dawn-design is a problem. The distinction comes down to what changed.

Name deviations

A token name in your fork doesn't exist in canonical dawn-design, or a canonical token name has been renamed in your fork. Since dev code maps to token names, a name change means the Template App can no longer resolve that token correctly without extra dev work.

Structural deviations

The alias chain between tiers has been broken. Common examples:

• A core token aliases another token, instead of containing a resolved value
• A component token aliases a core token directly, skipping the semantic tier, outside of the rare documented exceptions
• A semantic token aliases a component token
• A color token has been added to semantic.json instead of light.json or dark.json

Any of these break the 3-tier architecture and should be corrected before merging.

Comparing your fork against the latest DS3

When checking your fork against dawn-design, always compare against the latest release on the default branch, not a specific older version you may have started from.