# Logo-to-mockup tool: build notes for Eric **From:** Logan (written with Claude) **What this is:** what the website needs so a customer can upload a logo and get back three design concepts shown on the Maggy and the DJ-10 Midnight. Two files come with this: - `SKILL.md`: the full prompt for Claude. It is the system prompt for the job. Everything Claude needs to know about the products, the design style, colors, and Imgy is in there. - `dfg_art.py`: the Python toolkit the prompt tells Claude to use. It draws the artwork and calls Imgy. The same code is also pasted inside `SKILL.md` section 16. ## 1. How it works end to end 1. Customer fills in the form (section 2) and submits. 2. Your code creates a job folder, saves the logo and a `job.json` into it (section 3). 3. Your code runs Claude with `SKILL.md` as the system prompt, in an environment where it can run Python and look at images (section 4). 4. Claude builds six artwork files, calls Imgy for three mockups, and writes `result.json` into the job folder (section 6). 5. Your code reads `result.json` and shows the customer the three mockups and the message. A full run took several minutes per customer in testing, so this needs to be a background job with a waiting state, not a blocking page load. ## 2. The form Four inputs. Only the first two are required. | Field | Required | Details | |---|---|---| | **Business name** | Yes | Used in every file name. Claude strips it to letters, digits, spaces, `&` and `-`, max 40 characters. | | **Logo drop zone** | Yes | Accept `.svg`, `.pdf`, `.ai`, `.png`, `.jpg`, `.jpeg`, `.webp`. Suggest a 10 MB limit. Tell customers vector files (SVG, PDF, AI) give the best result and PNGs should have a transparent background. EPS is not supported. | | **Primary color picker** | No | Standard color picker plus a hex text box. Must be clearable. Send as `#RRGGBB` or null. | | **Secondary color picker** | No | Same. | | **Design style** | No | Short free text, suggest a 300 character limit. Placeholder idea: "Bold and sporty", "Clean and professional", "Patriotic". Fine to leave blank. | **Why the color pickers matter.** Many customers upload a logo that is only black or only white, which tells Claude nothing about their brand color. Without a picked color, Claude falls back to a neutral black and charcoal set. With one, it builds the whole palette around it. When both a picked color and logo colors exist, the picked color wins. **How Claude uses them** - Primary: the background of the plain concept, and the base that every other shade is derived from. - Secondary: an accent only (pinstripes, one stripe). It never becomes a background. If empty, the accent is white. - Light colors like yellow are handled specially (dark logo instead of white, no muddy darkened shades). **Nice to have, not required:** after the logo uploads, pre-fill the pickers with colors detected in the logo so most customers just confirm. `dfg_art.Logo(path).colors` returns them as `[(hex, share), ...]`. ## 3. What your code hands to Claude One folder per job, containing the logo and `job.json`: ```json { "customer_name": "Securenet", "logo_file": "logo.svg", "primary_color": "#1174AC", "secondary_color": null, "style_note": "Clean and professional" } ``` Save the upload under a name you choose (`logo.`), not the customer's file name. Three environment variables for the process Claude's code runs in: | Variable | Value | |---|---| | `DFG_JOB_DIR` | The job folder as Claude's code sees it. Claude writes only inside it. | | `DFG_JOB_SERVER_PATH` | The same folder as the file server sees it. Must start with `/opt/files/`. If the code runs on the DFG server itself, this is identical to `DFG_JOB_DIR`. | | `IMGY_API_KEY` | The Imgy key. It is deliberately not in the prompt. Keep it server-side only. | Suggested location: `/opt/files/imgy/web//`. ## 4. Running Claude Claude needs three abilities for this job: run Python, read and write files in the job folder, and look at the images it makes (it checks its own work visually, and that is what catches mistakes). **Anthropic's hosted code sandbox will not work for this.** Per their docs, it has no internet access (so no Imgy calls), and you cannot install packages, and it lacks `cairosvg`, `opencv` and `pdftocairo`. The Python has to run on infrastructure you control. Two reasonable ways to do that: - **Messages API with your own tools.** Define a "run Python/bash" tool and a "view image" tool, run them on your side, and loop until Claude stops calling tools. - **Claude Agent SDK** running headless on your server, pointed at the job folder, with `SKILL.md` as the system prompt. It already has file, shell and image-viewing tools built in. Either way, **sandbox it.** Claude will be writing and running Python while handling a file and text from a stranger. Run it as a restricted user or in a container or VM that can only touch its own job folder, can only reach Anthropic, `imgy.dfgadmin.com` and `files.dfgadmin.com`, and has a time limit. The server has no Docker installed today. ## 5. The Imgy side This is the part that was blocking mockups in testing. Three things must be true. **1. Imgy has to be able to read the artwork.** Imgy takes each layer as an absolute path under `/opt/files/` or an `https://` URL. It cannot read from wherever Claude's code happens to run. Putting the job folder under `/opt/files/` solves it: Claude saves `art/x.png` in the job folder and passes Imgy `/art/x.png`. If you run Claude's code on a different machine, you need either a synced or mounted folder, or a small upload endpoint added to Imgy that accepts a PNG and returns its server path. **2. The key is in the environment** as `IMGY_API_KEY`. **3. The template and layer keys match.** The toolkit uses: | Setting | Value | |---|---| | Endpoint | `POST https://imgy.dfgadmin.com/api/external/batch` with header `X-Api-Key` | | Template slug | `maggy-and-dj-10-midnight-model-holding-forward` | | Layer keys | `Maggy` and `DJ-10` | | Output | One 1080 x 1920 PNG per concept, written to `/mockups/` | | Artwork PNG sizes | Maggy 732 x 732, DJ-10 709 x 650, transparent outside the plate shape | `dfg_art.job_mockups(job, files)` builds the request, sends all three concepts in one call, and downloads the results. **Things to know about Imgy's behavior** - **A wrong layer key or unreadable file fails silently.** Imgy falls back to the template's sample art (an American flag on this template) and still reports success. The prompt tells Claude to look at every mockup for this. If you ever rename the template's layers, update `TEMPLATE` and the keys in `dfg_art.py` and section 11 of the prompt. - **Same output folder and name overwrites.** Useful for re-renders. - **Results are public.** Imgy returns a `files.dfgadmin.com` URL, and that host shows directory listings. Anyone who finds the `web/` folder could browse every customer's logo and concepts. Use unguessable job IDs and consider turning off listing for that folder. - **Nothing cleans up.** Decide how long job folders live. ## 6. What comes back Claude writes `result.json` in the job folder: ```json { "status": "complete", "customer_message": "Your three concepts are ready! ...", "concepts": [ { "number": 1, "name": "Classic Blue", "description": "Your logo in white on a solid field of your blue.", "artwork": { "maggy": "art/....png", "dj10": "art/....png" }, "mockup": "mockups/....png", "mockup_url": "https://files.dfgadmin.com/..." } ], "notes_for_dfg": ["..."] } ``` | Status | Meaning | What to show | |---|---|---| | `complete` | Artwork and mockups done | The three mockups with each `name` and `description`, plus `customer_message` | | `artwork_only` | Artwork done, Imgy failed | `customer_message` (it explains previews hit a snag). Alert someone at DFG; the error is in `notes_for_dfg` | | `needs_new_logo` | Logo unusable | `customer_message` (it says what file would work) and let them re-upload | | `declined` | Logo or request breaks a content rule | `customer_message` | `notes_for_dfg` is for staff only. Never show it to the customer. If `result.json` is missing when the run ends, treat it as a failure. ## 7. Server setup I checked the DFG server (read-only) on 2026-10-08: | Item | Status | |---|---| | macOS 15.3.1, arm64 | | | Python 3.14.6 (Homebrew) | Present | | `numpy` 2.5.3, `Pillow` 12.3.0 | Present | | `pdftocairo` 26.03 (poppler), `rsvg-convert` | Present | | `opencv`, `scipy`, `cairosvg` | **Missing.** The toolkit needs all three | | `anthropic` Python package | Missing | | Docker | Not installed | To install: `pip install opencv-python-headless scipy cairosvg anthropic`, ideally in a virtualenv. `cairosvg` also needs the cairo library (`brew install cairo` if it is not found). The toolkit was developed on Python 3.13 on Linux; it has not been run on Python 3.14 or macOS, so confirm those packages install there and run the smoke test below. ## 8. Testing **What has been tested** - The toolkit on five real logos: a wide single-color wordmark, a multi-color wordmark, a stacked lockup with small text, a round single-color mark, and a PNG. - A live Imgy render through the toolkit's Imgy function, using artwork already on the server. - A blind run: a fresh Claude given only an earlier version of the prompt and an unseen logo produced three usable concepts. The gaps it exposed (light colors, round logos, named colors) are fixed in this version. **What has not been tested** - The whole flow running through the API on your infrastructure. - `job_mockups()` translating job-folder paths on the real server. - The toolkit on Python 3.14 and macOS. - This updated prompt in a second blind run. **Smoke test once it is installed** 1. Make a job folder under `/opt/files/imgy/web/test1/` with a logo and a `job.json`. 2. Set the three environment variables and run: ```python import os, dfg_art as A job = A.load_job() logo = A.Logo(job['logo_path']) files = A.standard_three(logo, job['customer_name'], os.path.join(job['dir'], 'art'), primary=job['primary_color'], secondary=job['secondary_color']) print(A.job_mockups(job, files)) ``` 3. You should get six artwork sets in `art/` and three mockups in `mockups/`, each showing the uploaded logo on both products. If a mockup shows a flag, the layer keys or file paths are wrong. That proves the toolkit and Imgy. After that, run the same job through Claude with `SKILL.md` and check `result.json`. **Before launch**, run ten or so varied logos through it: wide wordmark, round mark, multi-color, PNG with and without transparency, a lockup with a tagline, black-only with no color picked, a very light picked color, and something that should be declined. ## 9. Decisions that are yours - Messages API with custom tools, or the Agent SDK. - How to sandbox the code Claude runs. - Where job folders live and how long they are kept. - Rate limits, since each run costs API usage and a few Imgy renders. - Which model to use. The designs in this project were made with an Opus-class model; a smaller model will be cheaper and should be tested for design quality before you commit to it. Source for the sandbox limits: https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool