원클릭으로 Manus에서 모든 스킬 실행

app-uiux-designer

스타2

포크0

업데이트2026년 1월 26일 10:57

Enterprise UI/UX design expert using Chain of Repository (CoR) architecture. SRS/SDD → 100% UI/UX + 100% Navigation. Platform: iOS HIG / Material Design 3 / WCAG. ⚠️ 本 Skill 僅負責 Phase 3: UI Flow 產生智慧預測已在 Phase 2 (app-requirements-skill) 完成

설치

Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.

Manus에서 실행

출처

jrjohn

jrjohn/arcana-skills

GitHub 저장소 열기 Creator 저장소 보기

다운로드

Manus에서 실행

UI/UX Designer Skill (Chain of Repository)

Core: SDD (含完整畫面清單) → 100% UI/UX 生成 → 100% Navigation 驗證 Architecture: Chain of Repository - 按需載入節點，減少 token 使用

與 app-requirements-skill 整合

┌─────────────────────────────────────────────────────────────────┐
│ Phase 1-2: 由 app-requirements-skill 負責                        │
├─────────────────────────────────────────────────────────────────┤
│ • SRS 撰寫                                                      │
│ • SDD 撰寫 + 智慧預測 + 畫面補充                                  │
│ • 確認完整畫面清單 (Appendix A)                                   │
└─────────────────────────────────────────────────────────────────┘
                              ↓
              ⚠️ 進入條件: SDD 完整 + 智慧預測完成
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ Phase 3: 由 app-uiux-designer.skill 負責 ← 本 Skill              │
├─────────────────────────────────────────────────────────────────┤
│ Step 1: UI Flow 框架初始化 (00-init)                             │
│ Step 2: 產出完整 UI Flow HTML (03-generation)                    │
│ Step 3: 導航驗證 (04-validation)                                 │
│ Step 4: UI Flow Diagram 產出 (05-diagram)                        │
│ Step 5: 產出截圖 (06-screenshot)                                 │
│ Step 6: 回補 SDD/SRS + 重新產生 DOCX (07-feedback) ⚠️            │
│ Step 7: 最終驗證 + 完成報告 (08-finalize)                         │
└─────────────────────────────────────────────────────────────────┘
                              ↓
                        ✅ UI Flow 完成

07-feedback 回補內容 (MANDATORY)

文件	回補內容
SDD	每個 SCR-* 區塊加入 UI 原型參考 (iPad/iPhone 截圖)、確認 `對應需求` 欄位
SRS	新增 Screen References 章節、Inferred Requirements、User Flows、加入 `SDD 追蹤` 欄位
DOCX	重新產生 SDD.docx 和 SRS.docx (含嵌入圖片)

IEC 62304 雙向追蹤 (MANDATORY)

⚠️ 強制要求：回補時必須建立 SRS ↔ SDD 雙向追蹤

方向	欄位	範例
SRS → SDD	`\| SDD 追蹤 \| SCR-xxx \|`	`SCR-AUTH-001-login, SCR-AUTH-002-register`
SDD → SRS	`\| 對應需求 \| REQ-xxx \|`	`REQ-AUTH-001, REQ-AUTH-002`

設計理念

目標是 100% 完成 UI/UX，不是部分實作！

驗證標準 (全部必須達成)

項目	要求
UI/UX 覆蓋率	100% - 所有 SDD 畫面都已生成
導航覆蓋率	100% - 所有可點擊元素都有有效導航
空按鈕	0 個 - 禁止 `onclick=""`
Alert 佔位符	0 個 - 禁止 `onclick="alert('...')"`

禁止項目

❌ onclick="" 或無 onclick
❌ onclick="alert('功能說明')"
❌ onclick="void(0)" 無效導航
❌ href="#" 懸空連結
❌ 部分畫面實作

🔒 Skill 檔案保護規則 (CRITICAL)

驗證失敗時，禁止修改驗證腳本來「通過」驗證！

強制規則

驗證腳本為唯讀 - ~/.claude/skills/ 目錄下的所有檔案未經用戶許可不得修改
驗證失敗時的正確做法：
- ✅ 修復專案中的 HTML 檔案以符合驗證標準
- ✅ 修復專案中的導航問題
- ❌ 禁止修改驗證腳本來接受無效的值（如 void(0)）
需要修改 Skill 檔案時 - 必須先取得用戶明確許可

違規範例

❌ 錯誤做法：驗證報告 void(0) 無效 → 修改 validate-navigation.js 接受 void(0)
✅ 正確做法：驗證報告 void(0) 無效 → 將 void(0) 改為 history.back() 或有效導航

例外情況

只有在以下情況下才能修改 Skill 檔案（必須取得用戶明確許可）：

修復驗證腳本的 bug（如漏檢 aria-hidden 裝飾性元素）
新增功能或改進驗證規則（必須先詢問用戶並獲得許可）
用戶明確要求修改

🚨 onclick 生成強制規則 (CRITICAL)

生成任何 <button> 標籤時，必須同時寫入 onclick 屬性！

生成時強制檢查流程

寫 <button> 標籤時：
1. 查 SDD Button Navigation → 有目標 → 使用指定目標
                           ↓ 無
2. 根據按鈕文字預測 → 可預測 → 使用預測目標
                   ↓ 無法預測
3. 使用合理預設 → 查看類 → 相關詳情頁
               → 操作類 → history.back() 或來源頁

常見按鈕文字預設目標

按鈕文字	預設目標
查看獎勵/成就	`../engage/SCR-ENGAGE-004-badges.html`
查看報表	`../progress/SCR-PROGRESS-001-overview.html`
開始學習	`../train/SCR-TRAIN-001-select-vocab.html`
儲存/保存/取消	`history.back()`
設定	`../setting/SCR-SETTING-001-main.html`

生成後自檢命令

# 每個畫面生成後立即執行
grep -n '<button' SCR-*.html | grep -v 'onclick='
# 若有輸出 → 必須立即修復！

詳細規則: 見 process/03-generation/README.md Step 3

Quick Start

檢查進入條件: 確認 SDD 已完成智慧預測
檢查狀態: 讀取 {PROJECT}/04-ui-flow/workspace/current-process.json
進入節點: 讀取對應的 [SKILL_DIR]/process/XX/README.md
執行步驟: 依照 README.md 執行
⚠️ 自動驗證: 每個節點完成前必須執行驗證 (見下方 Auto-Validation 規則)
更新狀態: 驗證通過後更新 workspace/current-process.json

⚠️ 重要: workspace/ 目錄位於專案的 04-ui-flow/ 下，不是 skill 目錄！

🚨🚨🚨 MANDATORY VALIDATION EXECUTION (BLOCKING) 🚨🚨🚨

⚠️ CRITICAL: Claude 必須實際執行以下驗證腳本，不能只閱讀文檔！

強制執行命令 (每次 phase 完成前必須執行)

# 🚨 在標記任何 phase 為 completed 之前，必須執行此命令！
node ~/.claude/skills/app-uiux-designer.skill/templates/ui-flow/post-generation-gate.js Z:/path/to/project/04-ui-flow

驗證清單 (必須全部通過)

檔案	驗證項目	執行命令
index.html	存在 + 模組完整 + 無未替換變數	`node post-generation-gate.js`
device-preview.html	存在 + 側邊欄畫面數正確	`node post-generation-gate.js`
ui-flow-diagram-ipad.html	存在 + 畫面數匹配	`node post-generation-gate.js`
ui-flow-diagram-iphone.html	存在 + 畫面數匹配	`node post-generation-gate.js`

禁止行為 (FORBIDDEN)

❌ 禁止：只用 grep 檢查而不執行 post-generation-gate.js
❌ 禁止：手動更新 current-process.json 而不執行驗證
❌ 禁止：標記 phase 為 completed 而沒有驗證輸出
❌ 禁止：跳過驗證步驟繼續下一個 phase

正確執行流程

完成 03-generation / 04-validation / 05-diagram 後：

1. 執行 post-generation-gate.js
   └── node ~/.claude/skills/app-uiux-designer.skill/templates/ui-flow/post-generation-gate.js {PROJECT}/04-ui-flow

2. 確認輸出顯示 "✅ PASSED"
   └── 若顯示 "❌ FAILED" → 必須修復問題再重新執行

3. 才能更新 current-process.json
   └── 將 phase 標記為 completed

4. 才能進入下一個 phase

Claude 自我檢查問題

在標記任何 phase 為 completed 之前，Claude 必須能回答：

✅ 我是否執行了 node post-generation-gate.js？
✅ 輸出是否顯示 "PASSED"？
✅ index.html 是否通過驗證？
✅ device-preview.html 是否通過驗證？
✅ ui-flow-diagram-ipad.html 是否通過驗證？
✅ ui-flow-diagram-iphone.html 是否通過驗證？

若任一答案為 "否"，禁止進入下一階段！

⚠️ Auto-Validation Rules (MANDATORY - 不可跳過)

Claude 必須在每個節點完成前自動執行驗證，無需用戶提醒！

驗證觸發時機

節點	何時驗證	驗證內容
00-init	模板複製完成後	模板完整性、變數替換
03-generation	畫面生成完成後	Template Compliance Gate
04-validation	修復完成後	導航 100% + 一致性
06-screenshot	截圖產生後	截圖檔案存在
07-feedback	回補完成後	UI 原型參考完整性 + Use Case 完整性

03-generation Template Compliance Gate (Critical)

在標記 03-generation 為 completed 前，必須通過以下所有驗證！

#!/bin/bash
# === Template Compliance Gate (自動執行) ===
cd {PROJECT}/04-ui-flow

ERRORS=0

echo "🔍 執行 Template Compliance Gate..."

# 1. index.html 完整性
echo ""
echo "📊 驗證 index.html 模板合規..."
grep -q 'flow-iframe' index.html || { echo "❌ 缺少 UI Flow Diagram iframe"; ERRORS=$((ERRORS+1)); }
grep -q 'switchDevice' index.html || { echo "❌ 缺少裝置切換功能"; ERRORS=$((ERRORS+1)); }
grep -q 'device-toggle-btn' index.html || { echo "❌ 缺少裝置切換按鈕"; ERRORS=$((ERRORS+1)); }
grep -q 'sidebar' index.html || { echo "❌ 缺少模組圖例側邊欄"; ERRORS=$((ERRORS+1)); }
grep -q '{{' index.html && { echo "❌ 有未替換變數"; ERRORS=$((ERRORS+1)); }
[ $ERRORS -eq 0 ] && echo "✅ index.html 基本合規"

# 2. index.html 雙版本 Diagram 切換檢核 (MANDATORY)
echo ""
echo "📱 驗證 index.html 引用 iPad/iPhone 雙版本 Diagram..."
grep -q 'ui-flow-diagram-ipad.html' index.html || { echo "❌ index.html 缺少 ui-flow-diagram-ipad.html 引用"; ERRORS=$((ERRORS+1)); }
grep -q 'ui-flow-diagram-iphone.html' index.html || { echo "❌ index.html 缺少 ui-flow-diagram-iphone.html 引用"; ERRORS=$((ERRORS+1)); }
# 確認 switchDevice 使用獨立檔案而非 query parameter
grep -q "ui-flow-diagram.html?device=" index.html && { echo "❌ index.html 使用舊版 query parameter 切換方式，應使用獨立檔案"; ERRORS=$((ERRORS+1)); }
[ $ERRORS -eq 0 ] && echo "✅ index.html 雙版本切換正確"

# 3. docs/ui-flow-diagram-ipad.html 存在與畫面同步
echo ""
echo "📱 驗證 ui-flow-diagram-ipad.html..."
IPAD_COUNT=$(find . -name "SCR-*.html" -not -path "./iphone/*" -not -path "./docs/*" | wc -l | tr -d ' ')
[ -f "docs/ui-flow-diagram-ipad.html" ] || { echo "❌ 缺少 docs/ui-flow-diagram-ipad.html"; ERRORS=$((ERRORS+1)); }
if [ -f "docs/ui-flow-diagram-ipad.html" ]; then
  IPAD_DIAGRAM_COUNT=$(grep -c 'onclick="openScreen\|screen-card' docs/ui-flow-diagram-ipad.html 2>/dev/null | head -1 || echo "0")
  # 使用 onclick 計數更準確
  IPAD_DIAGRAM_COUNT=$(grep -c 'onclick="openScreen' docs/ui-flow-diagram-ipad.html 2>/dev/null || echo "0")
  [ "$IPAD_DIAGRAM_COUNT" -eq "$IPAD_COUNT" ] && echo "✅ iPad Diagram 畫面數: $IPAD_DIAGRAM_COUNT" || { echo "❌ iPad Diagram ($IPAD_DIAGRAM_COUNT) ≠ 實際 ($IPAD_COUNT)"; ERRORS=$((ERRORS+1)); }
fi

# 4. docs/ui-flow-diagram-iphone.html 存在與畫面同步
echo ""
echo "📱 驗證 ui-flow-diagram-iphone.html..."
[ -f "docs/ui-flow-diagram-iphone.html" ] || { echo "❌ 缺少 docs/ui-flow-diagram-iphone.html"; ERRORS=$((ERRORS+1)); }
if [ -f "docs/ui-flow-diagram-iphone.html" ]; then
  IPHONE_DIAGRAM_COUNT=$(grep -c 'onclick="openScreen\|onclick="loadScreen' docs/ui-flow-diagram-iphone.html 2>/dev/null || echo "0")
  [ "$IPHONE_DIAGRAM_COUNT" -eq "$IPAD_COUNT" ] && echo "✅ iPhone Diagram 畫面數: $IPHONE_DIAGRAM_COUNT" || { echo "❌ iPhone Diagram ($IPHONE_DIAGRAM_COUNT) ≠ 實際 ($IPAD_COUNT)"; ERRORS=$((ERRORS+1)); }
