Worklog Design
Designworklog-designWorklog Design is an Agent Skill for design published in the regisx001/Worklog repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Design and UI skill for the Worklog desktop project manager. Stack: SvelteKit 5 (Svelte Runes), Tauri v2, carbon-components-svelte, TypeScript, Bun. Use whenever building, refactoring, or extending Worklog's UI — new views, components, layouts, theming, or visual polish aligned with the Carbon Design System and the local-first desktop product philosophy.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/regisx001/Worklog/blob/HEAD/.github/skills/desgin/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/worklog-design, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Worklog Design Skill
Project Identity
Worklog is a local-first, keyboard-driven desktop project manager for small dev teams.
Core qualities that should always be felt in the UI:
| Quality | What it means in practice |
|---|---|
| Fast | Instant feedback. No loading skeletons for local SQLite data. Transitions ≤ 150 ms. |
| Keyboard-first | Every action reachable without a mouse. Shortcuts visible in tooltips. |
| Dense, not cluttered | Information-rich layout typical of desktop apps. Prefer compact Carbon sizing. |
| Local-first transparency | No cloud metaphors. Workspace = folder on disk. |
| Small team focus | No enterprise complexity. One workspace, one team, clear hierarchy. |
Stack Constraints
SvelteKit 5 + Svelte Runes
- Components use
$state,$derived,$effect— nowritable()stores for new code. - Layouts own scope: workspace scope in
+layout.svelte, board scope in nested layouts. - Use
$pagefrom$app/storesfor route params; prefer typed params viaRouteParams. - Async data goes in
+page.ts/+layout.tsload()functions, not inlineonMount. - Avoid
onMountfor data fetching; it causes flash-of-empty-content in Tauri webview.
Tauri v2
- All persistence calls go through Tauri SQL plugin (
@tauri-apps/plugin-sql) via the repository layer insrc/lib/db/. - Never call the repository directly from a component — always go through a hook in
src/lib/hooks/. - Tauri
invokefor custom Rust commands (e.g., Git sync, file system operations). - Window is frameless; the app shell owns the drag region and custom title bar area.
- No
localStorage,sessionStorage, or IndexedDB — SQLite is the source of truth. - File paths use Tauri path API (
appDataDir,join) — never hardcode OS paths.
carbon-components-svelte
- Theme: use Gray 90 (
g90) dark theme as the default — it matches the existing dark shell.- Import in
app.htmlor root+layout.svelte:import 'carbon-components-svelte/css/g90.css' - For light mode support, dynamically swap to
g10.
- Import in
- Use
optimizeImportsfromcarbon-preprocess-svelteinsvelte.config.jsto avoid slow dev builds. - Prefer Carbon's compact density tokens:
size="sm"on buttons/inputs inside panels. - Do not fight Carbon's CSS custom properties — override with
--cds-*tokens, never with!importanthacks. - Common components to reach for first:
| Use case | Carbon component |
|---|---|
| Sidebar nav | SideNav, SideNavItems, SideNavLink, SideNavMenu |
| Command palette / search | Search + custom modal overlay |
| Ticket cards | Tile, ClickableTile |
| Modals / dialogs | Modal |
| Forms | TextInput, TextArea, Select, Toggle, Checkbox |
| Tags / labels | Tag |
| Data tables | DataTable, Toolbar, ToolbarSearch |
| Notifications | InlineNotification, ToastNotification |
| Buttons | Button, IconButton |
| Context menus | OverflowMenu, OverflowMenuItem |
| Tooltips | Tooltip, TooltipDefinition |
| Progress / loading | InlineLoading, SkeletonText |
Layout Architecture
AppShell (root +layout.svelte)
├── TitleBar ← custom drag region, app name, window controls
├── SideNav ← workspaces list + board tree
│ ├── WorkspaceHeader
│ ├── BoardTree ← per-board SideNavLink with right-click OverflowMenu
│ └── NavFooter ← settings link, sync status badge
└── MainContent ← <slot /> — swapped by nested routes
├── KanbanView ← /boards/[id]
├── TableView ← /boards/[id]/table
├── TimelineView ← /boards/[id]/timeline
└── SettingsView ← /settings/[tab]
Key layout rules:
- The sidebar is fixed-width (
240pxdefault, resizable via CSS variable--worklog-sidebar-width). - The title bar drag region must use
-webkit-app-region: dragwith interactive elements set to-webkit-app-region: no-drag. - Never use full-page loading states — local SQLite is fast; show stale data instantly, then update.
Design Tokens & Custom Properties
Override or extend Carbon tokens at :root in src/app.css:
:root {
/* Sidebar */
--worklog-sidebar-width: 240px;
--worklog-sidebar-bg: var(--cds-ui-background); /* matches g90 */
/* Kanban columns */
--worklog-column-width: 280px;
--worklog-column-gap: 12px;
/* Ticket card */
--worklog-card-radius: 2px; /* Carbon is square-ish */
--worklog-card-padding: 12px;
/* Status colors — extend Carbon's semantic palette */
--worklog-status-backlog: var(--cds-text-02);
--worklog-status-todo: var(--cds-interactive-01);
--worklog-status-in-progress: #f1c21b; /* Carbon yellow-30 */
--worklog-status-done: #42be65; /* Carbon green-40 */
/* Priority */
--worklog-priority-low: var(--cds-text-02);
--worklog-priority-medium: var(--cds-interactive-01);
--worklog-priority-high: #ff832b; /* Carbon orange-40 */
--worklog-priority-critical: var(--cds-support-error);
/* Typography — Carbon uses IBM Plex by default; Worklog inherits this */
--worklog-font-mono: 'IBM Plex Mono', monospace;
/* Zoom — controlled by app settings (50%–200%) */
--worklog-zoom: 1;
}
Apply zoom at the app shell level:
#app-shell {
zoom: var(--worklog-zoom); /* Tauri webview supports this */
}
Component Patterns
Kanban Board
<!-- KanbanBoard.svelte -->
<script lang="ts">
import { Tag, OverflowMenu, OverflowMenuItem } from 'carbon-components-svelte';
import type { Ticket } from '$lib/db/types';
let { columns }: { columns: KanbanColumn[] } = $props();
</script>
<div class="kanban-board">
{#each columns as col}
<div class="kanban-column">
<header class="col-header">
<span class="col-title">{col.label}</span>
<Tag size="sm">{col.tickets.length}</Tag>
</header>
<div class="col-body">
{#each col.tickets as ticket (ticket.id)}
<TicketCard {ticket} />
{/each}
</div>
</div>
{/each}
</div>
<style>
.kanban-board {
display: flex;
gap: var(--worklog-column-gap);
height: 100%;
overflow-x: auto;
padding: 16px;
}
.kanban-column {
flex: 0 0 var(--worklog-column-width);
display: flex;
flex-direction: column;
background: var(--cds-ui-01);
border: 1px solid var(--cds-ui-03);
}
.col-header {
display: flex;
align-items: center;
justify-content: space-between;
padding: 8px 12px;
border-bottom: 1px solid var(--cds-ui-03);
font-size: 0.75rem;
font-weight: 600;
text-transform: uppercase;
letter-spacing: 0.08em;
color: var(--cds-text-02);
}
.col-body {
flex: 1;
overflow-y: auto;
display: flex;
flex-direction: column;
gap: 4px;
padding: 8px;
}
</style>
Ticket Card
<!-- TicketCard.svelte -->
<script lang="ts">
import { Tag, OverflowMenu, OverflowMenuItem } from 'carbon-components-svelte';
import type { Ticket } from '$lib/db/types';
let { ticket, onSelect, onMove }: {
ticket: Ticket;
onSelect: (id: string) => void;
onMove: (id: string, direction: 'next' | 'prev') => void;
} = $props();
function handleKeydown(e: KeyboardEvent) {
if (e.key === 'm') onMove(ticket.id, 'next');
if (e.key === 'Escape') { /* close panel */ }
}
</script>
<div
class="ticket-card"
tabindex="0"
role="button"
aria-label="Ticket: {ticket.title}"
onclick={() => onSelect(ticket.id)}
onkeydown={handleKeydown}
>
<div class="ticket-header">
<span class="ticket-id">{ticket.id.slice(0, 8)}</span>
<OverflowMenu size="sm" flipped>
<OverflowMenuItem text="Move forward" on:click={() => onMove(ticket.id, 'next')} />
<OverflowMenuItem text="Move back" on:click={() => onMove(ticket.id, 'prev')} />
<OverflowMenuItem text="Delete" danger />
</OverflowMenu>
</div>
<p class="ticket-title">{ticket.title}</p>
<div class="ticket-meta">
{#if ticket.priority}
<Tag size="sm" type="outline"
style="--tag-color: var(--worklog-priority-{ticket.priority})">
{ticket.priority}
</Tag>
{/if}
{#if ticket.due_date}
<span class="ticket-date">{formatDate(ticket.due_date)}</span>
{/if}
</div>
</div>
<style>
.ticket-card {
background: var(--cds-ui-02);
border: 1px solid var(--cds-ui-03);
border-radius: var(--worklog-card-radius);
padding: var(--worklog-card-padding);
cursor: pointer;
transition: border-color 120ms ease, background 120ms ease;
}
.ticket-card:hover,
.ticket-card:focus-visible {
border-color: var(--cds-interactive-01);
outline: none;
background: var(--cds-hover-ui);
}
.ticket-header {
display: flex;
align-items: center;
justify-content: space-between;
margin-bottom: 6px;
}
.ticket-id {
font-family: var(--worklog-font-mono);
font-size: 0.6875rem;
color: var(--cds-text-03);
}
.ticket-title {
font-size: 0.875rem;
line-height: 1.4;
color: var(--cds-text-01);
margin: 0 0 8px;
}
.ticket-meta {
display: flex;
align-items: center;
gap: 6px;
flex-wrap: wrap;
}
.ticket-date {
font-size: 0.6875rem;
color: var(--cds-text-03);
font-family: var(--worklog-font-mono);
}
</style>
Command Palette
Worklog's command palette (Ctrl/Cmd+K) should use Carbon's Search inside a Modal:
<!-- CommandPalette.svelte -->
<script lang="ts">
import { Modal, Search } from 'carbon-components-svelte';
let open = $state(false);
let query = $state('');
</script>
<svelte:window onkeydown={(e) => {
if ((e.ctrlKey || e.metaKey) && e.key === 'k') {
e.preventDefault();
open = true;
}
}} />
<Modal bind:open size="sm" passiveModal modalHeading="" hasScrollingContent>
<Search bind:value={query} placeholder="Type a command…" autofocus size="lg" />
<!-- filtered results list -->
</Modal>
Interaction & Motion
Worklog is a productivity tool — motion must be functional, never decorative:
- Transitions:
transition: background 120ms ease, border-color 120ms easefor hover/focus states. - Panel slide-in: Ticket detail panel should slide in from the right at
200ms ease-out. Use Svelte'sflytransition:transition:fly={{ x: 320, duration: 200 }}. - Column drag-and-drop: Use
dndzonefromsvelte-dnd-action— it handles accessibility and keyboard DnD natively. - No skeleton loaders: Local SQLite data is synchronous-ish. Show last-known state immediately; update reactively.
- Toast notifications: Use
ToastNotificationfor Git sync events (success / failure). Position bottom-right, auto-dismiss after 4 s.
Accessibility (a11y)
Carbon handles most a11y out of the box. Worklog-specific requirements:
- Every interactive Svelte component that isn't a native button must have
role+tabindex="0"+onkeydownhandler. - Keyboard shortcut hints: show in
TooltipDefinitionwithalign="bottom", text likeM — move ticket. - Focus management: when ticket detail panel opens, move focus to the panel's close button; when it closes, return focus to the triggering card.
- Use
aria-live="polite"on the sync status badge in the sidebar.
File Conventions
| File | Purpose |
|---|---|
src/app.css | Global CSS, custom properties, Carbon theme import |
src/lib/components/app/ | Domain feature components (KanbanBoard, TicketCard, etc.) |
src/lib/components/ui/ | Generic reusable components that wrap or extend Carbon |
src/lib/hooks/ | Svelte 5 Runes hooks — data fetching, mutations, reactive state |
src/lib/db/ | Repository layer — only place that calls @tauri-apps/plugin-sql |
src/routes/ | SvelteKit routes; layouts own scope |
Do / Don't
| ✅ Do | ❌ Don't |
|---|---|
Use Carbon tokens (--cds-*) for all colors | Use raw hex colors inside components |
| Put data access in hooks, not components | Call db.* directly from a .svelte file |
Use $state / $derived (Svelte 5 Runes) | Use writable() / readable() stores |
| Reach for Carbon components first | Rebuild what Carbon already provides |
| Keep transitions ≤ 200 ms | Add decorative animations or loading spinners |
Use OverflowMenu for context actions | Build custom dropdown menus |
Apply size="sm" in dense panel areas | Use default (md) sizing everywhere — too tall |
| Test keyboard navigation on every new component | Ship mouse-only interactions |