windmill/frontend/CLAUDE.md

Frontend Development (Svelte 5)

Core Principles

• Follow @svelte5-best-practices.mdc for detailed guidelines
• Use Runes ($state, $derived, $effect) for reactivity
• Keep components small and focused
• Always use keys in {#each} blocks

UI Guidelines

Styling Guidelines

• Use Tailwind CSS for all styling instead of custom CSS
• Use Windmill's theming classes for consistent colors and surfaces
• Avoid custom styles - prefer Tailwind utility classes
• Follow existing patterns - look at other components for reference

Windmill Theme Classes

Use these semantic color classes that automatically handle light/dark modes:

Backgrounds

• bg-surface - Main surface background
• bg-surface-secondary - Secondary/elevated surfaces
• bg-surface-hover - Hover states for interactive elements

Text Colors

• text-primary - Primary text color
• text-secondary - Secondary text (less prominent)
• text-tertiary - Tertiary text (subtle/muted)

Borders

• border-gray-200 dark:border-gray-700 - Standard borders that adapt to theme

Status Colors

Use standard Tailwind color classes with dark mode variants:

• Success: text-green-500, bg-green-100 dark:bg-green-900/30
• Error: text-red-500, bg-red-50 dark:bg-red-900/20
• Warning: text-yellow-500, bg-yellow-100 dark:bg-yellow-900/30
• Info: text-blue-500, bg-blue-100 dark:bg-blue-900/30

Typography

• font-mono - For code/technical content
• text-xs, text-sm, text-2xs - Standard text sizes
• Use font-medium, font-semibold for emphasis

Layout Guidelines

• Use Tailwind spacing utilities (p-3, m-2, gap-2, etc.)
• Use flexbox/grid utilities for layouts
• Use transition-colors for smooth hover effects
• Use overflow-hidden, rounded-md for consistent card styles

Backend API

• If you need to call the backend API, you can find the available routes in ../backend/windmill-api/openapi.yaml
• You can also use the associated types and services that are auto generated from the openapi file. They are in src/lib/gen/*gen.ts files

OpenAPI Autogeneration

Windmill automatically generates TypeScript types and services from the OpenAPI specification.

Service Generation Pattern

The autogeneration follows this pattern:

• Tag → Service Name: The OpenAPI tag becomes the service name with "Service" suffix
• operationId → Method Name: The operationId becomes the method name in the service

Example

Given this OpenAPI specification:

/w/{workspace}/audit/list:
  get:
    summary: list audit logs (requires admin privilege)
    operationId: listAuditLogs
    tags:
      - audit
    parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PerPage'
      - $ref: '#/components/parameters/Before'
      - $ref: '#/components/parameters/After'
      - $ref: '#/components/parameters/Username'
      - $ref: '#/components/parameters/Operation'
      - name: operations
        in: query
        description: comma separated list of exact operations to include
        schema:
          type: string

This generates:

• Service: AuditService (from tag "audit")
• Method: listAuditLogs (from operationId)

Method Arguments

The generated method arguments correspond to the OpenAPI parameters:

AuditService.listAuditLogs({
  workspace: string,           // from WorkspaceId parameter
  page?: number,              // from Page parameter
  perPage?: number,           // from PerPage parameter
  before?: string,            // from Before parameter
  after?: string,             // from After parameter
  username?: string,          // from Username parameter
  operation?: string,         // from Operation parameter
  operations?: string         // from operations parameter
})