DTCG typography tokens: model composites and verify the CSS result

As of October 24, 2026, the final DTCG 2025.10 publication governs the exchange format for this workflow. It describes the specification as stable and intended for implementation. Because it is a Community Group report rather than a W3C Standard, record the authority precisely as DTCG 2025.10 final.

The detailed drafts-path page uses the same Format Module version name, but it's a later preview dated September 8, 2026. Its warning says not to implement it or cite it as authoritative. The page can explain proposed changes, but it can't silently replace the final report in an implementation contract.

A typography token can carry reusable values and relationships. A composite groups a font family, size, weight, letter spacing, and line height into a semantic role such as body text. Aliases let several roles reuse one foundation without copying its literal value.

That contract stops before font delivery and component adoption. The token doesn't download a font, create an @font-face rule, establish that a requested face exists, choose fallback behavior for every script, or apply itself to a component. Those decisions belong to the web transform, font resources, project mapping, and component implementation.

• Authored source: token names, types, values, references, and composite structure.
• Resolved value: concrete DTCG values after the resolver has followed valid references.
• Transformed output: target names, unit serialization, composite expansion, and project-added fallbacks.
• Font resources: family names, static faces or variable ranges, styles, character coverage, and delivery locations.
• Project mapping: the variables, utilities, classes, or components that consume the emitted artifact.
• Rendered observation: computed values, selected fonts, wrapping, and fallback behavior under recorded conditions.

Start with the needs of named consumers. "The web" isn't a useful consumer description. Marketing-site CSS build, React Button label, and documentation preview are specific enough to inspect. For each one, determine whether its toolchain accepts composites, needs resolved atomic values, or requires a local mapping.

A mixed model is a useful starting point, not a standard requirement. Before choosing it, inventory the transformer's capabilities, the font resources each role requires, the fallback owner, and at least one consumer where you can inspect the entire route.

1. List the roles the product currently uses, such as body, label, heading, and code.
2. Mark which properties must change together and which are reused independently.
3. Check composite and alias support in the pinned transformer version.
4. Inventory the static faces or variable ranges and styles required by those roles.
5. Assign fallback policy to the portable source or a named target transform.
6. Select one representative consumer and write its expected result before running the pipeline.

The fixture below is original and illustrative. Atlas Sans is fictional, and no transformer was run for this article. The source combines atomic foundations with one composite body role. Before using this pattern in production, check the final DTCG 2025.10 Format and Resolver reports and the contract of your chosen tool.

{
  "font": {
    "family": {
      "sans": {
        "$type": "fontFamily",
        "$value": "Atlas Sans"
      }
    },
    "size": {
      "body": {
        "$type": "dimension",
        "$value": { "value": 16, "unit": "px" }
      }
    },
    "weight": {
      "regular": {
        "$type": "fontWeight",
        "$value": 400
      }
    },
    "lineHeight": {
      "body": {
        "$type": "number",
        "$value": 1.5
      }
    },
    "letterSpacing": {
      "body": {
        "$type": "dimension",
        "$value": { "value": 0, "unit": "px" }
      }
    }
  },
  "text": {
    "body": {
      "$type": "typography",
      "$description": "Default product body text",
      "$value": {
        "fontFamily": "{font.family.sans}",
        "fontSize": "{font.size.body}",
        "fontWeight": "{font.weight.regular}",
        "letterSpacing": "{font.letterSpacing.body}",
        "lineHeight": "{font.lineHeight.body}"
      }
    }
  }
}

After reference resolution, the expected composite still contains DTCG dimension objects. This is an expectation derived from the fixture, not output captured from a resolver.

{
  "fontFamily": "Atlas Sans",
  "fontSize": { "value": 16, "unit": "px" },
  "fontWeight": 400,
  "letterSpacing": { "value": 0, "unit": "px" },
  "lineHeight": 1.5
}

Keep this form intact. Converting the two dimension objects to 16px and 0px is a target transformation, not reference resolution. If resolution fails because of a missing target, cycle, or type conflict, fix that problem before investigating CSS serialization.

A web transform could serialize those dimensions, expand the composite, and add a project-owned fallback stack. The CSS below represents that target contract. It isn't output from an executed tool run.

:root {
  --type-body-font-family: "Atlas Sans", system-ui, sans-serif;
  --type-body-font-size: 16px;
  --type-body-font-weight: 400;
  --type-body-letter-spacing: 0px;
  --type-body-line-height: 1.5;
}

.text-body {
  font-family: var(--type-body-font-family);
  font-size: var(--type-body-font-size);
  font-weight: var(--type-body-font-weight);
  letter-spacing: var(--type-body-letter-spacing);
  line-height: var(--type-body-line-height);
}

The fallback families are a project decision added during transformation. If the fictional primary family is unavailable, the CSS remains valid while the browser selects system-ui or another fallback.

Typography delivery has two inputs that must agree: the role's declared values and font resources capable of fulfilling them. A role requesting weight 600 doesn't establish that a 600 static face is delivered or that a variable font covers that coordinate. Likewise, an available file doesn't establish that a component requests it.

• Family identity: deliberately map the token family to the CSS family used by @font-face.
• Weight availability: record each required static face or the relevant variable range.
• Style availability: identify required normal, italic, or oblique faces and deliberate omissions.
• Synthesis policy: decide whether synthetic bold or italic is acceptable, then include that condition in testing.
• Fallback order: choose ordered families for the role, scripts, symbols, and expected failure conditions.
• Loading policy: define font-display and delivery behavior in the font layer.
• Character coverage: test the content and scripts used by the named consumer.

