inkbridge 0.1.0-beta.2 → 0.1.0-beta.21

package/src/framework-adapters/shadcn.ts

@@ -0,0 +1,541 @@
+/**
+ * shadcn adapter — translates shadcn / base-ui runtime-CSS conventions
+ * into class-list patches the plugin can see.
+ *
+ * Why this exists
+ * ---------------
+ * shadcn primitives lean on stylesheet rules that live outside the
+ * consumer's JSX — most notably `position: absolute; inset: 0` on
+ * `[data-slot="avatar-image"]` so the image overlays the fallback when it
+ * loads. The plugin scans className strings, not CSS files, so a
+ * `<Avatar><AvatarImage /><AvatarFallback /></Avatar>` tree renders with
+ * Image + Fallback as flow siblings, fighting over 40px in a horizontal
+ * flex parent, and both collapse to invisible.
+ *
+ * The adapter recognises a small set of shadcn `data-slot` markers at the
+ * IR-transform stage and injects the missing Tailwind classes. The
+ * renderer's existing pipeline (absolute positioning, full-width fills,
+ * ...) then Just Works — no parallel code path in the renderer.
+ *
+ * Adding a new entry
+ * ------------------
+ * If a shadcn primitive renders wrong in Figma AND the fix is a small,
+ * static set of Tailwind classes the consumer's JSX would have had
+ * if runtime CSS weren't doing the job, add a `SLOT_CLASS_INJECTIONS`
+ * entry, a regression case in `shadcn-quirks-regression.ts`, and a note
+ * in `.ai/framework-adapters.md`. If the fix needs layout-time decisions
+ * (parent shape, sibling count, theme, ...) it belongs in the renderer
+ * instead — this file stays focused on "class-list patches the
+ * consumer's JSX should have had."
+ *
+ * Sibling adapters
+ * ----------------
+ * The `framework-adapters/` folder is the home for any future ports of
+ * this idea (MUI, Headless UI, Chakra, ...). Each lives in its own file
+ * and is composed via the dispatcher in `index.ts`.
+ */
+
+// Type-only import: avoid a runtime cycle with `tailwind/node-ir.ts`,
+// which imports this file's `applyShadcnAdapter`.
+import type { NodeIR } from '../tailwind/node-ir';
+import { isClassedElement, mergeMissing, resolveValuePercents } from '../tailwind/adapter-utils';
+
+/**
+ * `data-slot` → extra Tailwind classes injected before layout solving.
+ *
+ * - `avatar-image`: base-ui's stylesheet pins it `position: absolute;
+ *   inset: 0` so the image overlays the fallback when it loads. Without
+ *   the CSS, both children compete for flow space and collapse. Injecting
+ *   `absolute inset-0` reproduces the overlay shape via the renderer's
+ *   existing absolute-positioning pipeline.
+ */
+const SLOT_CLASS_INJECTIONS: Record<string, readonly string[]> = {
+  'avatar-image': ['absolute', 'inset-0'],
+};
+
+function getDataSlot(node: NodeIR): string | null {
+  if (!isClassedElement(node)) return null;
+  const raw = node.props ? node.props['data-slot'] : undefined;
+  return typeof raw === 'string' && raw.length > 0 ? raw : null;
+}
+
+/**
+ * Coerce a `kind: 'component'` node to a `kind: 'element'` div, optionally
+ * with a fresh class list. Used by the Slider adapter to bypass the
+ * state-instance master lookup — Slider's def is `type='state'` (scanner
+ * heuristic mis-classifies it because of `data-[disabled]:opacity-50`),
+ * so every `<SliderPrimitive.*>` node would otherwise route through
+ * `tryRenderSharedSymbolInstance` and get an empty state-instance.
+ *
+ * Element nodes carry `tagLower` and `tagName`; we keep the original
+ * tagName so layer names still read "SliderPrimitive.Thumb" etc., but
+ * render via the plain-element path.
+ */
+function toElementWithClasses(node: NodeIR, classes: string[]): NodeIR {
+  if (!isClassedElement(node)) return node;
+  const sameKind = node.kind === 'element';
+  const sameClasses = classes === node.classes;
+  if (sameKind && sameClasses) return node;
+  const patch: Record<string, unknown> = { kind: 'element', classes };
+  if (!('tagLower' in node) || !(node as unknown as { tagLower?: string }).tagLower) {
+    patch.tagLower = 'div';
+  }
+  return Object.assign({}, node, patch) as NodeIR;
+}
+
+export function getShadcnSlotInjections(slot: string): readonly string[] | null {
+  return SLOT_CLASS_INJECTIONS[slot] ?? null;
+}
+
+/**
+ * Tree transforms applied to an `[data-slot="avatar"]` subtree to mirror
+ * shadcn's runtime behaviour:
+ *
+ *   - **Drop the fallback when the image has a real src.** In shadcn,
+ *     `<AvatarFallback>` only renders if `<AvatarImage>` fails to load.
+ *     We can't observe load state, but we CAN observe "is there a
+ *     real-looking src on the sibling image?" at scan time. If yes, the
+ *     fallback would never visibly render in the browser — drop it so
+ *     Figma doesn't show a misleading initials disc behind the
+ *     successfully-rendered image.
+ *
+ * If the rules grow, split this out into its own helper / module — keep
+ * the registry pattern dominant.
+ */
+function looksLikeAvatarImageSrc(src: unknown): boolean {
+  if (typeof src !== 'string' || src.length === 0) return false;
+  return src.startsWith('/')
+    || src.startsWith('http://')
+    || src.startsWith('https://')
+    || src.startsWith('./')
+    || src.startsWith('../');
+}
+
+function dropFallbackWhenAvatarImageHasSrc(
+  parent: Extract<NodeIR, { kind: 'element' | 'component' }>,
+): NodeIR[] | null {
+  if (getDataSlot(parent) !== 'avatar') return null;
+  const children = parent.children;
+  if (!Array.isArray(children) || children.length === 0) return null;
+
+  let hasImageWithSrc = false;
+  for (const child of children) {
+    if (!isClassedElement(child)) continue;
+    if (getDataSlot(child) !== 'avatar-image') continue;
+    const src = child.props ? child.props.src : undefined;
+    if (looksLikeAvatarImageSrc(src)) {
+      hasImageWithSrc = true;
+      break;
+    }
+  }
+  if (!hasImageWithSrc) return null;
+
+  let dropped = false;
+  const next: NodeIR[] = [];
+  for (const child of children) {
+    if (isClassedElement(child) && getDataSlot(child) === 'avatar-fallback') {
+      dropped = true;
+      continue;
+    }
+    next.push(child);
+  }
+  return dropped ? next : null;
+}
+
+/**
+ * Resolve a shadcn Progress.Root's `value` prop to a 0-100 percent. The
+ * scanner stringifies every prop, so `<Progress value={60}>` arrives as
+ * `props.value === "60"`. `value={null}` (indeterminate) comes through
+ * as missing / undefined / "null" — for static-design purposes we
+ * surface a recognisably partial bar (33%) so Indeterminate doesn't
+ * look identical to Complete.
+ *
+ * Indeterminate visual choice: shadcn / base-ui animates the indicator
+ * sliding across the track. Figma can't animate; 33% is a recognised
+ * "in progress, no specific value" representation.
+ */
+const PROGRESS_INDETERMINATE_PERCENT = 33;
+
+function resolveProgressPercent(value: unknown): number {
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    return Math.max(0, Math.min(100, value));
+  }
+  if (typeof value === 'string') {
+    const trimmed = value.trim();
+    if (trimmed.length === 0 || trimmed === 'null' || trimmed === 'undefined') {
+      return PROGRESS_INDETERMINATE_PERCENT;
+    }
+    const parsed = parseFloat(trimmed);
+    if (Number.isFinite(parsed)) {
+      return Math.max(0, Math.min(100, parsed));
+    }
+  }
+  return PROGRESS_INDETERMINATE_PERCENT;
+}
+
+/**
+ * Walk the Progress subtree and inject a width class on the
+ * `progress-indicator` descendant so the bar visibly reflects the
+ * value prop. shadcn / base-ui sets this via inline `transform:
+ * translateX(-N%)` at runtime which the plugin's className-only
+ * scanner never sees.
+ */
+function applyProgressIndicatorWidth(
+  root: Extract<NodeIR, { kind: 'element' | 'component' }>,
+): NodeIR | null {
+  if (getDataSlot(root) !== 'progress') return null;
+  const percent = resolveProgressPercent(root.props ? root.props.value : undefined);
+  // `w-[N%]` so the universal parser (sizing.ts) sets widthMode=FILL +
+  // widthFraction = N/100; the post-append pipeline resizes the
+  // indicator to N% of the Track's content width.
+  const widthClass = `w-[${percent}%]`;
+
+  let changed = false;
+  const inject = (n: NodeIR): NodeIR => {
+    if (!isClassedElement(n)) {
+      // Walk through ring / fragment shapes.
+      if (n.kind === 'fragment') {
+        let any = false;
+        const nx: NodeIR[] = [];
+        for (const c of n.children) {
+          const r = inject(c);
+          if (r !== c) any = true;
+          nx.push(r);
+        }
+        return any ? Object.assign({}, n, { children: nx }) : n;
+      }
+      if (n.kind === 'ring') {
+        const nc = inject(n.child);
+        return nc === n.child ? n : Object.assign({}, n, { child: nc });
+      }
+      return n;
+    }
+    let nextN: NodeIR = n;
+    if (getDataSlot(n) === 'progress-indicator') {
+      const merged = mergeMissing(n.classes ?? [], [widthClass]);
+      if (merged !== n.classes) {
+        nextN = Object.assign({}, n, { classes: merged });
+        changed = true;
+      }
+    }
+    if (!('children' in nextN) || !Array.isArray((nextN as { children?: unknown }).children)) {
+      return nextN;
+    }
+    let kidsChanged = false;
+    const kids = (nextN as { children: NodeIR[] }).children;
+    const nextKids: NodeIR[] = [];
+    for (const c of kids) {
+      const r = inject(c);
+      if (r !== c) kidsChanged = true;
+      nextKids.push(r);
+    }
+    return kidsChanged ? Object.assign({}, nextN, { children: nextKids }) : nextN;
+  };
+
+  const out = inject(root);
+  return changed ? out : null;
+}
+
+/**
+ * Walk the Slider subtree and rebuild it so the indicator + thumbs
+ * reflect the value prop:
+ *
+ *   - **Indicator** gets `absolute left-[min%] w-[(max-min)%]` so the
+ *     filled portion of the track matches the value range (for a
+ *     single-value slider, min=0 and the indicator stretches from the
+ *     left edge to the thumb position).
+ *   - **Thumbs**: the scanner emits a SINGLE template even for range
+ *     sliders (`{values.map(...)}` is not statically expanded). The
+ *     adapter clones the template once per value and injects
+ *     `absolute left-[Vi%] -translate-x-1/2` on each clone, centering
+ *     it on its value point exactly like base-ui's inline styles do
+ *     at runtime.
+ */
+function applySliderPositioning(
+  root: Extract<NodeIR, { kind: 'element' | 'component' }>,
+): NodeIR | null {
+  if (getDataSlot(root) !== 'slider') return null;
+  const rawValue = root.props && (root.props.defaultValue ?? root.props.value);
+  const rawMax = root.props ? root.props.max : undefined;
+  // base-ui's Slider is min=0..max only; pass min=0 explicitly.
+  const pcts = resolveValuePercents(rawValue, 0, rawMax);
+  if (pcts.length === 0) return null;
+
+  // Figma plugin sandbox doesn't support spread (`...arr`); compute min/max
+  // by hand. For a single-value slider, the bar fills from 0 to that value.
+  let minPct = pcts[0];
+  let maxPct = pcts[0];
+  if (pcts.length > 1) {
+    for (let i = 1; i < pcts.length; i++) {
+      if (pcts[i] < minPct) minPct = pcts[i];
+      if (pcts[i] > maxPct) maxPct = pcts[i];
+    }
+  } else {
+    minPct = 0;
+  }
+  const indicatorWidth = Math.max(0, maxPct - minPct);
+
+  let touched = false;
+
+  const transform = (n: NodeIR): NodeIR | NodeIR[] => {
+    if (!isClassedElement(n)) {
+      if (n.kind === 'fragment') {
+        let any = false;
+        const out: NodeIR[] = [];
+        for (const c of n.children) {
+          const r = transform(c);
+          if (Array.isArray(r)) {
+            any = true;
+            for (let i = 0; i < r.length; i++) out.push(r[i]);
+            continue;
+          }
+          if (r !== c) any = true;
+          out.push(r);
+        }
+        return any ? Object.assign({}, n, { children: out }) : n;
+      }
+      if (n.kind === 'ring') {
+        const r = transform(n.child);
+        const next = Array.isArray(r) ? r[0] : r;
+        return next === n.child ? n : Object.assign({}, n, { child: next });
+      }
+      return n;
+    }
+
+    const slot = getDataSlot(n);
+
+    // Indicator: position + width. Also convert kind='component' → 'element'
+    // so the renderer doesn't try a state-instance lookup (Slider's def is
+    // mis-classified as `state` by the scanner because of `data-[disabled]`
+    // — every sub-primitive resolves back to that same def and would try
+    // the state-master which can't represent the value-driven geometry).
+    if (slot === 'slider-indicator') {
+      const extras = [`left-[${minPct}%]`, `w-[${indicatorWidth}%]`];
+      const merged = mergeMissing(n.classes ?? [], extras);
+      const out = toElementWithClasses(n, merged !== n.classes ? merged : n.classes ?? []);
+      if (out !== n) touched = true;
+      return out;
+    }
+
+    // Thumb template → one clone per value, each absolutely positioned
+    // AND coerced to `kind: 'element'` for the same reason as the
+    // indicator above.
+    if (slot === 'slider-thumb') {
+      const clones: NodeIR[] = [];
+      for (const pct of pcts) {
+        const extras = ['absolute', `left-[${pct}%]`, '-translate-x-1/2'];
+        const cloneClasses = mergeMissing(n.classes ?? [], extras);
+        clones.push(toElementWithClasses(n, cloneClasses));
+      }
+      touched = true;
+      return clones;
+    }
+
+    // Non-leaf slider parts (`slider`, `slider-control`, `slider-track`):
+    // coerce to element so the wrapper-frame path renders the JSX children
+    // instead of going through the state-instance lookup.
+    let nextN: NodeIR = n;
+    if (slot === 'slider' || slot === 'slider-control' || slot === 'slider-track') {
+      const coerced = toElementWithClasses(n, n.classes ?? []);
+      if (coerced !== n) {
+        nextN = coerced;
+        touched = true;
+      }
+    }
+
+    // Recurse — and splice in any cloned children returned as arrays.
+    if (!('children' in nextN) || !Array.isArray((nextN as { children?: unknown }).children)) {
+      return nextN;
+    }
+    let kidsChanged = false;
+    const original = (nextN as { children: NodeIR[] }).children;
+    const next: NodeIR[] = [];
+    for (const c of original) {
+      const r = transform(c);
+      if (Array.isArray(r)) {
+        if (r.length !== 1 || r[0] !== c) kidsChanged = true;
+        // sandbox: no spread — push items one-by-one
+        for (let i = 0; i < r.length; i++) next.push(r[i]);
+      } else {
+        if (r !== c) kidsChanged = true;
+        next.push(r);
+      }
+    }
+    return kidsChanged ? Object.assign({}, nextN, { children: next }) : nextN;
+  };
+
+  const out = transform(root);
+  const single = Array.isArray(out) ? out[0] : out;
+  return touched ? single : null;
+}
+
+/**
+ * Drop Radix ScrollArea control children AND flatten the Viewport
+ * wrapper. Two operations rolled into one pass because they target
+ * sibling positions inside the same ScrollAreaPrimitive.Root subtree.
+ *
+ * 1. `ScrollAreaPrimitive.Scrollbar` / `.Thumb` / `.Corner` are
+ *    runtime-only behavioural overlays (scrollbar fades in while the
+ *    user scrolls, Corner only appears when both axes overflow). In a
+ *    static design-system render they manifest as visible content
+ *    blobs inside the scroll-area. Strip them.
+ *
+ * 2. `ScrollAreaPrimitive.Viewport` is a structural wrapper Radix
+ *    uses for `overflow: hidden` + scroll-position tracking — it
+ *    carries no visual styling beyond `h-full w-full
+ *    rounded-[inherit]`. In Figma the default frame fill (white)
+ *    paints it as a second nested rounded rectangle, producing the
+ *    "double card / ghost-border" effect the user reported. Flatten
+ *    by pulling Viewport's children up to be Root's direct children.
+ *
+ * Returns the rewritten children array when something changed, `null`
+ * when the subtree was untouched (so callers can keep object identity
+ * stable for caching).
+ */
+const RADIX_SCROLL_AREA_RUNTIME_TAGS = new Set([
+  'ScrollAreaPrimitive.Scrollbar',
+  'ScrollAreaPrimitive.Thumb',
+  'ScrollAreaPrimitive.Corner',
+]);
+
+/**
+ * JSX-tree tags the shadcn adapter unconditionally drops at render time.
+ * Exposed so pre-render scans that walk classes (e.g. responsive-signal
+ * detection) can ignore classes that won't actually reach Figma — without
+ * this, a `sm:bg-black/60` on `ScrollAreaPrimitive.Scrollbar` falsely
+ * trips `treeHasResponsiveClasses` and emits a duplicate-content
+ * Responsive preview block even though every breakpoint render is
+ * identical post-adapter.
+ */
+export function isShadcnAdapterDroppedTag(tagName: string): boolean {
+  return RADIX_SCROLL_AREA_RUNTIME_TAGS.has(tagName);
+}
+function flattenScrollAreaSubtree(node: NodeIR): NodeIR[] | null {
+  if (!('children' in node) || !Array.isArray(node.children)) return null;
+  let changed = false;
+  const next: NodeIR[] = [];
+  for (const child of node.children) {
+    if (!isClassedElement(child)) {
+      next.push(child);
+      continue;
+    }
+    const tag = (child as { tagName?: string }).tagName;
+    if (typeof tag === 'string' && RADIX_SCROLL_AREA_RUNTIME_TAGS.has(tag)) {
+      changed = true;
+      continue;
+    }
+    if (tag === 'ScrollAreaPrimitive.Viewport') {
+      const viewportChildren = ('children' in child && Array.isArray(child.children))
+        ? child.children
+        : [];
+      for (const vc of viewportChildren) next.push(vc);
+      changed = true;
+      continue;
+    }
+    next.push(child);
+  }
+  return changed ? next : null;
+}
+
+/**
+ * Recurse the IR, injecting registry classes for any element whose
+ * `data-slot` matches a known shadcn pattern AND applying shadcn-specific
+ * tree transforms (e.g. drop AvatarFallback when AvatarImage has a real
+ * src). Returns a new tree (input untouched) only when something
+ * actually changed; identical-shape input is returned by reference so
+ * downstream caches (`NODE_LAYOUT_CACHE`) stay warm.
+ */
+export function applyShadcnAdapter(node: NodeIR): NodeIR {
+  if (!node || node.kind === 'text' || node.kind === 'divider') return node;
+
+  if (node.kind === 'fragment') {
+    let changed = false;
+    const nextChildren: NodeIR[] = [];
+    for (const child of node.children) {
+      const next = applyShadcnAdapter(child);
+      if (next !== child) changed = true;
+      nextChildren.push(next);
+    }
+    return changed ? Object.assign({}, node, { children: nextChildren }) : node;
+  }
+
+  if (node.kind === 'ring') {
+    const nextChild = applyShadcnAdapter(node.child);
+    return nextChild === node.child ? node : Object.assign({}, node, { child: nextChild });
+  }
+
+  let nextNode: NodeIR = node;
+
+  const slot = getDataSlot(node);
+  if (slot) {
+    const extras = SLOT_CLASS_INJECTIONS[slot];
+    if (extras && isClassedElement(node)) {
+      const merged = mergeMissing(node.classes ?? [], extras);
+      if (merged !== node.classes) {
+        nextNode = Object.assign({}, node, { classes: merged });
+      }
+    }
+  }
+
+  if (!('children' in nextNode) || !Array.isArray((nextNode as { children?: unknown }).children)) {
+    return nextNode;
+  }
+
+  // Tree transform: shadcn Avatar drops its Fallback when the Image has
+  // a real src. Runs before recursion so the fallback subtree isn't
+  // walked unnecessarily.
+  if (isClassedElement(nextNode)) {
+    const filtered = dropFallbackWhenAvatarImageHasSrc(nextNode);
+    if (filtered) {
+      nextNode = Object.assign({}, nextNode, { children: filtered });
+    }
+  }
+
+  // Tree transform: Radix ScrollArea drops its Scrollbar / Thumb /
+  // Corner overlays (runtime-only behaviour, not visual content) AND
+  // flattens its Viewport wrapper (no visual styling of its own —
+  // Figma's default frame fill would render it as a ghost-bordered
+  // duplicate of Root).
+  if (isClassedElement(nextNode)) {
+    const filtered = flattenScrollAreaSubtree(nextNode);
+    if (filtered) {
+      nextNode = Object.assign({}, nextNode, { children: filtered });
+    }
+  }
+
+  // Tree transform: shadcn Progress reads `value` on Root and (at
+  // runtime) inline-styles the Indicator's transform/width. Inject a
+  // `w-[N%]` class on the descendant indicator so the universal
+  // fractional-width pipeline sizes it correctly.
+  if (isClassedElement(nextNode)) {
+    const withIndicator = applyProgressIndicatorWidth(nextNode);
+    if (withIndicator) {
+      nextNode = withIndicator;
+    }
+  }
+
+  // Tree transform: shadcn Slider positions its indicator + thumbs from
+  // the Root's `defaultValue` / `value` prop at runtime. Inject percent
+  // positioning so each thumb sits at its value point and the indicator
+  // fills the value range. For range sliders the scanner only emits one
+  // thumb template — the transform clones it into N siblings.
+  if (isClassedElement(nextNode)) {
+    const sliderPositioned = applySliderPositioning(nextNode);
+    if (sliderPositioned) {
+      nextNode = sliderPositioned as typeof nextNode;
+    }
+  }
+
+  let childrenChanged = false;
+  const original = (nextNode as { children: NodeIR[] }).children;
+  const nextChildren: NodeIR[] = [];
+  for (const child of original) {
+    const next = applyShadcnAdapter(child);
+    if (next !== child) childrenChanged = true;
+    nextChildren.push(next);
+  }
+  if (childrenChanged) {
+    return Object.assign({}, nextNode, { children: nextChildren });
+  }
+  return nextNode;
+}

