chore: resolve merge conflict in benchmark fixture

Accept HEAD timestamps after dev merge.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: himerus

.changeset/fix-css-snippet-slot-guidance.md

@@ -0,0 +1,6 @@
+---
+'helixir': patch
+'@helixir/core': patch
+---
+
+fix: buildCssSnippet self-referential var() bug, add slot styling guidance and font inheritance warnings

.changeset/library-agnostic-tokens.md

@@ -0,0 +1,6 @@
+---
+'helixir': minor
+'@helixir/core': minor
+---
+
+feat: make suggest_fix token suggestions library-agnostic with optional tokenPrefix parameter

packages/core/src/handlers/styling-diagnostics.ts

@@ -188,6 +188,16 @@ export function buildAntiPatterns(meta: ComponentMetadata): AntiPatternWarning[]
     });
   }
 
+  // Warn about font vs layout inheritance through slots
+  if (meta.slots.length > 0) {
+    warnings.push({
+      pattern: `${tag}::slotted(div) { margin: 10px; } /* expecting layout to inherit */`,
+      explanation:
+        'Slotted content inherits font styles (color, font-size, line-height) from the shadow DOM, but layout properties (margin, padding, display, width) must be set in light DOM CSS — they do not inherit through the shadow boundary.',
+      correctApproach: `Style layout in light DOM CSS: ${tag} > div { margin: 10px; }. Font properties like color and font-size will inherit from the component's shadow DOM automatically.`,
+    });
+  }
+
   return warnings;
 }
 
@@ -200,13 +210,14 @@ export function buildCssSnippet(meta: ComponentMetadata): string {
   const lines: string[] = [];
   const tag = meta.tagName;
 
-  // Token customization section
+  // Token customization section — show how to OVERRIDE custom properties
   if (meta.cssProperties.length > 0) {
-    lines.push(`/* Token customization */`);
+    lines.push(`/* Token customization — override on the component host */`);
     lines.push(`${tag} {`);
     for (const prop of meta.cssProperties.slice(0, 5)) {
-      const defaultVal = prop.description ? `/* ${prop.description} */` : '';
-      lines.push(`  ${prop.name}: var(${prop.name}) ${defaultVal};`.trimEnd());
+      const value = prop.default ?? guessDefaultValue(prop.name);
+      const comment = prop.description ? ` /* ${prop.description} */` : '';
+      lines.push(`  ${prop.name}: ${value};${comment}`);
     }
     lines.push(`}`);
   }
@@ -223,6 +234,25 @@ export function buildCssSnippet(meta: ComponentMetadata): string {
     }
   }
 
+  // Slot styling section — show how to style slotted content in light DOM
+  if (meta.slots.length > 0) {
+    lines.push('');
+    lines.push(`/* Slot styling — target slotted elements in light DOM CSS */`);
+    const hasDefaultSlot = meta.slots.some((s) => s.name === '');
+    const namedSlots = meta.slots.filter((s) => s.name !== '');
+
+    if (hasDefaultSlot) {
+      lines.push(`${tag} > * { /* styles for default slot content */ }`);
+    }
+    for (const slot of namedSlots.slice(0, 3)) {
+      const desc = slot.description ? ` /* ${slot.description} */` : '';
+      lines.push(`${tag} [slot="${slot.name}"] { ${desc.trim()} }`);
+    }
+    lines.push(`/* Note: slotted content inherits font styles (color, font-size)`);
+    lines.push(`   from the shadow DOM, but layout (margin, padding, display)`);
+    lines.push(`   must be set here in light DOM CSS. */`);
+  }
+
   if (lines.length === 0) {
     lines.push(`/* ${tag} exposes no CSS customization points in its CEM. */`);
     lines.push(`/* Check the component documentation for styling options. */`);
@@ -231,6 +261,23 @@ export function buildCssSnippet(meta: ComponentMetadata): string {
   return lines.join('\n');
 }
 
+/**
+ * Guesses a sensible placeholder value based on CSS property name patterns.
+ * Used when the CEM doesn't specify a default value.
+ */
+function guessDefaultValue(propName: string): string {
+  const lower = propName.toLowerCase();
+  if (/color|bg|background/.test(lower)) return '#value';
+  if (/size|font/.test(lower)) return '1rem';
+  if (/radius/.test(lower)) return '4px';
+  if (/spacing|padding|margin|gap/.test(lower)) return '1rem';
+  if (/shadow/.test(lower)) return '0 1px 2px rgba(0,0,0,.1)';
+  if (/weight/.test(lower)) return '400';
+  if (/width|height/.test(lower)) return 'auto';
+  if (/opacity/.test(lower)) return '1';
+  return '#value';
+}
+
 // ─── Main Entry Point ────────────────────────────────────────────────────────
 
 /**

packages/core/src/handlers/suggest-fix.ts

@@ -36,26 +36,41 @@ export interface SuggestFixInput {
   memberName?: string;
   suggestedName?: string;
   eventName?: string;
+  /** Optional token prefix from the component's library (e.g. '--hx-', '--fast-'). When provided, suggested tokens use this prefix instead of generic placeholders. */
+  tokenPrefix?: string;
 }
 
 // ─── Token heuristics ────────────────────────────────────────────────────────
 
