SvelteKit Agile Sizing Tool

Expert guidance for developing a real-time agile story point sizing tool for sprint planning. Built with SvelteKit 2.x, Svelte 5 (runes API), TypeScript, shadcn-svelte, and Tailwind CSS.

Project Context

This is a client-only planning poker application for agile teams. All data persists in localStorage with no backend. Supports anonymous/named voting, multiple point scales (Fibonacci, T-shirt, man-days, custom), and session/round management.

**Target Audience:** Agile teams, Scrum masters, Product owners

**Key Goal:** Privacy-respecting, fast sprint estimation tool

Technology Stack Requirements

Architecture Guidelines

Directory Structure

Core Architecture Principles

1. **Client-Only:** No server-side logic, all state in localStorage

2. **Privacy-First:** No external API calls, tracking, or analytics

3. **Session Management:** 8-character codes (exclude '0' and 'o')

4. **Roles:** Owner/host and participants with observer mode toggle

5. **Real-Time Simulation:** Event listeners and polling via `SessionClient`

Coding Standards

Svelte 5 Runes API

Always use Svelte 5 runes for reactive state:

```typescript

let count = $state(0);

let doubled = $state.derived(() => count * 2);

$effect(() => {

console.log(`Count changed to ${count}`);

});

```

Component Patterns

**Modals:**

**State Management:**

UI Standards

1. **Always use shadcn-svelte** for new UI components

2. **Tailwind CSS** for all styling

3. **Layout Standard:**

- Settings/exit buttons: top-right

- Session info: top-left

4. **Color Theme:**

- Primary: red, white, blue

- Buttons: gray

- Text: black

- Work area: white background

Session Code Rules

Voting Features

1. **Anonymous Mode:** No names required

2. **Man-Days Mode:** When `storyPointOptions = ['man_days']`, show numeric input

3. **Keyboard Shortcuts:** 0-8 for quick voting, ? for help

4. **Point Scales:** Fibonacci, T-shirt sizes, custom arrays

Development Workflow

Commands

```bash

npm run dev # Start dev server

npm run build # Production build

npm run preview # Preview production build

npm run test # Unit tests (Vitest)

npm run test:unit # Alias for unit tests

npm run test:e2e # E2E tests (Playwright)

npm run lint # Lint code

npm run format # Format code

npm run check # TypeScript/Svelte checks

```

Docker (Optional)

```bash

npm run docker:up # Start containers

npm run docker:down # Stop containers

```

Database Scripts (Admin/Dev)

```bash

npm run db:setup # Initialize database

npm run db:reset # Reset database

```

Key Features Implementation

Session Management

Voting System

Round Management

Data Persistence

Testing Requirements

Unit Tests (Vitest)

E2E Tests (Playwright)

Current Implementation Status

Completed Features

Known TODOs

Important Constraints

1. **No Server-Side Logic:** All features must work client-side

2. **No External Dependencies:** No external APIs or tracking services

3. **localStorage Only:** All persistence via browser storage

4. **Privacy Requirement:** Zero data collection or transmission

5. **Accessibility:** Keyboard navigation and screen reader support

6. **Responsive Design:** Must work on desktop, tablet, and mobile

When Working on This Project

1. **Always check** `src/lib/localStore.ts` for data persistence patterns

2. **Reference** `src/routes/session/[sessionCode]/+page.svelte` for main voting logic

3. **Use** shadcn-svelte components before creating custom UI

4. **Follow** the established color theme (red/white/blue, gray buttons, black text)

5. **Maintain** the top-right settings/exit and top-left session info layout

6. **Test** both anonymous and named voting modes

7. **Validate** session codes exclude '0' and 'o'

8. **Ensure** observer mode works correctly (no voting, view-only)

Example Code Patterns

Creating a Modal Component

```svelte

<script lang="ts">

let { isOpen, onClose, onSubmit } = $props();

let inputValue = $state('');

function handleSubmit() {

onSubmit(inputValue);

onClose();

}

</script>

{#if isOpen}

<Dialog.Root open={isOpen}>

<!-- Modal content -->

</Dialog.Root>

{/if}

```

Using localStorage Service

```typescript

import { localStore } from '$lib/localStore';

// Save session

localStore.saveSession(sessionCode, sessionData);

// Get session

const session = localStore.getSession(sessionCode);

// Get recent sessions

const recent = localStore.getRecentSessions();

```

Managing Participant State

```typescript

import { roundService } from '$lib/services/roundService';

// Add participant vote

roundService.addVote(sessionCode, roundId, participantId, vote);

// Reveal votes

roundService.revealVotes(sessionCode, roundId);

// Calculate consensus

const consensus = roundService.calculateConsensus(votes);

```

Success Criteria