view-contracts 0.2.0 → 0.3.0

package/docs/cli-reference.md

@@ -2,7 +2,7 @@
 
 Contract-first UI design toolchain. Compiles restricted view-contract TSX to language-neutral View IR and renders platform targets (React, SwiftUI, Compose).
 
-**Version:** 0.1.0
+**Version:** 0.3.0
 
 ## Table of Contents
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "view-contracts",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Contract-first UI design toolchain — restricted TSX to View IR to platform renderers",
   "type": "module",
   "workspaces": [
@@ -13,6 +13,7 @@
     "dist/view-contracts.bundle.mjs",
     "dist/view-contracts.bundle.mjs.map",
     "renderers/react/runtime",
+    "renderers/react/defaults",
     "src/generated/schema",
     "spec",
     "renderers",
@@ -93,6 +94,9 @@
     "ajv": "^8.18.0",
     "cli-contracts": "^0.33.13",
     "esbuild": "^0.28.0",
+    "pixelmatch": "^7.2.0",
+    "playwright": "^1.61.0",
+    "pngjs": "^7.0.0",
     "tsx": "^4.21.0",
     "vite": "^6.4.1",
     "vitest": "^4.1.9"

package/renderers/compose/templates/Screen.kt.hbs

@@ -0,0 +1,15 @@
+// {{screenName}} — Jetpack Compose scaffold (Phase 5)
+// Theme IR: {{themeJsonPath}}
+// Token IR: {{tokensJsonPath}}
+//
+// TODO(Phase C): Load theme.json and emit Modifier.primaryButton(), vcTextMuted(), etc.
+
+package {{packageName}}
+
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+
+@Composable
+fun {{screenName}}Screen() {
+    Text("{{screenName}} — Compose scaffold")
+}

package/renderers/compose/templates/VcTheme.kt.hbs

@@ -0,0 +1,19 @@
+// VcTheme — Compose theme scaffold (Phase 5)
+// Load Token IR + Theme IR from assets:
+//   {{tokensJsonPath}}
+//   {{themeJsonPath}}
+//
+// TODO(Phase C): Map Theme IR variants to Modifier extensions and ColorScheme.
+
+package {{packageName}}
+
+import android.content.Context
+
+object VcTheme {
+    const val TOKENS_ASSET = "{{tokensJsonPath}}"
+    const val THEME_ASSET = "{{themeJsonPath}}"
+
+    /** Placeholder — read theme.json from assets in Phase C. */
+    fun loadThemeJson(context: Context): String? =
+        context.assets.open(THEME_ASSET).bufferedReader().use { it.readText() }
+}

package/renderers/react/defaults/theme.yaml

@@ -0,0 +1,41 @@
+# Default theme variants — component appearance via .vc-{element}--{variant} rules.
+variants:
+  Button:
+    primary:
+      background: "{ui.primary}"
+      foreground: "{ui.on-primary}"
+    secondary:
+      background: "{ui.button-secondary}"
+      foreground: "{ui.text}"
+    ghost:
+      background: "{ui.transparent}"
+      foreground: "{ui.text}"
+    danger:
+      background: "{ui.danger}"
+      foreground: "{ui.on-primary}"
+  Text:
+    muted:
+      foreground: "{ui.text-muted}"
+  Card:
+    default:
+      background: "{ui.surface}"
+  Badge:
+    default:
+      background: "{ui.surface-muted}"
+    primary:
+      background: "{ui.primary-weak}"
+    success:
+      background: "{ui.success-weak}"
+    warning:
+      background: "{ui.warning-weak}"
+    danger:
+      background: "{ui.danger-weak}"
+  Alert:
+    default:
+      background: "{ui.surface}"
+    success:
+      background: "{ui.success-weak}"
+    warning:
+      background: "{ui.warning-weak}"
+    danger:
+      background: "{ui.danger-weak}"

package/renderers/react/defaults/tokens.yaml

@@ -0,0 +1,59 @@
+# Default design tokens — mirrors renderers/react/runtime/theme.css :root variables.
+ui:
+  bg:
+    $type: color
+    $value: "#f6f8fb"
+  surface:
+    $type: color
+    $value: "#ffffff"
+  surface-muted:
+    $type: color
+    $value: "#f8fafc"
+  text:
+    $type: color
+    $value: "#111827"
+  text-muted:
+    $type: color
+    $value: "#6b7280"
+  primary:
+    $type: color
+    $value: "#2563eb"
+  primary-weak:
+    $type: color
+    $value: "#dbeafe"
+  success:
+    $type: color
+    $value: "#047857"
+  success-weak:
+    $type: color
+    $value: "#d1fae5"
+  warning:
+    $type: color
+    $value: "#b45309"
+  warning-weak:
+    $type: color
+    $value: "#fef3c7"
+  danger:
+    $type: color
+    $value: "#dc2626"
+  danger-weak:
+    $type: color
+    $value: "#fee2e2"
+  on-primary:
+    $type: color
+    $value: "#ffffff"
+  button-secondary:
+    $type: color
+    $value: "#eef2f7"
+  transparent:
+    $type: color
+    $value: "transparent"
+  border:
+    $type: color
+    $value: "#e5e7eb"
+  shadow:
+    $type: shadow
+    $value: "0 10px 30px rgba(15, 23, 42, 0.08)"
+  font:
+    $type: typography
+    $value: 'Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif'

package/renderers/react/element-config.meta.json

@@ -12,7 +12,6 @@
     "levelProp": { "type": "string" },
     "defaultLevel": { "type": "number" },
     "actionEvent": { "type": "enum", "values": ["onClick", "onSubmit"] },
-    "variantClass": { "type": "boolean" },
     "fieldWrap": { "type": "boolean" },
     "inputType": { "type": "string" },
     "sizeClass": { "type": "string" },

package/renderers/react/elements.yaml

@@ -5,83 +5,82 @@
 elements:
   Page:
     tag: main
-    className: ui-page
+    className: vc-page
     ariaLabel: true
   Box:
     tag: div
-    className: ui-box
+    className: vc-box
     ariaLabel: true
   Column:
     tag: div
-    className: ui-column
+    className: vc-column
     flex: column
     ariaLabel: true
   Row:
     tag: div
-    className: ui-row
+    className: vc-row
     flex: row
     wrapProp: wrap
     ariaLabel: true
   Stack:
     tag: div
-    className: ui-stack
+    className: vc-stack
     ariaLabel: true
   Spacer:
     tag: div
-    className: ui-spacer
+    className: vc-spacer
     ariaHidden: true
     flexGrowProp: weight
   Divider:
     tag: hr
-    className: ui-divider
+    className: vc-divider
     void: true
   Heading:
     tag: dynamic-heading
-    className: ui-heading
+    className: vc-heading
     levelProp: level
     defaultLevel: 2
   Text:
     tag: p
-    className: ui-text
+    className: vc-text
   Link:
     tag: a
-    className: ui-link
+    className: vc-link
     actionEvent: onClick
   Button:
     tag: button
-    className: ui-button
-    variantClass: true
+    className: vc-button
     actionEvent: onClick
   Form:
     tag: form
-    className: ui-form
+    className: vc-form
     actionEvent: onSubmit
     ariaLabel: true
   TextInput:
     tag: input
-    className: ui-input
+    className: vc-text-input
     fieldWrap: true
     inputType: text
-    sizeClass: ui-field
+    sizeClass: vc-field
   TextArea:
     tag: textarea
-    className: ui-textarea
+    className: vc-text-area
     fieldWrap: true
   Select:
     tag: select
-    className: ui-select
+    className: vc-select
     fieldWrap: true
-    sizeClass: ui-field
+    sizeClass: vc-field
     optionsProp: options
   Checkbox:
     tag: label
-    className: ui-check
+    className: vc-checkbox
     checkbox: true
   List:
     tag: ul
-    className: ui-list
+    className: vc-list
     defaultRole: list
   ListItem:
     tag: li
-    className: ui-list-item
+    className: vc-list-item
     defaultRole: listitem

package/renderers/react/lowering/lowerToJsx.ts

@@ -119,22 +119,47 @@ function actionHandler(props: Record<string, IrValue>, event: 'onClick' | 'onSub
   return `onClick={() => { void dispatchAction(${expr}); }}`;
 }
 
-function classNameAttr(entry: ElementMapEntry, props: Record<string, IrValue>, headingLevel?: number): string {
+function componentToKebab(name: string): string {
+  return name.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
+}
+
+function variantClassSuffix(elementName: string, props: Record<string, IrValue>): string | undefined {
+  const variantLit = propLiteral(props, 'variant');
+  if (typeof variantLit === 'string') {
+    return ` vc-${componentToKebab(elementName)}--${variantLit}`;
+  }
+  const variant = propExpr(props, 'variant');
+  if (variant) return ` vc-${componentToKebab(elementName)}--\${${variant}}`;
+  return undefined;
+}
+
+function classNameAttr(
+  elementName: string,
+  entry: ElementMapEntry,
+  props: Record<string, IrValue>,
+  headingLevel?: number,
+): string {
   const base = entry.className ?? '';
   if (entry.tag === 'dynamic-heading' && headingLevel !== undefined) {
-    return `className="ui-heading ui-heading-${headingLevel}"`;
+    const levelClass = `${base} vc-heading-${headingLevel}`;
+    const variantSuffix = variantClassSuffix(elementName, props);
+    if (!variantSuffix) return `className="${levelClass}"`;
+    const variantLit = propLiteral(props, 'variant');
+    if (typeof variantLit === 'string') {
+      return `className="${levelClass}${variantSuffix}"`;
+    }
+    return `className={\`${levelClass}${variantSuffix}\`}`;
   }
-  if (entry.variantClass) {
+  const variantSuffix = variantClassSuffix(elementName, props);
+  if (variantSuffix) {
     const variantLit = propLiteral(props, 'variant');
     if (typeof variantLit === 'string') {
-      return `className="${base} ui-button-${variantLit}"`;
+      return `className="${base}${variantSuffix}"`;
     }
-    const variant = propExpr(props, 'variant');
-    if (variant) return `className={\`${base} ui-button-\${${variant} ?? 'secondary'}\`}`;
-    return `className="${base} ui-button-secondary"`;
+    return `className={\`${base}${variantSuffix}\`}`;
   }
   if (entry.wrapProp && propLiteral(props, entry.wrapProp) === true) {
-    return `className="${base} ui-wrap"`;
+    return `className="${base} vc-wrap"`;
   }
   if (entry.sizeClass && props.size) {
     const size = propExpr(props, 'size');
@@ -150,22 +175,22 @@ function emitFieldWrap(inner: string, props: Record<string, IrValue>, level: num
   const label = propExpr(props, 'label');
   const help = propExpr(props, 'help');
   const error = propExpr(props, 'error');
-  const lines = [`${indent(level)}<label className="ui-field">`];
+  const lines = [`${indent(level)}<label className="vc-field">`];
   if (typeof labelLit === 'string') {
-    lines.push(`${indent(level + 1)}<span className="ui-field-label">{${JSON.stringify(labelLit)}}</span>`);
+    lines.push(`${indent(level + 1)}<span className="vc-field-label">{${JSON.stringify(labelLit)}}</span>`);
   } else if (label) {
-    lines.push(`${indent(level + 1)}{${label} ? <span className="ui-field-label">{${label}}</span> : null}`);
+    lines.push(`${indent(level + 1)}{${label} ? <span className="vc-field-label">{${label}}</span> : null}`);
   }
   lines.push(`${indent(level + 1)}${inner}`);
   if (typeof helpLit === 'string') {
-    lines.push(`${indent(level + 1)}<span className="ui-field-help">{${JSON.stringify(helpLit)}}</span>`);
+    lines.push(`${indent(level + 1)}<span className="vc-field-help">{${JSON.stringify(helpLit)}}</span>`);
   } else if (help) {
-    lines.push(`${indent(level + 1)}{${help} ? <span className="ui-field-help">{${help}}</span> : null}`);
+    lines.push(`${indent(level + 1)}{${help} ? <span className="vc-field-help">{${help}}</span> : null}`);
   }
   if (typeof errorLit === 'string') {
-    lines.push(`${indent(level + 1)}<span className="ui-field-error">{${JSON.stringify(errorLit)}}</span>`);
+    lines.push(`${indent(level + 1)}<span className="vc-field-error">{${JSON.stringify(errorLit)}}</span>`);
   } else if (error) {
-    lines.push(`${indent(level + 1)}{${error} ? <span className="ui-field-error">{${error}}</span> : null}`);
+    lines.push(`${indent(level + 1)}{${error} ? <span className="vc-field-error">{${error}}</span> : null}`);
   }
   lines.push(`${indent(level)}</label>`);
   return lines.join('\n');
@@ -176,7 +201,7 @@ function emitCheckbox(props: Record<string, IrValue>, level: number): string {
   const label = propExpr(props, 'label') ?? '""';
   const checked = props.checked ? `defaultChecked={${propExpr(props, 'checked')}}` : '';
   const disabled = props.enabled ? `disabled={${propExpr(props, 'enabled')} === false}` : '';
-  return `${indent(level)}<label className="ui-check">
+  return `${indent(level)}<label className="vc-checkbox">
 ${indent(level + 1)}<input type="checkbox" name={${name}} ${checked} ${disabled} />
 ${indent(level + 1)}<span>{${label}}</span>
 ${indent(level)}</label>`;
@@ -193,8 +218,13 @@ function emitSelectOptions(props: Record<string, IrValue>, level: number): strin
   return `${indent(level + 1)}{${expr}.map((option) => <option key={option.value} value={option.value}>{option.label}</option>)}`;
 }
 
-function emitVoidInput(entry: ElementMapEntry, props: Record<string, IrValue>, level: number): string {
-  const attrs: string[] = [classNameAttr(entry, props), styleAttr(entry, props)];
+function emitVoidInput(
+  elementName: string,
+  entry: ElementMapEntry,
+  props: Record<string, IrValue>,
+  level: number,
+): string {
+  const attrs: string[] = [classNameAttr(elementName, entry, props), styleAttr(entry, props)];
   if (props.name) attrs.push(`name={${propExpr(props, 'name')}}`);
   if (props.placeholder) attrs.push(`placeholder={${propExpr(props, 'placeholder')}}`);
   if (entry.inputType) attrs.push(`type={${propExpr(props, 'type') ?? JSON.stringify(entry.inputType)}}`);
@@ -205,7 +235,13 @@ function emitVoidInput(entry: ElementMapEntry, props: Record<string, IrValue>, l
   return `${indent(level)}<${entry.tag} ${attrs.join(' ')} />`;
 }
 
-function emitOpenTag(entry: ElementMapEntry, props: Record<string, IrValue>, tag: string, headingLevel?: number): string {
+function emitOpenTag(
+  elementName: string,
+  entry: ElementMapEntry,
+  props: Record<string, IrValue>,
+  tag: string,
+  headingLevel?: number,
+): string {
   const attrs: string[] = [];
   if (entry.ariaHidden) attrs.push('aria-hidden');
   if (props.id) attrs.push(`id={${propExpr(props, 'id')}}`);
@@ -223,7 +259,7 @@ function emitOpenTag(entry: ElementMapEntry, props: Record<string, IrValue>, tag
   if (entry.tag === 'button' && props.enabled) attrs.push(`disabled={${propExpr(props, 'enabled')} === false}`);
   if (entry.tag === 'a' && props.href) attrs.push(`href={${propExpr(props, 'href')}}`);
   if (entry.tag === 'button') attrs.push(`type={${propExpr(props, 'type') ?? '"button"'}}`);
-  attrs.push(classNameAttr(entry, props, headingLevel));
+  attrs.push(classNameAttr(elementName, entry, props, headingLevel));
   attrs.push(styleAttr(entry, props));
   return `<${tag} ${attrs.join(' ')}`;
 }
@@ -290,10 +326,10 @@ function lowerVocabularyElement(
     const tag = entry.tag;
     let inner: string;
     if (entry.optionsProp && props[entry.optionsProp]) {
-      const open = emitOpenTag(entry, props, tag);
+      const open = emitOpenTag(node.name, entry, props, tag);
       inner = `${indent(level + 1)}${open}>\n${emitSelectOptions(props, level + 2)}\n${indent(level + 1)}</${tag}>`;
     } else {
-      inner = emitVoidInput(entry, props, level + 1);
+      inner = emitVoidInput(node.name, entry, props, level + 1);
     }
     return visibilityGuard(emitFieldWrap(inner, props, level), props, level);
   }
@@ -303,7 +339,7 @@ function lowerVocabularyElement(
     if (typeof levelLit === 'number') {
       const clamped = Math.min(6, Math.max(1, levelLit));
       const tag = `h${clamped}`;
-      const open = emitOpenTag(entry, props, tag, clamped);
+      const open = emitOpenTag(node.name, entry, props, tag, clamped);
       const body = childContent
         ? `${indent(level)}${open}>\n${childContent}\n${indent(level)}</${tag}>`
         : `${indent(level)}${open} />`;
@@ -311,17 +347,17 @@ function lowerVocabularyElement(
     }
     const levelExpr = propExpr(props, 'level') ?? '2';
     const inner = childContent
-      ? `${indent(level + 1)}{(() => { const __level = Math.min(6, Math.max(1, ${levelExpr} ?? 2)); const Tag = ('h' + __level) as keyof JSX.IntrinsicElements; return <Tag className={\`ui-heading ui-heading-\${__level}\`} style={commonStyle(${collectStyleProps(props)})}>{/* children below */}</Tag>; })()}`
+      ? `${indent(level + 1)}{(() => { const __level = Math.min(6, Math.max(1, ${levelExpr} ?? 2)); const Tag = ('h' + __level) as keyof JSX.IntrinsicElements; return <Tag className={\`vc-heading vc-heading-\${__level}\`} style={commonStyle(${collectStyleProps(props)})}>{/* children below */}</Tag>; })()}`
       : '';
-    return visibilityGuard(inner || `${indent(level)}<h2 ${classNameAttr(entry, props, 2)} ${styleAttr(entry, props)} />`, props, level);
+    return visibilityGuard(inner || `${indent(level)}<h2 ${classNameAttr(node.name, entry, props, 2)} ${styleAttr(entry, props)} />`, props, level);
   }
 
   const tag = entry.tag;
   if (entry.void) {
-    return visibilityGuard(`${indent(level)}${emitOpenTag(entry, props, tag)} />`, props, level);
+    return visibilityGuard(`${indent(level)}${emitOpenTag(node.name, entry, props, tag)} />`, props, level);
   }
 
-  const open = emitOpenTag(entry, props, tag);
+  const open = emitOpenTag(node.name, entry, props, tag);
   let body: string;
   if (!childContent && entry.optionsProp && props[entry.optionsProp]) {
     body = `${indent(level)}${open}>\n${emitSelectOptions(props, level + 1)}\n${indent(level)}</${tag}>`;

package/renderers/react/renderRuntime.ts

@@ -3,6 +3,14 @@ import { resolve } from 'node:path';
 import type { ViewContractsConfig } from '../../src/config.js';
 import { projectRoot } from '../../src/config.js';
 import { loadThemeCss } from '../../src/catalog/loadThemeCss.js';
+import {
+  defaultThemePath,
+  defaultTokensPath,
+  emitTokenCss,
+  emitVariantCss,
+  extractStructuralThemeCss,
+  loadValidateDesign,
+} from '../../src/design/index.js';
 import { packageRoot } from '../../src/lib/packageRoot.js';
 import { renderTemplate } from '../../src/renderer/template.js';
 import { reactRuntimeDir, reactTemplatesDir } from './paths.js';
@@ -32,7 +40,7 @@ async function copySchemaBundle(componentsDir: string): Promise<void> {
 
   const schemaDest = resolve(componentsDir, 'schema');
   await cp(schemaSrc, schemaDest, { recursive: true });
-  for (const name of ['dsl-properties.ts', 'tokens.ts', 'schema-document.ts', 'index.ts'] as const) {
+  for (const name of ['dsl-properties.ts', 'dsl-enums.ts', 'schema-document.ts', 'index.ts'] as const) {
     const file = resolve(schemaDest, name);
     if (await pathExists(file)) {
       await writeFile(file, rewriteSchemaImports(await readFile(file, 'utf-8')), 'utf-8');
@@ -49,15 +57,30 @@ async function copyStyleBundle(componentsDir: string): Promise<void> {
   await writeFile(resolve(componentsDir, 'types.ts'), types, 'utf-8');
 }
 
-async function writeThemeCss(root: string, themeOut: string, templatesDir?: string): Promise<void> {
+async function writeThemeCss(
+  root: string,
+  themeOut: string,
+  config: ViewContractsConfig,
+  templatesDir?: string,
+): Promise<void> {
+  const tokensPath = config.design?.tokens ?? defaultTokensPath();
+  const themePath = config.design?.theme ?? defaultThemePath();
+  const { tokenIR, themeIR } = await loadValidateDesign(tokensPath, themePath);
   const runtimeTheme = resolve(reactRuntimeDir(), 'theme.css');
-  let css = await loadThemeCss(runtimeTheme);
-  const extensionsCss = resolve(root, 'src/theme.extensions.css');
+  const runtimeCss = await loadThemeCss(runtimeTheme);
+  const variantCss = emitVariantCss(tokenIR, themeIR);
+  let css = `${emitTokenCss(tokenIR)}\n\n${variantCss}\n\n${extractStructuralThemeCss(runtimeCss)}`;
+  const extensionsCss = config.design?.extensionsCss ?? resolve(root, 'src/theme.extensions.css');
   if (await pathExists(extensionsCss)) {
     css += `\n\n${await readFile(extensionsCss, 'utf-8')}`;
   }
   const content = await renderTemplate(reactTemplatesDir(templatesDir), 'theme.css.hbs', { themeCss: css });
   await writeFile(themeOut, content, 'utf-8');
+
+  const themeDir = resolve(config.generated.reactDir, '../theme');
+  await mkdir(themeDir, { recursive: true });
+  await writeFile(resolve(themeDir, 'tokens.json'), `${JSON.stringify(tokenIR, null, 2)}\n`, 'utf-8');
+  await writeFile(resolve(themeDir, 'theme.json'), `${JSON.stringify(themeIR, null, 2)}\n`, 'utf-8');
 }
 
 async function removeStaleGeneratedFiles(componentsDir: string): Promise<void> {
@@ -117,7 +140,7 @@ export async function renderReactRuntime(configPath: string, config: ViewContrac
     'utf-8',
   );
 
-  await writeThemeCss(root, resolve(config.generated.reactDir, '../theme.css'), templatesDir);
+  await writeThemeCss(root, resolve(config.generated.reactDir, '../theme.css'), config, templatesDir);
   await writeFile(
     resolve(runtimeDir, 'types.ts'),
     await renderTemplate(templates, 'runtime-types.ts.hbs', {}),

package/renderers/react/runtime/style.ts

@@ -1,5 +1,5 @@
 import type { CSSProperties } from 'react';
-import type { Align, Clip, ContentAlign, FontWeight, Justify, Shadow } from '../../../src/generated/schema/tokens.js';
+import type { Align, ContentAlign, FontWeight, Justify } from '../../../src/generated/schema/dsl-enums.js';
 import type { CommonProps } from './types.js';
 
 export function mapAlign(value?: Align): string | undefined {
@@ -23,12 +23,6 @@ function len(value: number): string {
   return `${value}px`;
 }
 
-const SHADOW: Record<Exclude<Shadow, 'none'>, string> = {
-  sm: '0 1px 3px rgba(15,23,42,0.08)',
-  md: '0 10px 30px rgba(15, 23, 42, 0.08)',
-  lg: '0 20px 40px rgba(15, 23, 42, 0.12)',
-};
-
 const CONTENT_ALIGN: Record<ContentAlign, string> = {
   topStart: 'start start',
   top: 'center start',
@@ -41,12 +35,6 @@ const CONTENT_ALIGN: Record<ContentAlign, string> = {
   bottomEnd: 'end end',
 };
 
-function shadowStyle(shadow: Shadow | boolean | undefined): string | undefined {
-  if (shadow === true) return SHADOW.md;
-  if (!shadow || shadow === 'none') return undefined;
-  return SHADOW[shadow];
-}
-
 function fontSizeStyle(size: number | string | undefined): string | undefined {
   if (size === undefined) return undefined;
   return typeof size === 'number' ? len(size) : size;
@@ -65,14 +53,6 @@ export function commonStyle(props: CommonProps): CSSProperties {
   if (typeof props.padding === 'number') style.padding = len(props.padding);
   if (typeof (props as { margin?: number }).margin === 'number') style.margin = len((props as { margin: number }).margin);
   if (typeof props.gap === 'number') style.gap = len(props.gap);
-  if (typeof props.radius === 'number') style.borderRadius = len(props.radius);
-  if (props.border) style.border = '1px solid var(--ui-border)';
-  const shadow = shadowStyle(props.shadow);
-  if (shadow) style.boxShadow = shadow;
-  if (props.opacity !== undefined) style.opacity = props.opacity;
-  if (props.clip && props.clip !== 'none') style.overflow = 'hidden';
-  if (props.background) style.background = `var(--ui-${props.background}, ${props.background})`;
-  if (props.foreground) style.color = `var(--ui-${props.foreground}, ${props.foreground})`;
   if (props.textAlign) style.textAlign = props.textAlign === 'start' ? 'left' : props.textAlign === 'end' ? 'right' : 'center';
   if (props.contentAlign) style.placeItems = CONTENT_ALIGN[props.contentAlign];
   if ((props as { overflow?: string }).overflow) style.overflow = (props as { overflow: string }).overflow;
@@ -93,4 +73,29 @@ export function toneClass(tone: string | undefined): string {
   return tone ? `ui-tone-${tone}` : 'ui-tone-default';
 }
 
-export type { Clip, ContentAlign, Shadow };
+function componentToKebab(name: string): string {
+  return name.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
+}
+
+const DEFAULT_VARIANT_ALIASES = new Set(['default', 'muted']);
+
+/** Resolve theme variant name from variant or legacy tone prop. */
+export function resolveExtensionVariant(variant?: string, tone?: string): string {
+  const raw = variant ?? tone;
+  if (!raw || DEFAULT_VARIANT_ALIASES.has(raw)) return 'default';
+  return raw;
+}
+
+/** Build vc-* base + --variant modifier for themed extension components. */
+export function extensionClassName(
+  component: string,
+  options?: { variant?: string; tone?: string; extra?: string | false },
+): string {
+  const base = `vc-${componentToKebab(component)}`;
+  const variant = resolveExtensionVariant(options?.variant, options?.tone);
+  const parts = [base, `${base}--${variant}`];
+  if (options?.extra) parts.push(options.extra);
+  return parts.filter(Boolean).join(' ');
+}
+
+export type { ContentAlign };