Merge pull request #154 from bookedsolidtech/feature/slot-styling-guidance

feat: add slot styling guidance to suggest_usage handler

Author: himerus

packages/core/src/handlers/suggest.ts

@@ -182,6 +182,7 @@ function buildStyling(
   meta: {
     cssProperties: Array<{ name: string; description: string; default?: string }>;
     cssParts: Array<{ name: string; description: string }>;
+    slots: Array<{ name: string; description: string }>;
   },
 ): SuggestUsageStyling | undefined {
   if (meta.cssProperties.length === 0 && meta.cssParts.length === 0) return undefined;
@@ -218,6 +219,35 @@ function buildStyling(
 
   const warnings: string[] = getShadowDomWarnings(tagName);
 
+  // Add slot-specific styling guidance when the component has slots
+  if (meta.slots.length > 0) {
+    const namedSlots = meta.slots.filter((s) => s.name !== '');
+    const hasDefaultSlot = meta.slots.some((s) => s.name === '');
+
+    warnings.push(
+      `To style slotted content, use light DOM CSS targeting the elements BEFORE they are slotted in. Do not use \`::slotted()\` in consumer CSS — it only works inside the shadow root stylesheet.`,
+    );
+
+    if (hasDefaultSlot) {
+      warnings.push(
+        `Default slot: style children of \`${tagName}\` in your page CSS (e.g. \`${tagName} > p { ... }\`). These selectors work because slotted elements remain in the light DOM.`,
+      );
+    }
+
+    if (namedSlots.length > 0) {
+      const slotExample = namedSlots[0];
+      if (slotExample) {
+        warnings.push(
+          `Named slots: style elements with \`[slot="${slotExample.name}"]\` attribute selector in your page CSS (e.g. \`${tagName} [slot="${slotExample.name}"] { ... }\`).`,
+        );
+      }
+    }
+
+    warnings.push(
+      `Slotted content inherits font styles (color, font-size, line-height) from the component's shadow DOM, but layout properties (margin, padding, display) must be set in light DOM CSS.`,
+    );
+  }
+
   return { cssProperties, cssParts, cssSnippet, warnings };
 }
 

tests/handlers/suggest.test.ts

@@ -712,6 +712,21 @@ describe('suggestUsage — styling section (my-button with CSS props and parts)'
     expect(allWarnings).toContain('Shadow DOM');
   });
 
+  it('styling.warnings include slot styling guidance for components with slots', async () => {
+    const result = await suggestUsage('my-button', makeConfig());
+    const allWarnings = result.styling!.warnings.join(' ');
+    // my-button has slots, so slot styling guidance should be present
+    expect(allWarnings).toContain('slotted content');
+    expect(allWarnings).toContain('light DOM CSS');
+  });
+
+  it('styling.warnings include named slot selectors when component has named slots', async () => {
+    const result = await suggestUsage('my-button', makeConfig());
+    const allWarnings = result.styling!.warnings.join(' ');
+    // my-button has named slots (prefix, suffix)
+    expect(allWarnings).toContain('[slot=');
+  });
+
   it('returns no styling when component has no CSS properties or parts', async () => {
     const noStyleCem = {
       schemaVersion: '1.0.0',