The starting file / native recordA successful command.
A partial answer.
Our fictional reading-room system has four colors, two type styles and one component. Its first lint run reports no errors. It also reports two warnings: two colors have no component references.
0errors
2 warnings · 1 information item
The exported theme contains the four colors, font names, font sizes, heading weight, rounding and spacing. It does not contain the instruction to put the reading queue beside the excerpt.
Open the actual lint record
Recorded with @google/design.md 0.4.0
designmd lint base.DESIGN.md
"summary": {
"errors": 0,
"warnings": 2,
"infos": 1
}Read the full JSON output
The warnings name colors.paper and colors.quiet. Both appear in our written design reasoning; neither is referenced by a component token. This warning is not a finding that their hex values are invalid.
A document result is not a rendered-page test. Keep the warnings with the output instead of reporting “passed” with no qualification.
Read the entire 55-line source ↗
Controlled change / prose onlyA different layout.
The same CSS.
We replaced one sentence so the reading queue should sit above the excerpt instead of beside it. The exported CSS stayed byte-for-byte identical. The native diff reports no token changes and regression: false.
Compare the two layout instructions
BASE
Keep a separate narrow reading queue alongside the excerpt.
PROSE CHANGE
Place the reading queue above the excerpt as a single wrapping line.
These are exact sentence changes, not screenshots of generated pages. The complete files retain all the other content. Read the native diff.
For a layout revision, send the changed DESIGN.md and say which sentence changed. A theme-only handoff would silently drop this decision. “No token regression” does not mean “no design change.”
Inspect the original layout paragraph ↗
Controlled change / one named colorOne value.
Two affected tokens.
#D1F15F→#F4B9D1
Changing only colors.signal changes the exported --color-signal. The diff lists both signal and button-primary as modified, because that component points to the color through {colors.signal}.
Inspect the token-change result
The component’s reference text is unchanged. Native diff follows its resolved value. The CLI still reports regression: false; changed tokens are not automatically a regression.
Use a named reference for a shared role; inspect dependent components when its value changes. Then update the prose too: our isolated test still says “Signal green,” so it is deliberately not a polished design handoff.
Repeated group / empty output / repairZero errors.
Empty export.
We added a fenced YAML block that defines colors again. Version 0.4.0 returns one duplicate-group warning and an empty theme. Both lint and export exit successfully. The draft specification dated 16 October requires duplicate top-level groups to be rejected; the recorded package behavior is different.
Actual output from css-tailwind export
@theme {
}See the duplicate and the repair
The added block repeats an existing top-level group
```yaml
colors:
extra: "#133277"
```
Repair: put the extra value in the original colors group; remove the second group.
colors:
primary: "#202025"
paper: "#F5EEDC"
signal: "#D1F15F"
quiet: "#5A5860"
extra: "#133277"
Our repaired file exports all five colors, including --color-extra: #133277;. Lint now reports three orphaned-token warnings, because the added color also has no component reference. Those warnings are visible; the empty-output failure is gone.
Duplicate inputRepaired inputRepaired output
If an export is empty, inspect both stderr/stdout and the actual file. Check repeated groups before assuming that every fenced block is unsupported. A zero process status alone is insufficient for this case.
Control case / same tokens in a fenced blockThe fence is not the failure.
We moved the complete YAML from the front matter into one fenced block under Colors, with no duplicated groups. Version 0.4.0 exported the same theme bytes as the baseline and returned the same two warnings.
What this control does—and does not—show
The input has one block containing all metadata and tokens. It proves that this specific fenced layout works in the recorded package. It does not test every legal distribution of groups across several blocks.
Choose where to place tokens for clarity, but define each top-level group once. If combining two files, consolidate their colors intentionally; merely pasting one after the other can create the repeated-group case above.