fi

# 5. device-preview.html 側邊欄同步
echo ""
echo "📱 驗證 device-preview.html 側邊欄同步..."
SIDEBAR_COUNT=$(grep -c 'screen-item' device-preview.html 2>/dev/null || echo "0")
[ "$SIDEBAR_COUNT" -eq "$IPAD_COUNT" ] && echo "✅ device-preview 側邊欄: $SIDEBAR_COUNT" || { echo "❌ device-preview ($SIDEBAR_COUNT) ≠ 實際 ($IPAD_COUNT)"; ERRORS=$((ERRORS+1)); }

# 6. 執行 Post-Generation Gate (整合所有驗證)
echo ""
echo "🚨 執行 Post-Generation Gate..."
node ~/.claude/skills/app-uiux-designer.skill/templates/ui-flow/post-generation-gate.js || ERRORS=$((ERRORS+1))

# 結果
echo ""
echo "======================================"
if [ $ERRORS -eq 0 ]; then
  echo "✅ Template Compliance Gate PASSED"
  echo "可以標記 03-generation 為 completed"
else
  echo "❌ Template Compliance Gate FAILED ($ERRORS errors)"
  echo "禁止進入下一階段！請修復問題後重新驗證。"
  exit 1
fi

Claude 必須在產生 index.html / device-preview.html 後立即執行 post-generation-gate.js

驗證失敗處理

失敗項目	修復動作
缺少 UI Flow Diagram iframe	從 `templates/ui-flow/index.html` 複製區塊
缺少裝置切換功能	從模板複製 `switchDevice()` 函數
缺少模組圖例側邊欄	從模板複製 sidebar 區塊
index.html 缺少 iPad/iPhone 雙版本引用	確保 `switchDevice()` 使用 `ui-flow-diagram-ipad.html` 和 `ui-flow-diagram-iphone.html`
使用舊版 query parameter 切換	將 `ui-flow-diagram.html?device=X` 改為獨立檔案路徑
缺少 ui-flow-diagram-ipad.html	建立 iPad 版本 Diagram (橫向框架 200x140)
缺少 ui-flow-diagram-iphone.html	建立 iPhone 版本 Diagram (直向框架 120x260)
iPad/iPhone Diagram 畫面數不符	同步更新對應的 Diagram HTML
device-preview 側邊欄不符	同步更新 `device-preview.html`
一致性驗證失敗	依據錯誤訊息修復

🚨 iframe src Path Validation (BLOCKING - 強制驗證)

所有 iframe src 路徑必須指向實際存在的 HTML 檔案！

#!/bin/bash
# === iframe src Path Validation (BLOCKING) ===
cd {PROJECT}/04-ui-flow

ERRORS=0
echo "🔍 執行 iframe src 路徑完整性驗證..."

# 1. 取得實際畫面檔案清單
IPAD_COUNT=$(find . -name "SCR-*.html" -not -path "./iphone/*" -not -path "./docs/*" | wc -l | tr -d ' ')
IPHONE_COUNT=$(find ./iphone -name "SCR-*.html" 2>/dev/null | wc -l | tr -d ' ')
echo "📊 實際畫面: iPad=$IPAD_COUNT, iPhone=$IPHONE_COUNT"

# 2. 驗證 ui-flow-diagram-ipad.html 的 iframe src
echo ""
echo "📱 驗證 ui-flow-diagram-ipad.html iframe src..."
if [ -f "docs/ui-flow-diagram-ipad.html" ]; then
  IPAD_MISSING=0
  for src in $(grep -oE "src=\"\.\./[^\"]+\.html\"" docs/ui-flow-diagram-ipad.html | sed 's/src="\.\.\/\([^"]*\)"/\1/' | sort -u); do
    if [ ! -f "$src" ]; then
      echo "❌ 缺少檔案: $src"
      IPAD_MISSING=$((IPAD_MISSING+1))
    fi
  done
  [ $IPAD_MISSING -eq 0 ] && echo "✅ iPad Diagram: 全部路徑正確" || { echo "❌ iPad Diagram 缺少 $IPAD_MISSING 個檔案"; ERRORS=$((ERRORS+IPAD_MISSING)); }
fi

# 3. 驗證 ui-flow-diagram-iphone.html 的 iframe src
echo ""
echo "📱 驗證 ui-flow-diagram-iphone.html iframe src..."
if [ -f "docs/ui-flow-diagram-iphone.html" ]; then
  IPHONE_MISSING=0
  for src in $(grep -oE "src=\"\.\./[^\"]+\.html\"" docs/ui-flow-diagram-iphone.html | sed 's/src="\.\.\/\([^"]*\)"/\1/' | sort -u); do
    if [ ! -f "$src" ]; then
      echo "❌ 缺少檔案: $src"
      IPHONE_MISSING=$((IPHONE_MISSING+1))
    fi
  done
  [ $IPHONE_MISSING -eq 0 ] && echo "✅ iPhone Diagram: 全部路徑正確" || { echo "❌ iPhone Diagram 缺少 $IPHONE_MISSING 個檔案"; ERRORS=$((ERRORS+IPHONE_MISSING)); }
fi

# 4. 驗證 device-preview.html 的 loadScreen 路徑
echo ""
echo "📱 驗證 device-preview.html loadScreen 路徑..."
if [ -f "device-preview.html" ]; then
  PREVIEW_MISSING=0
  for src in $(grep -oE "loadScreen\('[^']+\.html'" device-preview.html | sed "s/loadScreen('//" | sed "s/'$//" | sort -u); do
    if [ ! -f "$src" ]; then
      echo "❌ 缺少檔案: $src"
      PREVIEW_MISSING=$((PREVIEW_MISSING+1))
    fi
  done
  [ $PREVIEW_MISSING -eq 0 ] && echo "✅ device-preview: 全部路徑正確" || { echo "❌ device-preview 缺少 $PREVIEW_MISSING 個檔案"; ERRORS=$((ERRORS+PREVIEW_MISSING)); }
fi

# 5. 驗證 loadScreen 數量與實際畫面數量一致
PREVIEW_COUNT=$(grep -oE "loadScreen\('[^']+\.html'" device-preview.html | sort -u | wc -l | tr -d ' ')
[ "$PREVIEW_COUNT" -eq "$IPAD_COUNT" ] && echo "✅ device-preview 畫面數: $PREVIEW_COUNT" || { echo "❌ device-preview ($PREVIEW_COUNT) ≠ 實際 ($IPAD_COUNT)"; ERRORS=$((ERRORS+1)); }

# 結果
echo ""
echo "======================================"
if [ $ERRORS -eq 0 ]; then
  echo "✅ iframe src Path Validation PASSED"
else
  echo "❌ iframe src Path Validation FAILED ($ERRORS errors)"
  echo "⚠️ 禁止進入下一階段！"
  echo "📋 修復方式:"
  echo "   1. 確認所有畫面已正確生成"
  echo "   2. 更新 Diagram 檔案使用正確的畫面路徑"
  echo "   3. 更新 device-preview.html 側邊欄"
  exit 1
fi

驗證時機

節點完成後	必須執行此驗證
03-generation	✅ 產生畫面後必須驗證
05-diagram	✅ 產生 Diagram 後必須驗證
06-screenshot 之前	✅ 截圖前必須驗證路徑正確

⚠️ Critical: 若驗證失敗，禁止進入下一節點！必須修復所有路徑問題。

自動驗證行為要求

Claude 必須主動執行：不需用戶提醒或詢問
驗證失敗時不能繼續：必須修復後重新驗證
記錄驗證結果：在 current-process.json 中記錄
每次 compaction 後恢復：重新執行驗證確認狀態

07-feedback UI 原型參考完整性驗證 (Critical)

在標記 07-feedback 為 completed 前，必須通過以下驗證！

#!/bin/bash
# === UI 原型參考完整性驗證 ===
cd {PROJECT}/02-design
SDD_FILE=$(ls SDD-*.md | head -1)

ERRORS=0
echo "🔍 執行 UI 原型參考完整性驗證..."

# 1. 統計 SDD 本文畫面數
SCREEN_COUNT=$(grep -c "^#### SCR-" "$SDD_FILE")

# 2. 統計有圖片參考的畫面數 (iPad)
IPAD_REF=$(grep -c "images/ipad/SCR-.*\.png" "$SDD_FILE")

# 3. 統計有圖片參考的畫面數 (iPhone)
IPHONE_REF=$(grep -c "images/iphone/SCR-.*\.png" "$SDD_FILE")

echo "📊 統計結果:"
echo "   SDD 畫面數: $SCREEN_COUNT"
echo "   iPad 圖片參考: $IPAD_REF"
echo "   iPhone 圖片參考: $IPHONE_REF"

# 4. 驗證一致性
[ "$SCREEN_COUNT" != "$IPAD_REF" ] && { echo "❌ iPad 圖片參考不足"; ERRORS=$((ERRORS+1)); }
[ "$SCREEN_COUNT" != "$IPHONE_REF" ] && { echo "❌ iPhone 圖片參考不足"; ERRORS=$((ERRORS+1)); }

# 5. 驗證圖片檔案存在
MISSING_IPAD=$(for f in $(grep -oE "images/ipad/SCR-[^)\"]+\.png" "$SDD_FILE" | sort -u); do [ ! -f "$f" ] && echo "$f"; done | wc -l)
MISSING_IPHONE=$(for f in $(grep -oE "images/iphone/SCR-[^)\"]+\.png" "$SDD_FILE" | sort -u); do [ ! -f "$f" ] && echo "$f"; done | wc -l)
[ "$MISSING_IPAD" -gt 0 ] && { echo "❌ 缺少 $MISSING_IPAD 個 iPad 圖片檔案"; ERRORS=$((ERRORS+1)); }
[ "$MISSING_IPHONE" -gt 0 ] && { echo "❌ 缺少 $MISSING_IPHONE 個 iPhone 圖片檔案"; ERRORS=$((ERRORS+1)); }

# 結果
echo ""
if [ $ERRORS -eq 0 ]; then
  echo "✅ UI 原型參考完整性驗證 PASSED"
else
  echo "❌ UI 原型參考完整性驗證 FAILED ($ERRORS errors)"
  exit 1
fi

驗證項目	預期結果
SDD 畫面數 = iPad 圖片參考數	100% 一致
SDD 畫面數 = iPhone 圖片參考數	100% 一致
所有參考的圖片檔案都存在	0 缺失

SDD Use Case 完整性驗證 (Critical)

在回補 SDD 時，必須同時驗證 Use Case 完整性！

#!/bin/bash
# === Use Case 完整性驗證 ===
cd {PROJECT}/02-design
SDD_FILE=$(ls SDD-*.md | head -1)

echo "🔍 執行 Use Case 完整性驗證..."

# 1. 統計 Use Case 總覽表中的 UC 數量
TABLE_UC=$(grep -E "^\| UC-" "$SDD_FILE" | grep -v "^| UC-ID" | wc -l | tr -d ' ')

# 2. 統計詳細描述章節中的 UC 數量
DETAIL_UC=$(grep -c "^#### UC-" "$SDD_FILE")

echo "📊 統計結果:"
echo "   總覽表 UC 數: $TABLE_UC"
echo "   詳細描述 UC 數: $DETAIL_UC"

# 3. 驗證一致性
if [ "$TABLE_UC" != "$DETAIL_UC" ]; then
  echo ""
  echo "❌ Use Case 數量不一致！"
  echo ""
  echo "📋 總覽表中的 UC:"
  grep -E "^\| UC-" "$SDD_FILE" | grep -v "^| UC-ID" | awk -F'|' '{print "   " $2}'
  echo ""
  echo "📋 詳細描述中的 UC:"
  grep "^#### UC-" "$SDD_FILE" | sed 's/^#### /   /'
  echo ""
  echo "⚠️ 請補充缺少的 Use Case 詳細描述！"
  exit 1
else
  echo "✅ Use Case 完整性驗證 PASSED ($TABLE_UC 個)"
fi

驗證項目	預期結果
總覽表 UC 數 = 詳細描述 UC 數	100% 一致
每個 UC 都有前置/後置條件	必備
每個 UC 都有主要流程	必備

ASCII Art 禁止驗證 (Critical)

回補文件前，必須確認無 ASCII Art！

#!/bin/bash
# ASCII Art 偵測驗證
cd {PROJECT}
echo "🔍 驗證是否有禁用的 ASCII Art..."

ERRORS=0
for FILE in 01-requirements/SRS-*.md 02-design/SDD-*.md; do
  if [ -f "$FILE" ]; then
    ASCII_BLOCKS=$(awk '/^```[^m]|^```$/{flag=1; next} /^```/{flag=0} flag && /[┌┐└┘│─├┤┬┴┼→←↑↓▶◀■□●○]/' "$FILE" | wc -l | tr -d ' ')
    if [ "$ASCII_BLOCKS" -gt 0 ]; then
      echo "❌ $FILE 含有 ASCII Art ($ASCII_BLOCKS 行)"
      ERRORS=$((ERRORS+1))
    fi
  fi
done

[ $ERRORS -eq 0 ] && echo "✅ 無 ASCII Art 違規" || { echo "⚠️ 請改用 Mermaid"; exit 1; }

Process Chain (完整版)

