frontend-shadcn-svelte

name	frontend-shadcn-svelte
description	Guidelines for frontend development in the Currents SvelteKit app — visual identity, component usage, and shadcn-svelte conventions.

Frontend development — Currents

App vibe

Currents is a visual discovery app (Pinterest alternative). The UI should feel:

• Clean and image-first — content (images, collections) is the hero. Chrome is minimal and stays out of the way.
• Calm, not flashy — no heavy gradients, no aggressive animations. Subtle transitions only.
• Neutral with purpose — use the shadcn-svelte neutral palette as the base; color accents are rare and intentional.

Styling rules

1. Use shadcn-svelte exclusively for UI primitives. Do not reach for raw HTML elements when a shadcn-svelte component exists for the job.
2. Style everything with CSS variables from the shadcn-svelte theme. Never hardcode colors, radii, or shadows — use hsl(var(--background)), hsl(var(--foreground)), hsl(var(--muted)), hsl(var(--primary)), etc. See the Theming docs for the full token list.
3. Tailwind utility classes are fine for layout and spacing. Use them freely for flex, grid, gap, p-*, m-*, w-*, h-*, etc. For color/appearance, always prefer CSS variables over Tailwind color classes (e.g. text-foreground not text-gray-900).
4. Dark mode is a first-class concern. All color choices must work in both light and dark mode — this is automatic if you use CSS variables.

Component conventions

• Add components with the CLI: npx shadcn-svelte@latest add <component>. Do not hand-roll what shadcn-svelte already provides.
• Components live in src/lib/components/ui/ (managed by the CLI). Do not edit them directly — override via CSS variables or wrapper components.
• For app-specific composed components, put them in src/lib/components/ alongside the ui/ folder.

Workflow when building UI

1. Check which shadcn-svelte components are available before writing any markup — consult the list below or the MCP tools.
2. Use the svelte MCP server to look up component APIs and Svelte patterns:
   • list-sections — browse the docs structure
   • get-documentation — fetch a specific doc page
   • svelte-autofixer — catch and fix Svelte 5 issues after writing a component
   • playground-link — share a repro if debugging
3. After finishing a component, run svelte-autofixer to confirm there are no rune/syntax issues.

Visual verification with Playwright

You can verify rendered UI (layout, alignment, sizing, screenshots) in a real browser. Playwright and a cached Chromium are already available on this machine via the npx cache — no npm install is needed, and do not add Playwright to package.json just for a check.

Workflow:

1. Start the dev server in the background: npm run dev (reads frontend/.env, serves on http://localhost:5173). The top bar / search UI renders even if the appview backend is down, so most chrome can be checked without the full stack.
2. Confirm Playwright is reachable: npx --no-install playwright --version. Find the cached module path with find ~/.npm/_npx -path '*playwright/index.js'.
3. Write a throwaway .mjs script in /tmp and import the cached module by absolute path (ESM ignores NODE_PATH, and the package isn't resolvable from the project):

   import pw from '/Users/<you>/.npm/_npx/<hash>/node_modules/playwright/index.js';
   const { chromium } = pw;
   const browser = await chromium.launch();
   const page = await browser.newPage({ viewport: { width: 1280, height: 800 } });
   await page.goto('http://localhost:5173/explore', { waitUntil: 'domcontentloaded' });
   // measure: const box = await page.locator('[data-slot=select-trigger]').first().boundingBox();
   // screenshot: await page.locator('header').first().screenshot({ path: '/tmp/out.png' });
   await browser.close();
   

4. boundingBox() returns {x, y, width, height} — ideal for asserting alignment/equal heights. Screenshot to /tmp/*.png and read it back to eyeball the result.
5. Use a width >= 768 viewport to hit the md: breakpoint (the desktop search bar is hidden below it).
6. Clean up: kill the dev server (pkill -f "vite dev") and remove the /tmp script + screenshots when done.

shadcn-svelte documentation links

Full docs are available as LLM-readable markdown. Reference these when implementing or debugging:

Core

• Theming — CSS variables reference
• CLI — adding components
• components.json — project config
• SvelteKit installation

Components

• Form & Input: Button, Button Group, Calendar, Checkbox, Combobox, Date Picker, Field, Formsnap, Input, Input Group, Input OTP, Label, Native Select, Radio Group, Select, Slider, Switch, Textarea
• Layout & Navigation: Accordion, Breadcrumb, Navigation Menu, Resizable, Scroll Area, Separator, Sidebar, Tabs
• Overlays & Dialogs: Alert Dialog, Command, Context Menu, Dialog, Drawer, Dropdown Menu, Hover Card, Menubar, Popover, Sheet, Tooltip
• Feedback & Status: Alert, Badge, Empty, Progress, Skeleton, Sonner, Spinner
• Display & Media: Aspect Ratio, Avatar, Card, Carousel, Chart, Data Table, Item, Kbd, Table, Typography
• Misc: Collapsible, Pagination, Range Calendar, Toggle, Toggle Group

Component docs follow the pattern https://shadcn-svelte.com/docs/components/<name>.md (kebab-case).

Migration & dark mode

• Svelte 5 migration
• Tailwind v4 migration
• Dark mode (Svelte)