package/src/{github.ts → github/github.ts}

@@ -2,7 +2,7 @@
 // All GitHub operations are relayed through the UI iframe because the
 // Figma plugin sandbox has no direct network access.
 
-import { loadConfig, GITHUB_CONFIG } from './config';
+import { loadConfig, GITHUB_CONFIG, waitForUIReady } from '../plugin';
 import {
   TOKENS,
   getVariableTokenDiffWithOptions,
@@ -11,10 +11,9 @@ import {
   type ThemeTokens,
   type TokenGroup,
   type Tokens,
-} from './tokens';
-import { colorToLabel, debug, parseColor, mergeTokens as deepMergeTokens } from './colors';
-import { waitForUIReady } from './dev-server';
-import type { ResolvedTokenSourceMode, TokenSourceMode } from './token-source';
+} from '../tokens';
+import { colorToLabel, debug, parseColor, mergeTokens as deepMergeTokens } from '../tokens';
+import type { ResolvedTokenSourceMode, TokenSourceMode } from '../tokens';
 
 // ---------------------------------------------------------------------------
 // Types
@@ -101,7 +100,7 @@ const CSS_DISCOVERY_PATHS = [
   'styles/globals.css',
 ];
 const PATCH_ENDPOINT_PORTS = [4000, 3000, 5173];
