Weird things & diagnostics

Transtyle prefers surprising you loudly over failing silently. This page lists every diagnostic code and every behavior that looks wrong until you know why it’s right.

How a diagnostic is printed#

Two lines, never one:

✖ TST1301 Target "bootstrp" is not configured in transtyle.config.json
  ↳ Did you mean "bootstrap"? Configured targets: bootstrap, primeng

The first line says what is wrong; the ↳ hint says what to change. They’re separate fields (message and hint) in report.json too, so editors and CI annotations can place them independently. The “What to do” column below gives the same advice. The hint exists so you get it at the moment of failure, without coming here.

Two behaviors to know:

• Identical diagnostics are printed once. Derivation runs once per mode combination, so a single authoring mistake used to be reported once per combination. A two-token alias cycle printed twelve lines. Anything per-mode still says which mode in its message.
• Consequences are suppressed in favor of causes. A dangling alias makes semantic.color.primary.solid unresolvable, but you’re shown the dangling alias (TST1105), not the missing token (TST1201), because fixing the symptom wouldn’t have helped. Likewise an alias cycle reports TST1104 alone, not a “dangling alias” for each token in the loop. And a role whose .solid failed to resolve (TST1105, TST1104, TST1106) draws no dark-mode carry-over note (TST1204), because there is no light-mode colour to carry over. A role bound to a slot derived too late draws TST1205 only when its alias resolves in the end; a dangling or looping one reports TST1105 or TST1104 alone.

Diagnostic code reference#

TST1303 isn’t a separate code. An alias to a non-existent path is TST1105 above, part of the same “authoring mistake” family the DTCG validation pass (T10) documents together.

Aliasing a derived slot is fine and won’t raise TST1105: component.button.radius: "{semantic.radius.full}" works even though nothing authors radius.full, because such aliases resolve right after derivation. TST1105 means the target never exists, at any stage.

Surprising-but-correct behaviors#

A three-token design system is valid, and a target variable just goes missing#

Nothing obliges you to author a radius scale, a font stack, or a border color. If you don’t, the slots that derive from them don’t exist, and an exporter that has a binding for them emits nothing rather than a broken declaration. You’ll see the variable in report.json classed dropped, with a note naming the slot to author if you want it driven:

$btn-border-radius  dropped  nothing to bind: this design system has no
                             component.button.radius. The binding exists, its
                             source does not — author that slot (or the scale it
                             derives from) and this variable starts being driven.

The target’s own default then applies, which is what “we have nothing to say about this” should mean. A Bootstrap theme map is the one place an entry can’t go missing, because the exporter replaces Bootstrap’s whole map. The entry keeps Bootstrap’s own variable ("dark": $dark-text-emphasis) and is reported as $theme-colors-text.dark, dropped. check:minimal-ds compiles three design systems against every exporter on each CI run: a one-token one (only primary.solid, whose page and text the engine defaults), a three-token one (primary.solid, the page background elevation.0.surface and text.base), and one whose text.base is bound to a role cell (so neutral.text-strong and the content ladder stay empty). It asserts that none of them crashes and none writes a JavaScript value into a stylesheet.

My dark-native system comes out light-first#

modes.default declares your native mode; it doesn’t reorder exporter output. Exporters bind mode names. shadcn’s structure is always :root = light, .dark = dark, because that’s what shadcn consumers expect. Your native look is intact, just addressed by name. (Found by the Cathode example, now an IR rule.)

My brand color is identical in dark mode#

You didn’t author a dark value, so it falls back to the light one. That’s by design, and TST1204 (info) surfaces it in the report, not only here. The test is the resolved colour, not the token text: if you bound the role to your own vocabulary and that token carries a dark value, nothing carried over and no note is raised. Transtyle doesn’t invent brand decisions. Author primary.solid a dark-mode value (one line), or set derivation.autoDark: true so the carry-over is at least classified derived in coverage instead of authored. Either way the color itself stays the light one. autoDark doesn’t yet compute a distinct dark color, and that transform is still an open question (roadmap).

My dark page is my light text color#

You authored text.base with no dark value and left the page (elevation.0.surface) to the default, so dark mode got your light pair swapped: the page is your text color, the text is the light page. Before, your dark text carried over onto the default dark page at about 1:1. A page and its text, unlike a brand color, are not a brand decision, and the swap keeps your light mode’s exact contrast ratio. TST1206 (info) says it happened. transtyle explain semantic.color.text.base --mode dark shows the rule and the two light-mode values it read. Author both for color-scheme: dark to choose them yourself. An authored page is never swapped, even with no dark value: then the light pair carries over as written.

--secondary doesn’t look like my secondary color#

shadcn’s --secondary is a subtle surface (think of a secondary button background), not a brand-secondary. The exporter maps it from neutral.tint on purpose. Your brand secondary role exists in the IR and will map to targets that actually mean “second brand color”. The mistake in the other direction, porting a shadcn theme and binding its near-white --secondary gray to secondary.solid, is what TST1124 notes.

