Converting PSD Design Files to HTML: Architecture, Parsing Engine Comparison, and Implementation Details

Origin

During a casual chat with designers we discovered that most design hand‑offs use Sketch, while PSD files are rarely supported because Sketch maps well to CSS but PSD lacks a clear mapping, making parsing difficult.

Overall Design

The system consists of three layers: a web service for file upload, a parsing service that reconstructs layers and extracts properties, and a web service that generates the final page layout, preview, download, and storage.

Parsing Service

3.1 PSD Parsing Engine Comparison

We evaluated two popular PSD parsers and chose ag-psd over psd.js based on criteria such as parsing basis, star count, update frequency, issue response time, image mode support, traversal method, color mode, image handling, CSS conversion, and data size.

Parser

psd.js

ag-psd

Parsing basis

psd.rb parser

Photoshop official docs

Stars

2.5k

297

Update frequency

Last year

Last month

Issue response

Weeks‑months

Days

Image mode support

Limited

Almost all

Traversal

Plugin API

Raw data manipulation

Color mode

rgba

rgba

Image handling

to PNG

Canvas API

CSS conversion

Limited properties

Many properties

Data size (6.8 MB PSD)

135 KB

34.1 MB

Success rate

Issues with duplicate layers

100 %

Result: despite a lower star count, ag-psd outperforms in all other aspects, so we adopted it.

3.2 Layer Reconstruction

We classify layers into three types: group , text , and image . Groups may contain any layer type, while text layers only contain text.

export enum LayerShowType { GROUP = 'group', TEXT = 'text', IMAGE = 'image' }

Steps:

Filter hidden layers (opacity 0, hidden false, width 0) and remove them.

Handle positioning by preserving absolute coordinates from the PSD.

export type Location = { left?: number; top?: number; right?: number; bottom?: number; }

3.3 Property Parsing

Common properties (width, height, opacity, borderRadius, backgroundColor) are directly mapped to CSS. Text properties require more work: boolean flags for underline, strikethrough, bold, etc., and conversion of PSD’s leading to CSS line‑height.

class Text { fontFamily = ''; fontSize = 0; color = ''; fontWeight = FontWeight.NORMAL; text = ''; lineHeight = 0; }

Example of raw PSD style runs:

{ "styleRuns": [ { "length": 1, "style": { "fontSize": 24, "autoKerning": false, "fillColor": {"r":9.0,"g":0,"b":137.0,"a":1} } }, { "length": 69, "style": { "fontSize": 24, "autoKerning": true, "fillColor": {"r":225.99,"g":61.15,"b":61.15,"a":1} } } ] }

Web Service

The web service invokes the parsing service, receives a JSON describing the page, and uses cheerio (a Node‑js DOM manipulation library) to build the final HTML. Elements are created based on layer type (div for groups, p for text, img for images) and styled with absolute positioning.

$imgEle(`#${id}`).attr('src', dataURL); $imgEle(`#${id}`).css('position','absolute'); $imgEle(`#${id}`).css('left', `${left*ratio}${unit}`); /* …other CSS properties… */

Because mobile designs use a 750 px width baseline, we convert pixel units to rem (base font‑size = 100 px) and add a small width compensation for text to avoid line‑break issues.

let newWidth = (Math.ceil(width/10)*10*ratio + 0.3) + unit;

File Storage & Result Display

Generated HTML files are uploaded to WOS for online preview. The conversion achieves roughly 85 % visual fidelity compared to the original PSD.

Future Plans

Significantly improve design‑to‑HTML fidelity.

Complete an online PSD design‑preview feature for front‑end developers.

Integrate PSD annotation capabilities into the Fenghuolun platform.

To try the tool, visit the Picasso website, click the “Parse PSD” button, or explore the open‑source project on GitHub.