design-spatial – skill Thiết kế & UI cho agent AI

Design — spatial composition

When to Use

Use this skill when you need design — spatial composition.

A model cannot trust its own UI output. Everything else follows from two failures.

1. It can't see what it made

UI is generated as a token stream, never as pixels — so the model cannot perceive collisions, overlap, imbalance, or broken spacing. It will write a headline that runs into the hero image and have no idea.

Render it and judge the image, not the code. Serve with any static server (e.g. python3 -m http.server or npx serve) and screenshot headless via Playwright. Screenshot at a few widths.

Critique with fresh eyes — not your own. Grading your own output rationalizes it; the builder looks at its overlapping headline and calls it fine (this is exactly how a real collision shipped in testing). Use a separate judge — a subagent that did *not* write the page — and tell it to hunt for what's *wrong*: collisions, edge tangents, ragged alignment, lopsided weight, no clear focal point, breaks at some width. Fix, re-render, re-judge.

2. Its first idea is the average

Whatever it produces first is the mean of its training data — and there is more than one mean:

• the generic-AI mean: Inter, purple-on-white gradients, centered single column, three equal cards;
• the designer-trend mean: oversized condensed caps, dark-mode + grain, monospace "vibes" microtext, sticker badges.

Landing on the second isn't taste — it's a more flattering average, which is why it slips past. **Treat your first instinct as the mean and deviate deliberately — toward *this product's specific world* (use design-thinking's domain / color-world / signature as the direction), not toward another trend.** If the result could be any startup, you shipped the mean.

3. So don't prescribe a style

Any fixed rule — a 12-col grid, an 8-point scale, "mono = data" — *becomes* next cycle's mean, and a blind model executes it into collisions anyway. Prescribe the process, not the look: see it with fresh eyes, and push off the average toward the domain. Taste supplies the direction (design-thinking / design-philosophy); this skill only insists you look and don't ship the mean.

For iterative spatial tuning, a local page with live controls (sliders, pickers, drag handles) beats one-shot critique.

4. NEVER ship horizontal overflow — THE mandatory gate, no exceptions

> **BLOCKING GATE. You may not call any web UI "done", "working", "fixed", or

> "looks good" until you have run the scrollWidth check below at a narrow width

> THIS turn and seen 0. Not "I added overflow-x:clip so it's fine." Not "it

> looked fine at my width." MEASURE. Narrow. Every time. If you didn't measure,

> it isn't done — say "haven't checked overflow yet" instead of claiming done.**

A side-to-side scrollbar that doesn't match the content is the **single most common

and most embarrassing** layout failure, and it ships *over and over* because the dev

viewport is wide enough to hide it — the overflow only appears once the window is

narrower than some element. It is invisible at desktop width, so the §1

render-critique loop will NOT catch it unless you screenshot narrow. Separate,

explicit, non-negotiable gate.

It recurs because layouts GROW after they were last checked. Every time you add a

nav tab, a toolbar button, a header control, a chip, a wider equation/<pre>, or any

new item to a flex/inline row, you have invalidated the last overflow check — the

row that fit yesterday now pushes past the edge between ~720–1200px while your 1440px

dev window shows nothing wrong. (Real ship, 2026-06, TWICE: a progress-bar edge label

overflowed 23px; then a flex-wrap:nowrap header that grew 4 tabs scrolled the whole

page 309px across 720–1200px — both invisible at dev width, both caught only by

measuring narrow.) **So: any change that adds an element to a horizontal row re-arms

this gate. Re-measure.**

Default defenses to apply up front (so the gate passes by construction):

• Header / nav / toolbar rows: flex-wrap: wrap, never nowrap. A growing

single-row flex is the #1 source of this bug. Wrapping is a no-op when it fits and

saves you when it doesn't.

• Use clipping only for intentional decorative overflow after checking focus rings, menus and offscreen content; do not apply it globally to conceal a layout defect.