Step	Process	進入條件	退出條件
00	init	SDD 完整 + 智慧預測完成	模板已複製、變數已替換
03	generation	00 完成	100% 畫面 HTML 已產生
04	validation	03 完成	100% Navigation + 0 alert (BLOCKING)
05	diagram	04 完成	UI Flow Diagram (iPad/iPhone 雙版本)
06	screenshot	05 完成 + 路徑驗證通過	iPad/iPhone 截圖已產生 (見 Error Recovery)
07	feedback	06 完成	SDD/SRS 已回補 + DOCX 已重新產生 ⚠️
08	finalize	07 完成	追溯驗證通過 + 完成報告

⚠️ 注意: 01-discovery 和 02-planning 已由 app-requirements-skill 完成，本 Skill 跳過

🚨 Phase 完成前強制驗證 (BLOCKING - 每次都要執行)

Phase	完成後必須執行	預期結果
03-generation	`node post-generation-gate.js`	✅ PASSED
04-validation	`node post-generation-gate.js`	✅ PASSED
05-diagram	`node post-generation-gate.js`	✅ PASSED

# 🚨 每個 phase 完成後必須執行此命令
node ~/.claude/skills/app-uiux-designer.skill/templates/ui-flow/post-generation-gate.js {PROJECT}/04-ui-flow

# 若無法執行 Node.js，使用快速檢查
echo "=== Quick File Check ==="
ls -la {PROJECT}/04-ui-flow/index.html
ls -la {PROJECT}/04-ui-flow/device-preview.html
ls -la {PROJECT}/04-ui-flow/docs/ui-flow-diagram-ipad.html
ls -la {PROJECT}/04-ui-flow/docs/ui-flow-diagram-iphone.html

🚨 06-screenshot Error Recovery Logic (BLOCKING)

若截圖過程中發現畫面不存在，必須返回 03-generation 重新生成！

截圖前必須驗證

#!/bin/bash
# === 06-screenshot Pre-Validation (BLOCKING) ===
cd {PROJECT}/04-ui-flow

echo "🔍 截圖前驗證..."

# 1. 執行 iframe src Path Validation (見上方)
# 2. 若失敗，禁止進入 06-screenshot

# 3. 額外驗證：確認 Diagram 畫面數與實際一致
ACTUAL_COUNT=$(find . -name "SCR-*.html" -not -path "./iphone/*" -not -path "./docs/*" | wc -l | tr -d ' ')
DIAGRAM_IPAD_COUNT=$(grep -c 'onclick="openScreen' docs/ui-flow-diagram-ipad.html 2>/dev/null || echo "0")
DIAGRAM_IPHONE_COUNT=$(grep -c 'onclick="openScreen' docs/ui-flow-diagram-iphone.html 2>/dev/null || echo "0")

if [ "$ACTUAL_COUNT" != "$DIAGRAM_IPAD_COUNT" ] || [ "$ACTUAL_COUNT" != "$DIAGRAM_IPHONE_COUNT" ]; then
  echo "❌ 畫面數不一致！"
  echo "   實際畫面: $ACTUAL_COUNT"
  echo "   iPad Diagram: $DIAGRAM_IPAD_COUNT"
  echo "   iPhone Diagram: $DIAGRAM_IPHONE_COUNT"
  echo ""
  echo "⚠️ 必須返回 05-diagram 重新生成 Diagram！"
  exit 1
fi

echo "✅ 截圖前驗證通過，可以執行截圖"

截圖錯誤處理流程

06-screenshot 執行時：

1. Puppeteer 嘗試載入畫面
   ├── 成功 → 繼續截圖
   └── 失敗 (404/無法載入) → Error Recovery 流程

2. Error Recovery 流程：
   ├── 記錄缺少的畫面 ID 到 error-log.json
   ├── 統計錯誤數量
   └── 若有任何錯誤 → 返回 03-generation

3. 返回 03-generation：
   ├── 重設 current-process.json: current_process = "03-generation"
   ├── 重設 progress: 03-generation = "in_progress"
   ├── 讀取 error-log.json 找出缺少的畫面
   ├── 補充生成缺少的畫面
   └── 完成後重新走 04 → 05 → 06 流程

capture-screenshots.js Error Recovery 實作

// 在 capture-screenshots.js 中加入
async function captureScreen(page, screenPath, outputPath) {
  try {
    const response = await page.goto(`file://${screenPath}`, {
      waitUntil: 'networkidle0',
      timeout: 10000
    });

    if (!response || response.status() === 404) {
      throw new Error(`Screen not found: ${screenPath}`);
    }

    await page.screenshot({ path: outputPath });
    return { success: true, path: screenPath };
  } catch (error) {
    console.error(`❌ 截圖失敗: ${screenPath}`);
    return {
      success: false,
      path: screenPath,
      error: error.message,
      recovery: 'return-to-03-generation'
    };
  }
}

// 執行完畢後檢查
async function processResults(results) {
  const failures = results.filter(r => !r.success);

  if (failures.length > 0) {
    console.log('');
    console.log('🚨 截圖失敗統計:');
    console.log(`   失敗數量: ${failures.length}`);
    console.log(`   缺少畫面: ${failures.map(f => f.path).join(', ')}`);
    console.log('');
    console.log('⚠️ 必須返回 03-generation 補充缺少的畫面！');

    // 寫入 error-log.json
    const errorLog = {
      timestamp: new Date().toISOString(),
      phase: '06-screenshot',
      failures: failures,
      recovery_action: 'return-to-03-generation',
      missing_screens: failures.map(f => f.path.match(/SCR-[^/]+/)?.[0]).filter(Boolean)
    };

    fs.writeFileSync(
      path.join(process.cwd(), 'workspace/screenshot-error-log.json'),
      JSON.stringify(errorLog, null, 2)
    );

    // 更新 current-process.json
    const processFile = path.join(process.cwd(), 'workspace/current-process.json');
    const processData = JSON.parse(fs.readFileSync(processFile, 'utf8'));
    processData.current_process = '03-generation';
    processData.progress['03-generation'] = 'in_progress';
    processData.progress['04-validation'] = 'pending';
    processData.progress['05-diagram'] = 'pending';
    processData.progress['06-screenshot'] = 'pending';
    processData.context.last_action = `Screenshot failed: ${failures.length} screens missing`;
    fs.writeFileSync(processFile, JSON.stringify(processData, null, 2));

    process.exit(1);
  }

  console.log('✅ 所有截圖完成');
}

失敗原因與修復

失敗原因	修復方式
畫面檔案不存在	返回 03-generation 生成缺少的畫面
路徑錯誤 (typo)	修正 Diagram/device-preview 中的路徑
畫面 ID 不一致	確認 SDD 與實際生成的畫面 ID 一致
模組資料夾錯誤	確認模組名稱對應 (auth → AUTH)

07-feedback 回補步驟詳解

1. 更新 SDD 每個 SCR-* 區塊:
   ├── 加入 UI 原型參考 (不使用表格)
   ├── iPad 版本：![](images/ipad/SCR-*.png)
   └── iPhone 版本：![](images/iphone/SCR-*.png)

2. 更新 SRS:
   ├── 新增 Screen References 章節 (REQ → SCR 對照)
   ├── 新增 Inferred Requirements (從 UI Flow 推導)
   └── 更新 User Flows (Mermaid 流程圖)

3. 重新產生 DOCX:
   ├── node md-to-docx.js SDD-*.md → SDD.docx (含截圖)
   └── node md-to-docx.js SRS-*.md → SRS.docx

Node Loading Protocol

Claude 收到 skill 啟用時：
1. 讀取此 SKILL.md (本檔案)
2. 從 skill args 取得專案路徑 (PROJECT_PATH)
3. 驗證進入條件:
   - 檢查 SDD 是否存在
   - 檢查 screen-prediction.json 是否存在且 completion_status = "completed"
   - 若未完成 → 拒絕進入，提示先完成 Phase 2
4. 讀取 {PROJECT_PATH}/04-ui-flow/workspace/current-process.json
   - 若檔案不存在 → 從 00-init 開始
   - 若 current_process 存在 → 恢復到該節點
5. 讀取 [SKILL_DIR]/process/{current}/README.md
6. 執行節點步驟
7. 完成後執行 Node Transition Protocol (NTP) ⭐
8. 進入下一節點

⭐ 使用 NTP 轉換節點: node node-transition.js <from> <to> [project-path]

路徑說明：

[SKILL_DIR] = ~/.claude/skills/app-uiux-designer.skill/ (skill 本身)
{PROJECT_PATH} = 專案根目錄 (從 args 取得)
workspace 在專案: {PROJECT_PATH}/04-ui-flow/workspace/

進入條件驗證 (Critical)

在開始 UI Flow 生成前，必須驗證：

// 檢查 {PROJECT}/04-ui-flow/workspace/screen-prediction.json
{
  "completion_status": "completed",  // 必須為 completed
  "sdd_updated": true,               // 必須為 true
  "analysis": {
    "total_screens": 53              // 必須 > 0
  }
}

若驗證失敗，顯示訊息：

⚠️ 無法進入 UI Flow 階段
原因: 智慧預測尚未完成
請先完成 Phase 2 (app-requirements-skill):
- 執行智慧預測
- 補充所有預測畫面
- 確認 Appendix A 畫面清單

Workspace Management

檔案 (專案內)	說明
`04-ui-flow/workspace/current-process.json`	目前流程狀態
`04-ui-flow/workspace/screen-prediction.json`	智慧預測結果 (Phase 2 產生)
`04-ui-flow/workspace/phase-summary.md`	⭐ 最新 Phase Summary (NTP 產生)
`04-ui-flow/workspace/phase-history.md`	所有 Phase Summary 歷史
`04-ui-flow/workspace/validation-chain.json`	驗證歷史記錄
`04-ui-flow/workspace/state/`	Compaction 保存點

初始化 workspace

# 在專案的 04-ui-flow/ 下建立 workspace
mkdir -p {PROJECT}/04-ui-flow/workspace/{context,state}

Blocking Checkpoints

節點	阻斷條件
進入條件	智慧預測必須完成 (screen-prediction.json)
00-init	模板必須完整複製、變數必須替換
03-generation	100% 畫面已生成，無遺漏
04-validation	100% Navigation + 0 空按鈕 + 0 alert
05-diagram	iframe src Path Validation 必須通過 (見驗證章節)
06-screenshot	Pre-Validation 必須通過 + 若截圖失敗 → 返回 03-generation

Device Specifications

Device	Viewport	Body Style
iPad Pro 11"	1194 x 834	`width: 1194px; height: 834px;`
iPhone 15/16 Pro	393 x 852	`width: 393px; height: 852px;`

Key Scripts

腳本	位置	說明
init-project.sh	`process/00-init/templates/`	專案初始化
node-transition.js	`templates/ui-flow/`	⭐ 節點轉換 + Phase Summary (NTP)
exit-gate.js	`templates/ui-flow/`	統一驗證入口
quick-health-check.sh	`templates/ui-flow/`	Compaction 後快速檢查
post-generation-gate.js	`templates/ui-flow/`	🚨 產生後閘門 (BLOCKING - 自動執行所有驗證)
validate-navigation.js	`templates/ui-flow/`	導航驗證
validate-iframe-src.js	`templates/ui-flow/`	iframe src 路徑驗證
validate-consistency.js	`templates/ui-flow/`	一致性驗證
capture-screenshots.js	`templates/ui-flow/`	截圖生成 + Error Recovery
convert-to-iphone.sh	專案內 `scripts/`	iPad→iPhone 轉換

🚨 post-generation-gate.js (MANDATORY)

產生 index.html / device-preview.html / Diagram 後必須執行！

# 產生檔案後立即執行
node ~/.claude/skills/app-uiux-designer.skill/templates/ui-flow/post-generation-gate.js

# 或指定專案路徑
node ~/.claude/skills/app-uiux-designer.skill/templates/ui-flow/post-generation-gate.js /path/to/04-ui-flow

自動執行的驗證:

✅ 必要檔案存在檢查 (index.html, device-preview.html, Diagrams)
✅ validate-iframe-src.js - iPad/iPad mini/iPhone 路徑驗證
✅ validate-consistency.js - 一致性驗證
✅ validate-navigation.js - 導航驗證

驗證結果:

PASSED → 可以進入下一階段
FAILED → 禁止進入下一階段，自動重設 progress

自動行為:

更新 workspace/current-process.json 的 validation_passed 狀態
若失敗，自動將 03-generation / 05-diagram 重設為 in_progress
產生 workspace/validation-report.json 詳細報告

validate-iframe-src.js 使用方式

# 驗證當前目錄
node ~/.claude/skills/app-uiux-designer.skill/templates/ui-flow/validate-iframe-src.js

# 驗證指定專案
node ~/.claude/skills/app-uiux-designer.skill/templates/ui-flow/validate-iframe-src.js /path/to/project/04-ui-flow

驗證內容:

docs/ui-flow-diagram-ipad.html 的所有 iframe src
docs/ui-flow-diagram-iphone.html 的所有 iframe src
device-preview.html 的 loadScreen() / iframe src / data-iphone 路徑
畫面數量一致性 (實際檔案 = Diagram = device-preview)

Exit Code:

0 - 驗證通過
1 - 驗證失敗 (BLOCKING)

References (按需載入)

類別	檔案
文件標準	`~/.claude/skills/app-requirements-skill/references/iec62304-document-standards.md`
必要模組 HTML	`templates/common-modules/{auth,profile,setting,common}/`
平台	`references/platforms/{ios-hig,material-design,wcag}.md`
心理學	`references/psychology/{gestalt,cognitive,emotional}.md`
程式碼生成	`references/code-gen/{react,angular,swiftui,compose}.md`

必要模組 HTML 模板

在 00-init 階段，可從 templates/common-modules/ 複製必要模組模板：

