Nesting Mechanism

How nesting works

The token system is hierarchical:

Seed tone
 └─ Surface 0 (tone computed from seed via levelConfig)
     ├─ Content on Surface 0 (contrast from Surface 0 tone)
     ├─ Inv-Content on Surface 0 (flipped direction)
     ├─ Container 0 on Surface 0 (contrast from Surface 0 tone)
     │   ├─ Content on Container 0 / Surface 0
     │   └─ Inv-Content on Container 0 / Surface 0
     ├─ Container 1 on Surface 0
     │   └─ ...
     ├─ Inv-Container 0 on Surface 0 (flipped direction)
     │   ├─ Content on Inv-Container 0 / Surface 0
     │   └─ ...
     └─ ...
 └─ Surface 1
     └─ ... (same structure repeated)
 └─ Surface 2
     └─ ...

Collection mapping

Each nesting combination gets its own Figma collection. Direct and inverse tokens are merged into the same collection (inverse tokens use path prefixes):

• theme/surfaces -- all surface levels in one collection
• theme/containers/surfaces-0 -- all container levels on Surface 0 (direct + inverse via inv/ prefix)
• theme/containers/surfaces-1 -- all container levels on Surface 1 (direct + inverse)
• theme/content-on-surfaces/surfaces-0 -- content tokens computed from Surface 0 tone (direct + inverse via inv/ prefix)
• theme/content-on-containers/surfaces-0 -- content on containers on Surface 0 (direct, inverse, on-inv, inv-on-inv -- all in one collection)

Why per-surface-level collections?

Containers on Surface 0 have different tones than containers on Surface 2. A button at 1.6:1 contrast on a near-white surface is a different color than the same 1.6:1 contrast on a darker surface. By splitting into per-surface collections, designers can reference the exact container level they need for each nesting depth.

surfaceScope optimization

If a container or content entity sets surfaceScope: "last", tokens are only generated for the last (deepest) surface level, reducing collection count significantly. In the preview, all levels still show the same values (computed from the scoped level) for visual consistency.

---