-const PATCH_ENDPOINT_PATH = '/api/figma/patch-tokens';
+const PATCH_ENDPOINT_PATH = '/api/inkbridge/patch-tokens';
 
 // ---------------------------------------------------------------------------
 // Module-level state for the GitHub fetch relay
@@ -398,16 +397,15 @@ export function applyClassChangesToFile(content: string, componentChange: Compon
 }
 
 function normalizeTokenSourceInfo(raw: unknown): TokenSourceInfo {
-  const source =
-    raw && typeof raw === 'object' && typeof (raw as any).source === 'string' && (raw as any).source.trim()
-      ? (raw as any).source.trim()
-      : 'embedded:tokens.ts';
-  const modeRaw = raw && typeof raw === 'object' ? (raw as any).mode : null;
+  const obj = raw && typeof raw === 'object' ? (raw as Record<string, unknown>) : null;
+  const sourceRaw = obj && typeof obj.source === 'string' ? obj.source.trim() : '';
+  const source = sourceRaw || 'embedded:tokens.ts';
+  const modeRaw = obj ? obj.mode : null;
   const mode: ResolvedTokenSourceMode =
     modeRaw === 'css' || modeRaw === 'dtcg' || modeRaw === 'embedded' ? modeRaw : 'embedded';
-  const requestedRaw = raw && typeof raw === 'object' ? (raw as any).requestedMode : null;
+  const requestedRaw = obj ? obj.requestedMode : null;
   const requestedMode: TokenSourceMode | undefined =
-    requestedRaw === 'auto' || requestedRaw === 'css' || requestedRaw === 'dtcg' ? requestedRaw : undefined;
+    requestedRaw === 'css' || requestedRaw === 'dtcg' ? requestedRaw : undefined;
   return { source, mode, requestedMode };
 }
 
