agentleFS
s-frantzs-frantz/sleek-geospatial-skills/.claude/skills/ui-icons/SKILL.md

ui-icons

Skill0 starsChanged 2 months agoMITView on GitHub

Size and centre icons objectively by measuring the drawn ink with npm run icons, treating SIZE and CENTRING as the two separate problems they are. Use whenever an icon "looks off", a new control button is added, or glyph art changes.

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    ONLY when the glyph genuinely should read a different size than its neighbours (see below).

    line 68
  2. Distinctive:

    Every time. A size change moves the ink centre, so a centring correction computed before a size change is stale.

    line 97
  3. Very specific:

    Never: put a number in SIZE_FACTOR or NUDGE that did not come from the measurer.

    line 102

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Icon centering

Where an icon sits and how big it is are settled by measurement, not by eye and not by arithmetic on path data.

Why both of the obvious approaches fail

Glyphs here share a 24-unit viewBox and a 2-unit stroke. Two things follow that are not obvious, and each has already shipped as a bug in this repo.

1. Equal art boxes do not give equal-looking icons. Each glyph fills its viewBox by a different fraction. Measured, in this app: at the same nominal size, the gear drew 17.00px of ink and the info circle drew 15.50px, because the gear runs to the edge of its box and the circle stops short. The CSS insisted they matched. They did not.

2. A centred art box does not give a centred icon. place-items: center and margin: auto centre the BOX. If the ink sits high inside the art, the glyph draws high, and no size change will ever fix it.

So there are two independent problems, SIZE and CENTRING, with two independent fixes, and conflating them is why "I fixed the icons" gets said more than once.

The loop

1. Measure

npm run icons

It starts the app, screenshots each on-screen icon button at 2x, finds the ink by pixel difference against the button's own face colour, and prints:

  glyph            ink w x h     want     dx      dy    headroom T/R/B/L
  gear             17.00 x 17.00  17.00    0.50    0.50    7.00  6.00  6.00  7.00
  info             17.50 x 17.50  17.00    0.25    0.25    6.50  6.00  6.00  6.50
columnmeaningpasses when
ink w x hthe glyph's real bounding box, CSS pxlong axis within sizeTolerance of want
wantthe intended size — see below
dx, dyink centre minus BUTTON centreboth within centreTolerance
headroomink to each button edgeleft equals right, top equals bottom

Negative dy means the glyph sits high. Left and right headroom that disagree is the thing the eye registers as "that one looks pushed over" without being able to say why.

It exits non-zero when anything of ours is out of tolerance, so it belongs in a verify chain. A row for a button the measurer found but this app didn't draw (a third-party control it doesn't recognise) prints (not ours) and is informational only — it never fails the build.

Where want comes from

Three sources, in priority order, from scripts/icon-ink.mjs:

const want = TARGETS.want[name] ?? meta.ink ?? TARGETS.defaultWant;
  1. scripts/icon-targets.json's want block — an explicit override for one glyph, used ONLY when the glyph genuinely should read a different size than its neighbours (see below).
  2. data-ink, the size the glyph's own caller asked for via icon(name, size). Most glyphs are covered here — a 17px control glyph and a 13px row glyph are measured against their own request, not one repo-wide number.
  3. defaultWant in the same JSON file, the fallback for a glyph nobody has opinionated about at all.

The override in (1) exists for exactly one documented reason today: a plus and a minus are bare strokes reaching the full extent of their box with nothing in between, so the eye reads their whole box as the glyph. A gear measured to the same number is a dense shape whose bulk sits inboard of its widest teeth — matched by the ruler, the cross reads a size larger than its neighbours. icon-targets.json sets plus/minus to 14.5 against everything else's 17, with the reasoning written in the file itself, because this is the one place in the repo where a number is an optical judgement rather than a measurement — writing it out loud in the targets file is what keeps it from being quietly mistaken for one if it moved into SIZE_FACTOR.

2. Fix ONE problem

Both tables are in app/js/icons.js.

Size is SIZE_FACTOR. New factor = old factor x want / measured. The info glyph: 1.1 x 17 / 15.5 = 1.21.

Centring is NUDGE, in viewBox units, positive y moving the glyph down. Convert the reported dy in CSS pixels: nudge_y = -dy x 24 / renderedBoxPx.

3. Re-measure

Every time. A size change moves the ink centre, so a centring correction computed before a size change is stale.

Rules

  • Never put a number in SIZE_FACTOR or NUDGE that did not come from the measurer. An entry is a result. A guess reads exactly like a result and is worth less than an omission, which is why unmeasured glyphs are simply absent from both tables rather than set to a plausible value.
  • Never adjust a number because a screenshot looked better afterwards.
  • Guides (document.body.classList.add('sgs-guides')) draw the button's centre lines in red. They SHOW a problem; they do not measure it.
  • A glyph is only responsible for its own box. The measurer subtracts the button's sub-pixel position before comparing ink centre to box centre, because an element screenshot is cropped on whole device pixels: a button whose box starts at x=181.86 is captured from x=181 and everything in it sits 0.86px late in the crop. The panel is width: max-content, so its width comes from text metrics and is fractional almost always, and renaming a demo layer once reported the pin as 1px off centre with the art untouched. Charging that to the glyph would have put a compensation for one label's width into NUDGE, where it would be wrong for every other label forever. The crop origin is FLOORED, which is measured rather than assumed: rounding to nearest moved the reported offset the wrong way.
  • The corollary: genuinely half-pixel chrome renders soft and this tool will not say so. That is a layout check, and it is not this one.
  • The measurer insets 2 CSS px (INSET_CSS in scripts/icon-ink.mjs) before it starts looking for the button's own face colour. A rounded corner's pixels are transparent, which resolved to black in the very first version of this script, made the whole button read as "ink", and reported every glyph as filling its box — a caught bug, not a hypothetical one.

When to run it

  • A new control button.
  • Any change to glyph art in icons.js.
  • An icon that "looks off". Measure before touching anything: about half the time the ink is correct and what is actually wrong is the button's padding.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.