A variable is classified approximated#

Three current causes: --input (shadcn distinguishes input borders; the catalog doesn’t yet); gamut clamping where a target writes hex or HSL (shadcn’s tailwind-v3 era, Radix’s step scales, ECharts; the note says so); unit conversions. Approximation is information, not an error. The report exists so you can decide if you care.

Bootstrap and Storybook also write hex, but their reports do not class a clamped colour approximated yet. When the colour you authored is outside sRGB, TST1120 says so whatever the target, with the hex every hex-writing target ships.

Negative radius in the output#

shadcn derives its smaller rungs with fixed offsets: --radius-sm: calc(var(--radius) - 4px) and --radius-md: calc(var(--radius) - 2px). With radius.md: 0rem both are negative, and browsers clamp a negative calc() radius to 0, which is exactly what a square design asked for: nothing is reported. With a small non-zero radius (0.125rem, 2px), the same clamp turns rounded-sm and rounded-md square while you asked for rounded corners. That case is TST2104 (info), once per shadcn instance; author radius.md above 4px to keep every rung rounded.

Contrast warning on a color I like#

TST2101 prints the measured contrast: a WCAG ratio, or under check.contrast.standard: "apca" an APCA Lc whose sign gives the polarity (negative for light text on a dark background). Both are rounded toward zero, so a pair just under the level never prints as the level itself. It’s a warning, not a veto: set check.failOn to decide whether your CI cares. The number is real, though, and near misses (4.4:1) are the ones eyes don’t catch.

Two colors that can’t be told apart#

TST2102 and TST2103 measure the distance in OKLab (ΔE_OK, the Euclidean distance CSS Color 4 uses for gamut mapping, where 0.02 is the just-noticeable difference). They warn under 0.05, and they report a cluster once per mode: four status roles that all resolve to the same color give one warning naming the four, not six pairs. Two slots bound to one token (warning and a custom crt-amber role both bound to {semantic.color.crt.amber}) are a stated intent, so that pair is skipped. Equal colors in different tokens are the accident the check exists for. Both are warnings, so check.failOn decides whether CI cares. The derived palette and derived status roles never trip them (closest pairs: 0.082 and 0.12); they guard authored values.

Part of my scale went backwards#

The catalog fills every rung you don’t author with its default (space steps by 0.25rem, type.size is a 1.25 modular scale), and authored tokens always win. Tuning one rung is fine. Authoring an 8px space.1 to space.4 (0.5, 1, 1.5, 2rem) is not: space.4 is 2rem while the default space.5 is 1.25rem, so the shipped scale goes backwards. Authoring a scale under your own names (space.sm/md/lg) replaces nothing, because targets read the catalog’s rung names. Both are TST1121 (warning), once per scale. Units are compared in px (rem at units.remBase, 16px by default) or ms; em and calc() values are skipped.

Suppressing a diagnostic#

A warning or info you have looked at and accept can be silenced in transtyle.config.json, with the reason written next to it:

"check": {
  "suppress": [
    { "code": "TST1305", "path": "scratch", "reason": "scratch is a throwaway group for a spike" }
  ]
}

reason is required (an empty or blank one fails config load as TST1010). path is optional: an exact token path, or a prefix ending in .* (component.button.* matches the group’s children, not the group). Without path, the entry matches every diagnostic with that code, the only way to silence one that isn’t about a token, such as an exporter’s own TST2104. A suppressed diagnostic is silenced, not downgraded. It’s no longer printed and no longer counts for check.failOn. It stays auditable, listed with its reason under suppressed in report.json and check --json. Errors can’t be suppressed. An entry that matches nothing raises TST1012 (an info).

Where a diagnostic points#

A diagnostic about something you authored names the file, line and column of its key (✖ TST1105 tokens/brand.tokens.json:17:9 …), and report.json carries path, file, line and column. A diagnostic about a value Transtyle derived (a contrast ratio of a computed on-solid, a missing primary.solid) has no source line, because the value is in no file: it prints without one. Config-file errors name the file but not the line yet.

A generated file I didn’t touch is reported as changed#

TST1312 compares each generated file with the hash its last build recorded in transtyle-manifest.json. Something other than you can change a file. A formatter or a linter run over the whole repository (Prettier, Stylelint --fix) can, and so can an editor that trims trailing whitespace on save, or a merge that resolved a conflict inside dist/. Exclude the output directories from those tools (.prettierignore, the linter’s ignore file), then rebuild. Line endings are not a cause: hashes are taken with CRLF turned into LF, so a Windows checkout with core.autocrlf is not reported.

Two builds, byte-identical output#

Not a bug, a promise. No timestamps, no randomness, sorted file loading, fixed number formatting. If two builds of the same inputs ever differ, that is a bug, so please report it.