模組	模板數量	說明
auth	3 個	login, register, forgot
profile	2 個	view, edit
setting	4 個	main, account, privacy, about
common	4 個	loading, empty, error, no-network

📁 模板包含 {{VARIABLE}} 佔位符，需根據專案設定替換

⚠️ 07-feedback 回補時必須遵循 iec62304-document-standards.md

Mermaid 圖表使用 flowchart TB (直式)

禁止 ASCII Art

SCR 區塊格式需包含 UI 原型表格

DOCX 轉換使用 md-to-docx.js

Commands

指令	動作
`進入節點 XX`	讀取 `process/XX/README.md`
`下一步`	執行 NTP 轉換到下一節點 ⭐
`保存狀態`	複製 current-process.json 到 state/
`恢復狀態`	執行 quick-health-check.sh + 讀取 phase-summary.md
`顯示進度`	讀取 current-process.json 的 progress
`健康檢查`	執行 quick-health-check.sh

Screen ID Format

類型	格式	範例
畫面	`SCR-{MODULE}-{NNN}-{name}`	SCR-AUTH-001-login
需求	`REQ-{MODULE}-{NNN}`	REQ-AUTH-001

Module Codes: AUTH, ONBOARD, HOME, VOCAB, TRAIN, REPORT, SETTING, PARENT, PROFILE, COMMON

輸出結果

完成 Phase 3 後，產生以下檔案供 Phase 4 使用：

📁 04-ui-flow/
├── 📁 ipad/
│   ├── SCR-AUTH-001-login.html
│   ├── SCR-AUTH-002-register.html
│   └── ... (所有畫面)
├── 📁 iphone/
│   └── ... (iPhone 版本)
├── 📁 screenshots/
│   ├── 📁 ipad/
│   │   └── *.png
│   └── 📁 iphone/
│       └── *.png
└── 📁 workspace/
    └── current-process.json (progress.06-screenshot = "completed")

Architecture Benefits

減少 Token 使用 - 只載入當前節點相關檔案
Compaction 恢復 - 狀態保存在 workspace/
清晰流程 - 每個節點有明確進入/退出條件
整合簡化 - 智慧預測在 Phase 2 完成，本 Skill 專注 UI Flow

🚨 Anti-Forgetting Protocol (CRITICAL)

防止 Claude 在 Compaction 或長對話中遺忘驗證步驟的機制

問題背景

Claude AI 有以下限制可能導致遺忘：

Context Window 限制 - 對話過長會觸發 compaction（壓縮）
Compaction 資訊損失 - 壓縮時 "how" 比 "what" 更容易遺失
注意力分散 - 長對話中後面的指令優先級可能降低
狀態不一致 - 記憶中的狀態與實際檔案狀態可能不同

核心原則

每個節點完成前：
1. 必須執行 exit-validation.sh
2. 必須更新 current-process.json 的 validation_state
3. 必須記錄到 validation-chain.json
4. 使用 NTP 轉換節點 (自動產生 phase-summary.md) ⭐

Compaction 後恢復：
1. 執行 quick-health-check.sh
2. 讀取 phase-summary.md 恢復上下文 ⭐ NTP
3. 讀取 validation-chain.json 確認已完成的驗證
4. 從最後一個有效狀態繼續

Enhanced current-process.json 結構

{
  "project_name": "WordPlay",
  "current_process": "04-validation",
  "last_updated": "2026-01-16T10:30:00Z",
  "progress": {
    "00-init": "completed",
    "03-generation": "completed",
    "04-validation": "in_progress",
    "05-diagram": "pending",
    "06-screenshot": "pending",
    "07-feedback": "pending",
    "08-finalize": "pending"
  },
  "validation_state": {
    "00-init": {
      "passed": true,
      "timestamp": "2026-01-16T09:00:00Z",
      "checks": ["templates_copied", "variables_replaced"]
    },
    "03-generation": {
      "passed": true,
      "timestamp": "2026-01-16T09:30:00Z",
      "checks": ["all_screens_generated", "onclick_coverage", "index_populated"]
    },
    "04-validation": {
      "passed": false,
      "timestamp": null,
      "pending_checks": ["navigation_100%", "zero_alerts", "consistency"]
    }
  },
  "recovery_hints": {
    "last_action": "Fixed onclick handlers in parent module",
    "pending_fixes": [],
    "files_modified": ["parent/SCR-PARENT-002.html", "parent/SCR-PARENT-003.html"]
  },
  "context": {
    "total_screens": 48,
    "modules": ["auth", "common", "dash", "parent", "profile", "progress", "setting", "train", "vocab"]
  }
}

validation-chain.json 結構

{
  "chain": [
    {
      "node": "00-init",
      "validation": "exit-validation",
      "result": "PASSED",
      "timestamp": "2026-01-16T09:00:00Z",
      "details": {
        "templates_copied": true,
        "variables_replaced": true
      }
    },
    {
      "node": "03-generation",
      "validation": "template-compliance-gate",
      "result": "PASSED",
      "timestamp": "2026-01-16T09:30:00Z",
      "details": {
        "ipad_screens": 48,
        "iphone_screens": 48,
        "onclick_coverage": "100%",
        "index_populated": true
      }
    }
  ],
  "last_valid_checkpoint": "03-generation"
}

Exit Validation Scripts

每個節點都需要一個 exit-validation.sh：

節點	驗證腳本	驗證內容
00-init	`process/00-init/exit-validation.sh`	模板完整、變數替換
03-generation	`process/03-generation/exit-validation.sh`	畫面 100%、onclick、index.html
04-validation	`process/04-validation/exit-validation.sh`	導航 100%、0 alert
05-diagram	`process/05-diagram/exit-validation.sh`	Diagram 完整、路徑正確
06-screenshot	`process/06-screenshot/exit-validation.sh`	截圖存在
07-feedback	`process/07-feedback/exit-validation.sh`	SDD/SRS 回補完整

Compaction Recovery Protocol

當 Claude 從 compaction 恢復時，必須立即執行：

# 1. 執行快速健康檢查
bash ~/.claude/skills/app-uiux-designer.skill/templates/ui-flow/quick-health-check.sh [project-path]

# 2. 讀取 Phase Summary 恢復上下文 ⭐ NTP
cat workspace/phase-summary.md

# 3. 檢查輸出並恢復狀態
node ~/.claude/skills/app-uiux-designer.skill/templates/ui-flow/recover-state.js [project-path]

quick-health-check.sh 內容

#!/bin/bash
# Quick Health Check - Compaction 後立即執行
cd "${1:-.}"

echo "🏥 Quick Health Check..."
echo ""

# 1. 確認 workspace 存在
[ -d "workspace" ] || { echo "❌ workspace/ 不存在"; exit 1; }

# 2. 讀取當前狀態
if [ -f "workspace/current-process.json" ]; then
  CURRENT=$(cat workspace/current-process.json | grep -o '"current_process": "[^"]*"' | cut -d'"' -f4)
  echo "📍 當前節點: $CURRENT"
else
  echo "⚠️ current-process.json 不存在"
  CURRENT="unknown"
fi

# 3. 快速計數
IPAD_COUNT=$(find . -name "SCR-*.html" -not -path "./iphone/*" -not -path "./docs/*" 2>/dev/null | wc -l | tr -d ' ')
IPHONE_COUNT=$(find ./iphone -name "SCR-*.html" 2>/dev/null | wc -l | tr -d ' ')
echo "📊 畫面數: iPad=$IPAD_COUNT, iPhone=$IPHONE_COUNT"

# 4. 檢查關鍵檔案
echo ""
echo "📁 關鍵檔案檢查:"
[ -f "index.html" ] && echo "  ✅ index.html" || echo "  ❌ index.html"
[ -f "device-preview.html" ] && echo "  ✅ device-preview.html" || echo "  ❌ device-preview.html"
[ -f "docs/ui-flow-diagram-ipad.html" ] && echo "  ✅ ui-flow-diagram-ipad.html" || echo "  ❌ ui-flow-diagram-ipad.html"
[ -f "docs/ui-flow-diagram-iphone.html" ] && echo "  ✅ ui-flow-diagram-iphone.html" || echo "  ❌ ui-flow-diagram-iphone.html"

# 5. 讀取 validation chain
echo ""
if [ -f "workspace/validation-chain.json" ]; then
  echo "📋 已完成的驗證:"
  cat workspace/validation-chain.json | grep -o '"node": "[^"]*"' | cut -d'"' -f4 | while read node; do
    echo "  ✅ $node"
  done
else
  echo "⚠️ validation-chain.json 不存在，需要重新驗證"
fi

echo ""
echo "🏥 Health Check 完成"
echo "📍 請從節點 '$CURRENT' 繼續"

強制執行規則

情境	必須執行
節點完成時	`exit-validation.sh` + 更新 `validation-chain.json`
Compaction 後恢復	`quick-health-check.sh` + `recover-state.js`
用戶詢問進度	讀取 `current-process.json` + `validation-chain.json`
開始新節點	確認前一節點的 validation_state.passed = true

Claude 行為要求

每次對話開始時：檢查是否需要執行 health check
完成任何修改後：更新 recovery_hints.last_action
完成節點前：必須執行 exit-validation 並記錄
發現不一致時：優先相信檔案狀態而非記憶

⭐ Node Transition Protocol (NTP)

節點轉換時自動產生 Phase Summary，支援 Context Compact

概念

NTP 確保在節點轉換時：

自動驗證當前節點完成
產生 Phase Summary 保存上下文
更新流程狀態
輸出下一節點指引

轉換流程

┌─────────────────────────────────────────────────────────────┐
│  1. Exit Validation    - 驗證當前節點完成                      │
│  2. Generate Summary   - 產生 Phase Summary                   │
│  3. Save to Workspace  - 保存到 phase-summary.md              │
│  4. Update State       - 更新 current-process.json            │
│  5. Output Prompt      - 輸出下一節點指引                       │
└─────────────────────────────────────────────────────────────┘

執行命令

# 節點轉換時使用
node ~/.claude/skills/app-uiux-designer.skill/templates/ui-flow/node-transition.js <from-node> <to-node> [project-path]

# 範例：從 03-generation 轉到 04-validation
node ~/.claude/skills/app-uiux-designer.skill/templates/ui-flow/node-transition.js 03-generation 04-validation /path/to/04-ui-flow

Phase Summary 保存位置

檔案	說明
`workspace/phase-summary.md`	當前 Phase Summary (最新)
`workspace/phase-history.md`	所有 Phase Summary 歷史

Compaction 後恢復流程

當 Claude 從 compaction 恢復時：

# 1. 快速健康檢查
bash ~/.claude/skills/app-uiux-designer.skill/templates/ui-flow/quick-health-check.sh [project-path]

# 2. 讀取 Phase Summary 恢復上下文
cat workspace/phase-summary.md

# 3. 讀取當前節點
cat workspace/current-process.json | jq '.current_process'

# 4. 繼續執行當前節點

NTP 與 AFP 整合

機制	功能	時機
NTP	產生 Phase Summary	節點轉換時
AFP	驗證歷史 + 狀態恢復	任何時候
Exit Gate	統一驗證入口	節點完成前
Quick Health Check	快速狀態確認	Compaction 後

節點完成流程 (使用 NTP)

完成當前節點工作
       ↓
執行 exit-gate.js 驗證
       ↓
   ┌───┴───┐
   ↓       ↓
 PASS    FAIL
   ↓       ↓
執行     修復問題
NTP      重新驗證
   ↓
自動產生 Phase Summary
自動更新 current-process.json
       ↓
讀取下一節點 README.md
       ↓
繼續執行

使用範例

# 03-generation 完成後，轉換到 04-validation
node ~/.claude/skills/app-uiux-designer.skill/templates/ui-flow/node-transition.js 03-generation 04-validation

# 輸出範例：
# ╔════════════════════════════════════════════════════════════╗
# ║           NODE TRANSITION PROTOCOL (NTP)                   ║
# ╚════════════════════════════════════════════════════════════╝
#
# ▶ Running exit validation for 03-generation...
# ✅ Saved to: workspace/phase-summary.md
# ✅ current-process.json updated
#
# CONTEXT COMPACT POINT
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# PHASE SUMMARY (Preserve this information)
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#
# ## Completed: 03-generation (HTML Generation)
# - iPad screens: 48
# - iPhone screens: 48
# - Modules: auth, common, dash, ...
#
# ## Next: 04-validation
# - Action: Validate 100% navigation coverage
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

name	app-uiux-designer
description	Enterprise UI/UX design expert using Chain of Repository (CoR) architecture. SRS/SDD → 100% UI/UX + 100% Navigation. Platform: iOS HIG / Material Design 3 / WCAG. ⚠️ 本 Skill 僅負責 Phase 3: UI Flow 產生智慧預測已在 Phase 2 (app-requirements-skill) 完成

UI/UX Designer Skill (Chain of Repository)

Core: SDD (含完整畫面清單) → 100% UI/UX 生成 → 100% Navigation 驗證 Architecture: Chain of Repository - 按需載入節點，減少 token 使用

與 app-requirements-skill 整合

