Logo Clinic

---
name: logo-clinic
description: Gives a logo an honest examination and hands back one self-contained HTML report that prints to A4, with an overall score, a weighted scorecard, real stress tests run on the actual image (16 px and 32 px favicon, one colour, inverted, blurred at a distance, greyscale, busy background, on black), the single biggest problem and three to five specific changes. Compares two to four candidates and picks one. Judges Chinese wordmarks properly, including stroke clogging. Use when someone asks whether a logo is any good, which logo to choose, why a logo looks bad small, or wants a logo review or critique. Not a trademark or originality check.
version: 1.1.0
---

# Logo Clinic

Someone hands over a logo, or a few candidates, and gets a verdict they can act on. The tests are run by script on their actual file. Your job is to run them, then read the results honestly and write the judgement.

## For someone who just wants the result

Most people asking for this do not want to hear about scripts. Ask the questions below in plain words, do all the setup yourself, and hand over the finished file. Never ask them to install or run anything. Do not use words like favicon, SVG, raster, threshold or script with them: say "the little icon in a browser tab", "the logo file", "the test". When you deliver, say in two or three sentences what the verdict is and what to do first, and give them the file.

## Inputs to ask for

Ask once, in one message.

1. The logo image, or up to four candidates. PNG, JPG or SVG. If they only have a picture in a document or a screenshot, take it, and say a clean export would be more accurate.
2. The brand name.
3. Who the customers are, in a sentence.
4. Optional: where it will appear most (a shop sign, an app, packaging), and which candidate they are leaning towards.
5. For a Chinese logo: the characters exactly as they are written in the logo, in order.

If the brief is thin, restate what you were told, never invent facts about the brand, and list anything you inferred when you deliver. If nobody can answer, proceed with what you have and list your assumptions. A missing audience lowers what you can say about fit: say so in that row's note.

## Setup

Node.js is needed, plus Playwright with its browser. It draws the image in a local browser so that no image library is needed, and nothing leaves the computer.

```
mkdir -p /tmp/logo-clinic-tools && cd /tmp/logo-clinic-tools
npm install playwright && npx playwright install chromium
export NODE_PATH=/tmp/logo-clinic-tools/node_modules
```

Do this yourself, once, only if `scripts/examine.mjs` says Playwright is missing. If Chrome is installed, the script can use it when the Chromium download fails.

## Steps

1. Make a working folder and copy `assets/brief-template.json` there as `brief.json`.
2. Examine each logo. Each takes a few seconds:
   ```
   node scripts/examine.mjs --input logo.png --out exam/a
   ```
   For a Chinese wordmark add the character count, and `--vertical` if it reads top to bottom: `--han 3`. The count must be a whole number. A malformed value prints a `WARNING:` and the Chinese test is skipped, so check that `measures.json` has a `han` block. Read any line starting `NOTE:` or `WARNING:` and pass the point on to the person.
3. Read every `exam/*/measures.json` and look at the pictures in each folder, especially `f16x.png`, `one.png` and `busy.png`. Open them. Judge what you see, not only the numbers.
4. Fill `brief.json`:
   - `judged.fit` and `judged.idea`: your own scores from 0 to 100, with a note saying why. These are the only scores you set.
   - `verdict`: one honest sentence. A person should know what to do from it alone.
   - `biggest`: one problem, the one that matters most for this audience. Quote the measured numbers. Do not list several.
   - `changes`: three to five. Each is something you could brief a designer on today, with a number or a named element in it, tied to the test that exposed it. "Simplify it" is not a change. "Cut the wheat to three solid ears, each at least 8% of the mark's width" is.
   - `pick` when there are several candidates. Decide from the owner's actual uses. If two are close, say what would decide it. Choose one anyway.
   - `sketch` only when words will not do. Plain shapes, drawn roughly.
   - Delete optional blocks you do not use. `lang` is `en` or `zh`. Set `fictional` to true only for a made-up sample.
