Instruction file imported from ASAP-Digest/ASAP-Digest (.cursor/rules/add-shadcn-svelte-component.mdc). Copyright stays with the author.

Add Shadcn-svelte 5 Component

(Self-correction: Added clarification on internal component structure vs external usage)

1. Pre-installation Checks:

   • Verify component does not exist: cd "/Volumes/Macintosh HD/Users/vsmith/Local Sites/asap-digest/app/public/app" && pnpm list shadcn-svelte
   • Check component dependencies in Shadcn documentation
   • Review usage in codebase
   • Ensure you're in SvelteKit root: /Volumes/Macintosh HD/Users/vsmith/Local Sites/asap-digest/app/public/app

2. Installation:

   • Install via CLI: npx shadcn-svelte@next add [component]
   • Verify installation success in package.json
   • Check component files were created in correct location (app/src/lib/components/ui/[component]/)

3. Icon Management:

   • Scan new component .svelte files for Lucide icon imports using grep: grep -r "from 'lucide-svelte'" app/src/lib/components/ui/[component]
   • NEVER use direct icon imports from lucide-svelte in UI components consuming Shadcn components.
   • Add ALL icons used by the new component to /app/src/lib/utils/lucide-compat.js:

     import { Icon1, Icon2 } from 'lucide-svelte'
     import { createIconObject } from './icon-utils' // Assuming this utility exists
     
     export const Icon1 = createIconObject(Icon1)
     export const Icon2 = createIconObject(Icon2)
     // OR direct re-export if utility not used: export { Icon1, Icon2 };

   • Update the newly added Shadcn component .svelte files to import icons from $lib/utils/lucide-compat.js and render them using the <Icon icon={...}> wrapper:

     // Inside the Shadcn component .svelte file (e.g., dropdown-menu-item.svelte)
     import Icon from '$lib/components/ui/icon/icon.svelte'
     import { SpecificIconNeeded } from '$lib/utils/lucide-compat.js'
     
     // In template:
     <Icon icon={SpecificIconNeeded} class="w-4 h-4" />

   • Document icon usage within the component's JSDoc if applicable.

4. Component Integration & Usage:

   • When Using/Consuming: Import directly from .svelte files ONLY:

     // CORRECT (In your page/layout/wrapper component)
     import Component from '$lib/components/ui/component/component.svelte'
     // INCORRECT
     // import { Component } from '$lib/components/ui/component'
     // import * as Component from '$lib/components/ui/component/index.js' // Avoid index files per sk2-scns5-t4-int.mdc

   • Internal Structure: The Shadcn component .svelte files themselves will typically import primitives directly from bits-ui (e.g., import { DropdownMenu as DropdownMenuPrimitive } from "bits-ui";) and use those primitives (e.g., <DropdownMenuPrimitive.Content>). Do not confuse this internal structure with the external usage pattern.
   • Use Svelte 5 Runes syntax (const { ... } = $props();, {@render ...()}).
   • Apply Tailwind 4 HSL color variables (text-[hsl(var(--primary))]) per golden-ratio-design-system-protocol.mdc.

5. Testing Requirements:

   • Test component with all its variants.
   • Verify icon rendering through Icon component.
   • Check responsive behavior.
   • Test dark/light mode transitions.
   • Verify accessibility features.

6. Documentation:

   • Document component usage in project where applicable.
   • List all icons added to compatibility layer in relevant docs/changelog.
   • Note any specific configuration requirements.

7. Error Prevention:

   • Verify all icons are exported correctly from lucide-compat.js.
   • Check for any style conflicts (adhere to golden-ratio-design-system-protocol.mdc).
   • Test component in isolation if possible.
   • Verify build completes successfully (pnpm build).
   • Check for SSR compatibility with icons and component logic.