svelte-ui-design

name	svelte-ui-design
description	Guides designing and building Svelte 5 UI components in the bootc extension. Covers @podman-desktop/ui-svelte components, Tailwind CSS, Svelte 5 runes, page layouts, tables, forms, and upstream component patterns. Triggers when creating or modifying Svelte components, building UI pages or forms, working with the component library, or asking about frontend design patterns.
paths	["packages/frontend/src/**/*.svelte","packages/frontend/src/**/*.ts","packages/frontend/src/**/*.css"]

Svelte UI Design Guide

Component Library Priority

Always use @podman-desktop/ui-svelte first. This library provides Podman Desktop's design system. Only create custom components when the library does not cover the use case.

• Source: https://github.com/podman-desktop/podman-desktop/tree/main/packages/ui
• Storybook: https://podman-desktop.io/storybook

<script lang="ts">
import { Button, Input, Table, FormPage, NavPage, EmptyScreen } from '@podman-desktop/ui-svelte';
</script>

Check API

Component APIs change across versions. Read the installed package directly:

1. List all exports: Read node_modules/@podman-desktop/ui-svelte/dist/index.d.ts
2. Check component props: Read the .d.ts file for any component, e.g. node_modules/@podman-desktop/ui-svelte/dist/button/Button.svelte.d.ts
3. Browse all component dirs: ls node_modules/@podman-desktop/ui-svelte/dist/
4. Check package exports: Read node_modules/@podman-desktop/ui-svelte/package.json for the full exports map (shows all importable paths)
5. See how we already use them: grep -r "from '@podman-desktop/ui-svelte'" packages/frontend/src/

Always verify props against the actual .d.ts files before using a component.

Svelte 5 Runes (Required)

This project uses Svelte 5 runes. Never use legacy Svelte 4 reactive syntax.

<script lang="ts">
// Correct: Svelte 5 runes
let items = $state<MyItem[]>([]);
let loading = $state(true);
let filtered = $derived(items.filter(i => i.active));

$effect(() => {
  fetchItems().then(result => {
    items = result;
    loading = false;
  });
});

// Wrong: Legacy Svelte 4
// $: filtered = items.filter(i => i.active);
// let items = writable([]);
</script>

Props Pattern

<script lang="ts">
// Svelte 5 props with defaults
let {
  title,
  items = [],
  onselect,
}: {
  title: string;
  items?: MyItem[];
  onselect?: (item: MyItem) => void;
} = $props();
</script>

Routing

Hash-based routing via tinro. Routes are defined in App.svelte.

<!-- App.svelte -->
<Route path="/my-feature" breadcrumb="My Feature">
  <MyFeature />
</Route>

<!-- Add navigation entry in Navigation.svelte -->
<SettingsNavItem title="My Feature" href="/my-feature" icon={faMyIcon} selected={meta.url.startsWith('/my-feature')} />

Navigate programmatically:

import { router } from 'tinro';
router.goto('/disk-images/build');

Navigation helpers are in packages/frontend/src/lib/navigation.ts.

RPC Reactive Stores

Auto-refreshing stores that subscribe to backend messages:

import { rpcReadable } from '/@/stores/rpcReadable';
import { bootcClient } from '/@/api/client';
import { Messages } from '/@shared/src/messages/Messages';

export const imageInfos = rpcReadable<ImageInfo[]>([], Messages.MSG_IMAGE_UPDATE, () => bootcClient.listBootcImages());

Use in components:

<script lang="ts">
import { imageInfos } from '/@/stores/imageInfo';
let images = $derived($imageInfos);
</script>

Tailwind CSS

Use Podman Desktop CSS variables (var(--pd-*)) for all theme-dependent styles. Font sizes are smaller than Tailwind defaults (text-base = 12px).

Common variables: --pd-content-card-bg, --pd-content-text, --pd-content-header, --pd-content-divider, --pd-button-primary-bg.

For the full Tailwind config (custom font sizes, content paths, theme overrides):

cat packages/frontend/tailwind.config.js

Grep existing components for CSS variable usage patterns:

grep -rn "var(--pd-" packages/frontend/src/ | head -30

Upstream Components

Local components in packages/frontend/src/lib/upstream/ provide patterns not covered by @podman-desktop/ui-svelte. Browse them to find available components:

ls packages/frontend/src/lib/upstream/

Checklist: Adding a New UI Page

1. Create the component in packages/frontend/src/ or src/lib/
2. Add route in App.svelte using <Route path="..." />
3. Add navigation entry in Navigation.svelte using <SettingsNavItem />
4. Use the appropriate layout: NavPage (list), FormPage (form), or DetailsPage (detail)
5. Use @podman-desktop/ui-svelte components for all standard UI elements
6. Connect to backend via bootcClient from /@/api/client
7. Add empty state with EmptyScreen or FilteredEmptyScreen
8. Run pnpm svelte:check to validate component types
9. Test with pnpm watch + Podman Desktop dev mode