Communitygithub.com

yg2224/app-shell-ui

以兩種明確分離的模式建構或重新設計前端:App 模式提供簡潔、克制的 macOS 風格桌面工具外殼(左側導航+內容區、柔和表面、浮凸卡片、單一品牌強調色、設定列表用語、淺色與深色主題),網站模式則適用於行銷頁面、落地頁、作品集、編輯/閱讀型頁面、型錄與文件等公開前端。

app-shell-ui 是什麼?

App Shell UI 是一項專門用於建構前端 UI 的 AI 技能,其核心理念是「先選擇表面模式,再決定像素細節」。它將設計場景明確劃分為 App 模式(適用於登入後工具、設定、控制台等內部操作流程)與網站模式(適用於行銷網站、作品集、文件等公開內容),並為每種模式提供詳細的工作流程、架構規範與元件組合指南。此技能支援 React 與純 HTML/CSS 等技術棧,預設使用 CSS 變數搭配 Tailwind/shadcn,強制要求同時實作淺色與深色主題,並強調內容優先、單一品牌色、等高的側邊欄卡片、以及單一視窗內完成主要任務的容量預算。其 150 行以上的 SKILL.md 文件是為 Claude Code 等 AI 代理設計的系統提示,開發者可直接引用以獲得一致、高品質、可重用的前端實作,避免常見的「英雄區+三卡片」模板或混合不同設計系統的錯誤。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add yg2224/app-shell-ui

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

App Shell UI

您正在實作 App Shell UI:一項可重複使用的前端設計技能,具有兩種模式。 先選擇表面模式,再決定像素細節。不要將每個請求都變成桌面外殼,也不要將每個應用程式都變成通用的行銷頁面。

先選擇表面模式

模式用途預設結構不適用於
App 模式已登入的工具、設定、控制台、聊天、郵件、工作台、操作流程固定左側導航 + 任務畫布公開行銷、閱讀、商務或作品集頁面
網站模式行銷網站、產品發表、作品集、編輯頁面、型錄、文件、公開內容根據使用者旅程選取的頁面特定巨觀結構通用的英雄區 + 三張卡片 + 行動呼籲模板,或偽造的應用程式外殼

如果請求包含兩種表面模式,請分別設計:網站模式用於獲取或公開資訊,App 模式用於已登入的產品。在適當時共享品牌代幣,但不要在兩種模式中強制使用相同的佈局或密度。

預飛(兩種模式)

在對現有專案進行視覺決策之前,請檢查路由及其最近的視覺真相來源:目前的代幣、排版、主題機制、資源、框架、元件原語以及已安裝的圖示/動畫庫。除非使用者要求重新設計,否則保留已建立的系統。在新增依賴項之前檢查 package.json;不要假設某個程式庫已存在,也不要在同一個表面上混合兩個不相關的設計系統。

如果需求摘要確實模糊,可能導致兩種實質上不同的結果,則僅問一個簡短的問題。否則用一句話說明推斷並繼續進行。不要將一個小小的實作請求變成需求訪談。

App 模式工作流程

  1. 選擇佈局模板(在像素之前必選):
    • 設定型 — 窄左側導航 + 表單/切換列表
    • 控制台型 — 左側導航 + 卡片網格/狀態列表
    • 工作台型 — 會話樹 + 居中空狀態 + 編輯器卡片
    • IM / 三欄型 — 圖示欄 + 列表 + 詳細
  2. 設定視窗容量預算 — 定義目標桌面視窗(最小 1280×800)以及在新增內容之前該路由的首要任務。請參閱 references/layouts.md → Viewport budget / 單頁容量。
  3. 鎖定雙主題代幣 — 使用 references/tokens.md(淺色 + 深色 預設兩者都必須實作)。
  4. 從配方組合 — 使用 references/components.md(導航項目、卡片、列表行、切換、藥丸、空狀態/編輯器)。配方與主題無關;只有變數會改變。
  5. 實作 — 使用 CSS 變數 + data-theme="light"|"dark";新增主題切換按鈕;Tailwind/shadcn 映射為選用。
  6. 自我檢查 — 在交付前,在兩種主題以及目標視窗下執行本檔案末尾的檢查清單。