┌─────────────────────────────────────────────────────────────────┐
│ Phase 1-2: 由 app-requirements-skill 負責                        │
├─────────────────────────────────────────────────────────────────┤
│ • SRS 撰寫                                                      │
│ • SDD 撰寫 + 智慧預測 + 畫面補充                                  │
│ • 確認完整畫面清單 (Appendix A)                                   │
└─────────────────────────────────────────────────────────────────┘
                              ↓
              ⚠️ 進入條件: SDD 完整 + 智慧預測完成
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ Phase 3: 由 app-uiux-designer.skill 負責 ← 本 Skill              │
├─────────────────────────────────────────────────────────────────┤
│ Step 1: UI Flow 框架初始化 (00-init)                             │
│ Step 2: 產出完整 UI Flow HTML (03-generation)                    │
│ Step 3: 導航驗證 (04-validation)                                 │
│ Step 4: UI Flow Diagram 產出 (05-diagram)                        │
│ Step 5: 產出截圖 (06-screenshot)                                 │
│ Step 6: 回補 SDD/SRS + 重新產生 DOCX (07-feedback) ⚠️            │
│ Step 7: 最終驗證 + 完成報告 (08-finalize)                         │
└─────────────────────────────────────────────────────────────────┘
                              ↓
                        ✅ UI Flow 完成

07-feedback 回補內容 (MANDATORY)

文件	回補內容
SDD	每個 SCR-* 區塊加入 UI 原型參考 (iPad/iPhone 截圖)、確認 `對應需求` 欄位
SRS	新增 Screen References 章節、Inferred Requirements、User Flows、加入 `SDD 追蹤` 欄位
DOCX	重新產生 SDD.docx 和 SRS.docx (含嵌入圖片)

IEC 62304 雙向追蹤 (MANDATORY)

⚠️ 強制要求：回補時必須建立 SRS ↔ SDD 雙向追蹤

方向	欄位	範例
SRS → SDD	`\| SDD 追蹤 \| SCR-xxx \|`	`SCR-AUTH-001-login, SCR-AUTH-002-register`
SDD → SRS	`\| 對應需求 \| REQ-xxx \|`	`REQ-AUTH-001, REQ-AUTH-002`

設計理念

目標是 100% 完成 UI/UX，不是部分實作！

驗證標準 (全部必須達成)

項目	要求
UI/UX 覆蓋率	100% - 所有 SDD 畫面都已生成
導航覆蓋率	100% - 所有可點擊元素都有有效導航
空按鈕	0 個 - 禁止 `onclick=""`
Alert 佔位符	0 個 - 禁止 `onclick="alert('...')"`

禁止項目

❌ onclick="" 或無 onclick
❌ onclick="alert('功能說明')"
❌ onclick="void(0)" 無效導航
❌ href="#" 懸空連結
❌ 部分畫面實作

🔒 Skill 檔案保護規則 (CRITICAL)

驗證失敗時，禁止修改驗證腳本來「通過」驗證！

強制規則

驗證腳本為唯讀 - ~/.claude/skills/ 目錄下的所有檔案未經用戶許可不得修改
驗證失敗時的正確做法：
- ✅ 修復專案中的 HTML 檔案以符合驗證標準
- ✅ 修復專案中的導航問題
- ❌ 禁止修改驗證腳本來接受無效的值（如 void(0)）
需要修改 Skill 檔案時 - 必須先取得用戶明確許可

違規範例

❌ 錯誤做法：驗證報告 void(0) 無效 → 修改 validate-navigation.js 接受 void(0)
✅ 正確做法：驗證報告 void(0) 無效 → 將 void(0) 改為 history.back() 或有效導航

例外情況

只有在以下情況下才能修改 Skill 檔案（必須取得用戶明確許可）：

修復驗證腳本的 bug（如漏檢 aria-hidden 裝飾性元素）
新增功能或改進驗證規則（必須先詢問用戶並獲得許可）
用戶明確要求修改

🚨 onclick 生成強制規則 (CRITICAL)

生成任何 <button> 標籤時，必須同時寫入 onclick 屬性！

生成時強制檢查流程

寫 <button> 標籤時：
1. 查 SDD Button Navigation → 有目標 → 使用指定目標
                           ↓ 無
2. 根據按鈕文字預測 → 可預測 → 使用預測目標
                   ↓ 無法預測
3. 使用合理預設 → 查看類 → 相關詳情頁
               → 操作類 → history.back() 或來源頁

常見按鈕文字預設目標

按鈕文字	預設目標
查看獎勵/成就	`../engage/SCR-ENGAGE-004-badges.html`
查看報表	`../progress/SCR-PROGRESS-001-overview.html`
開始學習	`../train/SCR-TRAIN-001-select-vocab.html`
儲存/保存/取消	`history.back()`
設定	`../setting/SCR-SETTING-001-main.html`

生成後自檢命令

# 每個畫面生成後立即執行
grep -n '<button' SCR-*.html | grep -v 'onclick='
# 若有輸出 → 必須立即修復！

詳細規則: 見 process/03-generation/README.md Step 3

Quick Start

檢查進入條件: 確認 SDD 已完成智慧預測
檢查狀態: 讀取 {PROJECT}/04-ui-flow/workspace/current-process.json
進入節點: 讀取對應的 [SKILL_DIR]/process/XX/README.md
執行步驟: 依照 README.md 執行
⚠️ 自動驗證: 每個節點完成前必須執行驗證 (見下方 Auto-Validation 規則)
更新狀態: 驗證通過後更新 workspace/current-process.json

⚠️ 重要: workspace/ 目錄位於專案的 04-ui-flow/ 下，不是 skill 目錄！

🚨🚨🚨 MANDATORY VALIDATION EXECUTION (BLOCKING) 🚨🚨🚨

⚠️ CRITICAL: Claude 必須實際執行以下驗證腳本，不能只閱讀文檔！

強制執行命令 (每次 phase 完成前必須執行)

# 🚨 在標記任何 phase 為 completed 之前，必須執行此命令！
node ~/.claude/skills/app-uiux-designer.skill/templates/ui-flow/post-generation-gate.js Z:/path/to/project/04-ui-flow

驗證清單 (必須全部通過)

檔案	驗證項目	執行命令
index.html	存在 + 模組完整 + 無未替換變數	`node post-generation-gate.js`
device-preview.html	存在 + 側邊欄畫面數正確	`node post-generation-gate.js`
ui-flow-diagram-ipad.html	存在 + 畫面數匹配	`node post-generation-gate.js`
ui-flow-diagram-iphone.html	存在 + 畫面數匹配	`node post-generation-gate.js`

禁止行為 (FORBIDDEN)

❌ 禁止：只用 grep 檢查而不執行 post-generation-gate.js
❌ 禁止：手動更新 current-process.json 而不執行驗證
❌ 禁止：標記 phase 為 completed 而沒有驗證輸出
❌ 禁止：跳過驗證步驟繼續下一個 phase

正確執行流程

完成 03-generation / 04-validation / 05-diagram 後：

1. 執行 post-generation-gate.js
   └── node ~/.claude/skills/app-uiux-designer.skill/templates/ui-flow/post-generation-gate.js {PROJECT}/04-ui-flow

2. 確認輸出顯示 "✅ PASSED"
   └── 若顯示 "❌ FAILED" → 必須修復問題再重新執行

3. 才能更新 current-process.json
   └── 將 phase 標記為 completed

4. 才能進入下一個 phase

Claude 自我檢查問題

在標記任何 phase 為 completed 之前，Claude 必須能回答：

✅ 我是否執行了 node post-generation-gate.js？
✅ 輸出是否顯示 "PASSED"？
✅ index.html 是否通過驗證？
✅ device-preview.html 是否通過驗證？
✅ ui-flow-diagram-ipad.html 是否通過驗證？
✅ ui-flow-diagram-iphone.html 是否通過驗證？

若任一答案為 "否"，禁止進入下一階段！

⚠️ Auto-Validation Rules (MANDATORY - 不可跳過)

Claude 必須在每個節點完成前自動執行驗證，無需用戶提醒！

驗證觸發時機

節點	何時驗證	驗證內容
00-init	模板複製完成後	模板完整性、變數替換
03-generation	畫面生成完成後	Template Compliance Gate
04-validation	修復完成後	導航 100% + 一致性
06-screenshot	截圖產生後	截圖檔案存在
07-feedback	回補完成後	UI 原型參考完整性 + Use Case 完整性

03-generation Template Compliance Gate (Critical)

在標記 03-generation 為 completed 前，必須通過以下所有驗證！

#!/bin/bash
# === Template Compliance Gate (自動執行) ===
cd {PROJECT}/04-ui-flow

ERRORS=0

echo "🔍 執行 Template Compliance Gate..."

# 1. index.html 完整性
echo ""
echo "📊 驗證 index.html 模板合規..."
grep -q 'flow-iframe' index.html || { echo "❌ 缺少 UI Flow Diagram iframe"; ERRORS=$((ERRORS+1)); }
grep -q 'switchDevice' index.html || { echo "❌ 缺少裝置切換功能"; ERRORS=$((ERRORS+1)); }
grep -q 'device-toggle-btn' index.html || { echo "❌ 缺少裝置切換按鈕"; ERRORS=$((ERRORS+1)); }
grep -q 'sidebar' index.html || { echo "❌ 缺少模組圖例側邊欄"; ERRORS=$((ERRORS+1)); }
grep -q '{{' index.html && { echo "❌ 有未替換變數"; ERRORS=$((ERRORS+1)); }
[ $ERRORS -eq 0 ] && echo "✅ index.html 基本合規"

# 2. index.html 雙版本 Diagram 切換檢核 (MANDATORY)
echo ""
echo "📱 驗證 index.html 引用 iPad/iPhone 雙版本 Diagram..."
grep -q 'ui-flow-diagram-ipad.html' index.html || { echo "❌ index.html 缺少 ui-flow-diagram-ipad.html 引用"; ERRORS=$((ERRORS+1)); }
grep -q 'ui-flow-diagram-iphone.html' index.html || { echo "❌ index.html 缺少 ui-flow-diagram-iphone.html 引用"; ERRORS=$((ERRORS+1)); }
# 確認 switchDevice 使用獨立檔案而非 query parameter
grep -q "ui-flow-diagram.html?device=" index.html && { echo "❌ index.html 使用舊版 query parameter 切換方式，應使用獨立檔案"; ERRORS=$((ERRORS+1)); }
[ $ERRORS -eq 0 ] && echo "✅ index.html 雙版本切換正確"

# 3. docs/ui-flow-diagram-ipad.html 存在與畫面同步
echo ""
echo "📱 驗證 ui-flow-diagram-ipad.html..."
IPAD_COUNT=$(find . -name "SCR-*.html" -not -path "./iphone/*" -not -path "./docs/*" | wc -l | tr -d ' ')
[ -f "docs/ui-flow-diagram-ipad.html" ] || { echo "❌ 缺少 docs/ui-flow-diagram-ipad.html"; ERRORS=$((ERRORS+1)); }
if [ -f "docs/ui-flow-diagram-ipad.html" ]; then
  IPAD_DIAGRAM_COUNT=$(grep -c 'onclick="openScreen\|screen-card' docs/ui-flow-diagram-ipad.html 2>/dev/null | head -1 || echo "0")
  # 使用 onclick 計數更準確
  IPAD_DIAGRAM_COUNT=$(grep -c 'onclick="openScreen' docs/ui-flow-diagram-ipad.html 2>/dev/null || echo "0")
  [ "$IPAD_DIAGRAM_COUNT" -eq "$IPAD_COUNT" ] && echo "✅ iPad Diagram 畫面數: $IPAD_DIAGRAM_COUNT" || { echo "❌ iPad Diagram ($IPAD_DIAGRAM_COUNT) ≠ 實際 ($IPAD_COUNT)"; ERRORS=$((ERRORS+1)); }
fi

# 4. docs/ui-flow-diagram-iphone.html 存在與畫面同步
echo ""
echo "📱 驗證 ui-flow-diagram-iphone.html..."
[ -f "docs/ui-flow-diagram-iphone.html" ] || { echo "❌ 缺少 docs/ui-flow-diagram-iphone.html"; ERRORS=$((ERRORS+1)); }
if [ -f "docs/ui-flow-diagram-iphone.html" ]; then
  IPHONE_DIAGRAM_COUNT=$(grep -c 'onclick="openScreen\|onclick="loadScreen' docs/ui-flow-diagram-iphone.html 2>/dev/null || echo "0")
  [ "$IPHONE_DIAGRAM_COUNT" -eq "$IPAD_COUNT" ] && echo "✅ iPhone Diagram 畫面數: $IPHONE_DIAGRAM_COUNT" || { echo "❌ iPhone Diagram ($IPHONE_DIAGRAM_COUNT) ≠ 實際 ($IPAD_COUNT)"; ERRORS=$((ERRORS+1)); }
fi

# 5. device-preview.html 側邊欄同步
echo ""
echo "📱 驗證 device-preview.html 側邊欄同步..."
SIDEBAR_COUNT=$(grep -c 'screen-item' device-preview.html 2>/dev/null || echo "0")
[ "$SIDEBAR_COUNT" -eq "$IPAD_COUNT" ] && echo "✅ device-preview 側邊欄: $SIDEBAR_COUNT" || { echo "❌ device-preview ($SIDEBAR_COUNT) ≠ 實際 ($IPAD_COUNT)"; ERRORS=$((ERRORS+1)); }

# 6. 執行 Post-Generation Gate (整合所有驗證)
echo ""
echo "🚨 執行 Post-Generation Gate..."
node ~/.claude/skills/app-uiux-designer.skill/templates/ui-flow/post-generation-gate.js || ERRORS=$((ERRORS+1))

# 結果
echo ""
echo "======================================"
if [ $ERRORS -eq 0 ]; then
  echo "✅ Template Compliance Gate PASSED"
  echo "可以標記 03-generation 為 completed"
else
  echo "❌ Template Compliance Gate FAILED ($ERRORS errors)"
  echo "禁止進入下一階段！請修復問題後重新驗證。"
  exit 1
fi

Claude 必須在產生 index.html / device-preview.html 後立即執行 post-generation-gate.js

