yg2224/app-shell-ui/app-shell-ui

App Shell UI

You are implementing App Shell UI: a reusable frontend design skill with two modes. Choose the surface before choosing pixels. Do not turn every request into a desktop shell, and do not turn every app into a generic marketing page.

Choose the surface first

If the request has both surfaces, design them separately: Website Mode for acquisition or public information, App Mode for the signed-in product. Share brand tokens where appropriate, but do not force the same layout or density across both.

Pre-flight (both modes)

Before making visual decisions in an existing project, inspect the route and its nearest visual source of truth: current tokens, typography, theme mechanism, assets, framework, component primitives, and installed icon/motion libraries. Preserve an established system unless the user asks for a redesign. Check package.json before adding a dependency; do not assume a library exists or mix two unrelated design systems in one surface.

If the brief is genuinely ambiguous between two materially different outcomes, ask exactly one short question. Otherwise state the inference in one sentence and continue. Do not turn a small implementation request into a requirements interview.

App Mode Workflow

1. Pick a layout template (required before pixels):

• 设置型 — narrow left nav + form / toggle list
• 控制台型 — left nav + card grid / status list
• 工作台型 — session tree + centered empty state + composer card
• IM / 三栏型 — icon rail + list + detail

1. Set the viewport budget — define the target desktop viewport (minimum 1280×800) and the one primary task for the route before adding content. See references/layouts.md → Viewport budget / 单页容量.
2. Lock dual-theme tokens — use references/tokens.md (light + dark are both required by default).
3. Compose from recipes — use references/components.md (nav item, card, list row, toggle, pill, empty/composer). Recipes are theme-agnostic; only variables change.
4. Implement with CSS variables + data-theme="light"|"dark"; add a theme toggle; Tailwind/shadcn mapping optional.
5. Self-check — run the checklist at the end of this file in both themes and at the target viewport before delivery.

Default stack when free to choose:

Prefer a single self-contained HTML for demos unless the user wants project integration.

App Mode Architecture

L0  Window chrome (optional traffic lights / title bar / top tools + theme toggle)
L1  Sidebar or icon rail
L2  Content canvas (soft gray light / soft charcoal dark)
L3  Surfaces (raised cards, panels, lists)

Sidebar width: 220–260px (text nav) or 48–56px (icon rail). Content padding: 20–28px. Spacing on 4px grid.

Default page budget: the initial desktop state should complete its primary task in one viewport after the shell chrome is included. Keep a small bottom breathing room; do not make the whole page vertically scroll just to reveal routine secondary content. Long collections may use one bounded inner scroll region when the product genuinely needs it. 中文偏好：每个页面尽量一屏完成，内容达到首屏容量就停止继续堆叠。

App Mode Non-negotiables