The font-display descriptor belongs to an @font-face rule and controls display behavior while a face is loading or unavailable. Keep it out of a semantic typography role unless a separate, explicit project convention says otherwise. The token requests a family. The asset layer offers faces, the loading policy affects their display, and the browser chooses what renders.

Ambient Sage v1 provides a real public source record. It declares Plus Jakarta Sans for heading and body roles at weights 400, 500, 600, and 700. JetBrains Mono serves the mono role and technical strings at weights 400, 500, and 700. The published scale is compact-product, and the kit offers a DTCG export.

This intake establishes the declared roles, weights, scale, and artifact availability. It doesn't expose protected serialization or establish compatibility with a particular transformer. Font-file delivery, application mapping, accessibility, and rendering remain project checks.

{
  "source": "Ambient Sage v1",
  "sourceStatus": "public upstream intake",
  "declaredRoles": {
    "heading": "Plus Jakarta Sans",
    "body": "Plus Jakarta Sans",
    "mono": "JetBrains Mono"
  },
  "publishedWeights": {
    "headingAndBody": [400, 500, 600, 700],
    "mono": [400, 500, 700]
  },
  "scale": "compact-product",
  "serializationInspected": false,
  "transformCompatibility": "unresolved",
  "fontResourcesVerified": false,
  "namedConsumerObserved": false
}

Start with one role in one named consumer. Write the expectation first, then inspect the chain in order. Stop at the first divergence because later differences may follow from that earlier fault.

1. 1

   1. Validate the pinned source

   Record the final DTCG report version, source revision, token path, expected type, and expected value. Fail this stage for invalid source structure, an unexpected type, or a validator configured for another contract.

2. 2

   2. Inspect reference resolution

   Compare the resolver result with the expected DTCG object. Fail this stage for a missing target, cycle, incompatible reference, stale value, or premature target serialization.

3. 3

   3. Inspect transform normalization

   Record the transformer and version, target platform, name mapping, unit serialization, composite expansion, and fallback policy. Fail when the documented transform and actual configuration disagree.

4. 4

   4. Inspect the emitted artifact

   Open the CSS or target file distributed to the project. Confirm that the expected names and serialized values exist there, not only in an intermediate build location.

5. 5

   5. Verify font resources

   Inspect the family mapping, requested weights or variable range, required styles, character coverage, delivery route, and loading policy. Fail when the requested face can't be supplied under the test condition.

6. 6

   6. Verify project mapping

   Trace the emitted property into the named class, utility, theme entry, or component contract. Confirm that the consumer imports the intended artifact version.

7. 7

   7. Check component overrides

   Inspect local declarations, inheritance, responsive rules, states, and approved exceptions. Record any deliberate exception. Treat an unexplained override as a failure at this layer.

8. 8

   8. Observe the rendered result

   Record the browser, viewport, loading condition, and test content. Inspect computed styles and the selected font, then compare the result with the written expectation.

Keep the resolved DTCG value and emitted CSS in separate fields. Fill in expectations before execution. Add observations only after collecting evidence; not-run is a valid status.

{
  "governingContract": "DTCG 2025.10 final",
  "sourceVersion": "commit-or-release-id",
  "sourceToken": "text.body",
  "expectedResolvedValue": {
    "fontFamily": "Atlas Sans",
    "fontSize": { "value": 16, "unit": "px" },
    "fontWeight": 400,
    "letterSpacing": { "value": 0, "unit": "px" },
    "lineHeight": 1.5
  },
  "transformer": {
    "name": "record-the-actual-tool",
    "version": "record-the-actual-version",
    "target": "web-css"
  },
  "expectedEmittedCss": {
    "font-family": "\"Atlas Sans\", system-ui, sans-serif",
    "font-size": "16px",
    "font-weight": "400",
    "letter-spacing": "0px",
    "line-height": "1.5"
  },
  "namedConsumer": "Account settings body copy",
  "testContent": "Profile details 0123456789 Äé中",
  "inspectionCriteria": [
    "Expected CSS variables reach the component",
    "Computed values match expectedEmittedCss",
    "The intended face supplies the inspected glyphs",
    "No unrecorded component override changes the role"
  ],
  "failureConditions": [
    "A reference is unresolved or resolves to another value",
    "The emitted CSS differs from the recorded transform contract",
    "The requested face is unavailable or not selected",
    "A stale mapping or local override replaces the role"
  ],
  "observationStatus": "not-run",
  "observedResult": null,
  "firstDivergence": null,
  "correctionOwner": null,
  "nextTest": "Run the pinned transform, inspect the distributed CSS, then check computed values and the rendered font in the named consumer"
}

Run this record first for one body role. If it passes, add a heading at a different weight and a mono role with representative technical content. The next test will then cover distinct faces and use cases instead of repeating the same path under more token names.

• Design Tokens Technical Reports 2025.10: The DTCG 2025.10 publication is a stable Final Community Group Report intended for implementation and identifies the Format, Color, and Resolver modules.
• Design Tokens Format Module 2025.10 preview: The later draft is explicitly labeled as preview material and says not to implement it or cite it as authoritative.
• The design tokens spec (DTCG) explained: The explainer covers general DTCG concepts including types, aliases, composite tokens, and tool support.
• Typography - Composite - Tokens Studio for Figma: Tokens Studio documents composite typography and related atomic token types within its own authoring environment.
• font-display CSS at-rule descriptor: The font-display descriptor controls how a downloaded font face is displayed based on whether and when it is available.
• Best practices for fonts: Font declaration, loading, delivery, and rendering are distinct web implementation concerns with separate choices and checks.
• Ambient Sage Design Kit: The public Ambient Sage v1 kit declares Plus Jakarta Sans for heading and body roles, JetBrains Mono for technical strings, published role weights, a compact-product scale, and a DTCG export.