驗證失敗處理

失敗項目	修復動作
缺少 UI Flow Diagram iframe	從 `templates/ui-flow/index.html` 複製區塊
缺少裝置切換功能	從模板複製 `switchDevice()` 函數
缺少模組圖例側邊欄	從模板複製 sidebar 區塊
index.html 缺少 iPad/iPhone 雙版本引用	確保 `switchDevice()` 使用 `ui-flow-diagram-ipad.html` 和 `ui-flow-diagram-iphone.html`
使用舊版 query parameter 切換	將 `ui-flow-diagram.html?device=X` 改為獨立檔案路徑
缺少 ui-flow-diagram-ipad.html	建立 iPad 版本 Diagram (橫向框架 200x140)
缺少 ui-flow-diagram-iphone.html	建立 iPhone 版本 Diagram (直向框架 120x260)
iPad/iPhone Diagram 畫面數不符	同步更新對應的 Diagram HTML
device-preview 側邊欄不符	同步更新 `device-preview.html`
一致性驗證失敗	依據錯誤訊息修復

🚨 iframe src Path Validation (BLOCKING - 強制驗證)

所有 iframe src 路徑必須指向實際存在的 HTML 檔案！

#!/bin/bash
# === iframe src Path Validation (BLOCKING) ===
cd {PROJECT}/04-ui-flow

ERRORS=0
echo "🔍 執行 iframe src 路徑完整性驗證..."

# 1. 取得實際畫面檔案清單
IPAD_COUNT=$(find . -name "SCR-*.html" -not -path "./iphone/*" -not -path "./docs/*" | wc -l | tr -d ' ')
IPHONE_COUNT=$(find ./iphone -name "SCR-*.html" 2>/dev/null | wc -l | tr -d ' ')
echo "📊 實際畫面: iPad=$IPAD_COUNT, iPhone=$IPHONE_COUNT"

# 2. 驗證 ui-flow-diagram-ipad.html 的 iframe src
echo ""
echo "📱 驗證 ui-flow-diagram-ipad.html iframe src..."
if [ -f "docs/ui-flow-diagram-ipad.html" ]; then
  IPAD_MISSING=0
  for src in $(grep -oE "src=\"\.\./[^\"]+\.html\"" docs/ui-flow-diagram-ipad.html | sed 's/src="\.\.\/\([^"]*\)"/\1/' | sort -u); do
    if [ ! -f "$src" ]; then
      echo "❌ 缺少檔案: $src"
      IPAD_MISSING=$((IPAD_MISSING+1))
    fi
  done
  [ $IPAD_MISSING -eq 0 ] && echo "✅ iPad Diagram: 全部路徑正確" || { echo "❌ iPad Diagram 缺少 $IPAD_MISSING 個檔案"; ERRORS=$((ERRORS+IPAD_MISSING)); }
fi

# 3. 驗證 ui-flow-diagram-iphone.html 的 iframe src
echo ""
echo "📱 驗證 ui-flow-diagram-iphone.html iframe src..."
if [ -f "docs/ui-flow-diagram-iphone.html" ]; then
  IPHONE_MISSING=0
  for src in $(grep -oE "src=\"\.\./[^\"]+\.html\"" docs/ui-flow-diagram-iphone.html | sed 's/src="\.\.\/\([^"]*\)"/\1/' | sort -u); do
    if [ ! -f "$src" ]; then
      echo "❌ 缺少檔案: $src"
      IPHONE_MISSING=$((IPHONE_MISSING+1))
    fi
  done
  [ $IPHONE_MISSING -eq 0 ] && echo "✅ iPhone Diagram: 全部路徑正確" || { echo "❌ iPhone Diagram 缺少 $IPHONE_MISSING 個檔案"; ERRORS=$((ERRORS+IPHONE_MISSING)); }
fi

# 4. 驗證 device-preview.html 的 loadScreen 路徑
echo ""
echo "📱 驗證 device-preview.html loadScreen 路徑..."
if [ -f "device-preview.html" ]; then
  PREVIEW_MISSING=0
  for src in $(grep -oE "loadScreen\('[^']+\.html'" device-preview.html | sed "s/loadScreen('//" | sed "s/'$//" | sort -u); do
    if [ ! -f "$src" ]; then
      echo "❌ 缺少檔案: $src"
      PREVIEW_MISSING=$((PREVIEW_MISSING+1))
    fi
  done
  [ $PREVIEW_MISSING -eq 0 ] && echo "✅ device-preview: 全部路徑正確" || { echo "❌ device-preview 缺少 $PREVIEW_MISSING 個檔案"; ERRORS=$((ERRORS+PREVIEW_MISSING)); }
fi

# 5. 驗證 loadScreen 數量與實際畫面數量一致
PREVIEW_COUNT=$(grep -oE "loadScreen\('[^']+\.html'" device-preview.html | sort -u | wc -l | tr -d ' ')
[ "$PREVIEW_COUNT" -eq "$IPAD_COUNT" ] && echo "✅ device-preview 畫面數: $PREVIEW_COUNT" || { echo "❌ device-preview ($PREVIEW_COUNT) ≠ 實際 ($IPAD_COUNT)"; ERRORS=$((ERRORS+1)); }

# 結果
echo ""
echo "======================================"
if [ $ERRORS -eq 0 ]; then
  echo "✅ iframe src Path Validation PASSED"
else
  echo "❌ iframe src Path Validation FAILED ($ERRORS errors)"
  echo "⚠️ 禁止進入下一階段！"
  echo "📋 修復方式:"
  echo "   1. 確認所有畫面已正確生成"
  echo "   2. 更新 Diagram 檔案使用正確的畫面路徑"
  echo "   3. 更新 device-preview.html 側邊欄"
  exit 1
fi

驗證時機

節點完成後	必須執行此驗證
03-generation	✅ 產生畫面後必須驗證
05-diagram	✅ 產生 Diagram 後必須驗證
06-screenshot 之前	✅ 截圖前必須驗證路徑正確

⚠️ Critical: 若驗證失敗，禁止進入下一節點！必須修復所有路徑問題。

自動驗證行為要求

Claude 必須主動執行：不需用戶提醒或詢問
驗證失敗時不能繼續：必須修復後重新驗證
記錄驗證結果：在 current-process.json 中記錄
每次 compaction 後恢復：重新執行驗證確認狀態

07-feedback UI 原型參考完整性驗證 (Critical)

在標記 07-feedback 為 completed 前，必須通過以下驗證！

#!/bin/bash
# === UI 原型參考完整性驗證 ===
cd {PROJECT}/02-design
SDD_FILE=$(ls SDD-*.md | head -1)

ERRORS=0
echo "🔍 執行 UI 原型參考完整性驗證..."

# 1. 統計 SDD 本文畫面數
SCREEN_COUNT=$(grep -c "^#### SCR-" "$SDD_FILE")

# 2. 統計有圖片參考的畫面數 (iPad)
IPAD_REF=$(grep -c "images/ipad/SCR-.*\.png" "$SDD_FILE")

# 3. 統計有圖片參考的畫面數 (iPhone)
IPHONE_REF=$(grep -c "images/iphone/SCR-.*\.png" "$SDD_FILE")

echo "📊 統計結果:"
echo "   SDD 畫面數: $SCREEN_COUNT"
echo "   iPad 圖片參考: $IPAD_REF"
echo "   iPhone 圖片參考: $IPHONE_REF"

# 4. 驗證一致性
[ "$SCREEN_COUNT" != "$IPAD_REF" ] && { echo "❌ iPad 圖片參考不足"; ERRORS=$((ERRORS+1)); }
[ "$SCREEN_COUNT" != "$IPHONE_REF" ] && { echo "❌ iPhone 圖片參考不足"; ERRORS=$((ERRORS+1)); }

# 5. 驗證圖片檔案存在
MISSING_IPAD=$(for f in $(grep -oE "images/ipad/SCR-[^)\"]+\.png" "$SDD_FILE" | sort -u); do [ ! -f "$f" ] && echo "$f"; done | wc -l)
MISSING_IPHONE=$(for f in $(grep -oE "images/iphone/SCR-[^)\"]+\.png" "$SDD_FILE" | sort -u); do [ ! -f "$f" ] && echo "$f"; done | wc -l)
[ "$MISSING_IPAD" -gt 0 ] && { echo "❌ 缺少 $MISSING_IPAD 個 iPad 圖片檔案"; ERRORS=$((ERRORS+1)); }
[ "$MISSING_IPHONE" -gt 0 ] && { echo "❌ 缺少 $MISSING_IPHONE 個 iPhone 圖片檔案"; ERRORS=$((ERRORS+1)); }

# 結果
echo ""
if [ $ERRORS -eq 0 ]; then
  echo "✅ UI 原型參考完整性驗證 PASSED"
else
  echo "❌ UI 原型參考完整性驗證 FAILED ($ERRORS errors)"
  exit 1
fi

驗證項目	預期結果
SDD 畫面數 = iPad 圖片參考數	100% 一致
SDD 畫面數 = iPhone 圖片參考數	100% 一致
所有參考的圖片檔案都存在	0 缺失

SDD Use Case 完整性驗證 (Critical)

在回補 SDD 時，必須同時驗證 Use Case 完整性！

#!/bin/bash
# === Use Case 完整性驗證 ===
cd {PROJECT}/02-design
SDD_FILE=$(ls SDD-*.md | head -1)

echo "🔍 執行 Use Case 完整性驗證..."

# 1. 統計 Use Case 總覽表中的 UC 數量
TABLE_UC=$(grep -E "^\| UC-" "$SDD_FILE" | grep -v "^| UC-ID" | wc -l | tr -d ' ')

# 2. 統計詳細描述章節中的 UC 數量
DETAIL_UC=$(grep -c "^#### UC-" "$SDD_FILE")

echo "📊 統計結果:"
echo "   總覽表 UC 數: $TABLE_UC"
echo "   詳細描述 UC 數: $DETAIL_UC"

# 3. 驗證一致性
if [ "$TABLE_UC" != "$DETAIL_UC" ]; then
  echo ""
  echo "❌ Use Case 數量不一致！"
  echo ""
  echo "📋 總覽表中的 UC:"
  grep -E "^\| UC-" "$SDD_FILE" | grep -v "^| UC-ID" | awk -F'|' '{print "   " $2}'
  echo ""
  echo "📋 詳細描述中的 UC:"
  grep "^#### UC-" "$SDD_FILE" | sed 's/^#### /   /'
  echo ""
  echo "⚠️ 請補充缺少的 Use Case 詳細描述！"
  exit 1
else
  echo "✅ Use Case 完整性驗證 PASSED ($TABLE_UC 個)"
fi

驗證項目	預期結果
總覽表 UC 數 = 詳細描述 UC 數	100% 一致
每個 UC 都有前置/後置條件	必備
每個 UC 都有主要流程	必備

ASCII Art 禁止驗證 (Critical)

回補文件前，必須確認無 ASCII Art！

#!/bin/bash
# ASCII Art 偵測驗證
cd {PROJECT}
echo "🔍 驗證是否有禁用的 ASCII Art..."

ERRORS=0
for FILE in 01-requirements/SRS-*.md 02-design/SDD-*.md; do
  if [ -f "$FILE" ]; then
    ASCII_BLOCKS=$(awk '/^```[^m]|^```$/{flag=1; next} /^```/{flag=0} flag && /[┌┐└┘│─├┤┬┴┼→←↑↓▶◀■□●○]/' "$FILE" | wc -l | tr -d ' ')
    if [ "$ASCII_BLOCKS" -gt 0 ]; then
      echo "❌ $FILE 含有 ASCII Art ($ASCII_BLOCKS 行)"
      ERRORS=$((ERRORS+1))
    fi
  fi
done

[ $ERRORS -eq 0 ] && echo "✅ 無 ASCII Art 違規" || { echo "⚠️ 請改用 Mermaid"; exit 1; }

Process Chain (完整版)

Step	Process	進入條件	退出條件
00	init	SDD 完整 + 智慧預測完成	模板已複製、變數已替換
03	generation	00 完成	100% 畫面 HTML 已產生
04	validation	03 完成	100% Navigation + 0 alert (BLOCKING)
05	diagram	04 完成	UI Flow Diagram (iPad/iPhone 雙版本)
06	screenshot	05 完成 + 路徑驗證通過	iPad/iPhone 截圖已產生 (見 Error Recovery)
07	feedback	06 完成	SDD/SRS 已回補 + DOCX 已重新產生 ⚠️
08	finalize	07 完成	追溯驗證通過 + 完成報告

⚠️ 注意: 01-discovery 和 02-planning 已由 app-requirements-skill 完成，本 Skill 跳過

🚨 Phase 完成前強制驗證 (BLOCKING - 每次都要執行)

Phase	完成後必須執行	預期結果
03-generation	`node post-generation-gate.js`	✅ PASSED
04-validation	`node post-generation-gate.js`	✅ PASSED
05-diagram	`node post-generation-gate.js`	✅ PASSED

# 🚨 每個 phase 完成後必須執行此命令
node ~/.claude/skills/app-uiux-designer.skill/templates/ui-flow/post-generation-gate.js {PROJECT}/04-ui-flow

# 若無法執行 Node.js，使用快速檢查
echo "=== Quick File Check ==="
ls -la {PROJECT}/04-ui-flow/index.html
ls -la {PROJECT}/04-ui-flow/device-preview.html
ls -la {PROJECT}/04-ui-flow/docs/ui-flow-diagram-ipad.html
ls -la {PROJECT}/04-ui-flow/docs/ui-flow-diagram-iphone.html

🚨 06-screenshot Error Recovery Logic (BLOCKING)

