edgerunner-terminal — Vite 后台模板

SHA-256: 758c62fd39c9c293fec1a6ea43711999f65dfa3328d83621cc3d970b08807135

2026-10-15T09:00:51.355Z

# Edgerunner Terminal

A data-dense **trading-portfolio dashboard template** with first-class loading, empty, and error states — built to be judged by its worst moment, not its populated screenshot.

[![License: MIT](https://img.shields.io/badge/License-MIT-111111.svg)](LICENSE)
[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/moyger/edgerunner-terminal)

![Edgerunner Terminal — overview, dark theme](docs/assets/overview-dark.png)

Vite + React 19 + TypeScript + Tailwind v4, on a token-strict design system. Mock data only, no backend — clone it and run it.

**Live demo: [edgerunner.karloestrada.com](https://edgerunner.karloestrada.com)** — or spin up your own in one click with the button above.

---

## Why this one is different

Most dashboard templates are sold on a screenshot where everything is populated and calm. That is the state a real dashboard is rarely in. This one treats **loading, empty, and error** as first-class: every async section on every screen renders through one gate (`QuerySection`) with four outcomes — skeleton, error + retry, empty + call to action, or content.

Every state is inspectable. A floating dev toolbar forces any data domain into any state live, and the states are addressable by URL:

| | |
|---|---|
| ![Error state](docs/assets/state-error.png) | ![Empty state](docs/assets/state-empty.png) |
| `?state=error&domain=positions` | `?state=empty&domain=all` |

## Features

- **Five screens** — Overview (KPIs, portfolio chart, allocation, positions), Markets, Orders, Billing, Settings.
- **Every state, everywhere** — loading skeletons, retryable errors, and empty states with CTAs, on every async block.
- **State simulator** — force any domain into any state from the dev toolbar or via URL params.
- **Dark + light themes** — one attribute flip; charts and SVGs retheme via CSS variables. Both palettes audited for WCAG AA contrast at build time.
- **Token-strict** — no raw hex, no off-grid spacing; colors and a strict 4px grid come from the design system.
- **Responsive** — sidebar collapses to a drawer, tables use column-priority + horizontal scroll, KPI grid reflows.
- **Typed mock data** — deterministic seeded generators with simulated latency and failure injection. No backend to stand up.

## Quick start

```bash
git clone https://github.com/moyger/edgerunner-terminal.git
cd edgerunner-terminal
pnpm install
pnpm dev          # http://localhost:5173
```

That's it. The design system is **vendored into `vendor/ui-next`**, so the repo is self-contained — no linked sibling packages, no extra setup.

```bash
pnpm build        # type-check + production build
pnpm typecheck
```

## Simulating states

The whole point of the template. Drive states three ways:

- **Dev toolbar** (bottom-right) — per-domain normal / empty / error, plus a latency dial (0–4s).
- **URL params** — `?state=error&domain=positions`, `?state=empty&domain=all`, `?latency=3000`.
- **TanStack Query** — every section is a real query; the toolbar invalidates and refetches live.

## Theming

Dark is the default (`:root`); light is a `data-theme="light"` override. Toggle in the topbar or in Settings → Appearance; preference persists with a FOUC guard. Charts bind to `var(--color-*)`, so they follow the theme too.

![Overview in the light theme](docs/assets/overview-light.png)

## The design system

This template is built on the **Edgerunner design system** ([repo](https://github.com/moyger/design-system-kit)), vendored into [`vendor/ui-next`](vendor/ui-next). Tokens come from a single source of truth (`design.md`) and are generated, not hand-edited. To re-sync the vendored copy from a local checkout of the kit:

```bash
pnpm sync:kit
```

Generic UI primitives (Table, Tabs, Dialog, Tooltip, Skeleton, EmptyState, Card, …) live in the kit. This repo holds only app-specific composites: the layout shell, charts, `StatCard`, and the `QuerySection` data-state wrapper.

## Project structure

```
src/
├── data/            # typed models, seeded generators, fake client, query hooks, sim config
├── components/
│   ├── layout/      # AppShell, Sidebar, Topbar, MobileNav
│   ├── data-state/  # QuerySection, ErrorState, skeletons
│   ├── charts/      # Recharts wrappers (token-bound)
│   └── dev-toolbar.tsx
├── features/        # overview, markets, orders, billing, settings
└── theme/           # theme provider + persistence
vendor/ui-next/      # vendored Edgerunner design system
```

## Stack

Vite 6 · React 19 · TypeScript (strict) · React Router 7 · TanStack Query 5 · Tailwind CSS v4 · Recharts 3 · lucide-react.

## Customize / reuse

See [`docs/REUSE.md`](docs/REUSE.md) — how to stand it up, point it at real holdings (your own positions or a live price API), and re-skin it for a different domain.

## The story

A short write-up on the thinking behind it lives in [`docs/article-the-states-are-the-product.md`](docs/article-the-states-are-the-product.md).

## License

[MIT](LICENSE) © Karlo Estrada. The data is mock; the portfolio persona ("Alex Rivera") is fictional.