步骤 1 — 文件确认

检查用户提供的文件路径的扩展名。

• 非 .pdf/.txt/.md → 显示明确的错误信息并终止
• 文件不存在 → 请求重新确认路径

步骤 2 — 文本提取

PDF 输入时:

# 安装依赖项（仅首次需要）
cd ~/.claude/skills/screen-design-doc/scripts && npm install --silent

# 文本提取 — 必须保存到此路径
node ~/.claude/skills/screen-design-doc/scripts/extract_pdf_text.js \
  <输入.pdf> -o <工作空间_根目录>/screen-design/extracted/source.txt

提取的文件必须保存在 screen-design/extracted/source.txt 路径下。

TXT/MD 输入时: 使用 Read 工具直接读取。

步骤 3 — 需求分析

从文本中识别以下项目：

1. 需求 ID 检测 : 检查原始文档中是否存在 ID 模式

   • 检测模式示例：REQ-001、FR-01、F-001、요구사항번호 等
   • 如果没有 → 省略 ID 追踪，仅分配 SC ID
   • 如果有 → 在推导每个屏幕时一并记录对应的需求 ID

2. 站点判断 : 判断是否需要多站点

   • 多站点标准（满足以下至少一项）：
     • 用户角色不同且屏幕构成完全不同（例如：管理员 vs 普通用户）
     • 目标设备/平台不同（例如：桌面端网页 vs 移动端网页）
     • 需要独立部署（例如：admin.example.com vs app.example.com）
   • 多站点 → 确定站点 slug（小写英文，例如：admin、user、partner）
   • 单站点 → 保持现有的扁平结构

3. 屏幕列表推导 : 将功能单元分组为屏幕单元

   • 具有相同目的/上下文的功能 → 归为一个屏幕
   • 识别屏幕间的层级关系（主 → 子 → 详情）

4. 屏幕分组 : 确定 IA 上层类别（例如：认证、仪表板、设置）

   • 组号将成为 SC ID 的第一部分

将分析结果整理为以下格式，然后进入下一步：

单站点:

[组 01: 认证]
  - SC-01-01: 登录屏幕 ← REQ-001, REQ-002
  - SC-01-02: 注册屏幕 ← REQ-003
  - SC-01-03: 找回密码屏幕 ← REQ-004

[组 02: 仪表板]
  - SC-02-01: 主仪表板 ← REQ-010, REQ-011
  - SC-02-02: 通知列表 ← REQ-012

多站点:

[站点: admin — 管理员 / 桌面端网页 / 侧边栏]
  [组 01: 认证]
    - SC-ADMIN-01-01: 登录屏幕 ← REQ-001
  [组 02: 仪表板]
    - SC-ADMIN-02-01: 仪表板 ← REQ-010
    - SC-ADMIN-02-02: 会员管理 ← REQ-011

[站点: user — 普通用户 / 移动端网页 / 底部标签栏]
  [组 01: 引导]
    - SC-USER-01-01: 引导 ← REQ-020
  [组 02: 首页]
    - SC-USER-02-01: 首页屏幕 ← REQ-030

步骤 4 — 创建 IA 站点地图

参考 references/screen-design-guide.md 中的 IA 模式，使用 Mermaid 表示整个屏幕层级。

所有 ia-sitemap.md 文件顶部需包含元数据表格：

| 项目 | 值 |
|------|-----|
| 站点 | default |
| 目标 | 全体用户 |
| 平台 | 移动端网页 |
| 布局 | 底部标签栏 |

单站点:

flowchart TD
    root[🖥️ 系统名称]

    root --> g01[认证]
    root --> g02[仪表板]

    g01 --> sc0101["SC-01-01\n登录"]
    g01 --> sc0102["SC-01-02\n注册"]

    g02 --> sc0201["SC-02-01\n主仪表板"]

保存到 screen-design/ia-sitemap.md。

多站点:

为每个站点创建单独的 ia-sitemap.md 文件。SC ID 中包含站点 slug。

• screen-design/admin/ia-sitemap.md — 管理员站点 IA
• screen-design/user/ia-sitemap.md — 用户站点 IA

步骤 5 — 创建屏幕设计文档

为每个屏幕创建带编号的 MD 文件。基于 references/screen-design-guide.md 中的屏幕设计文档模板进行编写。

屏幕 ID 体系 :

• 单站点：SC-[组号]-[序号]（例如：SC-01-01、SC-02-03）
• 多站点：SC-[站点]-[组号]-[序号]（例如：SC-ADMIN-01-01、SC-USER-02-03）文件名 : 整体序号（2位）+ 英文名称（例如：01-login.md、04-dashboard.md）

每个屏幕设计文档文件构成：

