@transtyle/exporter-radix 0.1.0-alpha.0

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@transtyle/exporter-radix",
+  "version": "0.1.0-alpha.0",
+  "description": "Transtyle exporter for Radix Colors 12-step scales — the role grid's acceptance test.",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "dependencies": {
+    "@transtyle/ir": "0.1.0-alpha.0"
+  },
+  "transtyle": {
+    "kind": "exporter",
+    "name": "radix",
+    "irSpec": "v0-draft",
+    "pluginApi": "0",
+    "targets": {
+      "radix": [
+        "*"
+      ]
+    },
+    "modes": [
+      "color-scheme"
+    ],
+    "capabilities": [
+      "build"
+    ]
+  },
+  "files": [
+    "src"
+  ],
+  "publishConfig": { "access": "public" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/transtyle/transtyle.git",
+    "directory": "packages/exporter-radix"
+  },
+  "homepage": "https://github.com/transtyle/transtyle#readme",
+  "bugs": "https://github.com/transtyle/transtyle/issues",
+  "license": "MIT"
+}

package/src/index.js

@@ -0,0 +1,170 @@
+/**
+ * @transtyle/exporter-radix — emits Radix Colors-shaped 12-step scales from
+ * the resolved IR. Spec: docs/specs/exporters/radix.md.
+ *
+ * This is the role grid's acceptance test (proposal 0001 §7): Radix's 12
+ * steps ARE the grid, just numbered instead of named. If every step maps
+ * cleanly from an existing catalog cell (only 2 of 12 need a fresh mix —
+ * steps 2 and 6, both flagged `approximated`), the grid is validated as a
+ * universal projection, not a shape invented to fit shadcn or Bootstrap.
+ *
+ * Mapping (per role, both modes):
+ *   1  <- elevation.0.surface (app bg)              7/8  <- outline / outline-hover
+ *   2  <- mix(solid, surface(0), 0.96) [approx.]     9/10 <- solid / solid-hover
+ *   3/4/5 <- tint / tint-hover / tint-active         11/12 <- text / text-strong
+ *   6  <- mix(solid, surface(1), 0.78) [approx.]     contrast <- on-solid
+ * Alpha steps (`-a1`..`-a12`): the same 12 colors, alpha computed from a
+ * fixed ramp (not Radix's real per-color alpha derivation — approximated,
+ * documented). `neutral` is also emitted as `--gray-*`, Radix's conventional
+ * paired-gray name, alongside `--neutral-*`.
+ */
+
+import { COLOR_ROLES, droppedDimensions } from '@transtyle/ir';
+
+const S = 'semantic.color.';
+const ALPHA_RAMP = [0.05, 0.1, 0.15, 0.22, 0.3, 0.4, 0.5, 0.6, 0.75, 0.85, 0.92, 0.97];
+
+export default {
+  name: 'radix',
+
+  emit(normalized, ctx) {
+    const light = normalized.modes.light ?? normalized.modes[normalized.defaultMode];
+    const dark = normalized.modes.dark;
+    const coverage = [];
+
+    const buildMode = (map, isFirst) => {
+      const surface0 = map.get(`${S}elevation.0.surface`)?.value;
+      const surface1 = map.get(`${S}elevation.1.surface`)?.value;
+      const lines = [];
+      for (const role of COLOR_ROLES) {
+        const get = (cell) => map.get(`${S}${role}.${cell}`)?.value;
+        const solid = get('solid');
+        if (!solid) continue;
+
+        const steps = {
+          1: surface0,
+          2: surface0 && ctx.mix(solid, surface0, 0.96),
+          3: get('tint'),
+          4: get('tint-hover'),
+          5: get('tint-active'),
+          6: surface1 && ctx.mix(solid, surface1, 0.78),
+          7: get('outline'),
+          8: get('outline-hover'),
+          9: solid,
+          10: get('solid-hover'),
+          11: get('text'),
+          12: get('text-strong'),
+        };
+
+        for (const [step, value] of Object.entries(steps)) {
+          if (!value) continue;
+          const name = `--${role}-${step}`;
+          lines.push(`  ${name}: ${ctx.formatColor(value)};`);
+          if (isFirst) {
+            const mixed = step === '2' || step === '6';
+            const clamped = ctx.formatHex(value).clamped;
+            const notes = [
+              ...(mixed ? ['no direct grid cell — mixed toward the surface at a ratio filling the gap between tint and outline'] : []),
+              ...(clamped ? ['out of sRGB gamut at this lightness/chroma combination — browsers gamut-map oklch(), which may render noticeably differently than intended'] : []),
+            ];
+            coverage.push({ variable: name, slot: `${S}${role}.*`, class: (mixed || clamped) ? 'approximated' : 'native', ...(notes.length && { note: notes.join('; ') }) });
+          }
+          const alpha = ALPHA_RAMP[Number(step) - 1];
+          const aName = `--${role}-a${step}`;
+          lines.push(`  ${aName}: ${ctx.formatColor({ ...value, alpha })};`);
+          if (isFirst) coverage.push({ variable: aName, slot: `${S}${role}.*`, class: 'approximated', note: 'fixed alpha ramp, not a colorimetric derivation of Radix\'s real per-color alpha' });
+        }
+
+        const onSolid = get('on-solid');
+        if (onSolid) {
+          lines.push(`  --${role}-contrast: ${ctx.formatColor(onSolid)};`);
+          if (isFirst) coverage.push({ variable: `--${role}-contrast`, slot: `${S}${role}.on-solid`, class: 'native' });
+        }
+
+        if (role === 'neutral') {
+          for (const [step] of Object.entries(steps)) {
+            lines.push(`  --gray-${step}: var(--neutral-${step});`);
+            lines.push(`  --gray-a${step}: var(--neutral-a${step});`);
+          }
+          lines.push('  --gray-contrast: var(--neutral-contrast);');
+          if (isFirst) coverage.push({ variable: '--gray-*', slot: `${S}neutral.*`, class: 'native', note: 'Radix\'s conventional paired-gray name, aliased from neutral' });
+        }
+      }
+      return lines;
+    };
+
+    const lightLines = buildMode(light, true);
+    const darkLines = dark ? buildMode(dark, false) : [];
+
+    coverage.push({ variable: '(P3/wide-gamut variants)', slot: '—', class: 'dropped', note: 'Radix ships a P3 pair per scale for wide-gamut displays; the engine has one OKLCH value per slot, not a gamut-mapped pair' });
+    // 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']));
+
+    const css = [
+      '/*',
+      ` * GENERATED by transtyle — do not edit; source: ${ctx.projectName} token files`,
+      ' * Target: Radix Colors (12-step scales + alpha + contrast) · rules standard@1',
+      ' * A custom palette per https://www.radix-ui.com/colors/docs/overview/naming — ',
+      ' * override an existing Radix Themes scale name (see usage.md) to use it with',
+      ' * the <Theme accentColor="..."> component, or consume the variables directly.',
+      ' */',
+      '',
+      ':root {',
+      ...lightLines,
+      '}',
+      ...(darkLines.length ? ['', '.dark {', ...darkLines, '}'] : []),
+      '',
+    ].join('\n');
+
+    return {
+      files: [
+        { path: 'radix-colors.transtyle.css', contents: css, kind: 'stylesheet' },
+        { path: 'usage.md', contents: renderUsage(ctx, coverage), kind: 'doc' },
+      ],
+      coverage,
+    };
+  },
+};
+
+function renderUsage(ctx, coverage) {
+  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(' · ');
+  return `# Using this Radix Colors palette
+
+Generated from the **${ctx.projectName}** design system by transtyle: a 12-step scale (+ 12 alpha steps + a contrast color) per role, in Radix Colors' own naming convention. Coverage: ${summary}.
+
+## Standalone (no React, just the CSS variables)
+
+\`\`\`html
+<link rel="stylesheet" href="radix-colors.transtyle.css">
+\`\`\`
+
+\`\`\`css
+.my-button { background: var(--primary-9); color: var(--primary-contrast); }
+.my-button:hover { background: var(--primary-10); }
+.my-card { background: var(--primary-2); border: 1px solid var(--primary-6); }
+\`\`\`
+
+## With \`@radix-ui/themes\`
+
+The \`<Theme accentColor="...">\` component only accepts Radix's own preset names (it can't take an arbitrary string) — so to drive real Radix Themes components from your brand, **override one existing preset's variables** with your role's scale, then pass that preset's name:
+
+\`\`\`css
+/* after @radix-ui/themes/styles.css, before your app renders */
+:root {
+  --violet-1: var(--primary-1); --violet-2: var(--primary-2); /* ...through 12, plus -a1..a12 and -contrast */
+}
+\`\`\`
+
+\`\`\`jsx
+<Theme accentColor="violet" grayColor="gray">{/* --gray-* is already Radix's own name — no override needed */}</Theme>
+\`\`\`
+
+## Regenerating
+
+Never edit this file — change the design system tokens and run \`transtyle build radix\`.
+See \`report.json\` for the full coverage/provenance breakdown.
+`;
+}