google-labs-code / google-labs-code/design.md

dtcg export omits required typography properties, so output fails the schema it declares

Open
#172 1 comment 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
TypeScript
Stars
28k
Forks
2.3k
PR merge metrics
No merged PRs in 30d

Description

What happened

export --format dtcg emits typography tokens that are missing two of the five properties the DTCG typography value schema marks as required, so the output does not validate against the schema it declares in its own $schema field.

Reproduction

Any spec with a typography section — here olmo-earth/DESIGN.md from allenai/design.md:

npx @google/design.md@0.4.0 export --format dtcg olmo-earth/DESIGN.md | jq '.typography["body-md"]'
{
  "$type": "typography",
  "$value": {
    "fontFamily": "Manrope, Arial, sans-serif",
    "fontSize": { "value": 16, "unit": "px" },
    "fontWeight": 400
  }
}

The source frontmatter for that role is:

body-md:
  fontFamily: "{typography.font-body}"
  fontSize: 16px
  fontWeight: 400
  lineHeight: 1.6
Why it's a problem

The emitted document declares "$schema": "https://www.designtokens.org/schemas/2025.10/format.json". That schema's typography value definition:

properties: fontFamily, fontSize, fontWeight, letterSpacing, lineHeight
required:   fontFamily, fontSize, fontWeight, letterSpacing, lineHeight
additionalProperties: false

All five are required. The export emits three, so every typography token fails validation — 10 of 10 in the spec above, each missing letterSpacing and lineHeight.

lineHeight is the one that bites in practice: it's present in the source frontmatter and silently dropped, so a consumer round-tripping through DTCG loses it. (letterSpacing isn't in the DESIGN.md format at all, so it has no source value — worth deciding whether to emit a default, omit the $type, or target a profile that doesn't require it.)

Suggested fixes, in order of preference
  1. Emit lineHeight from the frontmatter, and emit letterSpacing with an explicit default ("0" / {value: 0, unit: "px"}) so the token validates.
  2. If a required property genuinely has no source value, drop $type: "typography" for that token and emit the sub-values as a plain group — invalid-by-omission is worse than untyped.
  3. Failing either, stop advertising the 2025.10 $schema in the output, so downstream validators don't reject a file that claims conformance.

Happy to send a PR for option 1 if that's the direction you'd want.

Environment

@google/design.md@0.4.0, Node 25.2.1, macOS.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reproducing the export --format dtcg command with olmo-earth/DESIGN.md, then trace the DTCG typography serialization entry point. Verify how frontmatter lineHeight is handled and decide how missing letterSpacing should be represented; done means the output validates against its declared schema without losing source values.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
cli
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
64/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.