psd-to-preview

psd-to-preview: PSD to preview and React components

AI Execution Instructions (Top Priority)

When a user requests to use this skill, the following steps must actually be executed to run the commands.

AI Execution Rules：

1. Default：psd-slicer Now supports exporting all layers by default (including Chinese characters and non-standard characters), and will automatically look for layer-tree.json and other mapping files in the PSD directory.
2. Normalization: If the design file's layer naming is messy and you want to standardize layer names, you can, when calling psd-slicer directly add the --auto-rename parameter to convert assets to layer-xxx format. If you want to force layer names to only be standard English + hyphens, you can use --strict-naming to filter out non-compliantly named layers.
3. Output Copy: If the user requests "output real text" or "copy to code", you must use --skip-typein step 2, and use --include-text

Skill Dependencies (Prerequisites)

This skill serves as the workflow entry point and is highly dependent on the following three core skills. Before execution, ensure they exist at the specified paths:

• psd-layer-reader: Responsible for parsing the PSD structure to generate a JSON tree.
• psd-slicer: Responsible for exporting layer slice images.
• psd-json-preview: Responsible for composing the JSON and images into terminal code (HTML/React/Vue).

Dependency Pre-check (Must Be Executed by AI Before Execution)

Before executing the workflow, the AImustfirst check whether the dependencies are installed:

# 检查 psd-tools
py -3 -c "import psd_tools" 2>&1
# 如果返回 ImportError，表示未安装

# 检查 scikit-image
py -3 -c "import skimage" 2>&1

If dependencies are missing, the AI must ask the user：

"The following dependencies were detected as missing. Install them?

• psd-tools(Required)
• scikit-image(Required)

Enter 'yes' to confirm installation, or 'no' to skip (some layers may fail to export)"

After the user confirms, the AI executes the installation：

# 安装必需依赖
py -3 -m pip install psd-tools

# 安装可选依赖（如果用户同意）
py -3 -m pip install scikit-image

Version Check (Optional)：

# 检查已安装的版本
py -3 -c "import psd_tools; print('psd-tools:', psd_tools.__version__)"
py -3 -c "import skimage; print('scikit-image:', skimage.__version__)"

Notes:

• If the user chooses not to install psd-tools, the workflow cannot continue
• If the user chooses not to install scikit-image, execution can proceed but some elements with layer effects will be skipped
• After installation is complete, it is recommended to re-check whether the dependencies were installed successfully

---

Execute Commands

# 步骤 1：图层解析
py -3 .claude/skills/psd-layer-reader/scripts/psd_layers.py \
  <PSD文件路径> --output <输出目录>/layer-tree.json

# 步骤 2：图层切片
py -3 .claude/skills/psd-slicer/scripts/export_slices.py \
  --psd <PSD文件路径> --output <输出目录>/sliced-images
# 注：psd-slicer 现默认允许各种图层导出并在工作目录自动查找映射 JSON。若用户需转命名规范化图形文件，可添加 --auto-rename。

# 步骤 3：代码生成
py -3 .claude/skills/psd-json-preview/scripts/generate_preview.py \
  --json <输出目录>/layer-tree.json --images <输出目录>/sliced-images \
  --out <输出目录> --generate-react --generate-vue \
  --component-name PsdComponent --preserve-names

---

### 高级方案：输出真实文本（保留文案可编辑性）

如果用户提到“要输出文案”、“文字转代码”或“文字不要切图”，请使用以下组合命令：

```powershell
# 步骤 2：图层切片（跳过文本图层，避免生成文字图片）
py -3 .claude/skills/psd-slicer/scripts/export_slices.py \
  --psd <PSD文件路径> --output <输出目录>/sliced-images --skip-type

# 步骤 3：代码生成（开启文本渲染，将文字转为 HTML/CSS）
py -3 .claude/skills/psd-json-preview/scripts/generate_preview.py \
  --json <输出目录>/layer-tree.json --images <输出目录>/sliced-images \
  --out <输出目录> --generate-react --generate-vue --include-text

**关键提醒**：

- ✅ 使用 `py -3`（Windows）或 `python3`（Linux/Mac）

---

### 执行检查清单

- [ ] `<输出目录>/layer-tree.json` 有数据
- [ ] `<输出目录>/sliced-images/` 有 PNG 文件
- [ ] `<输出目录>/preview/` 有 HTML 文件
- [ ] `<输出目录>/react-component/` 有 JSX 和 CSS 文件
- [ ] `<输出目录>/vue-component/` 有 Vue 文件

---

## 工作原理

PSD → psd-layer-reader → layer-tree.json → psd-slicer → sliced-images/ → psd-json-preview → preview/ + react-component/ + vue-component/

---

## 快速参考

### 核心参数

| 参数       | 说明         | 示例                    |
| ---------- | ------------ | ----------------------- |
| `<PSD路径>` | PSD 文件路径 | `assets/design.psd`     |
| `--output` | 输出目录     | `output/design-preview` |

### 常见问题

**Q: 某些图层没有被导出？**  
A: 大部分通常是因为图层不可见、不包含内容或者完全透明。如果使用了 `--strict-naming` 参数，则不合规命名（中文等）也会被跳过。

**Q: 导出的图层名字是乱的/中文的？**  
A: psd-slicer 会默认使用 PSD 中的原始名称进行导出。你可以在生成切片时加入 `--auto-rename` 将它们转化为通用的标准命名，或者确保 `psd-layer-reader` 已执行并在它的工作目录下自然匹配映射结构。

---

## 输出目录结构

output/ ├── layer-tree.json # Layer data ├── sliced-images/ # PNG slices ├── preview/ # HTML preview │ ├── index.html │ ├── styles.css │ └── images/ ├── react-component/ # React component │ ├── index.jsx │ ├── index.module.css │ └── images/ └── vue-component/ # Vue component ├── index.vue └── images/

---

## 故障排查

| 错误          | 原因       | 解决方案         |
| ------------- | ---------- | ---------------- |
| PSD 未找到    | 路径错误   | 检查文件路径     |
| 权限错误      | 无写入权限 | 检查目录权限     |
| 预览加载失败  | 路径错误   | 确保目录结构完整 |
| JSON 解析错误 | 文件损坏   | 重新运行工作流   |

---

## 依赖说明

### 必需依赖

- `psd-tools`: PSD 文件解析核心库

### 可选依赖

- `scikit-image`: 用于导出包含图层效果的元素（如阴影、发光、渐变等）

### 手动安装命令

如果预检查阶段的自动安装失败，可手动执行：

```bash
# 安装依赖
py -3 -m pip install psd-tools
py -3 -m pip install scikit-image

Note: Although SKILL.md contains installation commands, when the AI executesit will not run automatically. Please refer to the "Dependency Pre-check" section to have the AI check and install dependencies before executing the workflow.

---

Version: 1.6 | Update: March 12, 2026