Frontend

Frontend Skill

Use this skill when building or modifying frontend features in atopile. Default target is extension webviews (ui-server + vscode-atopile).

Quick Start

Dependency install:

cd src/ui-server
bun install

Frontend-only loop (no backend integration):

cd src/ui-server
bun run dev
bun run test
bun run build

Webview integration loop (backend + Vite):

cd src/ui-server
./dev.sh

Extension package/install loop:

ato dev compile && ato dev install cursor
# or
ato dev compile && ato dev install vscode

Command reference:

• bun install: install/sync JS dependencies.
• bun run dev: start local Vite dev server (frontend-only iteration).
• bun run test: run local Vitest suite once.
• bun run build: run local tsc && vite build.
• ./dev.sh: run backend + Vite for integration testing in browser.
• ato dev compile: build extension artifacts (default target all).
• ato dev install cursor|vscode: install latest built extension .vsix.
• ato dev ui: open a webpage for the user showing the shared component library components.

Relevant Files

Main Extension Webview App

• Root: src/ui-server/src/
• Transport: src/ui-server/src/api/
• Global state: src/ui-server/src/store/
• Feature hooks: src/ui-server/src/hooks/
• Feature components: src/ui-server/src/components/
• Shared components: src/ui-server/src/components/shared/
• Utilities: src/ui-server/src/utils/
• Styles/tokens: src/ui-server/src/styles/
• Contracts: src/ui-server/src/types/
• Tests: src/ui-server/src/__tests__/

Extension Host Bridge

• Root: src/vscode-atopile/src/
• Use for IDE commands/webview wiring/host integration.
• Keep core React UI logic out of this layer.

Specialized Standalone App Example

• Root: src/atopile/visualizer/web/src/
• Use as reference for compute/canvas/worker patterns.

Layout Editor (Specialized)

• Root: src/atopile/layout_server/frontend/src/
• Specialized layout editor frontend; not default architecture for webviews.

Dependants (Call Sites)

• Extension webviews are built from src/ui-server and loaded by src/vscode-atopile.
• ato dev compile and ato dev install are the common extension developer loop.
• src/atopile/visualizer/web is a separate app and reference pattern, not default target.

How to Work With / Develop / Test

Typical Change Paths

Use these patterns to keep changes scoped and predictable.

1. UI-only change (no contract changes)

• touch components/, styles/, small hooks/ usage
• avoid transport/store churn unless required
• validate through browser-first flow + focused component tests

2. UI + state change

• add/adjust store fields/actions/selectors
• keep transport untouched if payload shape is unchanged
• add store transition tests and UI interaction tests

3. UI + contract/transport change

• update Pydantic contracts first
• regenerate TS types
• update api/ mapping + store state transitions + UI
• add transport and state tests, then browser flow validation

Architecture Standard

Default architecture:

• Backend: FastAPI (domain, APIs, events)
• Frontend: React + Vite
• Realtime: WebSocket-first transport

Layer boundaries:

• api/: HTTP + WS transport and payload mapping
• store/: typed app state, actions, selectors
• components/: rendering/composition
• utils/lib: pure transforms/logic

Contract Standard (Required)

Schema-first contract workflow:

1. Define/modify backend Pydantic model.
2. Regenerate frontend TS schema/types.
3. Update frontend transport/store/components using generated types.
4. Add/update tests for changed contract behavior.

Do not:

• maintain duplicate handwritten interfaces if generated types exist
• use stringly-typed protocol payloads when typed contracts exist

One-Flow Rule (Required)

Implement one canonical user flow per feature.

Do not introduce fallback flow branches. If dependency/state is unavailable, surface a clear stop-state error in the same flow context.

WebSocket Standard

Use WebSocket for:

• interactive state sync
• action dispatch + action results
• long-running workflow updates

Use HTTP for:

• bootstrap reads
• direct idempotent reads
• file/artifact retrieval

Required WS client behavior:

• reconnect with bounded backoff
• explicit connected/disconnected state in store
• pending request timeout/cancel handling
• post-reconnect resync

Recommended WS client behavior:

• centralize WS connection in api/ module
• keep message decoding/type-guarding out of components
• record minimal telemetry/logging for reconnect and parse failures
• guard against stale async results when reconnecting

Example envelope shape:

type WsMessage =
  | { type: "state"; data: AppState }
  | { type: "event"; event: EventType; data: EventPayload }
  | {
      type: "action_result";
      action: string;
      requestId?: string;
      result: { success: boolean; error?: string };
    };

Reuse Rules

Before creating new primitives:

1. Check src/ui-server/src/components/shared/.
2. Check src/ui-server/src/utils/ for existing logic.
3. If adding compute/canvas behavior, check src/atopile/visualizer/web/src/lib/ and src/atopile/visualizer/web/src/workers/.
4. If behavior is IDE-host specific, keep it in src/vscode-atopile/src/.

Promote to shared when:

• used by 2+ feature surfaces, or
• repeated interaction semantics would drift if duplicated.

Shared Assets Reference

Shared Components (ui-server)

Prefer reusing the components in src/ui-server/src/components/shared/ before creating equivalents. If a new component is needed, create it in src/ui-server/src/components/shared/ and reuse it in the feature. If possible, compose complex components from existing shared components.

Shared Utilities (ui-server)

Prefer extending these utilities:

• src/ui-server/src/utils/codeHighlight.tsx
• src/ui-server/src/utils/nameValidation.ts
• src/ui-server/src/utils/packageUtils.ts
• src/ui-server/src/utils/searchUtils.ts

Specialized Utility Reference (visualizer)

Useful standalone reference:

• src/atopile/visualizer/web/src/lib/exportUtils.ts

Best Practices

Frontend Code Quality

• Keep strict TS and typed state transitions.
• Isolate side effects in transport/hooks, not leaf components.
• Use selectors, not broad full-store subscriptions.
• Implement explicit loading/error/empty states.

Example typed API boundary:

export async function fetchBuilds(
  projectRoot: string,
): Promise<BuildSummary[]> {
  const res = await fetch(
    `/api/builds?project_root=${encodeURIComponent(projectRoot)}`,
  );
  if (!res.ok) throw new APIError(res.status, "Failed to fetch builds");
  const data = (await res.json()) as { builds: BuildSummary[] };
  return data.builds;
}

Design System

Apply across all surfaces:

• host-native typography/colors first
• brand accents only where semantically useful
• complete interaction states (default/hover/focus-visible/active/disabled/loading)
• consistent spacing/row-height/typography rhythm
• tokenized colors/spacing/radius/z-index, no ad-hoc semantic hardcoding

Example tokenized control:

.btn-default {
  background: var(--accent);
  color: var(--text-on-accent);
  border: 1px solid var(--accent);
  border-radius: var(--radius-md);
  padding: 0 var(--spacing-md);
}
.btn-default:hover:not(:disabled) {
  background: var(--accent-hover);
  border-color: var(--accent-hover);
}
.btn-default:focus-visible {
  outline: 2px solid var(--info);
  outline-offset: 1px;
}
.btn:disabled {
  opacity: 0.5;
  cursor: not-allowed;
}

Accessibility Baseline

Required:

• keyboard-operable controls
• deterministic focus order
• ARIA only where native semantics are insufficient
• visible focus states
• readable contrast in light/dark modes