• 屏幕基本信息（ID、屏幕名称、目的、进入路径、上一个/下一个屏幕）
• 主要区域/部分
• 组件列表（按区域的 UI 元素）
• 用户操作 → 屏幕切换表格
• 需求追踪表格（如果存在需求 ID）

文件编号按组顺序连续排列所有屏幕：

01-login.md           (SC-01-01)
02-signup.md          (SC-01-02)
03-forgot-password.md (SC-01-03)
04-dashboard.md       (SC-02-01)

步骤 6 — 保存结果并报告

工作空间根目录 screen-design/ 文件夹：

单站点（保持现有扁平结构，仅在 ia-sitemap.md 中添加元数据表格）：

screen-design/
├── README.md               ← 屏幕组列表、SC ID 索引、文件链接
├── ia-sitemap.md           ← 元数据表格 + 完整屏幕层级 Mermaid
├── 01-login.md             ← 屏幕设计文档
├── 02-signup.md
├── ...
└── extracted/              ← 仅 PDF 输入时存在
    └── source.txt

多站点:

screen-design/
├── README.md               ← 整体站点概览、各站点链接
├── admin/
│   ├── ia-sitemap.md       ← 元数据表格 + 管理员 IA Mermaid
│   ├── 01-login.md
│   ├── 02-dashboard.md
│   └── ...
├── user/
│   ├── ia-sitemap.md       ← 元数据表格 + 用户 IA Mermaid
│   ├── 01-onboarding.md
│   ├── 02-home.md
│   └── ...
└── extracted/              ← 仅 PDF 输入时存在
    └── source.txt

保存完成后，向用户报告生成的屏幕数量、组结构、文件列表。

更新模式详细流程

当工作空间中已存在 screen-design/ 文件夹时使用的流程。

U-步骤 1 — 了解现状

读取所有现有文件以了解当前状态：

• screen-design/README.md — 屏幕列表、组结构
• 单站点：screen-design/ia-sitemap.md — 当前 IA 结构
• 多站点：screen-design/[站点]/ia-sitemap.md — 各站点 IA 结构
• screen-design/[序号]-[屏幕名].md 或 screen-design/[站点]/[序号]-[屏幕名].md — 各屏幕设计文档

了解当前的 SC ID 最后序号、组结构、屏幕数量。

U-步骤 2 — 了解变更内容

• 有新文档时 : 执行步骤 1~3 后与现有状态进行比较
• 仅有口头指示时 : 直接从用户描述中推导变更内容

变更类型分类：

[新增] 新屏幕、新组、新组件、新站点
[修改] 屏幕名称变更、组件变更、操作变更
[删除] 屏幕移除、组合并、站点移除

如有不明确的部分，在操作前向用户确认。

U-步骤 3 — 选择性修改

仅修改有变更的文件。

SC ID 处理:

• 绝对不更改现有的 SC ID（保留追踪历史）
• 新屏幕沿用该组最后一个 SC 序号的下一个
• 新组沿用现有最后一个组号的下一个
• 不重复使用已删除的 SC 的 ID

文件编号:

• 新文件沿用最后一个整体序号的下一个
• 如需在中间插入，则重新调整后续文件编号 + 更新 README.md 链接

U-步骤 4 — 变更摘要报告

✅ 更新完成

[已修改的文件]
- 03-product-list.md: 添加过滤器组件
- ia-sitemap.md: 反映支付组屏幕

[新增的文件]
- 07-payment.md: 新增支付屏幕 (SC-03-01)

[未变更的文件]
- 01-login.md, 02-signup.md (无变更)

参考文件

• references/screen-design-guide.md — IA 站点地图 Mermaid 模式、屏幕设计文档模板、SC ID 体系、需求追踪表格格式

Weekly Installs

1

Repository

dev-goraebap/sv…m-skills

First Seen

1 day ago

Security Audits

Gen Agent Trust HubWarnSocketPassSnykPass

Installed on

zencoder1

amp1

cline1

openclaw1

opencode1

cursor1

Step 1 — 파일 확인

사용자가 제공한 파일 경로의 확장자를 확인한다.

• .pdf/.txt/.md 이외 → 명확한 오류 메시지와 함께 종료
• 파일이 존재하지 않으면 → 경로 재확인 요청

Step 2 — 텍스트 추출

PDF 입력일 때:

# 의존성 설치 (최초 1회)
cd ~/.claude/skills/screen-design-doc/scripts && npm install --silent

# 텍스트 추출 — 반드시 이 경로로 저장
node ~/.claude/skills/screen-design-doc/scripts/extract_pdf_text.js \
  <입력.pdf> -o <워크스페이스_루트>/screen-design/extracted/source.txt