若截圖過程中發現畫面不存在，必須返回 03-generation 重新生成！

截圖前必須驗證

#!/bin/bash
# === 06-screenshot Pre-Validation (BLOCKING) ===
cd {PROJECT}/04-ui-flow

echo "🔍 截圖前驗證..."

# 1. 執行 iframe src Path Validation (見上方)
# 2. 若失敗，禁止進入 06-screenshot

# 3. 額外驗證：確認 Diagram 畫面數與實際一致
ACTUAL_COUNT=$(find . -name "SCR-*.html" -not -path "./iphone/*" -not -path "./docs/*" | wc -l | tr -d ' ')
DIAGRAM_IPAD_COUNT=$(grep -c 'onclick="openScreen' docs/ui-flow-diagram-ipad.html 2>/dev/null || echo "0")
DIAGRAM_IPHONE_COUNT=$(grep -c 'onclick="openScreen' docs/ui-flow-diagram-iphone.html 2>/dev/null || echo "0")

if [ "$ACTUAL_COUNT" != "$DIAGRAM_IPAD_COUNT" ] || [ "$ACTUAL_COUNT" != "$DIAGRAM_IPHONE_COUNT" ]; then
  echo "❌ 畫面數不一致！"
  echo "   實際畫面: $ACTUAL_COUNT"
  echo "   iPad Diagram: $DIAGRAM_IPAD_COUNT"
  echo "   iPhone Diagram: $DIAGRAM_IPHONE_COUNT"
  echo ""
  echo "⚠️ 必須返回 05-diagram 重新生成 Diagram！"
  exit 1
fi

echo "✅ 截圖前驗證通過，可以執行截圖"

截圖錯誤處理流程

06-screenshot 執行時：

1. Puppeteer 嘗試載入畫面
   ├── 成功 → 繼續截圖
   └── 失敗 (404/無法載入) → Error Recovery 流程

2. Error Recovery 流程：
   ├── 記錄缺少的畫面 ID 到 error-log.json
   ├── 統計錯誤數量
   └── 若有任何錯誤 → 返回 03-generation

3. 返回 03-generation：
   ├── 重設 current-process.json: current_process = "03-generation"
   ├── 重設 progress: 03-generation = "in_progress"
   ├── 讀取 error-log.json 找出缺少的畫面
   ├── 補充生成缺少的畫面
   └── 完成後重新走 04 → 05 → 06 流程

capture-screenshots.js Error Recovery 實作

// 在 capture-screenshots.js 中加入
async function captureScreen(page, screenPath, outputPath) {
  try {
    const response = await page.goto(`file://${screenPath}`, {
      waitUntil: 'networkidle0',
      timeout: 10000
    });

    if (!response || response.status() === 404) {
      throw new Error(`Screen not found: ${screenPath}`);
    }

    await page.screenshot({ path: outputPath });
    return { success: true, path: screenPath };
  } catch (error) {
    console.error(`❌ 截圖失敗: ${screenPath}`);
    return {
      success: false,
      path: screenPath,
      error: error.message,
      recovery: 'return-to-03-generation'
    };
  }
}

// 執行完畢後檢查
async function processResults(results) {
  const failures = results.filter(r => !r.success);

  if (failures.length > 0) {
    console.log('');
    console.log('🚨 截圖失敗統計:');
    console.log(`   失敗數量: ${failures.length}`);
    console.log(`   缺少畫面: ${failures.map(f => f.path).join(', ')}`);
    console.log('');
    console.log('⚠️ 必須返回 03-generation 補充缺少的畫面！');

    // 寫入 error-log.json
    const errorLog = {
      timestamp: new Date().toISOString(),
      phase: '06-screenshot',
      failures: failures,
      recovery_action: 'return-to-03-generation',
      missing_screens: failures.map(f => f.path.match(/SCR-[^/]+/)?.[0]).filter(Boolean)
    };

    fs.writeFileSync(
      path.join(process.cwd(), 'workspace/screenshot-error-log.json'),
      JSON.stringify(errorLog, null, 2)
    );

    // 更新 current-process.json
    const processFile = path.join(process.cwd(), 'workspace/current-process.json');
    const processData = JSON.parse(fs.readFileSync(processFile, 'utf8'));
    processData.current_process = '03-generation';
    processData.progress['03-generation'] = 'in_progress';
    processData.progress['04-validation'] = 'pending';
    processData.progress['05-diagram'] = 'pending';
    processData.progress['06-screenshot'] = 'pending';
    processData.context.last_action = `Screenshot failed: ${failures.length} screens missing`;
    fs.writeFileSync(processFile, JSON.stringify(processData, null, 2));

    process.exit(1);
  }

  console.log('✅ 所有截圖完成');
}

失敗原因與修復

失敗原因	修復方式
畫面檔案不存在	返回 03-generation 生成缺少的畫面
路徑錯誤 (typo)	修正 Diagram/device-preview 中的路徑
畫面 ID 不一致	確認 SDD 與實際生成的畫面 ID 一致
模組資料夾錯誤	確認模組名稱對應 (auth → AUTH)

07-feedback 回補步驟詳解

1. 更新 SDD 每個 SCR-* 區塊:
   ├── 加入 UI 原型參考 (不使用表格)
   ├── iPad 版本：![](images/ipad/SCR-*.png)
   └── iPhone 版本：![](images/iphone/SCR-*.png)

2. 更新 SRS:
   ├── 新增 Screen References 章節 (REQ → SCR 對照)
   ├── 新增 Inferred Requirements (從 UI Flow 推導)
   └── 更新 User Flows (Mermaid 流程圖)

3. 重新產生 DOCX:
   ├── node md-to-docx.js SDD-*.md → SDD.docx (含截圖)
   └── node md-to-docx.js SRS-*.md → SRS.docx

Node Loading Protocol

Claude 收到 skill 啟用時：
1. 讀取此 SKILL.md (本檔案)
2. 從 skill args 取得專案路徑 (PROJECT_PATH)
3. 驗證進入條件:
   - 檢查 SDD 是否存在
   - 檢查 screen-prediction.json 是否存在且 completion_status = "completed"
   - 若未完成 → 拒絕進入，提示先完成 Phase 2
4. 讀取 {PROJECT_PATH}/04-ui-flow/workspace/current-process.json
   - 若檔案不存在 → 從 00-init 開始
   - 若 current_process 存在 → 恢復到該節點
5. 讀取 [SKILL_DIR]/process/{current}/README.md
6. 執行節點步驟
7. 完成後執行 Node Transition Protocol (NTP) ⭐
8. 進入下一節點

⭐ 使用 NTP 轉換節點: node node-transition.js <from> <to> [project-path]

路徑說明：

[SKILL_DIR] = ~/.claude/skills/app-uiux-designer.skill/ (skill 本身)
{PROJECT_PATH} = 專案根目錄 (從 args 取得)
workspace 在專案: {PROJECT_PATH}/04-ui-flow/workspace/

進入條件驗證 (Critical)

在開始 UI Flow 生成前，必須驗證：

// 檢查 {PROJECT}/04-ui-flow/workspace/screen-prediction.json
{
  "completion_status": "completed",  // 必須為 completed
  "sdd_updated": true,               // 必須為 true
  "analysis": {
    "total_screens": 53              // 必須 > 0
  }
}

若驗證失敗，顯示訊息：

⚠️ 無法進入 UI Flow 階段
原因: 智慧預測尚未完成
請先完成 Phase 2 (app-requirements-skill):
- 執行智慧預測
- 補充所有預測畫面
- 確認 Appendix A 畫面清單

Workspace Management

檔案 (專案內)	說明
`04-ui-flow/workspace/current-process.json`	目前流程狀態
`04-ui-flow/workspace/screen-prediction.json`	智慧預測結果 (Phase 2 產生)
`04-ui-flow/workspace/phase-summary.md`	⭐ 最新 Phase Summary (NTP 產生)
`04-ui-flow/workspace/phase-history.md`	所有 Phase Summary 歷史
`04-ui-flow/workspace/validation-chain.json`	驗證歷史記錄
`04-ui-flow/workspace/state/`	Compaction 保存點

初始化 workspace

# 在專案的 04-ui-flow/ 下建立 workspace
mkdir -p {PROJECT}/04-ui-flow/workspace/{context,state}

Blocking Checkpoints

節點	阻斷條件
進入條件	智慧預測必須完成 (screen-prediction.json)
00-init	模板必須完整複製、變數必須替換
03-generation	100% 畫面已生成，無遺漏
04-validation	100% Navigation + 0 空按鈕 + 0 alert
05-diagram	iframe src Path Validation 必須通過 (見驗證章節)
06-screenshot	Pre-Validation 必須通過 + 若截圖失敗 → 返回 03-generation

Device Specifications

Device	Viewport	Body Style
iPad Pro 11"	1194 x 834	`width: 1194px; height: 834px;`
iPhone 15/16 Pro	393 x 852	`width: 393px; height: 852px;`

Key Scripts

腳本	位置	說明
init-project.sh	`process/00-init/templates/`	專案初始化
node-transition.js	`templates/ui-flow/`	⭐ 節點轉換 + Phase Summary (NTP)
exit-gate.js	`templates/ui-flow/`	統一驗證入口
quick-health-check.sh	`templates/ui-flow/`	Compaction 後快速檢查
post-generation-gate.js	`templates/ui-flow/`	🚨 產生後閘門 (BLOCKING - 自動執行所有驗證)
validate-navigation.js	`templates/ui-flow/`	導航驗證
validate-iframe-src.js	`templates/ui-flow/`	iframe src 路徑驗證
validate-consistency.js	`templates/ui-flow/`	一致性驗證
capture-screenshots.js	`templates/ui-flow/`	截圖生成 + Error Recovery
convert-to-iphone.sh	專案內 `scripts/`	iPad→iPhone 轉換

🚨 post-generation-gate.js (MANDATORY)

產生 index.html / device-preview.html / Diagram 後必須執行！

# 產生檔案後立即執行
node ~/.claude/skills/app-uiux-designer.skill/templates/ui-flow/post-generation-gate.js

# 或指定專案路徑
node ~/.claude/skills/app-uiux-designer.skill/templates/ui-flow/post-generation-gate.js /path/to/04-ui-flow

自動執行的驗證:

✅ 必要檔案存在檢查 (index.html, device-preview.html, Diagrams)
✅ validate-iframe-src.js - iPad/iPad mini/iPhone 路徑驗證
✅ validate-consistency.js - 一致性驗證
✅ validate-navigation.js - 導航驗證

驗證結果:

PASSED → 可以進入下一階段
FAILED → 禁止進入下一階段，自動重設 progress

自動行為:

更新 workspace/current-process.json 的 validation_passed 狀態
若失敗，自動將 03-generation / 05-diagram 重設為 in_progress
產生 workspace/validation-report.json 詳細報告

validate-iframe-src.js 使用方式

# 驗證當前目錄
node ~/.claude/skills/app-uiux-designer.skill/templates/ui-flow/validate-iframe-src.js

# 驗證指定專案
node ~/.claude/skills/app-uiux-designer.skill/templates/ui-flow/validate-iframe-src.js /path/to/project/04-ui-flow

驗證內容:

docs/ui-flow-diagram-ipad.html 的所有 iframe src
docs/ui-flow-diagram-iphone.html 的所有 iframe src
device-preview.html 的 loadScreen() / iframe src / data-iphone 路徑
畫面數量一致性 (實際檔案 = Diagram = device-preview)

Exit Code:

0 - 驗證通過
1 - 驗證失敗 (BLOCKING)

References (按需載入)

類別	檔案
文件標準	`~/.claude/skills/app-requirements-skill/references/iec62304-document-standards.md`
必要模組 HTML	`templates/common-modules/{auth,profile,setting,common}/`
平台	`references/platforms/{ios-hig,material-design,wcag}.md`
心理學	`references/psychology/{gestalt,cognitive,emotional}.md`
程式碼生成	`references/code-gen/{react,angular,swiftui,compose}.md`

必要模組 HTML 模板

在 00-init 階段，可從 templates/common-modules/ 複製必要模組模板：

模組	模板數量	說明
auth	3 個	login, register, forgot
profile	2 個	view, edit
setting	4 個	main, account, privacy, about
common	4 個	loading, empty, error, no-network

📁 模板包含 {{VARIABLE}} 佔位符，需根據專案設定替換

⚠️ 07-feedback 回補時必須遵循 iec62304-document-standards.md

Mermaid 圖表使用 flowchart TB (直式)

禁止 ASCII Art

SCR 區塊格式需包含 UI 原型表格

DOCX 轉換使用 md-to-docx.js

Commands

指令	動作
`進入節點 XX`	讀取 `process/XX/README.md`
`下一步`	執行 NTP 轉換到下一節點 ⭐
`保存狀態`	複製 current-process.json 到 state/
`恢復狀態`	執行 quick-health-check.sh + 讀取 phase-summary.md
`顯示進度`	讀取 current-process.json 的 progress
`健康檢查`	執行 quick-health-check.sh

Screen ID Format

類型	格式	範例
畫面	`SCR-{MODULE}-{NNN}-{name}`	SCR-AUTH-001-login
需求	`REQ-{MODULE}-{NNN}`	REQ-AUTH-001

Module Codes: AUTH, ONBOARD, HOME, VOCAB, TRAIN, REPORT, SETTING, PARENT, PROFILE, COMMON

輸出結果

完成 Phase 3 後，產生以下檔案供 Phase 4 使用：