5. Build and check. The build refuses text that is too long, so shorten it rather than working around it. It reports every problem at once. Limits in characters, English / Chinese: brand 40 / 20, audience 70 / 34, verdict 76 / 32, biggest.title 56 / 24, biggest.body 250 / 110, biggest.evidence 100 / 50, each change `do` 86 / 38 and `why` 128 / 58, judged note 74 / 34, pick.why 300 / 130, sketch caption 96 / 42. For a Chinese wordmark, `hanText` must have exactly the `--han` count. Optional `hanFocus` (1 is the first character) chooses which character the one-character trial uses; without it the lightest is used, so set it when your prescription keeps a different one.
   ```
   node scripts/build.mjs --brief brief.json --out report.html
   node scripts/check.mjs report.html
   node scripts/render.mjs report.html --pdf report.pdf --shots shots --phone
   ```
6. Open every picture in `shots/`. Every sheet, then the phone view. Fix what reads badly, then rebuild.
7. Hand over `report.html` and, if they want something to attach or print, `report.pdf`.

## How to judge a Chinese wordmark

- Run with `--han`, and fill `hanText`. The report then adds a character clog test: for each character it counts how many strokes stack up, and works out the pixels it needs. Each stroke takes one pixel and each gap takes another.
- A 16-pixel icon shared between N characters gives each 16/N pixels. Say so plainly: for most names the answer is a one-character small version, and the report names the lightest character.
- Light Song-style faces lose horizontal strokes first, because they are much thinner than the verticals. Quote the thinnest stroke figure.
- Judge characters as characters. Does it still read as the right character, or as a similar one? Does the small version change the meaning? Measurements cannot tell you this: the stress tests only count strokes and pixels and cannot read whether a character is still legible as the right character. You must look at the character pictures yourself, and say in the report and to the person that this part is your judgement, not a measurement.
- Write in natural Chinese with no English interface words. Use 像素, 通过, 注意, 不合格.

## What you must never do

- Never say a logo is original, unique, safe to trademark or free of conflict, and never say it resembles a particular brand as a legal finding. If asked, say a trademark search is a separate job for an official register or a trademark attorney. Every sheet carries that notice.
- Never redraw the logo as if it were the owner's final logo. A sketch is rough, in the report only, and always stamped as a sketch.
- Never retouch or fabricate a test picture, or write a score that did not come from the exam. The check compares every test picture with the exam's fingerprints.
- Never soften a failing result to be kind. Be plain about the logo, and kind about the person: they have a problem you can name and they can fix.
- The build refuses a brand name on a short built-in list of very well-known companies unless the brief says `"entitled": true` (for example client work). The list is short and cannot catch every company, so the rule below still applies to every logo.
- Never add another company's logo to the report, for instance as a comparison. Real company logos do not go in examples or shared samples. If someone sends you a logo that plainly is not theirs, review it only if they are entitled to, such as for a client.

## Other situations

- **A different length.** The report's structure is fixed. For a one-line answer, give the verdict and top change in your message and still attach the report.
- **Logo on a photo, or a very small image.** The script warns you. Run it, say the results are less reliable, and ask for a clean export.
- **SVG with live text.** The script warns that the letters use this computer's fonts. Ask for outlines if the result looks wrong.
- **A logo meant only for large use,** such as a sign. Report it as measured, then say in the verdict that small sizes matter less for them. The score stays as it is.
- **More than four candidates.** Ask them to pick four, or examine all and report on the best four, saying which you left out.
- **The file will not open.** The script says so in plain words. Ask for a fresh export.

## Before delivering

- [ ] `check.mjs` passes and `render.mjs` reports no overfull sheet and matching page count.
- [ ] I looked at every sheet and the phone view.
- [ ] The verdict could be acted on by someone who reads only that line.
- [ ] Exactly one biggest problem, with a measured number in it.
- [ ] Three to five changes, each specific and tied to a test.
- [ ] Any sketch is rough and stamped.
- [ ] No claim about originality or trademark anywhere, including in my message.
- [ ] Assumptions and inferred facts listed in my message.

## When not to use it

For a trademark search or legal opinion. For designing a new logo from nothing. For judging a whole brand identity, which needs more than the logo. For logos inside photos of signs or products, unless a cleaner file truly cannot be had.

## Requirements

Node 18 or later. Playwright (Apache-2.0) with Chromium, or Chrome. Everything runs locally, with no account, no paid service and no network requests from the report. System fonts only. A4 by default, which also suits Chinese print use.