SuperAPI AI Directory
Partner中文AI newsFavorites
Skillspsd-slicer

psd-slicer

Design & creation

View repository

Updated 10-16 01:56

About this skill

PSD Slice Exporter

Core Features

Automatically exports visible layers of a PSD file as separate PNG images, with support for flexible filtering and naming validation.

Features：

  • ✅ Enforces naming validity checks (supports [a-zA-Z0-9_-] and layout tags [tag]）
  • ✅ Automatically handles layout tags (e.g., [flow-y]layout automatically exported as layout.png）
  • ✅ Recursively processes nested layer groups
  • ✅ Automatically handles duplicate name conflicts (with layer_id -level anti-shake and anti-word-overwrite mechanism)
  • ✅ Supports filtering by group/prefix
  • ✅ Skips invisible/blank layers
  • ✅ Supports exporting non-ASCII layer names such as Chinese and Japanese by default with no configuration required
  • ✅ Supports intelligently matching JSON structure files in the same directory, or via --auto-rename converting to generic slice naming

Usage

Basic Commands

# 导出所有合法命名的图层
py -3 scripts/export_slices.py --psd design.psd

# 自定义输出目录
py -3 scripts/export_slices.py --psd design.psd -o assets/layers

# 仅导出图层组（跳过单个图层）
py -3 scripts/export_slices.py --psd design.psd -g

# 按前缀过滤（如：slice-button）
py -3 scripts/export_slices.py --psd design.psd -p slice-

# 组合使用
py -3 scripts/export_slices.py --psd design.psd -o ./comps/ -g -p component-

Parameter Description

Parameter Short Option Description
--output -o Output directory (default:images/）
--groups-only -g Export layer groups only
--prefix -p Prefix filter (e.g.:slice-）
--strict-naming -s Force naming validity validation (invalid names will be skipped)
--auto-rename None Automatically rename layers to layer-xxx or group-xxx
--mapping-json -m Explicitly specify the JSON mapping file path. If not provided and a file with the same name or layer-tree.json exists in the working directory, it will be matched automatically.
--skip-type None Skip text layers (kind == 'type'）

When to Use Name Mapping and Automatic Naming

Default behavior: Now no processing is needed; by default, layers containing Chinese characters can be exported directly. When duplicate Chinese names are encountered (e.g., all named 背景under the root component), their independent layer_id is now used for association and deduplication (e.g., 背景_13.png and 背景_14.png), avoiding the loss of dictionary meaning caused by simple overlaps like _1 .

Recommended to use the --mapping-json parameter or let it match automatically: When there is a standard structure processed by psd-layer-reader that needs to be matched, since it has processed the tree relationship and also uniformly managed the special layout tag [tag] , it can achieve a complete one-to-one correspondence between slice naming and the name in JSON, which is especially critical for subsequent page generation. If the -m parameter is not provided, this tool will alsoautomatically search for a mapping file in the PSD directory(priority:[PSD同名文件].json > layer-tree.json > psd_layers.json）。

Use --auto-rename： If you do not need the messy, non-standard layer names from the original design, but instead want to uniformly convert them directly into layer-xxx semantic-free form for use by other engines or preview systems, you can directly use the --auto-rename parameter to convert the names of all layers that could not be matched.

Technical Implementation

Mapping Relationship:

  • In PSD, layer.name returns the original name (possibly Chinese)
  • In JSON, originalName Save the same original name
  • In JSON, name is a normalized legal filename
  • Mapping table structure: {layer.name: name} i.e. {原始名称: 规范化名称}

Workflow:

  1. Use psd-layer-reader Analyze the PSD structure and generate JSON
  2. Check the originalName and name mapping relationships in the JSON
  3. Use psd-slicer 's --mapping-json parameter to export layers

Example:

# 步骤 1: 生成 JSON 映射
py -3 .claude/skills/psd-layer-reader/scripts/psd_layers.py design.psd -o layer-tree.json

# 步骤 2: 使用映射导出
py -3 .claude/skills/psd-slicer/scripts/export_slices.py --psd design.psd --mapping-json layer-tree.json -o assets/

Notes:

  • Ensure the JSON file and the PSD file correspond to the same design draft (versions must stay in sync)
  • If the PSD is modified, the JSON file must be regenerated
  • The mapping feature automatically handles nested layer groups (recursively traverses children)
  • If a layer has no mapping in the JSON and its name is invalid, it will be skipped and a warning will be output
  • Mapping matches using the PSD's layer.name as the lookup key

Practical case: share-modal.psd

Complete workflow(including Chinese layer export):

# 步骤 1: 创建输出目录并生成 JSON 映射
py -3 .claude/skills/psd-layer-reader/scripts/psd_layers.py \
  --psd assets/share-modal.psd \
  --output verify-flow/verify-010/layer-tree.json

# 步骤 2: 使用映射导出中文图层
py -3 .claude/skills/psd-slicer/scripts/export_slices.py \
  --psd assets/share-modal.psd \
  --output verify-flow/verify-010/sliced-images \
  --mapping-json verify-flow/verify-010/layer-tree.json

Actual output example：

Loaded 177 name mappings
Mapped '背景' -> 'layer-npdngy.png'
Exported Layer: layer-npdngy.png
Mapped '图层 1' -> 'layer-9dgwjr.png'
Exported Layer: layer-9dgwjr.png
Mapped '唱片' -> 'group-9bi971.png'
Exported Group: group-9bi971.png
...
Done! Exported to: verify-flow/verify-010/sliced-images

Common warning handling：

  1. Duplicate name warning(normal phenomenon):

    Warning: Duplicate originalName '唱片'
Warning: Duplicate originalName '雨滴'

    This is because layers with the same name exist in the PSD, and the system will automatically add a _1、_2 suffix to distinguish them.

  2. Layer effect warning(dependency installation required):

    Warning: Could not export '活动规则': Layer effects require: scikit-image

    Solution：

    pip install scikit-image
# 或
pip install 'psd-tools[composite]'

Export statistics example：

  • Total layer mappings: 177
  • Successfully exported: 126 layers (31 groups + 95 images)
  • With layer effects requiring additional dependencies: about 10 (such as "活动规则", "SLOGAN", "标题", etc.)

Exclude text layers

If you plan to use real text (instead of images) in HTML, use the --skip-type parameter:

py -3 scripts/export_slices.py --psd design.psd --skip-type

Together with psd-json-preview 's --include-text parameter, perfect restoration of design draft text can be achieved.

Backward compatibility

  • Deprecated --allow-illegal-names(but passing it no longer causes a crash and it is a no-op). Instead, the script now allows Chinese and special names by default. If strict consistency validation is required, you must explicitly pass --strict-naming or -s。
  • If a layer has no mapping and no suitable JSON file exists in the current directory, it will be exported with its current name; unless --auto-rename is enabled, it will be automatically cleaned and converted.

Naming rules

Valid ✅：button、btn-primary、[flow-y]layout(automatically strips tags),[abs]icon Invalid ❌：按钮(Chinese),Button<>(special characters)

Rules: By default, only layers matching [a-zA-Z0-9_-] are exported. If a layer name is in the form [tag]name , the system will automatically recognize and strip the tag, extracting name as the filename to ensure file system compatibility.

Dependency notes

Required dependencies

  • psd-tools: Core library for PSD file parsing

Optional dependencies

  • scikit-image: Used to export elements containing layer effects (such as shadows, glows, gradients, etc.)

Manual installation command

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

Note: When the current script detects missing dependencies, it only prints a warning and does not install them automatically. It is recommended to use psd-to-preview Pre-check function for skills, allowing AI to check and install dependencies before execution.

Common Scenarios

  • Web Development: Extract design elements as HTML/CSS assets
  • Component Export: Use -g -p component- to export marked components
  • Preview Generation: Prepare slice images for the psd-json-preview skill
  • Design Delivery: Batch export all layers of a design file

Quick Reference

User Keywords AI Should Execute
"Chinese Layers" / "Chinese Naming" The default is sufficient. For good compatibility with code generation, it is still recommended to first perform JSON extraction to generate the structure so it can be automatically applied by the slicer.
"Unified Renaming" / "ID Conversion" Use --auto-rename parameter
"Export Groups Only" / "Layer Groups" Use -g / --groups-only parameter
"icon-" prefix Use -p icon- parameter
"Strict Name Checking" Use -s / --strict-naming parameter
"Save to xxx" Use -o xxx parameter
"Do Not Export Text" / "Convert Text to Code" Use --skip-type parameter

Asset Files

  • scripts/export_slices.py - Core export script (219 lines)