psd-json-preview

PSD JSON → HTML Preview

Generate static HTML/CSS previews from JSON layer trees and sliced images exported from PSD.

⭐ New Feature：

2026-02-11: Supports generating React components (JSX + CSS Modules) while generating HTML previews

Quick Start

Generate HTML preview + React components

py -3 scripts/generate_preview.py \
  --json /path/to/layer-tree.json \
  --images /path/to/images \
  --out /path/to/preview \
  --generate-react \
  --component-name MyComponent \
  --preserve-names

This will generate both:

HTML preview page (preview/index.html）
React components (preview/react-component/index.jsx + index.module.less）

Default mode: Generate only HTML preview (preserve group structure)

py -3 scripts/generate_preview.py \
  --json /path/to/layer-tree.json \
  --images /path/to/images \
  --out /path/to/preview

The generated HTML will preserve the PSD's group nesting, for example:

<div class="canvas">
  <div class="group_rs_card">
    <div class="layer_rs_layer_3"></div>
    <div class="layer_rs_layer_2"></div>
    <!-- ... -->
  </div>
</div>

Flat mode: All layers are flattened onto the canvas (old behavior)

py -3 scripts/generate_preview.py \
  --json /path/to/layer-tree.json \
  --images /path/to/images \
  --out /path/to/preview \
  --flatten

After adding the --flatten parameter, all layers will be placed directly under the canvas, without preserving group relationships.

Output Structure

Generate preview only

preview/
├── index.html    （HTML 预览页面）
├── styles.css    （CSS 样式文件）
└── images/       （复制的图片资源）
    └── <copied slices>

Generate preview + React components

preview/
├── index.html           （HTML 预览页面）
├── styles.css           （CSS 样式文件）
├── react-component/     （React 组件）
│   ├── index.jsx           （React 组件代码）
│   ├── index.module.less  （CSS Modules 样式）
│   └── images/            （组件图片资源）
│       └── <copied slices>
└── images/              （预览图片资源）
    └── <copied slices>

Expected JSON Structure

The JSON should be an array (or object), with node structure as follows:

{
  "name": "layer-name",
  "kind": "group|pixel|type",
  "visible": true,
  "bbox": [x1, y1, x2, y2],
  "children": []
}

The script uses bbox for positioning, and matches image files by name:

layer-name → layer-name.png(.jpg/.jpeg/.webp are also supported)

Core Behavior

Default mode (preserve groups)

✅ Automatically recognizes kind: "group" layer groups
✅ Generates nested <div> structures
✅ Automatically calculates relative coordinates (child layers are positioned relative to the parent container)
✅ Group containers automatically add position: absolute rules
✅ Convenient for subsequent manual adjustments and maintenance

Flat mode (--flatten)

All layers are placed directly under the canvas
Uses absolute coordinates (relative to the canvas)
Suitable for quick previews and design verification
Not convenient for subsequent code maintenance

Command-line Parameters

python scripts/generate_preview.py --help

Key parameters:

--json: JSON layer tree file path (required)
--images: Image directory path (required)
--out: Output directory path (required)
--flatten: Use flat mode (do not preserve group structure)
--dict: Project-level layer name translation dictionary JSON file path (optional, used to translate project-specific terms such as pinyin/abbreviations)
--copy-all: Copy all images (not just matched ones)
--include-text: Render text layers as <div> tags (disabled by default). When this parameter is enabled, the script will directly read the text content and styles from the JSON for HTML restoration, instead of looking for the corresponding sliced images. This is very important for scenarios that need to preserve page copy editability, SEO friendliness, or reduce image size.
--generate-react: Also generate React components (JSX + CSS Modules)
--generate-vue: Also generate Vue components (Single-File Components SFC)
--component-name: React component name (default is PsdComponent)
--preserve-names: Preserve the original PSD layer names as class names in React components (convenient for design correspondence)

Usage Recommendations

When to use default mode (preserve groups)

✅ Need to generate easily maintainable code
✅ Styles will be manually adjusted later
✅ The PSD design has a clear group structure
✅ As a starting point for front-end development

When to use tiling mode (--flatten)

✅ Only for design draft verification
✅ Quick effect preview
✅ PSD group structure is messy or meaningless
✅ As design delivery documentation

Technical details: automatic handling of group structure

In default mode, the script automatically:

Identifies groups: detects nodes of kind: "group" nodes with
Generates nested HTML: creates a container for each group <div>
Calculates relative coordinates: child layer coordinates = original coordinates - parent container offset

Generates CSS rules：

/* 分组容器 */
.group_rs_card {
  position: absolute;
  left: 119px;
  top: 145px;
  width: 620px;
  height: 849px;
}

/* 子元素定位规则 */
.group_rs_card > div {
  position: absolute;
  display: block;
}

/* 子图层（相对坐标） */
.layer_rs_layer_3 {
  left: 194px; /* 313 - 119 */
  top: 0px; /* 145 - 145 */
  width: 343px;
  height: 284px;
}

Note

If a layer cannot find a matching image, it will be skipped (unless --include-text）。
If the JSON root node is an array, use the first node containing bbox as the canvas.
By default only copiesmatchedimages to output/images。

Reference

For naming and mapping instructions, see references/json-format.md。
For the manual grouping guide for tiling mode, see references/MANUAL_GROUPING.md(only for --flatten mode).