psd-layer-reader

PSD Layer Reader

Overview

Export the PSD layer tree as JSON, filter by layer name, and return only matching branches. This skill is especially suitable for the early research phase of converting design mockups into code, enabling quick location of layers and retrieval of coordinates and styles.

Workflow

1) Install dependencies (only once per environment)

py -3 -m pip install psd-tools

2) Export the full layer tree (JSON)

py -3 -X utf8 scripts/psd_layers.py "path/to/file.psd" --output "psd_layers.json"

3) Export only matching branches (exact match)

py -3 -X utf8 scripts/psd_layers.py "path/to/file.psd" --name "rule-modal" --output "rule_modal.json"

4) Export only matching branches (contains match)

py -3 -X utf8 scripts/psd_layers.py "path/to/file.psd" --name "modal" --match contains --output "modal.json"

Output format (JSON)

Each node contains the following key fields:

• name (string): Safe name. After normalization, special characters are removed, ensuring it can be used directly for variable names or file names.
• originalName (string): Original layer name. Preserves the real name in the PSD for tracing and debugging.
• layerId (integer): Unique ID within the PSD, used for disambiguation.
• kind (string): Layer type (such as group, type, pixel）。
• visible (boolean): Whether it is visible.
• bbox ([x1, y1, x2, y2]): Layer bounding box coordinates.
• layoutTag (string|null): Layout tag extracted from the layer name (such as flow-y, fixed). If the layer name is [flow-y] content, then layoutTag is flow-y。
• textInfo (object|null): Only for text layers (kind == 'type')。
  • text: Full text content.
  • runs: List of text segments containing different styles.
  • fontSize, color, fontName, leading etc.: Style summary of the first text segment.
• children (array): List of child nodes.

Best practices and tips

• Name conflict handling: If there are duplicate layer names in the PSD, thename field automatically appends layerId(such as button-123) to ensure the uniqueness of the JSON structure.
• Layout restoration: When restoring HTML, prioritize referring to layoutTag. Layers with [flow-y] or [flow-x] tags usually correspond to Flex layout.
• Text extraction: If the text color or size is inaccurate, check textInfo.runs. Complex text layers may contain multiple styles within the same line.
• Encoding handling: When running scripts on Windows, be sure to include the -X utf8 parameter, otherwise processing Chinese layer names may cause errors.

Resources

• scripts/psd_layers.py: Core script for exporting the PSD layer tree. Supports --verbose to view conversion details.
• scripts/layer_parser.py: Layer information parsing logic.
• references/PSD_TOOLS_TEXT_EXTRACTION_EXAMPLES.md: Technical reference for psd-tools text layer extraction.