可自由選擇時的預設技術棧:

層級預設
標記語義 HTML 或 React
樣式CSS 變數 + 輕量實用工具/Tailwind
元件shadcn / @coss 風格 (New York + 鋅色中性色)
圖示Lucide 風格 1.5–2px 描邊,僅限同一系列
主題淺色 + 深色 (切換按鈕 + 選用 OS prefers-color-scheme)

對於展示用範例,偏好單一自包含 HTML,除非使用者想要專案整合。

App 模式架構

L0  視窗裝飾(選用的交通燈/標題列/頂部工具 + 主題切換)
L1  側邊欄或圖示欄
L2  內容畫布(淺色:柔和灰色 / 深色:柔和炭色)
L3  表面(浮凸卡片、面板、列表)

側邊欄寬度:220–260px(文字導航)或 48–56px(圖示欄)。 內容內邊距:20–28px。間距基於 4px 網格。

預設頁面容量預算:桌面初始狀態應在包含外殼裝飾後,於一個視窗內完成其主要任務。保留少量底部呼吸空間;不要讓整個頁面垂直滾動僅僅是為了顯示例行的次要內容。長列表可以在產品真正需要時使用一個有邊界的內部滾動區域。 中文偏好:每個頁面盡量一屏完成,內容達到首屏容量就停止繼續堆疊。

