@transtyle/exporter-shadcn 0.1.0-alpha.2 → 0.1.0-alpha.4

package/CHANGELOG.md

@@ -0,0 +1,126 @@
+# @transtyle/exporter-shadcn
+
+## 0.1.0-alpha.4
+
+### Minor Changes
+
+- dc79f14: Breaking (alpha): `semantic.color.border` is now a ladder, `semantic.color.border.{subtle, base, strong, field}`, and the catalog gains an inverse pair, `semantic.color.inverse.{surface, text}` (proposal 0005).
+
+  Move your border token from `semantic.color.border` to `semantic.color.border.base`: a token left at the old path is now an error (`TST1126`) that names the new one, and the css-variables exporter writes `--color-border-base` instead of `--color-border`. `border.base` derives from `text.base` when you don't author it, so a minimal design system now has a border; `border.subtle` and `border.strong` (the smallest step toward the text that reaches 3:1) derive from it, and `border.field`, the form-field border at rest, aliases it. `inverse.surface` / `inverse.text` default to `neutral.text-strong` / `elevation.0.surface` and are contrast-checked as a pair.
+
+  Exporters read the new slots where the target has a matching variable: shadcn's `--input` and Storybook's `inputBorder` read `border.field`; PrimeNG's field, card and overlay borders now follow your border instead of the neutral outline, its field, list and menu icons follow the text ladder, its `contrast` severity reads the inverse pair, and its tooltip does too when you author the pair; Bootstrap's tooltip follows an authored pair in both modes, and its close button and select chevron take `text.base` instead of staying `#000` and `#343a40`; Chakra's `bg.inverted`, `fg.inverted` and `border.subtle` read the new slots. Unauthored, Bootstrap, shadcn, daisyUI, ECharts, Radix, Storybook, Mantine and MUI colours are unchanged apart from those two Bootstrap glyphs.
+
+  A token that has both a `$value` and child tokens is now an error (`TST1314`), as DTCG requires; its children used to be dropped silently.
+
+  `transtyle bind --suggest` proposes `border.base` and the inverse pair, and its name table is now `synonyms@2`: a text or surface name with an inverse word (`text-inverse`, `background-inverse`) reads as `inverse.text` / `inverse.surface`, never as `text.inverse`.
+
+- 0ae9eb5: A JSON mapping table can now be an exporter, and a target can name the framework version it is built for.
+
+  **Declarative exporters.** Point a target at a mapping file next to the config (`"exporter": "./ourlib.mapping.json"`): rows of `{ variable, slot, part?, format?, class?, note? }` in CSS custom properties, Sass, Less or JSON files, with selector blocks per mode value. Core runs it like any exporter and derives the coverage report from the rows; no code runs. A package can ship a mapping instead of code (`"transtyle": { "declarative": "mapping.json", … }`): the CLI reads it and never imports the package. A malformed mapping is `TST1014`, a row naming an unknown slot `TST1015`; the format is published as `schemas/mapping/v0.json`. `@transtyle/core` exports `createDeclarativeExporter`, `validateMapping`, `loadDeclarativePackage` and friends, so `conformance(createDeclarativeExporter(mapping))` tests a mapping like any plugin.
+
+  **Version profiles.** `targets.<t>.version: "5.3.8"` selects the exporter manifest range that covers it; the exporter gets `ctx.targetVersion` and `ctx.targetProfile`, and `report.json` records `version: { requested, profile }`. A version outside every range is `TST1313`. shadcn's manifest now declares Tailwind ranges (`>=3 <4`, `>=4 <5`) instead of era names, so `"version": "3.4.17"` selects the tailwind-v3 output; `options.era` still wins when set, with a `TST2105` warning if the two disagree. plugin-kit's new `manifest-targets-ranges` check rejects a `targets` entry that isn't a version range. Without `version`, output is unchanged.
+
+  **css-variables** now writes `palette.categorical.*` in its dark block too; its dark values were missing.
+
+- a8afe0f: The reserved `contrast`, `motion` and `brand` mode dimensions now reach the targets. A mode-scoped layer may name several dimensions (`"mode": { "color-scheme": "dark", "contrast": "more" }`): its values apply to that combination only, and win there; a token with values on two dimensions and no such layer is reported `TST1125`. Under `contrast: more` the derived on-colors and content text aim at 7:1 (rule `contrast-more`) and `check` holds every `more` combination to 7:1; under `motion: reduced` every unauthored duration is `0ms` (rule `motion-reduced`). `check` now measures every combination of the mode matrix, and `explain --mode` lists the combination keys it accepts.
+
+  CSS targets (css-variables, shadcn, Radix, Bootstrap's `bootstrap-theme.css`) add `[data-contrast]`, `[data-motion]` and `[data-brand]` blocks, a compound block for each combination the separate ones would get wrong (dark + more contrast used to get the light values in css-variables), and `@media (prefers-contrast: more)` / `(prefers-reduced-motion: reduce)` copies so the OS setting applies until the page sets the attribute (css-variables: `options.mediaQueries: false` turns them off). daisyUI emits one theme per brand and contrast combination, ECharts one theme per brand and scheme, Storybook a toolbar per dimension, and Bootstrap's Sass files, PrimeNG, Mantine, Chakra and MUI one file per brand (`preset.transtyle.<brand>.ts`). A target that can't express a dimension reports a `dropped` row with its reason. `brand` values must be lowercase names (`^[a-z0-9][a-z0-9-]*$`). `@transtyle/ir` exports the helpers (`modeBlocks`, `emitPerValue`, `pinDimension`, `MODE_MEDIA_QUERIES`). A design system that declares none of these dimensions compiles to the same files as before.
+
+- 053f796: New info `TST2104`: when `radius.md` is above 0 but at most 4px, shadcn's own offsets bring `--radius-sm` (and `--radius-md` at 2px or less) to 0 or below, so `rounded-sm` renders square. The exporter now says so once per instance, in both eras (`borderRadius.sm`/`md` in tailwind-v3). `radius.md: 0` is a square design and stays silent.
+- a786b21: Carry DTCG `$description` and `$deprecated` through to the outputs.
+
+  Both fields used to load and then disappear. A token's `$description` is now written as a comment line above its variable in css-variables, shadcn and daisyUI (and above Bootstrap's `$primary…$danger`), added as `description` to the matching items of every `report.json`, and printed by `transtyle explain` under the value line. `$deprecated` (`true` or a reason, inherited from its group, `false` to opt out) reaches the same places, and a semantic or component slot whose value still comes from a deprecated token warns `TST1122` with the reason as the hint; every target's `usage.md` lists those variables under "Deprecated tokens", and their report items carry `deprecated` and `deprecatedBy`. A `$description` that isn't a string, or a `$deprecated` that isn't `true`, `false` or a string, warns `TST1311` and is ignored. Design systems that describe their tokens (GOV.UK and Carbon among the examples) see new comment lines in those files; nothing else changes. Exporter authors read `entry.description` and `entry.deprecated`, with `entryNotes()`, `blockComment()` and `lineComment()` from `@transtyle/ir`.
+
+### Patch Changes
+
+- 305dd4e: Accept a `fontFamily` written as one string, and list every diagnostic of a build in every `report.json`.
+
+  A `fontFamily` token (or a `typography` member) authored as a CSS list in one string, `"Inter, system-ui, sans-serif"`, which DTCG allows, crashed the shadcn, ECharts, Bootstrap and Storybook exporters with `TST3001`. NORMALIZE now splits it into the array of names exporters read, so both forms compile to the same bytes on every target; a quoted name (`'Helvetica Neue'`) loses its quotes like the array form, a `var(…)` stays whole, and an empty name or a non-string entry is `TST1106`. `@transtyle/ir` exports the two helpers the official exporters now share, `fontNames()` and `fontStack()`, for third-party exporters that read font families.
+
+  Each target's `report.json` was serialised as soon as that target ran, so a diagnostic an exporter raised for a later target (shadcn's `TST2104`) was missing from the earlier targets' reports. Reports are now built after the last target, from the final list, and `check.suppress` runs at that point too: an exporter's own diagnostic can be suppressed like any other, where a rule for it used to match nothing (`TST1012`) and leave it printed.
+
+- 5602f4a: Make the packages findable on npm.
+
+  All twelve alphas published with no `keywords`, which on npm is the same defect as the blank README the previous alpha fixed: search ranks on name, description and keywords, so a package with none is reachable only by someone who already knows what it is called — and the people it most needs to reach are precisely the ones who don't. Someone looking for "design tokens bootstrap theme" found nothing.
+
+  Every package now carries the two shared anchors (`design-tokens`, `design-system`) plus its own terms — the exporters name their target and that ecosystem's vocabulary, so `exporter-primeng` answers a PrimeNG search and `exporter-radix` a Radix Colors one. `check:manifests` was extended to enforce all of it: the field must exist, carry both anchors, and hold lowercase space-free tokens with no duplicates. Verified by breaking each of the four rules in turn and watching the message name the real problem.
+
+- e5bac21: Put the project's logo on every package page.
+
+  Each README now opens with the Transtyle mark, linked to the documentation site. It is referenced by absolute URL and in the on-dark variant on purpose: npm renders package pages outside the repository, so a relative path 404s there, and it renders them on both a light and a dark background from a single `<img>` with no way to swap per theme — the on-dark variant is the one that reads on both.
+
+  The mark itself is generated rather than maintained: one description in `scripts/gen-brand.mjs` renders both SVG variants, their PNG rasters, and the site's favicon and app icons, and a new `check:brand` guard fails on a stale asset or on a surface that has quietly stopped carrying it — including these twelve pages.
+
+- 570b458: Add `targets.<t>.modes` to emit only some mode values for a target.
+
+  A project declares its modes once and every target used to receive the whole matrix, so a light-only Bootstrap site next to a light+dark shadcn app meant a second config or unwanted dark blocks. A target can now narrow it: `"bootstrap": { "modes": { "color-scheme": ["light"] } }` keeps only that value (a dimension you don't name keeps all of its values). Derivation and checks still run once on the full matrix; the exporter receives only the kept combinations, so a single-value dimension behaves like today's single-mode projects. A subset that names an undeclared dimension or value, or leaves out the dimension's default, is the new error `TST1308` and nothing is emitted for any target. A dimension narrowed this way is a deliberate exclusion: no `dropped` coverage row, and the target's `usage.md` lists the modes its files contain. The Bootstrap, shadcn, daisyUI and css-variables `usage.md` no longer describe a dark mode they didn't generate. The config JSON schema gains the `modes` target key.
+
+- Updated dependencies [dc79f14]
+- Updated dependencies [abff3a3]
+- Updated dependencies [305dd4e]
+- Updated dependencies [5602f4a]
+- Updated dependencies [e5bac21]
+- Updated dependencies [ed1445d]
+- Updated dependencies [a8afe0f]
+- Updated dependencies [a786b21]
+  - @transtyle/ir@0.1.0-alpha.4
+
+## 0.1.0-alpha.3
+
+### Patch Changes
+
+- 3d71e2f: Ship `CHANGELOG.md` in every published package.
+
+  npm always includes `README` and `LICENSE` regardless of the `files` allowlist, but not the changelog — so the first three alphas published with no version history at all, on the one page a stranger reads to decide whether upgrading is safe. Changesets has been writing the file since `0.1.0-alpha.0`; only the allowlist was keeping it in the repo.
+
+  `check:manifests` now requires it, so a package added later cannot quietly ship without one.
+
+- af10209: Ship the MIT licence text in every published package.
+
+  npm adds a `LICENSE` file to a tarball only when one sits in the package directory. Only the monorepo root had one, so the first three alphas published twelve packages that each declared `"license": "MIT"` without carrying the text those terms ask to be distributed with them.
+
+  Each package now holds a copy, and `check:manifests` requires it to be byte-identical to the root one — twelve copies of a licence being exactly the sort of thing that drifts a copyright year with nobody noticing.
+
+- Updated dependencies [3d71e2f]
+- Updated dependencies [af10209]
+  - @transtyle/ir@0.1.0-alpha.3
+
+## 0.1.0-alpha.2
+
+### Patch Changes
+
+- 16dc98d: Give every package a README, and point `homepage` at its documentation page.
+
+  All twelve packages shipped `0.1.0-alpha.0` and `.1` with no README, so each rendered as a blank page on npmjs.com — the surface most people meet the project on, and the only one nobody working in the repo ever reopens. Each now says what it emits, how to use it, and that it is an experimental alpha, and links into the documentation site rather than at the monorepo root.
+
+  `@transtyle/exporter-primeng`'s description also claimed it was "not yet registered in the CLI". It has been since C6; the sentence was published to npm twice after it stopped being true.
+
+  `check:manifests` grew two checks for the class: a package must have a README that is more than a stub, and a `homepage` naming a docs page must name one that exists — a 404 baked into published metadata cannot be fixed without another release.
+
+- Updated dependencies [16dc98d]
+  - @transtyle/ir@0.1.0-alpha.2
+
+## 0.1.0-alpha.1
+
+### Patch Changes
+
+- @transtyle/ir@0.1.0-alpha.1
+
+## 0.1.0-alpha.0
+
+### Minor Changes
+
+- First public alpha.
+
+  Transtyle compiles a framework-agnostic description of a design system — DTCG tokens plus semantics and modes — into native theme artifacts for eight targets: Bootstrap, shadcn/ui, daisyUI, Apache ECharts, Storybook, Radix Colors/Themes, PrimeNG, and plain CSS variables. Unauthored values are filled by deterministic, inspectable derivation rules rather than hidden defaults, every generated value carries provenance you can query with `transtyle explain`, and every build emits a coverage report saying what mapped natively, what was derived, what was approximated, and what the target cannot express.
+
+  All three token tiers — raw/option, semantic and component — are mapped on the two component-heavy targets, Bootstrap and PrimeNG, each measured against a checked-in inventory of the target's real theming surface so gaps are reported rather than quietly skipped.
+
+  Import is DTCG only in this release. Tailwind, Figma and CSS-custom-property importers are post-alpha.
+
+  **This is an experimental alpha.** Breaking changes ship without a deprecation cycle: the token vocabulary, the generated output, the config format and the CLI surface can each change between alpha releases, and none of it carries a stability or support promise. Pin an exact version, and treat generated files as disposable output you regenerate rather than hand-edit. The reasoning is recorded in ADR-0010; the release process is documented in RELEASING.md.
+
+### Patch Changes
+
+- Updated dependencies
+  - @transtyle/ir@0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Julien Déramond and Transtyle contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,7 @@
+<p align="center">
+  <a href="https://transtyle.github.io/transtyle/"><img src="https://raw.githubusercontent.com/transtyle/transtyle/main/brand/transtyle-mark-on-dark-256.png" alt="Transtyle" width="88" height="88"></a>
+</p>
+
 # @transtyle/exporter-shadcn
 
 shadcn/ui backend for **[Transtyle](https://transtyle.github.io/transtyle/)**, a design system compiler.

package/package.json

@@ -1,14 +1,26 @@
 {
   "name": "@transtyle/exporter-shadcn",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.4",
   "description": "Transtyle exporter for shadcn/ui (tailwind-v4 era).",
+  "keywords": [
+    "design-tokens",
+    "design-system",
+    "dtcg",
+    "theming",
+    "shadcn",
+    "shadcn-ui",
+    "tailwindcss",
+    "tailwind-v4",
+    "radix",
+    "css-variables"
+  ],
   "type": "module",
   "main": "./src/index.js",
   "exports": {
     ".": "./src/index.js"
   },
   "dependencies": {
-    "@transtyle/ir": "0.1.0-alpha.2"
+    "@transtyle/ir": "0.1.0-alpha.4"
   },
   "transtyle": {
     "kind": "exporter",
@@ -17,8 +29,8 @@
     "pluginApi": "0",
     "targets": {
       "shadcn": [
-        "tailwind-v3",
-        "tailwind-v4"
+        ">=3 <4",
+        ">=4 <5"
       ]
     },
     "modes": [
@@ -29,7 +41,8 @@
     ]
   },
   "files": [
-    "src"
+    "src",
+    "CHANGELOG.md"
   ],
   "publishConfig": {
     "access": "public"

package/src/index.js

@@ -2,11 +2,15 @@
  * @transtyle/exporter-shadcn — emits a shadcn/ui theme from the resolved IR.
  * Spec: docs/specs/exporters/shadcn.md. Two era profiles (ADR-0006 mapping
  * profiles): "tailwind-v4" (OKLCH + @theme inline) and "tailwind-v3"
- * (HSL channel triplets + tailwind.config snippet). Selected via target
- * options.era in transtyle.config.json — never via CLI flags.
+ * (HSL channel triplets + tailwind.config snippet). shadcn has no version of
+ * its own: both profiles follow Tailwind CSS, so the manifest's ranges are
+ * Tailwind versions (`>=3 <4`, `>=4 <5`) and `targets.shadcn.version` is the
+ * project's Tailwind version, from which core selects the profile
+ * (ctx.targetProfile). `options.era` stays as an explicit override. Both are
+ * set in transtyle.config.json — never via CLI flags.
  */
 
-import { droppedDimensions } from '@transtyle/ir';
+import { droppedDimensions, entryNotes, blockComment, fontNames, fontStack, modeBlocks, formatModeBlocks, modeBlocksUsage } from '@transtyle/ir';
 
 const S = 'semantic.color.';
 const P = 'semantic.palette.categorical.';
@@ -32,9 +36,9 @@ const MAPPING = [
   { css: '--accent-foreground', slot: `${S}accent.on-tint`, cls: 'native' },
   { css: '--destructive', slot: `${S}danger.solid`, cls: 'native' },
   { css: '--destructive-foreground', slot: `${S}danger.on-solid`, cls: 'native' },
-  { css: '--border', slot: `${S}border`, cls: 'native' },
-  // shadcn distinguishes input borders; the IR does not (exercise F4)
-  { css: '--input', slot: `${S}border`, cls: 'approximated' },
+  { css: '--border', slot: `${S}border.base`, cls: 'native' },
+  // shadcn's input border is the catalog's field border (exercise F4, proposal 0005)
+  { css: '--input', slot: `${S}border.field`, cls: 'native' },
   { css: '--ring', slot: `${S}ring`, cls: 'native' },
   { css: '--chart-1', slot: `${P}1`, cls: 'native' },
   { css: '--chart-2', slot: `${P}2`, cls: 'native' },
@@ -48,11 +52,13 @@ const MAPPING = [
   { css: '--sidebar-primary-foreground', slot: `${S}primary.on-solid`, cls: 'native', note: 'exporter convention' },
   { css: '--sidebar-accent', slot: `${S}accent.tint`, cls: 'native', note: 'exporter convention' },
   { css: '--sidebar-accent-foreground', slot: `${S}accent.on-tint`, cls: 'native', note: 'exporter convention' },
-  { css: '--sidebar-border', slot: `${S}border`, cls: 'native', note: 'exporter convention' },
+  { css: '--sidebar-border', slot: `${S}border.base`, cls: 'native', note: 'exporter convention' },
   { css: '--sidebar-ring', slot: `${S}ring`, cls: 'native', note: 'exporter convention' },
 ];
 
 const ERAS = ['tailwind-v4', 'tailwind-v3'];
+/** The manifest's Tailwind ranges (package.json `transtyle.targets.shadcn`) → era profile. */
+const PROFILE_ERAS = { '>=3 <4': 'tailwind-v3', '>=4 <5': 'tailwind-v4' };
 
 export default {
   name: 'shadcn',
@@ -65,10 +71,22 @@ export default {
   },
 
   emit(normalized, ctx) {
-    const era = ctx.targetConfig.options?.era ?? 'tailwind-v4';
+    const explicit = ctx.targetConfig.options?.era;
+    const fromVersion = PROFILE_ERAS[ctx.targetProfile];
+    const era = explicit ?? fromVersion ?? 'tailwind-v4';
     if (!ERAS.includes(era)) {
       throw new Error(`exporter-shadcn: unknown era "${era}" (supported: ${ERAS.join(', ')})`);
     }
+    // A requested Tailwind version and an explicit era that disagree: the
+    // explicit option wins (it is the override), and the build says so.
+    const eraConflict = explicit && ctx.targetVersion && fromVersion && fromVersion !== explicit
+      ? {
+          severity: 'warning',
+          code: 'TST2105',
+          message: `options.era "${explicit}" overrides version ${ctx.targetVersion}, whose profile ("${ctx.targetProfile}") is ${fromVersion}; the output follows ${explicit}`,
+          hint: 'Remove options.era to follow the Tailwind version, or set "version" to the Tailwind release the project really uses.',
+        }
+      : null;
     // Mode polarity: shadcn's structure is fixed (:root = light, .dark = dark).
     // Bind mode NAMES, never the DS's default flag — a dark-native design
     // system still compiles to shadcn's light-first layout (ir.md#modes).
@@ -107,16 +125,69 @@ export default {
     }
     // Mode dimensions this exporter doesn't express (T8, ir.md#modes) — a
     // no-op unless the compile actually declares one, e.g. `density`.
-    coverage.push(...droppedDimensions(normalized.dimensionNames, ['color-scheme']));
+    // `contrast` and `brand` are expressed as attribute blocks next to `.dark`
+    // (#49, #50); shadcn's theme has no duration variable for `motion`.
+    coverage.push(...droppedDimensions(normalized.dimensionNames, ['color-scheme', 'contrast', 'brand'], {
+      motion: "shadcn's theme carries no duration or easing variable, so reduced-motion values have nowhere to go",
+    }));
+
+    // Blocks for the extra dimensions: the same variables, rendered per combo.
+    const fmt = era === 'tailwind-v4' ? (c) => ctx.formatColor(c) : (c) => ctx.formatHslTriplet(c).text;
+    const blocks = modeBlocks(normalized, {
+      dims: ['contrast', 'brand'],
+      darkSelector: dark ? '.dark' : undefined,
+      render: (map) =>
+        vars.flatMap((v) => {
+          const e = map.get(v.slot);
+          if (!e?.value) return [];
+          const value = fmt(e.value);
+          return [{ name: v.css, value, line: cssLine(v.css, value, v.slot, e.provenance.kind) }];
+        }),
+    });
 
     // EMIT: era profile decides artifacts
-    const shared = { vars, radius, fontSans, fontMono, ctx };
+    const shared = { vars, radius, fontSans, fontMono, ctx, blocks };
     const files = era === 'tailwind-v4' ? emitV4(shared) : emitV3(shared);
-    files.push({ path: 'usage.md', contents: renderUsage(ctx, coverage, era), kind: 'doc' });
-    return { files, coverage };
+    files.push({
+      path: 'usage.md',
+      contents: renderUsage(ctx, coverage, era, Boolean(normalized.modes.dark)) + modeBlocksUsage(normalized, blocks, { scheme: 'the `dark` class' }),
+      kind: 'doc',
+    });
+    const collapsed = radius && collapsedRungs(radius.value, era, ctx.units);
+    const diagnostics = [eraConflict, collapsed].filter(Boolean);
+    return { files, coverage, diagnostics };
   },
 };
 
+/** shadcn's own radius rungs, as offsets from --radius in px (both eras write the same arithmetic). */
+const RADIUS_OFFSETS = { sm: -4, md: -2 };
+
+/**
+ * TST2104 (info): shadcn derives its smaller rungs by subtracting a fixed
+ * offset from --radius, so a small non-zero radius.md (2px, say) gives
+ * `rounded-sm` and `rounded-md` a negative radius, which browsers clamp to 0:
+ * the author asked for rounded corners and gets square ones. Never fires for
+ * radius.md = 0, where every rung at 0 is exactly what was asked. Lengths are
+ * read in px, rem at the config's `units.remBase` through ctx.units (16px for a
+ * ctx without it); any other unit is left alone.
+ */
+function collapsedRungs(value, era, units) {
+  const m = /^(\d*\.?\d+)(px|rem)$/.exec(String(value).trim());
+  if (!m) return null;
+  const px = units?.toPx(m[0]) ?? parseFloat(m[1]) * (m[2] === 'rem' ? 16 : 1);
+  if (px <= 0) return null;
+  const rungs = Object.entries(RADIUS_OFFSETS).filter(([, off]) => px + off <= 0).map(([rung]) => rung);
+  if (!rungs.length) return null;
+  const name = (rung) => (era === 'tailwind-v4' ? `--radius-${rung}` : `borderRadius.${rung}`);
+  const shown = m[2] === 'rem' ? `${value} (${+px.toFixed(3)}px)` : value;
+  return {
+    severity: 'info',
+    code: 'TST2104',
+    message: `${rungs.map(name).join(' and ')} ${rungs.length > 1 ? 'resolve' : 'resolves'} to 0 or less with radius.md = ${shown}; browsers clamp ${rungs.length > 1 ? 'them' : 'it'} to 0`,
+    hint: `shadcn rounds its sm and md rungs at radius − 4px and radius − 2px. Author radius.md above ${+(4 / (units?.remBase ?? 16)).toFixed(4)}rem (4px) to keep every rung rounded, or 0 for a square design.`,
+  };
+}
+
 // ---------- shared helpers ----------
 
 const header = (ctx, era) => [
@@ -130,11 +201,12 @@ const header = (ctx, era) => [
 const cssLine = (name, value, slot, prov) =>
   `  ${name}: ${value}; /* ${slot.replace('semantic.', '')}${prov === 'derived' ? ' · derived' : ''} */`;
 
-const fontList = (value) => value.map((f) => (/[^a-z-]/.test(f) ? `"${f}"` : f)).join(', ');
-
 function colorBlocks(vars, fmt) {
   const lines = { light: [], dark: [] };
   for (const v of vars) {
+    // The slot's own $description / $deprecated (#30), above its light
+    // declaration only (the dark block re-declares the same variable).
+    for (const note of entryNotes(v.lightEntry)) lines.light.push(`  ${blockComment(note)}`);
     lines.light.push(cssLine(v.css, fmt(v.lightEntry.value), v.slot, v.lightEntry.provenance.kind));
     if (v.darkEntry?.value) lines.dark.push(cssLine(v.css, fmt(v.darkEntry.value), v.slot, v.darkEntry.provenance.kind));
   }
@@ -143,12 +215,12 @@ function colorBlocks(vars, fmt) {
 
 // ---------- tailwind-v4 profile ----------
 
-function emitV4({ vars, radius, fontSans, fontMono, ctx }) {
+function emitV4({ vars, radius, fontSans, fontMono, ctx, blocks }) {
   const lines = colorBlocks(vars, (c) => ctx.formatColor(c));
   const themeVars = vars.map((v) => `  --color${v.css.slice(1)}: var(${v.css});`);
   const extras = [];
-  if (fontSans) extras.push(`  --font-sans: ${fontList(fontSans.value)};`);
-  if (fontMono) extras.push(`  --font-mono: ${fontList(fontMono.value)};`);
+  if (fontSans) extras.push(`  --font-sans: ${fontStack(fontSans.value)};`);
+  if (fontMono) extras.push(`  --font-mono: ${fontStack(fontMono.value)};`);
   if (radius) {
     extras.push('  --radius-sm: calc(var(--radius) - 4px);');
     extras.push('  --radius-md: calc(var(--radius) - 2px);');
@@ -165,6 +237,7 @@ function emitV4({ vars, radius, fontSans, fontMono, ctx }) {
     '.dark {',
     ...lines.dark,
     '}',
+    ...formatModeBlocks(blocks),
     '',
     '@theme inline {',
     ...themeVars,
@@ -177,7 +250,7 @@ function emitV4({ vars, radius, fontSans, fontMono, ctx }) {
 
 // ---------- tailwind-v3 profile ----------
 
-function emitV3({ vars, radius, fontSans, fontMono, ctx }) {
+function emitV3({ vars, radius, fontSans, fontMono, ctx, blocks }) {
   const lines = colorBlocks(vars, (c) => ctx.formatHslTriplet(c).text);
   const css = [
     header(ctx, 'tailwind-v3'),
@@ -190,6 +263,7 @@ function emitV3({ vars, radius, fontSans, fontMono, ctx }) {
     '  .dark {',
     ...lines.dark.map((l) => '  ' + l),
     '  }',
+    ...formatModeBlocks(blocks, '  '),
     '}',
     '',
   ].join('\n');
@@ -226,8 +300,8 @@ function emitV3({ vars, radius, fontSans, fontMono, ctx }) {
     '  },',
     ...(fontSans || fontMono ? [
       '  fontFamily: {',
-      ...(fontSans ? [`    sans: ${JSON.stringify(fontSans.value)},`] : []),
-      ...(fontMono ? [`    mono: ${JSON.stringify(fontMono.value)},`] : []),
+      ...(fontSans ? [`    sans: ${JSON.stringify(fontNames(fontSans.value))},`] : []),
+      ...(fontMono ? [`    mono: ${JSON.stringify(fontNames(fontMono.value))},`] : []),
       '  },',
     ] : []),
     '};',
@@ -242,7 +316,7 @@ function emitV3({ vars, radius, fontSans, fontMono, ctx }) {
 
 // ---------- usage ----------
 
-function renderUsage(ctx, coverage, era) {
+function renderUsage(ctx, coverage, era, hasDark = true) {
   const counts = {};
   for (const c of coverage) counts[c.class] = (counts[c.class] ?? 0) + 1;
   const summary = Object.entries(counts).map(([k, v]) => `${v} ${k}`).join(' · ');
@@ -258,7 +332,7 @@ function renderUsage(ctx, coverage, era) {
    \`\`\`
 
    (Or replace the \`:root\`/\`.dark\`/\`@theme inline\` blocks that \`npx shadcn init\` created.)
-3. Dark mode: add the \`dark\` class on \`<html>\` (class strategy), as in standard shadcn setups.`
+${hasDark ? '3. Dark mode: add the \`dark\` class on \`<html>\` (class strategy), as in standard shadcn setups.' : '3. Light only: this theme was generated without a dark mode, so the \`.dark\` block is empty.'}`
     : `## Tailwind v3 project (shadcn "old" era, hsl(var(--x)) convention)
 
 1. Copy \`globals.transtyle.css\` into your app and import it in your global CSS
@@ -269,7 +343,7 @@ function renderUsage(ctx, coverage, era) {
    const transtyle = require("./tailwind.theme.transtyle.cjs");
    module.exports = { darkMode: ["class"], theme: { extend: transtyle } };
    \`\`\`
-3. Dark mode: class strategy (\`darkMode: ["class"]\`), toggle \`dark\` on \`<html>\`.`;
+${hasDark ? '3. Dark mode: class strategy (\`darkMode: ["class"]\`), toggle \`dark\` on \`<html>\`.' : '3. Light only: this theme was generated without a dark mode, so the \`.dark\` block is empty.'}`;
 
   return `# Using this shadcn theme