추출된 파일은 반드시screen-design/extracted/source.txt 경로에 저장한다.

TXT/MD 입력일 때: Read 도구로 직접 읽는다.

Step 3 — 요구사항 분석

텍스트에서 아래 항목을 식별한다:

1. 요구사항 ID 감지 : 원본 문서에 ID 패턴이 있는지 확인

   • 감지 패턴 예: REQ-001, FR-01, F-001, 요구사항번호 등
   • 없으면 → ID 추적 생략, SC ID만 부여
   • 있으면 → 각 화면 도출 시 해당 요구사항 ID를 함께 기록

2. 사이트 판단 : 멀티 사이트가 필요한지 판단한다

   • 멀티 사이트 기준 (아래 중 하나 이상 해당):
     • 사용자 역할이 다르고 화면 구성이 전혀 다름 (예: 관리자 vs 일반 사용자)
     • 대상 디바이스/플랫폼이 다름 (예: 데스크톱 웹 vs 모바일 웹)
     • 독립 배포가 필요함 (예: admin.example.com vs app.example.com)
   • 멀티 사이트 → 사이트 슬러그 결정 (소문자 영문, 예: admin, user, partner)
   • 단일 사이트 → 기존 플랫 구조 유지

3. 화면 목록 도출 : 기능 단위를 화면 단위로 묶는다

   • 동일 목적/맥락의 기능 → 한 화면
   • 화면 간 계층 관계 파악 (메인 → 서브 → 상세)

4. 화면 그룹핑 : IA 상위 카테고리 결정 (예: 인증, 대시보드, 설정)

   • 그룹 번호가 SC ID의 첫 번째 자리가 된다

분석 결과를 아래 형식으로 정리한 뒤 다음 단계로 진입한다:

단일 사이트:

[그룹 01: 인증]
  - SC-01-01: 로그인 화면 ← REQ-001, REQ-002
  - SC-01-02: 회원가입 화면 ← REQ-003
  - SC-01-03: 비밀번호 찾기 화면 ← REQ-004

[그룹 02: 대시보드]
  - SC-02-01: 메인 대시보드 ← REQ-010, REQ-011
  - SC-02-02: 알림 목록 ← REQ-012

멀티 사이트:

[사이트: admin — 관리자 / 웹 데스크톱 / 사이드바]
  [그룹 01: 인증]
    - SC-ADMIN-01-01: 로그인 화면 ← REQ-001
  [그룹 02: 대시보드]
    - SC-ADMIN-02-01: 대시보드 ← REQ-010
    - SC-ADMIN-02-02: 회원 관리 ← REQ-011

[사이트: user — 일반 사용자 / 모바일 웹 / 하단탭]
  [그룹 01: 온보딩]
    - SC-USER-01-01: 온보딩 ← REQ-020
  [그룹 02: 홈]
    - SC-USER-02-01: 홈 화면 ← REQ-030

Step 4 — IA 사이트맵 생성

references/screen-design-guide.md의 IA 패턴을 참고해 전체 화면 계층을 Mermaid로 표현한다.

모든 ia-sitemap.md 상단에 메타 테이블을 포함한다:

| 항목 | 값 |
|------|-----|
| 사이트 | default |
| 대상 | 전체 사용자 |
| 플랫폼 | 모바일 웹 |
| 레이아웃 | 하단탭 |

단일 사이트:

flowchart TD
    root[🖥️ 시스템명]

    root --> g01[인증]
    root --> g02[대시보드]

    g01 --> sc0101["SC-01-01\n로그인"]
    g01 --> sc0102["SC-01-02\n회원가입"]

    g02 --> sc0201["SC-02-01\n메인 대시보드"]

screen-design/ia-sitemap.md에 저장한다.

멀티 사이트:

각 사이트별로 별도의 ia-sitemap.md를 생성한다. SC ID에 사이트 슬러그가 포함된다.

• screen-design/admin/ia-sitemap.md — 관리자 사이트 IA
• screen-design/user/ia-sitemap.md — 사용자 사이트 IA

Step 5 — 화면설계서 생성

화면별로 넘버링된 MD 파일을 생성한다. references/screen-design-guide.md의 화면설계서 템플릿을 기준으로 작성한다.

화면 ID 체계 :

• 단일 사이트: SC-[그룹번호]-[순번] (예: SC-01-01, SC-02-03)
• 멀티 사이트: SC-[SITE]-[그룹번호]-[순번] (예: SC-ADMIN-01-01, SC-USER-02-03) 파일명 : 전체 순번 2자리 + 영문명 (예: 01-login.md, 04-dashboard.md)

각 화면설계서 파일 구성:

• 화면 기본 정보 (ID, 화면명, 목적, 진입 경로, 이전/다음 화면)
• 주요 영역/섹션
• 컴포넌트 목록 (영역별 UI 요소)
• 사용자 액션 → 화면 전환 테이블
• 요구사항 추적 테이블 (요구사항 ID가 있는 경우)

파일 넘버링은 그룹 순서대로 전체 화면을 이어서 붙인다:

01-login.md           (SC-01-01)
02-signup.md          (SC-01-02)
03-forgot-password.md (SC-01-03)
04-dashboard.md       (SC-02-01)

Step 6 — 결과물 저장 및 보고

워크스페이스 루트 screen-design/ 폴더:

단일 사이트 (기존 플랫 구조 유지, ia-sitemap.md에 메타 테이블만 추가):

screen-design/
├── README.md               ← 화면 그룹 목록, SC ID 인덱스, 파일 링크
├── ia-sitemap.md           ← 메타 테이블 + 전체 화면 계층 Mermaid
├── 01-login.md             ← 화면설계서
├── 02-signup.md
├── ...
└── extracted/              ← PDF 입력 시만
    └── source.txt

멀티 사이트:

screen-design/
├── README.md               ← 전체 사이트 개요, 사이트별 링크
├── admin/
│   ├── ia-sitemap.md       ← 메타 테이블 + 관리자 IA Mermaid
│   ├── 01-login.md
│   ├── 02-dashboard.md
│   └── ...
├── user/
│   ├── ia-sitemap.md       ← 메타 테이블 + 사용자 IA Mermaid
│   ├── 01-onboarding.md
│   ├── 02-home.md
│   └── ...
└── extracted/              ← PDF 입력 시만
    └── source.txt

저장 완료 후 생성된 화면 수, 그룹 구조, 파일 목록을 사용자에게 보고한다.

업데이트 모드 상세 절차

워크스페이스에 이미 screen-design/ 폴더가 있을 때 사용하는 플로우다.

U-Step 1 — 현황 파악

기존 파일을 모두 읽어 현재 상태를 파악한다:

• screen-design/README.md — 화면 목록, 그룹 구조
• 단일 사이트: screen-design/ia-sitemap.md — 현재 IA 구조
• 멀티 사이트: screen-design/[사이트]/ia-sitemap.md — 사이트별 IA 구조
• screen-design/[번호]-[화면명].md 또는 screen-design/[사이트]/[번호]-[화면명].md — 각 화면설계서

현재 SC ID 마지막 번호, 그룹 구조, 화면 수를 파악해둔다.

U-Step 2 — 변경 내용 파악

• 새 문서가 있는 경우 : Step 1~3을 수행한 뒤 기존 현황과 비교
• 구두 지시만 있는 경우 : 사용자 설명에서 직접 변경사항 도출

변경 유형 분류:

[추가] 새 화면, 새 그룹, 새 컴포넌트, 새 사이트
[수정] 화면명 변경, 컴포넌트 변경, 액션 변경
[삭제] 화면 제거, 그룹 통합, 사이트 제거

애매한 부분이 있으면 작업 전에 사용자에게 확인한다.

U-Step 3 — 선택적 수정

변경이 있는 파일만 수정한다.

SC ID 처리:

• 기존 SC ID는 절대 변경하지 않는다 (추적 이력 보존)
• 새 화면은 해당 그룹의 마지막 SC 순번 다음을 이어서 부여한다
• 새 그룹은 기존 마지막 그룹 번호 다음을 이어서 부여한다
• 삭제된 SC의 ID는 재사용하지 않는다

파일 넘버링:

• 새 파일은 마지막 전체 순번 다음을 이어서 붙인다
• 중간 삽입이 필요한 경우 이후 파일 번호 재조정 + README.md 링크 업데이트

U-Step 4 — 변경 요약 보고

✅ 업데이트 완료

[수정된 파일]
- 03-product-list.md: 필터 컴포넌트 추가
- ia-sitemap.md: 결제 그룹 화면 반영

[추가된 파일]
- 07-payment.md: 결제 화면 신규 추가 (SC-03-01)

[변경 없는 파일]
- 01-login.md, 02-signup.md (변경 없음)

참고 파일

• references/screen-design-guide.md — IA 사이트맵 Mermaid 패턴, 화면설계서 템플릿, SC ID 체계, 요구사항 추적 테이블 형식

Weekly Installs

1

Repository

dev-goraebap/sv…m-skills

First Seen

1 day ago

Security Audits

Gen Agent Trust HubWarnSocketPassSnykPass

Installed on

zencoder1

amp1

cline1

openclaw1

opencode1

cursor1