@@ -652,17 +650,40 @@ function getActiveThemeNames(tokens: Tokens): Set<string> {
   return out;
 }
 
+/**
+ * Detect whether the CSS file uses class-based theme selectors (.secondary)
+ * or data-theme attribute selectors (:root[data-theme="secondary"]).
+ * Defaults to 'class' (Tailwind-native) when no existing theme blocks are found.
+ */
+function detectThemeConvention(cssText: string): 'class' | 'data-theme' {
+  if (/\[data-theme\s*=\s*["']?[^"'\]]+["']?\]/.test(cssText)) return 'data-theme';
+  return 'class';
+}
+
 function parseRuleThemeNames(selector: string): string[] {
   const themes = new Set<string>();
   const normalized = String(selector || '').trim().toLowerCase();
   if (!normalized) return [];
 
+  // data-theme attribute approach: :root[data-theme="secondary"]
   const dataThemeMatches = normalized.matchAll(/\[data-theme\s*=\s*["']?([^"'\\\]]+)["']?\]/g);
   for (const match of dataThemeMatches) {
     const name = String(match[1] || '').trim();
     if (name) themes.add(name);
   }
 
+  // Class-based approach: .secondary, html.secondary
+  // Skip compound selectors that include .dark (e.g. .dark.secondary) — the
+  // plugin only writes light-theme tokens, so dark compound blocks are left alone.
+  const hasDarkClass = /(?:^|[\s.])dark\b/.test(normalized);
+  if (!hasDarkClass) {
+    const classMatches = normalized.matchAll(/\.([a-z][a-z0-9-]*)/g);
+    for (const match of classMatches) {
+      const name = String(match[1] || '').trim();
+      if (name && name !== 'dark' && name !== 'root') themes.add(name);
+    }
+  }
+
   if (/(\.|:)(dark)\b/.test(normalized)) themes.add('dark');
   if (normalized.includes(':root') && themes.size === 0) themes.add('primary');
   return Array.from(themes);
@@ -783,10 +804,10 @@ function findFirstBlockForTheme(cssText: string, themeName: string): CssRuleBloc
 export function patchCssVariables(
   cssText: string,
   updatesByTheme: Map<string, Map<string, string>>,
-  activeThemeNames?: Set<string>
-  ,
+  activeThemeNames?: Set<string>,
   fullThemeUpdatesByTheme?: Map<string, Map<string, string>>
 ): string {
+  const themeConvention = detectThemeConvention(cssText);
   let nextCss = cssText;
   const pending = cloneCssVariableUpdates(updatesByTheme);
   const fullThemeUpdates = fullThemeUpdatesByTheme
@@ -843,7 +864,11 @@ export function patchCssVariables(
       continue;
     }
 
-    const selector = themeName === 'primary' ? ':root' : ':root[data-theme="' + themeName + '"]';
+    const selector = themeName === 'primary'
+      ? ':root'
+      : themeConvention === 'class'
+        ? '.' + themeName
+        : ':root[data-theme="' + themeName + '"]';
     const completeThemeUpdates =
       fullThemeUpdates && fullThemeUpdates.get(themeName)
         ? new Map(fullThemeUpdates.get(themeName) as Map<string, string>)
@@ -919,8 +944,8 @@ function queueFileIfChanged(
 }
 
 function resolveConfiguredMode(mode: unknown): TokenSourceMode {
-  if (mode === 'css' || mode === 'dtcg' || mode === 'auto') return mode;
-  return 'auto';
+  if (mode === 'dtcg') return 'dtcg';
+  return 'css';
 }
 
 async function buildTokenCommitPlan(token: string): Promise<TokenCommitPlan> {
@@ -930,8 +955,8 @@ async function buildTokenCommitPlan(token: string): Promise<TokenCommitPlan> {
   // This avoids rewriting untouched tokens and keeps push diffs focused.
   const variableDiffOptions = {
     allowNewTokensFromFigma: GITHUB_CONFIG!.allowNewTokensFromFigma === true,
-    newTokenPrefixes: Array.isArray((GITHUB_CONFIG as any).newTokenPrefixes)
-      ? ((GITHUB_CONFIG as any).newTokenPrefixes as string[])
+    newTokenPrefixes: Array.isArray(GITHUB_CONFIG!.newTokenPrefixes)
+      ? GITHUB_CONFIG!.newTokenPrefixes
       : [],
   };
   const variableTokenPatch = getVariableTokenDiffWithOptions(variableDiffOptions);
@@ -946,7 +971,7 @@ async function buildTokenCommitPlan(token: string): Promise<TokenCommitPlan> {
 
   const preferDtcg =
     configuredMode === 'dtcg' ||
-    (configuredMode === 'auto' && sourceInfo.mode === 'dtcg');
+    (configuredMode === 'css' && sourceInfo.mode === 'dtcg');
 
   if (preferDtcg) {
     const dtcg = tokensToDTCG(workingTokens);

package/src/github/index.ts

@@ -0,0 +1 @@
+export * from './github';