name: shadcn-svelte description: Use this skill when the project uses shadcn-svelte and the task involves implementing or refactoring UI with that library. metadata: author: j13z

shadcn-svelte Agent Skill

Preparation

1. Projects may customize locations. Therefore read components.json completely and inspect its fields:
   • aliases.ui: hint to where components are located (replace $lib, likely with src/lib)
   • aliases.utils: hint where utils.ts is located (same logic)
   • tailwind.css: The main stylesheet with token and color definitions
2. Read references/shadcn-svelte-component-index-llms.md.

• Defer following specific component docs until you actually use a component or when you need more detailed information in advance for a specific task

shadcn-svelte does not come as regular node_modules dependency, but instead components are installed embedded into src/lib (resolve aliases.ui value) on demand.

• That means (important!): If you think that a useful shadcn-svelte component listed in shadcn-svelte-component-index-llms.md is missing, stop an ask the user to install it.
• Or – if you have the ability – install it yourself using the shadcn-svelte CLI: pnpm dlx shadcn-svelte@latest add button

Background

You need to understand these characteristics of shadcn-svelte:

• It's components are "open code", their source code is pulled into the application like "starter kit". This gives the project full control. But: Never modify the component sources.

• It's components compose very nicely because primitives forward the underlying element's attributes, especially the class attribute, so they remain full customizable and stylable.

  • You should however accept the default styles and only override them, if there's a clear reason.

• shadcn-svelte provides a basic design system and theme configuration based on Tailwind.

Before you use a component for the first time, consult its linked documentation: Read the usage instructions and code example (load references component docs lazily / on demand).

Component selection

Strongly prefer existing shadcn-svelte components when they already cover the intended UI pattern. Do not rebuild common UI primitives with raw HTML + Tailwind just because it seems faster in the moment.

Only build custom low-level UI when:

• the catalog clearly does not fit the use case
• the custom structure is truly simpler

Instructions

Specific Tailwind Classes

shadcn-svelte defines custom CSS variables for colors such as:

--background
--foreground
--card
--card-foreground
--primary
--primary-foreground
--muted
--muted-foreground
--accent
--accent-foreground
--border
--input
--ring
…

From these, Tailwind constructs classes like the following - these are just examples:

bg-primary
bg-background
bg-card
text-primary-foreground
text-foreground
text-muted-foreground
text-warning-foreground
…

Do

• If your component renders a primitive, expose a class prop an pass it on to maintain the an "openness" and composability properties. Use the cn(…) class composition helper function to pass on class / className props. Examples:

  <!-- With a `shadcn-svelte` Button -->
  <Button class={cn("<provided classes>", className)}>
    {@render children?.()}
  <Button>
  

  or the same with a simple DOM element:

  <button class={cn("<provided classes>", className)}>
    {@render children?.()}
  <button>
  

Avoid

• For basic component use you well rarely have to write complex Tailwind class expressions with values, examples:
  • Avoid: px-[13.5px], use: px-2 (standard design token value)
  • Avoid: shadow-[0_35px_35px_rgba(0,0,0,0.25)], use: shadow-xl (simple pre-defined value from the design system)

Hard Rules

Notations:

• Never use string interpolation to pass on classes, never: class="p-4 {className}" (instead: class={cn("p-4", className)}"). Reason: cn uses tailwind-merge to de-duplicate classes, so you don't end up e.g. with p-4 p2
• Never use Svelte's class:foo="value" syntax
• Avoid using the style
  • Exception: complex programmatic CSS transforms (or if instructed so); for simple ones prefer Tailwind
• Never hard-code specific color values like bg-slate-500. Always use semantic color roles like bg-background.
• Avoid using component-scoped stylesheeets (<style> element)
• Avoid manually set border, hover styles, or other low-level skill, unless your task requires deviating from the default stylig

Resources

• references/shadcn-svelte-component-index-llms.md