📁 04-ui-flow/
├── 📁 ipad/
│   ├── SCR-AUTH-001-login.html
│   ├── SCR-AUTH-002-register.html
│   └── ... (所有畫面)
├── 📁 iphone/
│   └── ... (iPhone 版本)
├── 📁 screenshots/
│   ├── 📁 ipad/
│   │   └── *.png
│   └── 📁 iphone/
│       └── *.png
└── 📁 workspace/
    └── current-process.json (progress.06-screenshot = "completed")

Architecture Benefits

減少 Token 使用 - 只載入當前節點相關檔案
Compaction 恢復 - 狀態保存在 workspace/
清晰流程 - 每個節點有明確進入/退出條件
整合簡化 - 智慧預測在 Phase 2 完成，本 Skill 專注 UI Flow

🚨 Anti-Forgetting Protocol (CRITICAL)

防止 Claude 在 Compaction 或長對話中遺忘驗證步驟的機制

問題背景

Claude AI 有以下限制可能導致遺忘：

Context Window 限制 - 對話過長會觸發 compaction（壓縮）
Compaction 資訊損失 - 壓縮時 "how" 比 "what" 更容易遺失
注意力分散 - 長對話中後面的指令優先級可能降低
狀態不一致 - 記憶中的狀態與實際檔案狀態可能不同

核心原則

每個節點完成前：
1. 必須執行 exit-validation.sh
2. 必須更新 current-process.json 的 validation_state
3. 必須記錄到 validation-chain.json
4. 使用 NTP 轉換節點 (自動產生 phase-summary.md) ⭐

Compaction 後恢復：
1. 執行 quick-health-check.sh
2. 讀取 phase-summary.md 恢復上下文 ⭐ NTP
3. 讀取 validation-chain.json 確認已完成的驗證
4. 從最後一個有效狀態繼續

Enhanced current-process.json 結構

{
  "project_name": "WordPlay",
  "current_process": "04-validation",
  "last_updated": "2026-01-16T10:30:00Z",
  "progress": {
    "00-init": "completed",
    "03-generation": "completed",
    "04-validation": "in_progress",
    "05-diagram": "pending",
    "06-screenshot": "pending",
    "07-feedback": "pending",
    "08-finalize": "pending"
  },
  "validation_state": {
    "00-init": {
      "passed": true,
      "timestamp": "2026-01-16T09:00:00Z",
      "checks": ["templates_copied", "variables_replaced"]
    },
    "03-generation": {
      "passed": true,
      "timestamp": "2026-01-16T09:30:00Z",
      "checks": ["all_screens_generated", "onclick_coverage", "index_populated"]
    },
    "04-validation": {
      "passed": false,
      "timestamp": null,
      "pending_checks": ["navigation_100%", "zero_alerts", "consistency"]
    }
  },
  "recovery_hints": {
    "last_action": "Fixed onclick handlers in parent module",
    "pending_fixes": [],
    "files_modified": ["parent/SCR-PARENT-002.html", "parent/SCR-PARENT-003.html"]
  },
  "context": {
    "total_screens": 48,
    "modules": ["auth", "common", "dash", "parent", "profile", "progress", "setting", "train", "vocab"]
  }
}

validation-chain.json 結構

{
  "chain": [
    {
      "node": "00-init",
      "validation": "exit-validation",
      "result": "PASSED",
      "timestamp": "2026-01-16T09:00:00Z",
      "details": {
        "templates_copied": true,
        "variables_replaced": true
      }
    },
    {
      "node": "03-generation",
      "validation": "template-compliance-gate",
      "result": "PASSED",
      "timestamp": "2026-01-16T09:30:00Z",
      "details": {
        "ipad_screens": 48,
        "iphone_screens": 48,
        "onclick_coverage": "100%",
        "index_populated": true
      }
    }
  ],
  "last_valid_checkpoint": "03-generation"
}

Exit Validation Scripts

每個節點都需要一個 exit-validation.sh：

節點	驗證腳本	驗證內容
00-init	`process/00-init/exit-validation.sh`	模板完整、變數替換
03-generation	`process/03-generation/exit-validation.sh`	畫面 100%、onclick、index.html
04-validation	`process/04-validation/exit-validation.sh`	導航 100%、0 alert
05-diagram	`process/05-diagram/exit-validation.sh`	Diagram 完整、路徑正確
06-screenshot	`process/06-screenshot/exit-validation.sh`	截圖存在
07-feedback	`process/07-feedback/exit-validation.sh`	SDD/SRS 回補完整

Compaction Recovery Protocol

當 Claude 從 compaction 恢復時，必須立即執行：

# 1. 執行快速健康檢查
bash ~/.claude/skills/app-uiux-designer.skill/templates/ui-flow/quick-health-check.sh [project-path]

# 2. 讀取 Phase Summary 恢復上下文 ⭐ NTP
cat workspace/phase-summary.md

# 3. 檢查輸出並恢復狀態
node ~/.claude/skills/app-uiux-designer.skill/templates/ui-flow/recover-state.js [project-path]

quick-health-check.sh 內容

#!/bin/bash
# Quick Health Check - Compaction 後立即執行
cd "${1:-.}"

echo "🏥 Quick Health Check..."
echo ""

# 1. 確認 workspace 存在
[ -d "workspace" ] || { echo "❌ workspace/ 不存在"; exit 1; }

# 2. 讀取當前狀態
if [ -f "workspace/current-process.json" ]; then
  CURRENT=$(cat workspace/current-process.json | grep -o '"current_process": "[^"]*"' | cut -d'"' -f4)
  echo "📍 當前節點: $CURRENT"
else
  echo "⚠️ current-process.json 不存在"
  CURRENT="unknown"
fi

# 3. 快速計數
IPAD_COUNT=$(find . -name "SCR-*.html" -not -path "./iphone/*" -not -path "./docs/*" 2>/dev/null | wc -l | tr -d ' ')
IPHONE_COUNT=$(find ./iphone -name "SCR-*.html" 2>/dev/null | wc -l | tr -d ' ')
echo "📊 畫面數: iPad=$IPAD_COUNT, iPhone=$IPHONE_COUNT"

# 4. 檢查關鍵檔案
echo ""
echo "📁 關鍵檔案檢查:"
[ -f "index.html" ] && echo "  ✅ index.html" || echo "  ❌ index.html"
[ -f "device-preview.html" ] && echo "  ✅ device-preview.html" || echo "  ❌ device-preview.html"
[ -f "docs/ui-flow-diagram-ipad.html" ] && echo "  ✅ ui-flow-diagram-ipad.html" || echo "  ❌ ui-flow-diagram-ipad.html"
[ -f "docs/ui-flow-diagram-iphone.html" ] && echo "  ✅ ui-flow-diagram-iphone.html" || echo "  ❌ ui-flow-diagram-iphone.html"

# 5. 讀取 validation chain
echo ""
if [ -f "workspace/validation-chain.json" ]; then
  echo "📋 已完成的驗證:"
  cat workspace/validation-chain.json | grep -o '"node": "[^"]*"' | cut -d'"' -f4 | while read node; do
    echo "  ✅ $node"
  done
else
  echo "⚠️ validation-chain.json 不存在，需要重新驗證"
fi

echo ""
echo "🏥 Health Check 完成"
echo "📍 請從節點 '$CURRENT' 繼續"

強制執行規則

情境	必須執行
節點完成時	`exit-validation.sh` + 更新 `validation-chain.json`
Compaction 後恢復	`quick-health-check.sh` + `recover-state.js`
用戶詢問進度	讀取 `current-process.json` + `validation-chain.json`
開始新節點	確認前一節點的 validation_state.passed = true

Claude 行為要求

每次對話開始時：檢查是否需要執行 health check
完成任何修改後：更新 recovery_hints.last_action
完成節點前：必須執行 exit-validation 並記錄
發現不一致時：優先相信檔案狀態而非記憶

⭐ Node Transition Protocol (NTP)

節點轉換時自動產生 Phase Summary，支援 Context Compact

概念

NTP 確保在節點轉換時：

自動驗證當前節點完成
產生 Phase Summary 保存上下文
更新流程狀態
輸出下一節點指引

轉換流程

┌─────────────────────────────────────────────────────────────┐
│  1. Exit Validation    - 驗證當前節點完成                      │
│  2. Generate Summary   - 產生 Phase Summary                   │
│  3. Save to Workspace  - 保存到 phase-summary.md              │
│  4. Update State       - 更新 current-process.json            │
│  5. Output Prompt      - 輸出下一節點指引                       │
└─────────────────────────────────────────────────────────────┘

執行命令

# 節點轉換時使用
node ~/.claude/skills/app-uiux-designer.skill/templates/ui-flow/node-transition.js <from-node> <to-node> [project-path]

# 範例：從 03-generation 轉到 04-validation
node ~/.claude/skills/app-uiux-designer.skill/templates/ui-flow/node-transition.js 03-generation 04-validation /path/to/04-ui-flow

Phase Summary 保存位置

檔案	說明
`workspace/phase-summary.md`	當前 Phase Summary (最新)
`workspace/phase-history.md`	所有 Phase Summary 歷史

Compaction 後恢復流程

當 Claude 從 compaction 恢復時：

# 1. 快速健康檢查
bash ~/.claude/skills/app-uiux-designer.skill/templates/ui-flow/quick-health-check.sh [project-path]

# 2. 讀取 Phase Summary 恢復上下文
cat workspace/phase-summary.md

# 3. 讀取當前節點
cat workspace/current-process.json | jq '.current_process'

# 4. 繼續執行當前節點

NTP 與 AFP 整合

機制	功能	時機
NTP	產生 Phase Summary	節點轉換時
AFP	驗證歷史 + 狀態恢復	任何時候
Exit Gate	統一驗證入口	節點完成前
Quick Health Check	快速狀態確認	Compaction 後

節點完成流程 (使用 NTP)

完成當前節點工作
       ↓
執行 exit-gate.js 驗證
       ↓
   ┌───┴───┐
   ↓       ↓
 PASS    FAIL
   ↓       ↓
執行     修復問題
NTP      重新驗證
   ↓
自動產生 Phase Summary
自動更新 current-process.json
       ↓
讀取下一節點 README.md
       ↓
繼續執行

使用範例

# 03-generation 完成後，轉換到 04-validation
node ~/.claude/skills/app-uiux-designer.skill/templates/ui-flow/node-transition.js 03-generation 04-validation

# 輸出範例：
# ╔════════════════════════════════════════════════════════════╗
# ║           NODE TRANSITION PROTOCOL (NTP)                   ║
# ╚════════════════════════════════════════════════════════════╝
#
# ▶ Running exit validation for 03-generation...
# ✅ Saved to: workspace/phase-summary.md
# ✅ current-process.json updated
#
# CONTEXT COMPACT POINT
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# PHASE SUMMARY (Preserve this information)
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#
# ## Completed: 03-generation (HTML Generation)
# - iPad screens: 48
# - iPhone screens: 48
# - Modules: auth, common, dash, ...
#
# ## Next: 04-validation
# - Action: Validate 100% navigation coverage
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

app-uiux-designer

이 저장소의 다른 Skills

UI/UX Designer Skill (Chain of Repository)

與 app-requirements-skill 整合

07-feedback 回補內容 (MANDATORY)

IEC 62304 雙向追蹤 (MANDATORY)

設計理念

驗證標準 (全部必須達成)

禁止項目

🔒 Skill 檔案保護規則 (CRITICAL)

強制規則

違規範例

例外情況

🚨 onclick 生成強制規則 (CRITICAL)

生成時強制檢查流程

常見按鈕文字預設目標

生成後自檢命令

Quick Start

🚨🚨🚨 MANDATORY VALIDATION EXECUTION (BLOCKING) 🚨🚨🚨

強制執行命令 (每次 phase 完成前必須執行)

驗證清單 (必須全部通過)

禁止行為 (FORBIDDEN)

正確執行流程

Claude 自我檢查問題

⚠️ Auto-Validation Rules (MANDATORY - 不可跳過)

驗證觸發時機

03-generation Template Compliance Gate (Critical)

驗證失敗處理

🚨 iframe src Path Validation (BLOCKING - 強制驗證)

驗證時機

自動驗證行為要求

07-feedback UI 原型參考完整性驗證 (Critical)

SDD Use Case 完整性驗證 (Critical)

ASCII Art 禁止驗證 (Critical)

Process Chain (完整版)

🚨 Phase 完成前強制驗證 (BLOCKING - 每次都要執行)

🚨 06-screenshot Error Recovery Logic (BLOCKING)

截圖前必須驗證

截圖錯誤處理流程

capture-screenshots.js Error Recovery 實作

失敗原因與修復

07-feedback 回補步驟詳解

Node Loading Protocol

進入條件驗證 (Critical)

Workspace Management

初始化 workspace

Blocking Checkpoints

Device Specifications

Key Scripts

🚨 post-generation-gate.js (MANDATORY)

validate-iframe-src.js 使用方式

References (按需載入)

必要模組 HTML 模板

Commands

Screen ID Format

輸出結果

Architecture Benefits

🚨 Anti-Forgetting Protocol (CRITICAL)

問題背景

核心原則

Enhanced current-process.json 結構

validation-chain.json 結構

Exit Validation Scripts

Compaction Recovery Protocol

quick-health-check.sh 內容

強制執行規則

Claude 行為要求

⭐ Node Transition Protocol (NTP)

概念

轉換流程

執行命令

Phase Summary 保存位置

Compaction 後恢復流程

NTP 與 AFP 整合

節點完成流程 (使用 NTP)

使用範例

UI/UX Designer Skill (Chain of Repository)

與 app-requirements-skill 整合

07-feedback 回補內容 (MANDATORY)

IEC 62304 雙向追蹤 (MANDATORY)