App 模式不可妥協事項

  1. 兩個主題:除非使用者明確只想要一個,否則需提供淺色和深色代幣集。
  2. 一個品牌主色用於:主要按鈕、切換 ON、進度條填滿、選中邊框/背景、連結。深色主題的主要顏色可以是稍微明亮的雙胞胎(例如 #007AFF → #0A84FF)。
  3. 表面階層(兩個主題):應用程式背景 → 側邊欄背景 → 浮凸表面(弱對比)。淺色:柔和灰色 + 白色卡片。深色:柔和炭色 + 抬高灰色卡片 — 不是純 #000 頁面 + 純 #fff 卡片。
  4. 文字階層:主要 / 次要 / 第三級(每個主題的值不同)。
  5. 優先使用 1px 邊框建立層級;陰影為選用且因主題而異。
  6. 圓角階層:8 / 12 / 16 / 999(跨主題共享)。
  7. 複製模式:標題 + 一個柔和的副標題行。
  8. 動畫:150–200ms 僅限顏色/背景;無彈跳特效。
  9. 主題切換:根元素上的 data-theme + 可見的切換按鈕;盡可能使用 localStorage 持久化。
  10. 圖示克制(內容):右側內容預設為文字 + 描邊圖示 + 狀態藥丸。表情符號/插圖僅為選用的強調元素 — 絕不成為每個列表行或卡片的預設。在密集列表中偏好零個表情符號;在橫幅或空狀態中最多一個裝飾標記。
  11. 等高同伴:任何並排的內容配對(列表 + 編輯器、面板 + 面板、形成一排卡片配對的統計數據)必須共享相同的外部底邊緣。使用網格/彈性盒 stretch + 列彈性盒 + 表面上的 flex: 1 — 永遠不要使用 align-items: start 導致一張卡片變矮。請參閱 references/layouts.md → Equal-height side-by-side columns。
  12. 單一視窗內容容量預算:在桌面上,預設路由不得需要頁面級別的垂直滾動。用優先級內容填滿可用畫布,但在超過第一個視窗之前停止。如果內容無法容納,則移除、縮短、分頁、揭露、分頁或拆分到另一個路由;切勿裁剪控制項或將文字縮小到低於可讀性。在行動裝置上,將主要操作和狀態保持在第一個視窗內;自然滾動僅保留給真正長的內容。

App 模式 應做 / 不應做

應做不應做
左側導航 + 右側內容將全版英雄圖作為整個應用程式
兩種主題下的柔和畫布 + 浮凸卡片預設使用霓虹暗黑或純 OLED 黑色
單一強調色(配對淺色/深色)彩虹導航圖示作為多個主色
導航和內容中的描邊圖示(Lucide 風格)混合填滿 + 描邊圖示集
文字優先的卡片/列表;用藥丸表示狀態每一行/卡片/章節標頭都使用表情符號
用小藥丸 / 柔和文字表示狀態對正常狀態使用響亮的全寬警告橫幅
主題切換置於外殼裝飾中透過 filter: invert() 實作深色模式
透過代幣進行邊框分隔硬編碼的 #fff / #000 外殼顏色
寬鬆的間距密集的試算表排列
每個主要區域 ≤1 個表情符號強調(或無)橫幅 + 卡片 + 列表全都充滿表情符號
並排卡片等高(stretch)一個高一個矮的同級(align-items: start)
一螢幕路由,優先級區塊堆疊無限制的頁面滾動用於例行內容
為長集合使用有邊界的內部滾動使用固定高度隱藏或裁剪內容

App 模式頁面組裝順序

  1. 外殼(視窗 + 側邊欄 + 主要)
  2. 側邊欄中的品牌區塊
  3. 導航群組 + 活動項目
  4. 頁面標題(H1 + 柔和的副標題 + 操作)
  5. 標題列或設定中的主題切換(展示用範例必需)
  6. 選用工具列(搜尋 + 分段篩選器)
  7. 按優先級排列內容區塊:橫幅 → 統計 → 主要網格/列表 → 次要兩欄。當視窗容量已滿時停止;將低優先級區塊移至分頁、揭露、分頁或另一個路由。
  8. 對於每個兩欄同伴行:應用等高配方(stretch + 彈性表面),而不強制溢出。
  9. 新增互動:導航切換、選擇、切換、篩選器、主題切換

App 模式實作注意事項

  • 將淺色代幣放在 :root, :root[data-theme="light"] 上,深色代幣放在 :root[data-theme="dark"] 上(請參閱 references/tokens.md)。
  • 元件僅使用變數 — 不在元件規則中硬編碼品牌/表面十六進制色碼。
  • 選中的導航:柔和的強調色背景 + 強調色文字,圓角 8px(背景混合因主題而異)。
  • 卡片:--bg-surface + 1px --border + 圓角 12;選中:強調色邊框。前導標記 = 柔和底板中的描邊圖示或無標記 — 預設不使用表情符號。
  • 設定 / 動態消息行:16–18px 描邊圖示(選用柔和底板)+ 標題 + 柔和描述 + 右側控制項。避免使用表情符號列表圖示。
  • 空狀態 / 新會話:居中標題 + 大圓角編輯器;提示晶片 + 主要行動呼籲。空狀態浮水印最多可以是一個微弱的描邊圖示或一個單一的柔和字形 — 不要用一堆表情符號。
  • 橫幅:文字優先;最多一個小的強調色瓷磚(通常沒有)。
  • 用於「空集合 + 建立」的虛線新增區域(加號,不是表情符號)。
  • 次要按鈕、分段軌道、切換 OFF 軌道必須使用主題代幣(--secondary-btn-bg、--seg-track、--toggle-off) — 淺灰色 rgba 在深色上不起作用。
  • 預設情況下保持頁面外殼固定(min-height: 0; overflow: hidden)。如果列表、日誌、表格或訊息歷史本質上是長的,則將滾動放在一個有明確高度預算的邊界子區域上;不要讓文檔主體或整個內容畫布成為預設滾動容器。
  • 在至少 1280×800 的桌面視窗(和窄行動視窗)下驗證首次載入狀態。檢查主要任務、控制項和狀態是否無需頁面滾動即可看到,並且沒有文字或控制項被裁剪。

主題 API (標準)

// data-theme = "light" | "dark"
// localStorage key: "app-shell-theme"
// 切換按鈕翻轉屬性;初始化先讀取 storage 然後讀取 prefers-color-scheme

最小 CSS 代幣區塊

從 references/tokens.md 複製雙主題區塊。

最小 HTML 骨架

<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 模式提示種子

淺色

macOS 桌面工具淺色 UI:240px 柔和灰色側邊欄(描邊圖示 + 標籤,選中 = 淺色強調色背景 + 8px 圓角),主要畫布柔和灰色搭配白色圓角卡片;單一主色 #007AFF 用於按鈕、切換、進度條、選中環;三種文字灰色;圓角 8–16px;幾乎無陰影,1px 淺色邊框;設定/列表行帶有小描邊圖示(非表情符號)+ 標題/描述 + 右側切換或狀態藥丸;內容區域文字優先,最少或無表情符號;空狀態 = 居中標題 + 大圓角編輯器。

深色

相同外殼的深色模式:柔和炭色畫布 #1C1C1E,側邊欄 #161617,浮凸卡片 #2C2C2E,邊框白色 8% 透明度,文字 #F5F5F7 / #A1A1A6 / #6C6C70,主色 #0A84FF,選中導航 = 主色 22% 混入卡片表面;無純黑頁面;無反相濾鏡;包含主題切換。

僅交換業務名詞;保留外殼 + 雙主題規則。

網站模式工作流程

網站模式適用於面向公眾的網頁工作。它可以使用正常的文檔滾動,不應繼承 App 模式的固定畫布、側邊欄、人造視窗裝飾或單一視窗內容限制。在實作網站模式之前,請閱讀 references/web-frontend.md。

  1. 進行設計解讀 — 說明頁面類型、目標受眾、主要任務以及具體的基調。 "乾淨現代"不是一個方向。從需求摘要和現有品牌推斷;僅在兩個方向會產生實質上不同的作品時才問一個簡短的問題。
  2. 選擇表面模式 — 對於轉換頁面或發表使用說服模式,對於文件或編輯內容使用閱讀模式,對於作品集/畫廊/活動使用體驗模式,或對於瀏覽和購買使用型錄模式。已登入的產品保持在 App 模式。
  3. 在元件之前選擇巨觀結構 — 選擇適合任務的頁面形狀,例如產品揭示、證據主導的故事、編輯敘事、作品索引、型錄、閱讀指南或活動海報。不要預設為居中英雄 -> 三張等寬卡片 -> 行動呼籲。
  4. 承諾使用一個視覺系統 — 鎖定調色盤、類型角色、間距/圓角規則、圖片處理方式以及一個可見的區分點。重用現有品牌代幣;否則定義語義 CSS 變數並使用它們,而不是在每個區塊即興使用顏色或字體。
  5. 規劃事實和媒體 — 使用提供的資訊、真實螢幕截圖/產品狀態、授權資源或適合需求摘要的生成點陣圖視覺效果。不要編造客戶、指標、推薦、Logo、假儀表板、瀏覽器裝飾或看起來像真實的佔位數據。未知的聲明保持可見地標記為佔位符或被省略。
  6. 建立資訊旅程 — 使用語義地標和使下一個操作顯而易見的層級。讓區塊在其任務不同時有變化的構成;卡片用於重複的、有邊界的項目,而不是頁面部門的預設包裝器。
  7. 實作完整的行為 — 在相關時使用原生控制項和連結、可見焦點、載入、空、錯誤、停用和成功狀態。動畫必須解釋回饋或空間變化,使用 transform/opacity,尊重 prefers-reduced-motion,並且除非實際上瞬間完成,否則遠離高頻率流程。
  8. 檢查渲染輸出 — 驗證桌面和行動裝置螢幕截圖、真實內容極端情況、對比度、鍵盤導航、載入影像尺寸、溢出以及第一個視窗。英雄區的價值主張、主要操作和視覺焦點必須在 1280x800 下容納;其下方的頁面滾動對於網站來說是正常的。

網站模式不可妥協事項

  1. 除非使用者明確要求產品預覽或已登入應用程式路由,否則不要將公開網站包裝在 App 模式的外殼裝飾中。
  2. 為每個公開……

相關技能