-const TOKEN_SUGGESTIONS: Record<string, string> = {
-  'background-color': '--sl-color-neutral-0',
-  background: '--sl-color-neutral-0',
-  color: '--sl-color-neutral-900',
-  'border-color': '--sl-color-neutral-300',
-  'box-shadow': '--sl-shadow-medium',
-  'font-family': '--sl-font-sans',
-  'font-size': '--sl-font-size-medium',
-  'border-radius': '--sl-border-radius-medium',
-  padding: '--sl-spacing-medium',
-  margin: '--sl-spacing-medium',
-  gap: '--sl-spacing-small',
+/** Maps CSS properties to semantic token suffixes (library-agnostic). */
+const TOKEN_SUFFIXES: Record<string, string> = {
+  'background-color': 'color-neutral-0',
+  background: 'color-neutral-0',
+  color: 'color-neutral-900',
+  'border-color': 'color-neutral-300',
+  'box-shadow': 'shadow-medium',
+  'font-family': 'font-sans',
+  'font-size': 'font-size-medium',
+  'border-radius': 'border-radius-medium',
+  padding: 'spacing-medium',
+  margin: 'spacing-medium',
+  gap: 'spacing-small',
 };
 
-function suggestTokenForProperty(property: string): string {
-  return TOKEN_SUGGESTIONS[property] ?? '--your-design-token';
+/**
+ * Suggests a token name for a CSS property. When a tokenPrefix is provided,
+ * generates a library-specific token (e.g. `--hx-color-neutral-0`).
+ * Without a prefix, returns a generic placeholder.
+ */
+function suggestTokenForProperty(property: string, tokenPrefix?: string): string {
+  const suffix = TOKEN_SUFFIXES[property];
+  if (!suffix) {
+    return tokenPrefix ? `${tokenPrefix}design-token` : '--your-design-token';
+  }
+  if (tokenPrefix) {
+    return `${tokenPrefix}${suffix}`;
+  }
+  return `--your-${suffix}`;
 }
 
 // ─── Shadow DOM fixes ────────────────────────────────────────────────────────
@@ -193,7 +208,7 @@ function fixShadowDom(input: SuggestFixInput): FixSuggestion {
 // ─── Token fallback fixes ────────────────────────────────────────────────────
 
 function fixTokenFallback(input: SuggestFixInput): FixSuggestion {
-  const { original, property } = input;
+  const { original, property, tokenPrefix } = input;
 
   if (input.issue === 'missing-fallback') {
     // Extract the var() call and add a sensible fallback
@@ -223,7 +238,7 @@ function fixTokenFallback(input: SuggestFixInput): FixSuggestion {
   }
 
   if (input.issue === 'hardcoded-color') {
-    const token = suggestTokenForProperty(property ?? 'color');
+    const token = suggestTokenForProperty(property ?? 'color', tokenPrefix);
     // Extract the property and value
     const propMatch = original.match(/([a-z-]+)\s*:\s*([^;]+)/i);
     if (propMatch) {
@@ -250,10 +265,10 @@ function fixTokenFallback(input: SuggestFixInput): FixSuggestion {
 // ─── Theme compatibility fixes ───────────────────────────────────────────────
 
 function fixThemeCompat(input: SuggestFixInput): FixSuggestion {
-  const { original, property } = input;
+  const { original, property, tokenPrefix } = input;
 
   if (input.issue === 'hardcoded-color') {
-    const token = suggestTokenForProperty(property ?? 'background');
+    const token = suggestTokenForProperty(property ?? 'background', tokenPrefix);
     const propMatch = original.match(/([a-z-]+)\s*:\s*([^;]+)/i);
     if (propMatch) {
       const [, prop, value] = propMatch;
@@ -269,9 +284,11 @@ function fixThemeCompat(input: SuggestFixInput): FixSuggestion {
   }
 
   if (input.issue === 'contrast-pair') {
+    const bgToken = suggestTokenForProperty('background-color', tokenPrefix);
+    const fgToken = suggestTokenForProperty('color', tokenPrefix);
     return {
       original,
-      suggestion: `background: var(--sl-color-neutral-0); color: var(--sl-color-neutral-900);`,
+      suggestion: `background: var(${bgToken}); color: var(${fgToken});`,
       explanation: `Light-on-light or dark-on-dark color pairs create contrast issues. Use semantic token pairs (surface + on-surface) that maintain readable contrast across themes.`,
       severity: 'warning',
     };

packages/core/src/tools/styling.ts

@@ -148,6 +148,7 @@ const SuggestFixArgsSchema = z.object({
   memberName: z.string().optional(),
   suggestedName: z.string().optional(),
   eventName: z.string().optional(),
+  tokenPrefix: z.string().optional(),
 });
 
 const ValidateComponentCodeArgsSchema = z.object({
@@ -622,6 +623,11 @@ export const STYLING_TOOL_DEFINITIONS = [
           type: 'string',
           description: 'Optional event name for event usage fixes.',
         },
+        tokenPrefix: {
+          type: 'string',
+          description:
+            'Optional token prefix from the component library (e.g. "--hx-", "--fast-", "--md-"). When provided, suggested replacement tokens use this prefix. Get this from diagnose_styling.',
+        },
       },
       required: ['type', 'issue', 'original'],
       additionalProperties: false,

tests/handlers/styling-diagnostics.test.ts

@@ -215,6 +215,19 @@ describe('buildAntiPatterns', () => {
     );
     expect(partWarning).toBeUndefined();
   });
+
+  it('includes font inheritance warning when slots exist', () => {
+    const warnings = buildAntiPatterns(buttonMeta);
+    const inheritWarning = warnings.find((w) => w.explanation.includes('inherit'));
+    expect(inheritWarning).toBeDefined();
+    expect(inheritWarning!.explanation).toContain('font');
+  });
+
+  it('skips font inheritance warning when no slots', () => {
+    const warnings = buildAntiPatterns(bareComponent);
+    const inheritWarning = warnings.find((w) => w.explanation.includes('inherit'));
+    expect(inheritWarning).toBeUndefined();
+  });
 });
 
 describe('buildCssSnippet', () => {
@@ -224,12 +237,55 @@ describe('buildCssSnippet', () => {
     expect(snippet).toContain('--my-button-bg');
   });
 
+  it('does NOT generate self-referential var() in token customization', () => {
+    const snippet = buildCssSnippet(buttonMeta);
+    // Should NOT contain --my-button-bg: var(--my-button-bg) — that's circular
+    expect(snippet).not.toMatch(/--my-button-bg:\s*var\(--my-button-bg\)/);
+    // Should contain a direct value assignment
+    expect(snippet).toMatch(/--my-button-bg:\s*[^v]/);
+  });
+
+  it('uses CEM default value when available', () => {
+    const metaWithDefaults: ComponentMetadata = {
+      ...bareComponent,
+      cssProperties: [
+        { name: '--my-card-bg', description: 'Background', default: '#ffffff' },
+        { name: '--my-card-radius', description: 'Radius', default: '4px' },
+      ],
+    };
+    const snippet = buildCssSnippet(metaWithDefaults);
+    expect(snippet).toContain('#ffffff');
+    expect(snippet).toContain('4px');
+  });
+
   it('includes part customization for components with CSS parts', () => {
     const snippet = buildCssSnippet(buttonMeta);
     expect(snippet).toContain('Part-based customization');
     expect(snippet).toContain('::part(base)');
   });
 
+  it('includes slot styling section when component has slots', () => {
+    const snippet = buildCssSnippet(buttonMeta);
+    expect(snippet).toContain('Slot styling');
+    expect(snippet).toContain('light DOM');
+  });
+
+  it('includes named slot selector example', () => {
+    const snippet = buildCssSnippet(buttonMeta);
+    expect(snippet).toContain('[slot="prefix"]');
+  });
+
+  it('includes default slot child selector example', () => {
+    const snippet = buildCssSnippet(buttonMeta);
+    // Default slot: style children of the host
+    expect(snippet).toContain('my-button >');
+  });
+
+  it('skips slot section for components without slots', () => {
+    const snippet = buildCssSnippet(bareComponent);
+    expect(snippet).not.toContain('Slot styling');
+  });
+
   it('generates fallback message for bare components', () => {
     const snippet = buildCssSnippet(bareComponent);
     expect(snippet).toContain('no CSS customization');
@@ -248,9 +304,6 @@ describe('buildCssSnippet', () => {
       })),
     };
     const snippet = buildCssSnippet(manyProps);
-    // Should have at most 5 properties listed (each appears twice: decl + var)
-    const propMatches = snippet.match(/--prop-/g);
-    expect(propMatches!.length).toBeLessThanOrEqual(10);
     // Should not contain --prop-5 through --prop-9
     expect(snippet).not.toContain('--prop-5');
     // Should have at most 3 parts listed

tests/handlers/suggest-fix.test.ts

@@ -308,6 +308,70 @@ describe('suggestFix — layout', () => {
   });
 });
 
+// ─── Library-agnostic token suggestions ─────────────────────────────────────
+
+describe('suggestFix — library-agnostic tokens', () => {
+  it('uses provided tokenPrefix instead of hardcoded --sl- tokens', () => {
+    const result = suggestFix({
+      type: 'token-fallback',
+      issue: 'hardcoded-color',
+      original: 'background-color: #3b82f6;',
+      property: 'background-color',
+      tokenPrefix: '--hx-',
+    });
+    expect(result.suggestion).toContain('--hx-');
+    expect(result.suggestion).not.toContain('--sl-');
+  });
+
+  it('uses generic placeholder when no tokenPrefix provided', () => {
+    const result = suggestFix({
+      type: 'token-fallback',
+      issue: 'hardcoded-color',
+      original: 'color: #333;',
+      property: 'color',
+    });
+    // Should NOT contain library-specific prefix
+    expect(result.suggestion).not.toContain('--sl-');
+    expect(result.suggestion).toContain('var(');
+  });
+
+  it('uses tokenPrefix in theme-compat hardcoded-color fix', () => {
+    const result = suggestFix({
+      type: 'theme-compat',
+      issue: 'hardcoded-color',
+      original: 'background: white;',
+      property: 'background',
+      tokenPrefix: '--fast-',
+    });
+    expect(result.suggestion).toContain('--fast-');
+    expect(result.suggestion).not.toContain('--sl-');
+  });
+
+  it('uses tokenPrefix in theme-compat contrast-pair fix', () => {
+    const result = suggestFix({
+      type: 'theme-compat',
+      issue: 'contrast-pair',
+      original: 'background: #f0f0f0; color: #e0e0e0;',
+      tokenPrefix: '--md-',
+    });
+    expect(result.suggestion).toContain('--md-');
+    expect(result.suggestion).not.toContain('--sl-');
+  });
+
+  it('generates property-appropriate token names from prefix', () => {
+    const result = suggestFix({
+      type: 'token-fallback',
+      issue: 'hardcoded-color',
+      original: 'border-radius: 8px;',
+      property: 'border-radius',
+      tokenPrefix: '--hx-',
+    });
+    expect(result.suggestion).toContain('--hx-');
+    // Should generate a radius-related token name
+    expect(result.suggestion).toMatch(/--hx-.*radius/i);
+  });
+});
+
 // ─── Result structure ───────────────────────────────────────────────────────
 
 describe('suggestFix — result structure', () => {