layered_design_file_editing v1.0.0

name: layered_design_file_editing description: Edit layered design files without the original app: open PSD, PSB, and Illustrator AI files in open source or browser editors, keep the source untouched, save edits beside the original, and prove layers, fonts, and color mode survived the round trip with an audit script and survival checklist. Use when a PSD or AI file arrives and Photoshop or Illustrator is not available, when choosing between GIMP, Krita, Photopea, and Inkscape for a layered file, or when a round trip may have flattened layers, substituted fonts, or shifted color.

Layered Design File Editing

Purpose

Get a real edit out of a layered file you did not create, in an editor you do have, without quietly wrecking the file. The core habit is a tested round trip: audit the original, edit a copy, save beside the original in the editor's native format and in the delivery format, then audit again and log every loss you found. A file that looks right on screen can still have lost editable text, a mask, or its color mode. This skill catches that before delivery.

Workflow

1. Protect the original. Copy the incoming file into the job folder and work on the copy. Record the original's size and checksum (sha256sum file.psd on Linux or macOS) in the change log. Nothing in this workflow ever saves over the only original.

1. Audit before you open anything. Run the bundled script on the original: python3 scripts/audit_design_file.py poster.psd It reads the PSD header (width, height, channels, depth, color mode, layer count) or reports whether an AI file is PDF-based, and it never writes to the file. PSD color modes per the Adobe specification are Bitmap, Grayscale, Indexed, RGB, CMYK, Multichannel, Duotone, and Lab, with depth 1, 8, 16, or 32 bits per channel. If the script exits with code 2, the file is not what its extension claims. Stop and report that instead of forcing it into an editor.

1. Export a flat reference. Before editing, export or save a flat PNG of the original at full size and keep it as reference-original.png. Every later visual check compares against this render, not against memory.

1. Pick the editor by file and job, using references/editor-matrix.md. Short version: Photopea for a quick PSD edit with no install, GIMP 3 for installed RGB raster work, Krita for paint-heavy or CMYK-origin PSDs, Inkscape for vector-first AI files, Photopea again for AI files that mix raster and vector. The matrix is editor-neutral and lists the first loss to test for in each editor.

1. Open the copy and inventory before editing. Count layers and groups, expand every group, and note text layers, masks, adjustment layers, Smart Objects or linked objects, and layer effects. Compare the count against step 2. If layers are already missing at open, that is an import loss, not an edit. Log it and, if the missing piece matters, try a second editor before doing any work.

1. Sort fonts before you touch text. List the fonts the file names, then check which are actually installed (fc-list on Linux, Font Book on macOS, or the editor's font menu). Adobe's own help is clear on the pattern in its apps: a missing font gets substituted with a default and highlighted, and preview-only fonts cannot be edited as real text. Substitute editors do the same kind of quiet swap. So: install the real font if you have the right to use it, or pick a substitute on purpose, log the swap and its effect on line breaks, and never let a default substitution ship unnoticed. If the text must stay pixel-perfect and the font is missing, edit everything except that text layer and say so.

1. Edit in the editor's native format first. Save the working file as XCF (GIMP), KRA (Krita), or SVG (Inkscape) beside the original, with a versioned name such as poster-v2.xcf. Native formats hold the most structure. Export the delivery PSD, PDF, or SVG only after the edit is done, as poster-v2.psd in the same folder. Saving straight back to PSD on every save degrades the file a little each round trip.

1. Run the round trip test. Close the delivery file, reopen it in the same editor, and run references/survival-checklist.md line by line: document size, depth, and color mode, layer count, names, order, groups, masks, blend modes, editable text, fonts, and vector paths. Then audit the delivery file and diff it against the original audit: python3 scripts/audit_design_file.py poster.psd poster-v2.psd Worked result from testing this script: a copy with its mode byte changed reported color_mode: 'RGB' -> 'CMYK' as the only diff, and an unchanged copy reported no header diffs. Also export a flat PNG of the edited file and flip it against the reference from step 3. Explain every difference, or log it as unexplained.

1. Handle color mode honestly. If the original is CMYK and the job is for print, say early that GIMP 3 edits in RGB and converts to CMYK on export (late binding, in the GIMP team's words), and that Photopea and Krita each handle CMYK-origin files differently. A mode change on the round trip is a delivery fact for whoever owns the print job, not a footnote. For screen work, an RGB original that comes back CMYK, or the reverse, is a failed round trip until someone approves it.

1. Check any companion short clip as a render only. Jobs sometimes ship with a preview MP4 or MOV. Probe it with ffprobe -v error -show_entries stream=codec_type,width,height -of default=noprint_wrappers=1 clip.mp4. A clip is flat video. It shows how the design looked, it holds no layers, and re-cutting it is not editing the design. If your edit changes the design, log that a fresh preview render is owed.

1. Write the change log and deliver. One log per job, saved beside the files as change-log.md, using the template in the Output Contract. Name what the editor changed on import, what you changed on purpose, what was lost, and what you could not test. Hand over the native work file, the delivery file, and the log together.

Output Contract

Every job leaves with:

• The original file, byte-identical to how it arrived (checksum matches step 1).
• A native work file beside it (.xcf, .kra, .svg, or a PSD work copy from Photopea), versioned, never named final.
• A delivery file beside the original (.psd, .pdf, or .svg), versioned to match the work file.
• reference-original.png and a flat export of the edited file, same dimensions, for visual comparison.
• A completed survival checklist from references/survival-checklist.md, with fails marked, not deleted.
• change-log.md with these sections: Source (file, checksum, audit output), Editor (name, version, platform, why chosen), Import changes (what the editor altered before any edit), Edits (what you changed, layer by layer), Losses (fonts substituted, layers or effects dropped, color mode or depth changed, with reasons), Untested (anything you could not check, and why).

Operating Rules

1. The original is read-only in practice. Work on a copy, save beside it, and prove the checksum at the end.
2. Editor-neutral by default. Choose from the matrix per job and record why. Loyalty to one editor is how files get mangled in the wrong tool.
3. No silent flattening. If an edit needs a merged copy, merge a duplicate layer or a duplicate file and keep the layered version intact.
4. No silent font substitution. Every missing font is either installed, deliberately replaced and logged, or left alone with the limitation stated.
5. Test the round trip on the actual file, every time. Claims about what an editor usually preserves are a starting guess. The checklist result on this file is the evidence.
6. State color limits plainly and early, especially CMYK for print. Do not promise native CMYK editing in an editor that converts on import or export.
7. Outlining text, rasterizing a Smart Object, or baking an adjustment layer is a one-way door. Do it only on a copy layer, and log it as a loss of editability.
8. If two editors both lose a feature the job needs, stop and report the gap with the two audit and checklist results, instead of shipping a file that only looks right flattened.
9. Keep private client files local where the tool allows it. Note in the log if an editor processed the file on a remote server, and get the file owner's word before using that route for sensitive work.