1. Two themes: ship light and dark token sets unless the user explicitly wants only one.
2. One brand primary for: primary buttons, toggle ON, progress fill, selected border/bg, links. Dark primary may be a slightly brighter twin (e.g. #007AFF → #0A84FF).
3. Surface ladder (both themes): app bg → sidebar bg → raised surface (weak contrast). Light: soft gray + white cards. Dark: soft charcoal + elevated gray cards — not pure #000 page + pure #fff cards.
4. Text ladder: primary / secondary / tertiary (values differ per theme).
5. Hierarchy via 1px borders first; shadow optional and theme-specific.
6. Radius ladder: 8 / 12 / 16 / 999 (shared across themes).
7. Copy pattern: title + one muted subtitle line.
8. Motion: 150–200ms color/background only; no bounce theater.
9. Theme switch: data-theme on root + visible toggle; persist with localStorage when possible.
10. Icon restraint (content): right-hand content defaults to text + stroke icons + status pills. Emoji/illustration are optional accents only — never the default for every list row or card. Prefer zero emoji in dense lists; at most one decorative mark in a banner or empty state.
11. Equal-height peers: any side-by-side content pair (list + composer, panel + panel, stats siblings that form a pair of cards in one row) must share the same outer bottom edge. Use grid/flex stretch + column flex + flex: 1 on surfaces — never align-items: start that leaves one short card. See references/layouts.md → Equal-height side-by-side columns.
12. Single-viewport content budget: on desktop, the default route must not require page-level vertical scrolling. Fill the usable canvas with prioritized content, but stop before the first viewport is exceeded. If content does not fit, remove, shorten, paginate, disclose, tab, or split it into another route; never clip controls or shrink text below readability. On mobile, keep the primary action and status in the first viewport; natural scrolling is reserved for genuinely long content.

App Mode Do / Don't

App Mode Page Assembly Order

1. Shell (window + sidebar + main)
2. Brand block in sidebar
3. Nav groups + active item
4. Page header (H1 + muted subtitle + actions)
5. Theme toggle in titlebar or settings (required for demos)
6. Optional toolbar (search + segmented filter)
7. Content blocks by priority: banner → stats → primary grid/list → secondary two-column. Stop when the viewport budget is full; move lower-priority blocks to tabs, disclosure, pagination, or another route.
8. For every two-column peer row: apply equal-height recipe (stretch + flex surfaces) without forcing overflow.
9. Wire interaction: nav switch, selection, toggles, filters, theme toggle

App Mode Implementation Notes

• Put light tokens on :root, :root[data-theme="light"] and dark on :root[data-theme="dark"] (see references/tokens.md).
• Components only consume variables — no hard-coded brand/surface hex in component rules.
• Selected nav: soft primary wash + primary text, radius 8px (wash mix differs by theme).
• Cards: --bg-surface + 1px --border + radius 12; selected: primary ring/border. Leading mark = stroke icon in muted plate or no mark — not emoji by default.
• Settings / feed rows: 16–18px stroke icon (optional soft plate) + title + muted desc + right control. Avoid emoji list icons.
• Empty / new session: centered title + large rounded composer; chips + primary CTA. Empty watermark may be one faint stroke icon or a single subdued glyph — not a stack of emoji.
• Banner: text-first; optional one small accent tile max (often none).
• Dashed add zone for “empty collection + create” (plus sign, not emoji).
• Secondary buttons, segment tracks, toggle OFF tracks must use theme tokens (--secondary-btn-bg, --seg-track, --toggle-off) — light gray rgba does not work on dark.
• Keep the page shell fixed (min-height: 0; overflow: hidden) by default. If a list, log, table, or message history is inherently long, put scrolling on one bounded child region with a clear height budget; do not make the document body or whole content canvas the default scroll container.
• Validate the first-load state at a desktop viewport of at least 1280×800 (and a narrow mobile viewport). Check that the primary task, controls, and status are visible without page scrolling and that no text or control is clipped.

Theme API (canonical)

// data-theme = "light" | "dark"
// localStorage key: "app-shell-theme"
// toggle flips attribute; init reads storage then prefers-color-scheme

Minimal CSS token block

Copy the dual-theme block from references/tokens.md.

Minimal HTML skeleton

<html data-theme="light">
…
<div class="window">
  <header class="titlebar">
    …
    <button type="button" data-theme-toggle aria-label="切换深浅色">…</button>
  </header>
  <div class="shell">
    <aside class="sidebar">…</aside>
    <main class="main">…</main>
  </div>
</div>

App Mode Prompt Seed

Light

macOS desktop-utility light UI: 240px soft-gray sidebar (stroke icons + label, selected = light primary wash + 8px radius), main canvas soft gray with white rounded cards; single primary #007AFF for buttons, toggles, progress, selection ring; three text grays; radius 8–16px; almost no shadow, 1px light borders; settings/list rows with small stroke icons (not emoji) + title/desc + right toggle or status pill; content area text-first, minimal or no emoji; empty state = centered title + large rounded composer.

Dark

Same shell in dark mode: soft charcoal canvas #1C1C1E, sidebar #161617, raised cards #2C2C2E, borders white 8% alpha, text #F5F5F7 / #A1A1A6 / #6C6C70, primary #0A84FF, selected nav = primary 22% mix into card surface; no pure black page; no invert filter; include theme toggle.

Swap business nouns only; keep shell + dual-theme rules.

Website Mode Workflow

Website Mode is for public-facing web work. It may use normal document scrolling and should not inherit App Mode's fixed canvas, sidebar, artificial window chrome, or one-viewport content limit. Read references/web-frontend.md before implementing Website Mode.