marspanel — HTML 后台模板

SHA-256: 503e4ef809ca6be5ef27ae6ca62197c97c6c31ec3544b2bac9c34ec51c81c671

2026-10-15T13:27:04.315Z

# marspanel

[![ci](https://github.com/umars28/marspanel/actions/workflows/ci.yml/badge.svg)](https://github.com/umars28/marspanel/actions/workflows/ci.yml)
[![licence](https://img.shields.io/github/license/umars28/marspanel?color=6366f1)](LICENSE)
[![dependencies](https://img.shields.io/badge/dependencies-0-22d3ee)](package.json)
[![contrast](https://img.shields.io/badge/WCAG%20AA-54%2F54-4ade80)](docs/accessibility.md)
[![demo](https://img.shields.io/badge/demo-live-a78bfa)](https://umars28.github.io/marspanel/)

Admin template for infrastructure consoles. Plain HTML, CSS and JavaScript — no build step for
consumers, no framework, and not one network request at runtime.

**[Live demo →](https://umars28.github.io/marspanel/)**

The default theme is **Aurora**: dark-first, layered translucency over a soft radial wash, with a
cyan → indigo → violet identity.

```
38 pages · 342 classes · 141 icons and illustrations · 0 dependencies · 54/54 contrast pairs pass
```

## Why another admin template

Every widely used admin template draws the happy path. Dashboards are green, tables are full,
nothing is mid-flight and nothing is broken. But the screen an operator actually stares at is the
one where something has gone wrong.

marspanel ships the ugly states as first-class: a failed instance, a workload stuck provisioning, a
volume that has been detaching for an hour, a backup that died on bucket quota, a quota at 92 %, a
cluster that is no longer N+1. If a template cannot render those legibly, it cannot render the job.

## Install

Copy `dist/` into your project. Four files, and the order matters.

```html
<link rel="stylesheet" href="/dist/marspanel.min.css">
<script src="/dist/marspanel-theme.js"></script>   <!-- in <head>, synchronous -->

<body class="mpn-root">
  <script src="/dist/sprites.js"></script>
  <div class="mpn-app">…</div>
  <script src="/dist/marspanel.js"></script>
</body>
```

`marspanel-theme.js` belongs in the head because it resolves dark or light **before first paint** —
move it lower and you get a flash of the wrong theme. `starter/index.html` is this skeleton with a
working shell; copy it and start deleting.

Or `npm install marspanel`, then `import "marspanel/css"`. There is no JavaScript API to import; the
CSS classes and the `data-mpn-*` attributes are the interface.

## Documentation

| | |
|---|---|
| [Getting started](docs/getting-started.md) | install, layout, breakpoints, building from source |
| [Theming](docs/theming.md) | the three token layers and how to write another theme |
| [JavaScript](docs/javascript.md) | every `data-mpn-*` attribute |
| [RTL and print](docs/rtl-and-print.md) | logical properties, the paper stylesheet |
| [Contrast audit](docs/accessibility.md) | generated by the build, not asserted by hand |
| [ADR 0001](docs/adr/0001-visual-direction.md) | the nine visual directions Aurora was chosen against |
| [ADR 0002](docs/adr/0002-packaging-and-structure.md) | why `dist/` is committed and the build has no dependencies |
| [Security](SECURITY.md) | scope, reporting, and a CSP that works |

Live pages: open `index.html`, or `pages/index.html` for the full list.

## The rule that makes it a system

Three hues, three jobs. Brand colour never argues with status colour.

| Hue | Token | Role | Where |
|---|---|---|---|
| Cyan `#22D3EE` | `--mpn-focus` | *pointing* | focus ring, active tab underline |
| Indigo `#6366F1` | `--mpn-accent` | *acting* | primary button, link, anything clickable |
| Violet `#A78BFA` | `--mpn-pending` | *in flight* | provisioning, reconciling, draining |

A focus ring is never the accent colour. A primary button is never cyan.

## One status vocabulary

Six states, one class, read by every stateful component:

```html
<span class="mpn-pill mpn-is-ok">running</span>
<div class="mpn-banner mpn-is-warn">…</div>
<div class="mpn-log-line mpn-is-danger">…</div>
```

`mpn-is-warn` works identically on a pill, a banner, a timeline dot, a calendar event, a board card,
an info box, a log line, a topology node and a donut segment — because each reads `--mpn-state` and
`--mpn-state-tint` rather than hard-coding a colour. Map your own nouns onto the six: `running`,
`bound`, `granted`, `paid` and `shipped` are all `ok`.

## Tokens are three layers deep, and the order is enforced

```
tokens/primitive.css      --mpn-indigo-500: #6366F1
tokens/semantic.css       --mpn-accent: var(--mpn-indigo-500)
components/button.css     background: var(--mpn-accent)
```

**Components never reference primitives.** That single constraint is what makes an alternate theme a
block of variables instead of a hunt through twenty stylesheets, and `build/verify.mjs` fails the
build if it is broken.

## Component coverage

| Group | Classes |
|---|---|
| Actions | `mpn-btn` (primary, solid, ghost, danger, sm, lg, block, group), `mpn-icon-btn`, `mpn-avatar` |
| Status | `mpn-pill`, `mpn-dot`, `mpn-tag`, `mpn-chip`, `mpn-env` |
| Surfaces | `mpn-card` (+head, body, foot, quiet, state), `mpn-infobox`, `mpn-stat-*`, `mpn-meter`, `mpn-kv` |
| Feedback | `mpn-banner`, `mpn-toast`, `mpn-progress`, `mpn-spinner`, `mpn-dots`, `mpn-skeleton`, `mpn-empty` |
| Data | `mpn-table` (striped, bordered, compact, fixed, flat, quiet, stack), sort, filter, bulk select, `mpn-pagination` |
| Forms | input, select, textarea, checkbox, radio, switch, range, OTP, tags, addon, drop zone, choice grid, validation states, date picker, searchable select, colour picker |
| Navigation | sidebar nav with collapsible groups, `mpn-tabs`, `mpn-crumbs`, `mpn-stepper`, `mpn-accordion`, `mpn-tree` |
| Overlays | `mpn-modal`, `mpn-drawer`, `mpn-menu`, `mpn-popover`, `mpn-palette`, `mpn-tooltip` |
| Charts | area, line, spark, bars, donut, gauge, stacked bar, heat matrix, meter rows — all hand-drawn SVG |
| Content | `mpn-list`, `mpn-media`, `mpn-comment`, `mpn-file-row`, `mpn-feed`, `mpn-timeline` |
| Code | `mpn-code`, `mpn-term`, `mpn-log`, `mpn-diff` |
| Workspace | `mpn-cal`, `mpn-board`, `mpn-chat`, `mpn-topo`, `mpn-split` |

## Right-to-left and print

`dir="rtl"` on `<html>` is the whole switch. Every directional rule is a logical property, so
`base/rtl.css` only has to fix what has no logical form — transforms, inset shadows, asymmetric
radii, the select arrow. The verifier fails the build on any `margin-left` or `border-right` outside
that file.

`base/print.css` relights the theme for paper, drops chrome and overlays, repeats table headers on
every page and keeps rows from breaking mid-way. Test it on `pages/invoice.html`.

## Structure

```
src/css/      tokens/ base/ components/ · the stylesheets
src/js/       theme.js ui.js widgets.js
src/sprites/  icons.svg illustrations.svg
build/        six Node scripts, standard library only
dist/         what you copy: bundled css, js, sprites
pages/        38 demo pages
starter/      minimal copy-me page
docs/         guides and decision records
```

```
node build/index.mjs     # build everything
node build/serve.mjs     # http://localhost:8777
```

There is nothing to `npm install`. Keeping it that way is a design constraint, not an accident.

`build/verify.mjs` runs on every build and in CI. It fails on an undeclared token, a class used but
never defined, a missing icon symbol, a broken link, a page missing its theme script, or a physical
CSS property that would break RTL. Fix the cause, never the check.

## No webfonts, no icon font, no CDN

System font stack for prose; monospace for anything a machine produced or a human has to type —
identifiers, states, addresses, sizes, durations. Icons are an inline SVG sprite.

This is not minimalism for its own sake. A console that fetches nothing renders identically when it
is served from a single binary on an air-gapped node.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). The public API is the set of `mpn-*` classes, `--mpn-*`
tokens and `data-mpn-*` attributes; renaming any of them is a breaking change.

## License

[MIT](LICENSE)