frontend-shadcn-svelte - SKILL.md Agent Skill

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

Use shadcn-svelte exclusively for UI primitives. Do not reach for raw HTML elements when a shadcn-svelte component exists for the job.
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.
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).
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

Check which shadcn-svelte components are available before writing any markup — consult the list below or the MCP tools.
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
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:

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.
Confirm Playwright is reachable: npx --no-install playwright --version. Find the cached module path with find ~/.npm/_npx -path '*playwright/index.js'.

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();

boundingBox() returns {x, y, width, height} — ideal for asserting alignment/equal heights. Screenshot to /tmp/*.png and read it back to eyeball the result.
Use a width >= 768 viewport to hit the md: breakpoint (the desktop search bar is hidden below it).
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