The check — run before calling ANY page done: document.documentElement.scrollWidth - document.documentElement.clientWidth must equal 0, tested at your dev width AND resized narrow (≤1024px, and a phone width ~390px). If > 0, find the offender:

document.querySelectorAll('*').forEach(el=>{const r=el.getBoundingClientRect();
  if(r.right>innerWidth+1||r.left<-1) console.log(Math.round(r.right), el);});

Safety net: overflow-x: clip on body (prefer clip over hidden — it clips without creating a scroll container, so it won't break position:sticky/anchored layouts). But a net is not a fix — find and kill the root cause:

• position:absolute + white-space:nowrap anchored at an edge (left:100%, right:0): a *centered* nowrap label on the right edge juts past the viewport. (Real ship, 2026-06: a progress bar's "300 · learned model" milestone label at left:100% with translateX(-50%) overflowed 23px → phantom horizontal scroll at sub-1180px widths.) Anchor edge labels inward — right end right:0; transform:none, left end left:0; transform:none.
• 100vw — includes the scrollbar width (~15px), so on any vertically-scrolling page it guarantees ~15px of horizontal overflow. Use 100%.
• flex / grid children without min-width:0 — they refuse to shrink below their content and blow out the track (a long title in a flex card, a <pre> in a grid cell). Add min-width:0.
• long unbreakable strings (URLs, hashes, tokens): overflow-wrap:anywhere or word-break:break-word.
• fixed pixel widths wider than the viewport; large negative margins; oversized position:absolute elements.

The generalization: anything pinned to an edge or sized in viewport units is a horizontal-overflow suspect — test narrow, measure scrollWidth, clip the body as backstop, and anchor edge-pinned content inward.

5. Lay out in TASK order — minimize transition cost

Before placing elements, **walk the user's actual step sequence for completing the

page's action**, then arrange elements in that same perceptual/view order. The

layout should read like the task: orient → work → confirm. Any mouse travel or

scrolling that serves no practical purpose is a defect.

• Orient at top: controls/options up top are good — they tell the user what

the page is for and what it can do before they commit to reading it.

• Confirm where the work ENDS: if the task is "review a long list, then act"

(approve, flag, submit, save), the action buttons must ALSO exist at the

bottom — where the user's eyes and cursor are when they finish. The original

failure: a delete-review page with confirm buttons only in the top toolbar —

after scrolling through 120 images, the user had to scroll all the way back up

to click "flag the rest." Duplicate the action bar at the bottom (or make the

toolbar sticky); both are one line of code, the scroll-back is paid per page.

• The heuristic: save the user transit time. Every interaction has a path:

where the eyes/cursor are when a step ends vs where the next step's control

is. Sum those distances; shrink the big ones. Fitts's law for the page as a

whole, not just one button.

• Check it in the render-and-critique loop (§1): ask the judge "trace the

task: where is the user when they finish each step, and how far is the next

control?" — a layout can be aligned, balanced, and still force a round trip.

6. Balance is measurable — don't eyeball it (or trust a VLM's eye)

§1 says render and have fresh eyes critique it. That qualitative pass catches

collisions and ragged alignment, but **a model has no reliable sense of visual

balance** — ask a VLM "is this centered / balanced?" and it confabulates a verdict.

The fix is to stop asking opinions and measure a number, then keep that number

honest with an *independent* check. Use both: §1's fresh-eyes critique AND the hard

number below. (This pairs a live in-browser box model + auto-balancer with an

offline pixel-oracle that re-measures the rendered screenshot — see the

layout-audit.js companion script in this skill.)

The principle. Visual balance is the *center of mass of visual weight*. It's

arithmetic, not taste — so compute it.

Optical center, not geometric. Target x = 0.50, y ≈ 0.46 — slightly high,

because a centroid at literal 50% reads as sagging.

Visual weight estimate = area × guessed ink-density. These coefficients and optical-center tolerances are exploratory heuristics, not validated perceptual laws. Same-size ≠ same-weight: a

solid-black heading is

… (nội dung đầy đủ có trong gói tải về)