Imported from mqtt-viewer/mqtt-viewer (frontend/AGENTS.md). Install upstream with npx skills add mqtt-viewer/mqtt-viewer --skill frontend. Copyright stays with the author.

Frontend / Component Library — Agent Guide

MQTT Viewer's frontend. Plain Svelte 5 (legacy syntax) + Vite + Tailwind 3, running inside a Wails desktop shell. This is also the code half of a design system that mirrors a Figma component library. Read this before touching src/components, src/views, or any .spec.json / .stories.svelte.

Full design: docs/design-system/STORYBOOK_SPEC.md. Workflow: docs/design-system/WORKFLOW.md.

Adding ANY new .svelte under src/components/ or src/views/? (yes, even mid-feature — this is not just for design-system tasks.) It MUST ship two colocated siblings or pnpm ds:validate fails CI (.github/workflows/design-system.yml):

1. pnpm ds:make-spec <Name> — scaffolds <Name>.spec.json.
2. Create <Name>.stories.svelte (copy a sibling; title = <Tier>/<path> exactly as ds:validate expects, tags: ["autodocs"], parameters.design).
3. pnpm ds:validate until green (it also regenerates component-index.json
   • COMPONENT_CHECKLIST.md — commit those too).

No hardcoded colors: use token utilities (bg-elevation-0, text-error), never hex like bg-[#0c0c0c] (rule 8 below).

Two CI steps, not one. ds:validate is the spec/story/token gate; pnpm test-storybook (also in the validate job) actually renders every story in vitest and fails on any unhandled error. So also:

• If the component imports a new Wails bound method, add it to .storybook/mocks/bindings/… (and any new event to mockEventSet in src/stories/fixtures.ts) — otherwise the story fails to import and the error cascades to every parent story that renders it.
• The component must not throw on mount with story props: stories render dialogs open (isOpen: writable(true)) with mockConnection. Beware top-level let x = reactiveVar.… — reactive $: assignments haven't run yet, so read from props directly and guard optional data.
• Run pnpm test-storybook AND pnpm ds:validate locally before pushing any branch that touches .svelte files (svelte-check + vite build are not enough — they don't render stories).

The design-system loop (why this library exists)

Figma library (design)  ──▶  Drift agent (/ds-figma-handover)  ──▶  handover doc
                                                                        │
                                                                        ▼
                              Implement agent (/ds-implement-handover) ──▶ code + spec + story

• Figma is authority for primitives (variants, tokens). Code follows.
• Code is authority for behavior/data wiring (views especially).
• The sync key is the PascalCase component name, identical in Figma and code.

Source of truth = colocated files (never a central registry)

Each component folder holds:

Button/
  Button.svelte          # component
  Button.stories.svelte  # Storybook story (visual layer)
  Button.spec.json       # design<->code contract (hand-authored TRUTH)

• src/design-system/component-index.json is generated from the .spec.json files. Never hand-edit it. Run pnpm ds:registry.
• src/design-system/ also holds the JSON Schemas, generated design-tokens.json, generated COMPONENT_CHECKLIST.md, and changes/ (handover docs). Only the prose plan lives in repo-root docs/design-system/.
• Validate everything with pnpm ds:validate (also regenerates the index + COMPONENT_CHECKLIST.md). This is the CI gate — keep it green.

Tiers (drive title namespace, diff strategy, layering rules)

Hard rules (validator enforces):

• No uphill dependencies. A primitive may not depend on a component/view.
• Raw tokens belong on primitives. Components/views consume primitives, not raw token names. (Warning if violated.)
• Tier wrong? Fix tier first — it changes how the sync engine diffs.

Authoring rules (so stories + sync work)

1. Props over fetching. A component must render from props alone in a story. No store reads / no bindings calls in the render path. Where a component currently reads a store or Wails, pass mock data in the story; if impossible without refactor, record it in spec.json.notes — don't fake it.
2. Wails is mocked in Storybook (.storybook/mocks/bindings/ and .storybook/mocks/wailsio-runtime.ts). Don't import real Go bindings into shared/presentational components.
3. Co-locate the story; title = <Tier>/<Name> (Primitives/Button).
4. tags: ['autodocs'] on every story meta (prop tables + smoke tests).
5. argTypes for every enum prop; options must match spec.json props[].options (which match the Figma variant values).
6. Figma link on every meta: parameters.design = { type: 'figma', url }. Use '' + // TODO(figma-url) until known.
7. Don't rewrite to runes. Components use Svelte 4 syntax (export let, on:click, $$Props) on Svelte 5 — leave it unless the task is a migration.
8. Tailwind tokens live in tailwind.config.js; the canonical list is src/design-system/design-tokens.json (generated by pnpm ds:tokens). Use token utilities (bg-primary, text-secondary-text), never hex.

.spec.json quick shape

Validated by src/design-system/component-spec.schema.json. Minimum: name, tier, status. When figma-linked: figma.url + figma.nodeId + props[]. tokens[] must all exist in design-tokens.json. Scaffold with make:spec <Name>.

Status lifecycle

todo → story-only → figma-linked → deprecated. Advance only when the requirements for the next state are real (validator checks).

Commands

Storybook MCP (agent read-access)

Agents read the rendered library (components, stories, props, screenshots, tests) via the framework-agnostic mcpland/storybook-mcp (STORYBOOK_URL=<storybook>/index.json). The official Storybook MCP is React-only in preview — don't use it here. The MCP needs Storybook served or built first (pnpm storybook, or pnpm build-storybook). It complements the specs (it knows rendered reality; the specs know Figma drift + the dep graph).

Writing copy (UI text, changelog, docs)

Anything a user reads (dialog copy, empty states, tooltips, the "What's new" changelog, README) follows docs/WRITING_STYLE.md: warm, first person, British spelling, concise, and no em dashes. The changelog lives in frontend/src/changelog.ts; use the /changelog skill to update it.

Skills

• /ds-add-component — scaffold or formalize a component (spec + story + tier).
• /ds-figma-handover — diff Figma library vs this code, emit a handover doc.
• /ds-implement-handover — apply a handover doc to code + specs + stories.
• /changelog — add to the "What's new" changelog, or promote it at release.