Visual polish
Working output is the starting line. A page is done when a demanding designer
would stop on it. This skill is the loop that got the 3D scene from a muddy
slab to a framed, lit subject; it applies to any block.
The loop
Render the real thing. Compile a representative fixture and capture it
at 1440, 768 and 375 in light and dark, plus print/PDF:
pnpm build && pnpm visual:check fixtures/<x>.yaml --out out/vc
It writes all six captures, page.pdf and one thumbnail sheet.png, and
prints {frames:[{fill, offsetX, offsetY}]} for each 3D frame. Read the
sheet first; open a full capture only to inspect a detail. Never judge from
code or a description. Rasterise the PDF with
pdftoppm -r 60 -png -f 1 -l 1 out/vc/page.pdf out/vc/pdf when print changed.
Name what is wrong in designer words, one line each, with the image it
shows in: loose framing, subject off centre, muddy or glaring surface, colour
off the theme palette, flat light, duplicated hierarchy, dead space,
controls that mean nothing in a still image.
Fix the cause in the compiler or runtime, never in the fixture alone.
A fixture change is fine only when the fixture itself was wrong (a duplicate
title, a caption that describes something not drawn).
Re-render and compare before and after side by side. Keep a change
only if it is visibly better in both schemes and at phone width.
Run pnpm qa:pre (verify, snapshot, gallery and schema checks, browser
tests). Regenerate snapshots and gallery for intended changes first. QA only
ever sees a tree that passes it, so it spends its time on design.
Score it. Spawn the QA subagent described in AGENTS.md. While it runs,
keep working; fold its findings in when the report lands and re-score until
it scores 8 or above.
QA prompt template
Give the QA subagent fixed inputs so it does not explore the repo:
Score this round /10, engineering and design weighted equally. Budget 10 min.
Inputs: diff `git diff <last-qa-commit>..HEAD`, contact sheet <path>/sheet.png,
metrics <visual:check JSON>, qa:pre = green, open DoD from last round: <list>.
Round 1: review all. Later rounds: check open DoD and the new diff only.
Output, max 300 words: `Score: x/10 (eng y, design z)` then one line per
finding: `ID | blocker|minor | fix | DoD with a measurable threshold`.
Defaults that held up
Start from these instead of searching again: camera fov 30, subject fill
0.84 of the frame (visual:check fill ≥ 0.6 on the stage, or fillY ≥ 0.7 with\nmarginY ≥ 0.06 when a wide stage fills by height; fit a loaded model in the\nruntime with the real aspect, centring its projected box), centre offset
≤ 0.05, shadow radius 9 with 16 blur samples, exposure 0.8 dark / 1 light,
metal metalness 0.85 roughness 0.32.
Rules of taste that held up
Frame the subject, not the stage. Fit the camera to the meaningful
objects; floors and backdrops never set the framing. Centre the projected
bounds, then fill about 84% of the frame.
Ground through shadow. A floor reads best as soft contact shadow on the
stage's own gradient, not as a hard-edged plane. Anything the reader cannot
see must not appear in a legend or caption.
Light like a studio. Key, fill and rim; an environment for reflections
(generated in code, so still offline); filmic tone mapping; soft shadows sized
to the scene. Dark themes need lower exposure so pastel tones keep their
facets.
Colour only from tokens. Derive surfaces by mixing theme tokens
(color-mix) rather than reusing a text colour as a fill.
Atmosphere is subtle. A faint accent glow from the top, an inset
highlight, fog toward the page background. If you notice it first, it is too
strong.
One title per idea. A block title that repeats the page title is noise.
Phone width is a first-class layout. Give a 3D stage 4:3 under 480px so
it does not shrink to a strip.
Stills are stills. In PNG and PDF, freeze the live frame at device scale
2; hide interactive chrome that has no meaning on paper.
Graphs: dim, never erase. For a selection in a dense graph, mix the
other nodes a quarter toward the muted tone and about half toward the
background, so group colour still reads; a full fade turns 1000 nodes into
a grey blob. Do not select anything on load in a large graph.
Graphs: adjacent groups need distant hues. Order the tone cycle so
neighbouring clusters never share a warm hue (accent, info, success,
danger, neutral, warning). Fit the camera to projected node bounds, not to
the layout extent.
Products: details stand proud. A driver, dial or port must sit in front
of the panel it is mounted on, or the beauty shot shows a blank box. Check
the plan for internal parts too: skip a part wholly inside another.
Products: neutral finishes are mixes, not tokens. A graphite or chalk
finish mixes the muted ink toward black or the surface toward white, so it
reads as a material in both schemes instead of flipping with the theme.
Products: close-ups keep context. A hotspot camera stands about three
quarters of the home distance away, turned partly toward the hotspot's side;
any closer and an exploded part fills the frame.
Globes: mix in linear space with care. A shader mix toward a cream ink
turns the ocean tan; scale the surface navy instead. Put the sun west of the
view and a little north, so a warm terminator and night crescent show on the
eastern limb. The atmosphere is a back-face shell whose glow peaks at the
limb and fades outward.
Globes: dense routes thin out. Past a few dozen arcs, scale arc width and
opacity down with the count, and link near neighbours rather than random
pairs, or 200 arcs become a hairball. Cluster markers when far out.
Morphs: soft shading, sharp outline. A shaded SVG drawing of a smooth
surface bands badly at 8 steps. Use about two dozen shade steps, then draw
the faces once crisp and once blurred (stdDeviation about 4) under an alpha
mask of the faces themselves: gradients read smooth and the silhouette stays
sharp. Blurring the whole drawing looks out of focus.
Morphs: one material, glossy. Clearcoat 1, roughness about 0.26, a little
iridescence and sheen under the studio environment make a plain primitive
look designed; blend the target tones with the shape so colour tells the
reader which state is arriving.
Point clouds: one spacing wide. Size points to about the cloud's own
spacing (world diameter near 5 / sqrt(drawn points)) and nearly flat
(a dome of at most 0.08) so surfaces read as surfaces, not beads; fade far
points toward the background for depth instead of lighting them. Keep one
uniform scale on all axes, fit the projected box corners to about 0.84 by
0.8 of the frame centred 3% below the middle (refit for the real aspect),
and sit ticks close to the box edges with at least 6 px between labels and
one tick per shared corner.
Point clouds: eye-dome lighting gives depth without normals. Render the
points into a target with a depth texture, then darken each pixel by
exp(-30 * mean(max(0, log2 depth - log2 neighbour depth))) over an
8-neighbour ring; roofs and crowns get outlines against what lies behind
them. In the same pass, fill an empty pixel when 5 of the 8 inner or 6 of
the 8 outer (3 px) neighbours hold points, with the nearest one's colour,
so the ground never shows the stage through it. Draw the selection marker
after the pass so it is never shaded.
Point clouds: the ramp's lightness runs one way. Take hues from the
theme's info, success, warning and danger tones, set them to one lightness
with a chroma floor, then mix toward the text colour (up to 40%) in oklab
and lower chroma to fit the gamut instead of clipping. A ramp through the
accent token reads olive-khaki on a light page.
Point clouds: the static sample is dense enough to read. About 5,000
points in level-of-detail order at radius 0.0085 x focal / depth draws
roofs, crowns and lane lines; fewer reads as noise.
Done means
- Screenshots at 1440, 768 and 375 in light and dark, plus a rasterised PDF
page, viewed and clean.
- Every gate green.
- QA score of 8 or above, with each finding's Definition of Done met.
1---2name: visual-polish3description: Polish ak-render output until it looks striking and refined, then prove it with screenshots and a scored QA gate. Use after a block, theme, 3D scene or export works but before its PR is opened, or when a reviewer says the output looks plain, muddy, loose or off-palette.4metadata:5 source: https://skillmd.com/skills/bestagentkits/visual-polish6---78# Visual polish910Working output is the starting line. A page is done when a demanding designer11would stop on it. This skill is the loop that got the 3D scene from a muddy12slab to a framed, lit subject; it applies to any block.1314## The loop15161. **Render the real thing.** Compile a representative fixture and capture it17 at 1440, 768 and 375 in light and dark, plus print/PDF:1819 ```bash20 pnpm build && pnpm visual:check fixtures/<x>.yaml --out out/vc21 ```2223 It writes all six captures, `page.pdf` and one thumbnail `sheet.png`, and24 prints `{frames:[{fill, offsetX, offsetY}]}` for each 3D frame. Read the25 sheet first; open a full capture only to inspect a detail. Never judge from26 code or a description. Rasterise the PDF with27 `pdftoppm -r 60 -png -f 1 -l 1 out/vc/page.pdf out/vc/pdf` when print changed.282. **Name what is wrong in designer words**, one line each, with the image it29 shows in: loose framing, subject off centre, muddy or glaring surface, colour30 off the theme palette, flat light, duplicated hierarchy, dead space,31 controls that mean nothing in a still image.323. **Fix the cause in the compiler or runtime, never in the fixture alone.**33 A fixture change is fine only when the fixture itself was wrong (a duplicate34 title, a caption that describes something not drawn).354. **Re-render and compare** before and after side by side. Keep a change36 only if it is visibly better in both schemes and at phone width.375. **Run `pnpm qa:pre`** (verify, snapshot, gallery and schema checks, browser38 tests). Regenerate snapshots and gallery for intended changes first. QA only39 ever sees a tree that passes it, so it spends its time on design.406. **Score it.** Spawn the QA subagent described in `AGENTS.md`. While it runs,41 keep working; fold its findings in when the report lands and re-score until42 it scores 8 or above.4344## QA prompt template4546Give the QA subagent fixed inputs so it does not explore the repo:4748```text49Score this round /10, engineering and design weighted equally. Budget 10 min.50Inputs: diff `git diff <last-qa-commit>..HEAD`, contact sheet <path>/sheet.png,51metrics <visual:check JSON>, qa:pre = green, open DoD from last round: <list>.52Round 1: review all. Later rounds: check open DoD and the new diff only.53Output, max 300 words: `Score: x/10 (eng y, design z)` then one line per54finding: `ID | blocker|minor | fix | DoD with a measurable threshold`.55```5657## Defaults that held up5859Start from these instead of searching again: camera fov 30, subject fill600.84 of the frame (`visual:check` fill ≥ 0.6 on the stage, or fillY ≥ 0.7 with\nmarginY ≥ 0.06 when a wide stage fills by height; fit a loaded model in the\nruntime with the real aspect, centring its projected box), centre offset61≤ 0.05, shadow radius 9 with 16 blur samples, exposure 0.8 dark / 1 light,62metal metalness 0.85 roughness 0.32.6364## Rules of taste that held up6566- **Frame the subject, not the stage.** Fit the camera to the meaningful67 objects; floors and backdrops never set the framing. Centre the projected68 bounds, then fill about 84% of the frame.69- **Ground through shadow.** A floor reads best as soft contact shadow on the70 stage's own gradient, not as a hard-edged plane. Anything the reader cannot71 see must not appear in a legend or caption.72- **Light like a studio.** Key, fill and rim; an environment for reflections73 (generated in code, so still offline); filmic tone mapping; soft shadows sized74 to the scene. Dark themes need lower exposure so pastel tones keep their75 facets.76- **Colour only from tokens.** Derive surfaces by mixing theme tokens77 (`color-mix`) rather than reusing a text colour as a fill.78- **Atmosphere is subtle.** A faint accent glow from the top, an inset79 highlight, fog toward the page background. If you notice it first, it is too80 strong.81- **One title per idea.** A block title that repeats the page title is noise.82- **Phone width is a first-class layout.** Give a 3D stage 4:3 under 480px so83 it does not shrink to a strip.84- **Stills are stills.** In PNG and PDF, freeze the live frame at device scale85 2; hide interactive chrome that has no meaning on paper.8687- **Graphs: dim, never erase.** For a selection in a dense graph, mix the88 other nodes a quarter toward the muted tone and about half toward the89 background, so group colour still reads; a full fade turns 1000 nodes into90 a grey blob. Do not select anything on load in a large graph.91- **Graphs: adjacent groups need distant hues.** Order the tone cycle so92 neighbouring clusters never share a warm hue (accent, info, success,93 danger, neutral, warning). Fit the camera to projected node bounds, not to94 the layout extent.95- **Products: details stand proud.** A driver, dial or port must sit in front96 of the panel it is mounted on, or the beauty shot shows a blank box. Check97 the plan for internal parts too: skip a part wholly inside another.98- **Products: neutral finishes are mixes, not tokens.** A graphite or chalk99 finish mixes the muted ink toward black or the surface toward white, so it100 reads as a material in both schemes instead of flipping with the theme.101- **Products: close-ups keep context.** A hotspot camera stands about three102 quarters of the home distance away, turned partly toward the hotspot's side;103 any closer and an exploded part fills the frame.104- **Globes: mix in linear space with care.** A shader mix toward a cream ink105 turns the ocean tan; scale the surface navy instead. Put the sun west of the106 view and a little north, so a warm terminator and night crescent show on the107 eastern limb. The atmosphere is a back-face shell whose glow peaks at the108 limb and fades outward.109- **Globes: dense routes thin out.** Past a few dozen arcs, scale arc width and110 opacity down with the count, and link near neighbours rather than random111 pairs, or 200 arcs become a hairball. Cluster markers when far out.112- **Morphs: soft shading, sharp outline.** A shaded SVG drawing of a smooth113 surface bands badly at 8 steps. Use about two dozen shade steps, then draw114 the faces once crisp and once blurred (stdDeviation about 4) under an alpha115 mask of the faces themselves: gradients read smooth and the silhouette stays116 sharp. Blurring the whole drawing looks out of focus.117- **Morphs: one material, glossy.** Clearcoat 1, roughness about 0.26, a little118 iridescence and sheen under the studio environment make a plain primitive119 look designed; blend the target tones with the shape so colour tells the120 reader which state is arriving.121- **Point clouds: one spacing wide.** Size points to about the cloud's own122 spacing (world diameter near 5 / sqrt(drawn points)) and nearly flat123 (a dome of at most 0.08) so surfaces read as surfaces, not beads; fade far124 points toward the background for depth instead of lighting them. Keep one125 uniform scale on all axes, fit the projected box corners to about 0.84 by126 0.8 of the frame centred 3% below the middle (refit for the real aspect),127 and sit ticks close to the box edges with at least 6 px between labels and128 one tick per shared corner.129- **Point clouds: eye-dome lighting gives depth without normals.** Render the130 points into a target with a depth texture, then darken each pixel by131 `exp(-30 * mean(max(0, log2 depth - log2 neighbour depth)))` over an132 8-neighbour ring; roofs and crowns get outlines against what lies behind133 them. In the same pass, fill an empty pixel when 5 of the 8 inner or 6 of134 the 8 outer (3 px) neighbours hold points, with the nearest one's colour,135 so the ground never shows the stage through it. Draw the selection marker136 after the pass so it is never shaded.137- **Point clouds: the ramp's lightness runs one way.** Take hues from the138 theme's info, success, warning and danger tones, set them to one lightness139 with a chroma floor, then mix toward the text colour (up to 40%) in oklab140 and lower chroma to fit the gamut instead of clipping. A ramp through the141 accent token reads olive-khaki on a light page.142- **Point clouds: the static sample is dense enough to read.** About 5,000143 points in level-of-detail order at radius 0.0085 x focal / depth draws144 roofs, crowns and lane lines; fewer reads as noise.145146## Done means147148- Screenshots at 1440, 768 and 375 in light and dark, plus a rasterised PDF149 page, viewed and clean.150- Every gate green.151- QA score of 8 or above, with each finding's Definition of Done met.