worklog-design

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:

---

Stack Constraints

SvelteKit 5 + Svelte Runes

• Components use $state, $derived, $effect — no writable() stores for new code.
• Layouts own scope: workspace scope in +layout.svelte, board scope in nested layouts.
• Use $page from $app/stores for route params; prefer typed params via RouteParams.
• Async data goes in +page.ts / +layout.ts load() functions, not inline onMount.
• Avoid onMount for 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 in src/lib/db/.
• Never call the repository directly from a component — always go through a hook in src/lib/hooks/.
• Tauri invoke for 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.html or root +layout.svelte: import 'carbon-components-svelte/css/g90.css'
  • For light mode support, dynamically swap to g10.
• Use optimizeImports from carbon-preprocess-svelte in svelte.config.js to 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 !important hacks.
• Common components to reach for first:

---

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 (240px default, resizable via CSS variable --worklog-sidebar-width).
• The title bar drag region must use -webkit-app-region: drag with 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 ease for hover/focus states.
• Panel slide-in: Ticket detail panel should slide in from the right at 200ms ease-out. Use Svelte's fly transition: transition:fly={{ x: 320, duration: 200 }}.
• Column drag-and-drop: Use dndzone from svelte-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 ToastNotification for 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" + onkeydown handler.
• Keyboard shortcut hints: show in TooltipDefinition with align="bottom", text like M — 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

---

Do / Don't