Frontend standards for atopile extension webviews: architecture, contracts, design system, and testing workflow.
name frontend description Frontend standards for atopile extension webviews: architecture, contracts, design system, and testing workflow. 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
/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
Performance Baseline
Required:
memoize expensive derived data/callbacks in hot paths
use
requestAnimationFrame
for drag/resize animation paths
move heavy layout/geometry/compute work to workers where needed
keep WS update handling efficient under active event streams
Operational checks:
avoid full-store subscriptions in high-frequency components
memoize derived collections used in render loops
verify no avoidable setState chains during drag/scroll/update streams
keep long-running transformations out of component render bodies
Implementation Playbooks
Playbook A: New Extension Webview Panel (
ui-server
)
Add/confirm contracts
if backend shape changes: update Pydantic + regenerate types
Add transport mapping
implement data/action methods in
src/ui-server/src/api/
Add store state/actions
add minimal new fields/actions in
store/
expose selectors for component use
Compose UI
build panel in
components/
reuse
components/shared/
primitives where possible
Validate
run tests
run browser-first flow
capture screenshot + inspect ui logs
Playbook B: Compute/Canvas-heavy Feature
Put core transforms into
utils/
or specialized
lib/
module.
Add worker offload if main-thread latency becomes visible.
Keep render components thin and memoized.
Validate interaction smoothness under active updates.
Playbook C: Long-running Workflow UI
Use one canonical flow:
trigger
in-progress
completion or error in same context
Required:
disable conflicting controls during in-progress state
emit progress updates via typed WS events
provide deterministic terminal state in store
Detailed Testing Notes
Testing Scope by Layer
Unit tests
pure utils/lib transforms
Store tests
action transitions and derived selector correctness
Transport tests
API/WS mapping, error handling, request correlation behavior
UI tests
user interaction + state rendering behavior
Browser automation checks
key flow interaction + screenshot + ui logs
WebSocket Feature Test Cases
At minimum test:
initial connect path
disconnect state update
reconnect and resync path
pending request timeout/cancel path
Recommended:
late or duplicate event tolerance
malformed message handling without UI crash
Testing Standard
Minimum per feature:
Store/action test
API/transport test
UI interaction test
Error/loading/empty-state test
Example matrix (build queue):
store: enqueue + complete transitions
API: build start error -> typed API error
UI: cancel click dispatches cancel action
state: disconnected WS state is visible
Browser-First Dev Viewer Flow (Required)
Agents should self-test in browser flow first:
cd
src/ui-server
./dev.sh
Then:
Validate interaction flow in browser webview page.
Capture key-state screenshots.
Inspect UI logs.
Fix issues.
Ask user to test in extension host only after browser flow is clean.
Relevant pages:
http://127.0.0.1:5173/
http://127.0.0.1:5173/log-viewer.html
http://127.0.0.1:5173/migrate.html
http://127.0.0.1:5173/test-explorer.html
Puppeteer + Vite Screenshot APIs
Use these built-in dev endpoints:
curl -sS -X POST http://127.0.0.1:5173/api/screenshot ./dev.sh
)[ ] Asked user to test in extension host only after browser checks passed