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

Mode	Use for	Default structure	Do not use for
App Mode	Logged-in tools, settings, consoles, chat, mail, workbenches, operational flows	Persistent left navigation + task canvas	Public marketing, reading, commerce, or portfolio surfaces
Website Mode	Marketing sites, product launches, portfolios, editorial pages, catalogues, docs, public content	A page-specific macrostructure selected from the user journey	A generic hero + three cards + CTA template, or a fake app shell

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
2. 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 / 单页容量.
3. Lock dual-theme tokens — use references/tokens.md (light + dark are both required by default).
4. Compose from recipes — use references/components.md (nav item, card, list row, toggle, pill, empty/composer). Recipes are theme-agnostic; only variables change.
5. Implement with CSS variables + data-theme="light"|"dark"; add a theme toggle; Tailwind/shadcn mapping optional.
6. Self-check — run the checklist at the end of this file in both themes and at the target viewport before delivery.