Isometrics (Line style)
You turn a short brief ("gallery isometrics", "an empty inbox state") into one drawn, animated object that ships as a complete state: the illustration, a heading, a line of copy and a button. Every object is built from 3D primitives in world units and projected in true isometric, so it shares one grid, one outline and one look with every other object made with this skill.
The look, in one line: one object, front-on if it is flat or at the true isometric angle if it is boxy, a 1 px outline over paper-white faces, one small brand-coloured mark, no shadow, no glow, one beat of motion and then stillness.
You do not skip stages. You do not call an object done until the checker passes and you have looked at its sheet.
Contents
| File | Read it |
|---|---|
SKILL.md | always: the workflow and the rules |
references/brief-to-concept.md | stage 1–2: turning a vague brief into three concepts |
references/motion.md | stage 4: choosing and timing the beat |
references/line-style.md | stage 3–5: every drawing rule, do and don't, with the reason |
references/engine-api.md | while building: the engine and the Line kit |
references/isometric-math.md | when a shape needs math the engine doesn't have |
examples/*.tsx | before building: start from the closest one |
engine/iso-core.tsx, engine/iso-line.tsx | copied into the user's project once |
scripts/check.mjs | stage 5: the strict render check |
Setup (once per project)
The objects are React client components for a project with Tailwind CSS
and shadcn/ui (they use @/lib/utils cn and @/components/ui/button)
and the motion package.
-
Check for
components/isometrics/iso-core.tsx. If it is missing, copyengine/iso-core.tsxandengine/iso-line.tsxfrom this skill intocomponents/isometrics/(or the folder the user prefers; objects import them relatively, so they all live in one folder). -
If the project has no
motion: install it (npm i motion, or the project's package manager). If it has no shadcn Button:npx shadcn@latest add button. -
For the checker, Playwright:
npm i -D playwrightandnpx playwright install chromium(or it uses an installed Chrome). -
A page to render one object alone, wrapped in
PlayOnHover(the checker plays it by hovering), e.g.app/isometrics-preview/<name>/page.tsxin Next.js, or a route in the project's own router:import { PlayOnHover } from "@/components/isometrics/iso-line"; import { MapPin } from "@/components/isometrics/map-pin"; export default function Page() { return ( <main className="flex min-h-svh items-center justify-center p-10"> <PlayOnHover><MapPin /></PlayOnHover> </main> ); }Create it per object; tell the user it is a preview page they can delete.
Never edit the engine to make one object work. If a shape is truly missing, add a helper inside the object's own file, built from 3D, and tell the user.
The workflow
Stage 1 · Read the brief
Turn the request into three answers before anything else:
- Subject: the thing or topic ("gallery" → photos, albums, images).
- Use: which state it serves: empty (nothing here yet), blocked (no access, off, not connected, not found), nothing found (search, filters), success / all clear, or a spot illustration in a feature card.
- Message: one plain sentence the state says ("You have no photos yet").
If the use isn't stated, the brief usually fits more than one; that is
what the concepts are for. See references/brief-to-concept.md.
Stage 2 · Three concepts, then wait
Unless the brief already names one object and one state, show the user three concepts as a table and stop and wait for their pick:
| Object | Message (heading) | The one beat | |
|---|---|---|---|
| A ★ | … | … | … |
| B | … | … | … |
| C | … | … | … |
Each concept must pass all four tests:
- Reads in outline at 120 px. A silhouette people know without colour.
- Rounded beats boxy. Rounded objects read friendlier in line; a plain box reads as a parcel or a wireframe.
- One object. Not a scene, not a pile. A second small part is fine only if it belongs to the object (a lid, a flag, a hand).
- The beat says the message. The motion is the verb of the sentence
(see
references/motion.md). If you can't name the beat, it's the wrong object.
Mark your recommendation with ★ and say why in one line. Vary the three: different objects, different beats. When the brief is specific ("an empty inbox state with a tray"), skip the table, state your choice and the beat, and go on.
Stage 3 · Break the object into parts
Write a parts table in world units before code: each part, the primitive
it is built from (Extrude, Slice, Ring, FacePath, Box…), its
size and position on the 0.5 grid, whether it moves, and which one part is
the brand mark. Then the copy: heading (≤ 28 characters), one or two
sentences, button label (≤ 22 characters) and its icon (the icon follows
the verb: a plus only where the action adds).
Rules that decide parts (all in references/line-style.md):
- Pick the view first. Flat or thin things (a page, a badge, a disk)
are
view="front"; boxy or deep things (a printer, a box, a server, a tray, a stick lying on a desk) areview="isometric". Front-on boxes read as flat stickers with doubled lines. - Build facing +y about x = 0, standing on z = 0.
- Three tiers of detail: form, the parts people recognise it by, and quiet marks (screws, vents, seams, a label).
- Clean lines: a front-view solid has no depth or a clear one (strip ≥ ~4 px); a part is flush or ≥ 0.5 proud; round stacks share one radius with one seam line.
- Flat things (paper, labels, screens) are faces, not solids.
- Round solids are slices between level circles, painted from the foot up.
- An outline that isn't convex needs its far edge drawn.
- A part that slides out of a housing is cut at the housing, not floated.
- One brand mark (palette
main); everything else is paper (surface).
Stage 4 · Choose and write the beat
Pick the move from the message (references/motion.md), then write the
storyboard comment at the top of the file before the drawing code:
times, what moves, how far, why. Every value in a named constant. The
beat waits 400 ms after the art scrolls into view, lasts 1.2–2.4 s and
plays once. When the user's code passes active, it plays each time
active turns true instead (80 ms delay), never on its own. Reduced
motion shows the resting pose.
Stage 5 · Build, render, check, look, fix
-
Start from the closest example in
examples/(table below). Keep its structure: storyboard, TIMING, geometry, tracks, poses, pieces,LineState. -
Render it on its preview page and run the checker:
node <skill>/scripts/check.mjs http://localhost:3000/<preview-path>/<name> --duration <wait+beat ms>It renders light and dark, plays the beat by hovering the art on a fake clock (so the preview page must wrap the object in
<PlayOnHover>), saves frames at 0, 25, 50, 75, 100 % and after, and checks:- no hydration or console errors, in light, dark and reduced motion;
- it plays when active, and there is no button inside the art;
- the beat settles exactly back to its resting pose;
- reduced motion is still, shows the resting pose, ignores
active; - every outline is about 1 px; no filters, glow, shadows or gradient paint;
- the resting drawing fits its frame;
- the drawing is centred on the heading within 2 px;
- clean lines: at most 6% of the outline in sustained doubles (two
lines 0.5–2 px apart along a real length; tiny blobs where lines
meet don't count), in
dark at 4× (
lines.png, doubles in red inlines-marked.png); - its optical size matches the set (√(w×h) 140–175 px).
-
Look at
sheet.pngandlines.png(open both) and go through the checklist below. The checker cannot see design; you can. -
Fix and run again. At most three rounds. If something still falls short after three, stop and tell the user exactly what, with the sheet.
-
Report: the concept, the storyboard, the checker result, what you fixed after looking, what still falls short, and the sheet's path.
Look at the sheet: the checklist
Reads
- Without the heading, would a stranger name the object at the size of a thumbnail?
- Nothing reads as a face by accident (two round parts over a curve).
- The brand mark is one small part, and it is the part the eye should land on.
Rests straight
- At rest every upright is vertical and every edge level; nothing leans, nothing hangs askew, second sheets are offset, not turned.
- The resting pose equals the reduced-motion pose (the checker compares pixels; you check it looks intended).
Lines (look at lines.png: dark, 4×)
- One outline weight everywhere; no doubled edges, no hairline seams between fills, no missing far edges on curved outlines, no fill poking past an outline, no line ending in the air.
- Every part is flush or clearly proud (≥ 0.5); no thin strips.
Realism
- The right view: flat things front-on, boxy things isometric.
- Three tiers: form, recognisable parts, quiet marks. Would someone who owns one say "yes, that's a printer"?
- The top strip (thickness seen from 30° above) is there on solids and absent on thin faces.
Motion
- The beat says the message; each movement is caused by the one before (a lag, a follow-through, a settle).
- Hinged parts never swing through their housing; tips never cross rest; swings stay small (≤ 6° on a hanging part, ≤ 25° on a flap).
- Nothing fades in or out; things that appear grow with scale.
Fits the page
- Centred on the copy; the frame isn't padded with dead space.
- Looks right in dark: paper faces become dark paper, the brand mark stays the brand.
Never again: mistakes this skill has made
Each of these shipped once, was caught in review, and is now a rule. Before you report an object, check it against every line.
| Mistake | Rule now |
|---|---|
| Boxes drawn front-on looked like flat stickers | Pick the view first: flat things front, boxy things view="isometric" (line-style.md) |
| Thin top strips, barely-proud parts and stepped rings drew doubled, dirty lines | No thin strips; flush or ≥ 0.5 proud; round stacks at one radius; the checker's clean-lines test must pass, and you look at lines.png (dark, 4×) |
| Objects were only an outline ("not realistic") | Three tiers of detail: form, recognisable parts, quiet marks |
| Sizes jumped between objects in a set | Optical size 140–175 px via defaultArtClassName |
| Pages flew 3 units outside the frame | Motion stays in the art's air; a little past the frame edge at most |
| Two latches, a full-width stripe as "one brand mark" | One small mark, really one |
| A slot over a dot, two latches over a seam read as a face | Look for accidental faces at thumbnail size |
| A corner flip toward the viewer was invisible front-on | Turns toward the viewer read at a fraction of their angle; prefer moves in the picture plane, or go large (motion.md) |
| A page tilted in its plane sheared at the isometric angle | In isometric view, turn a part only about its own normal or a hinge on its edge (motion.md) |
| A part one-frame-flashed its start pose on the first play | Parts driven by clock state reset when the clip changes and start at rest when held (engine-api.md) |
| Thin tray walls read as thin plastic | Sturdy walls get thickness (≥ 0.5); thin faces are for paper |
| Each object looked fine alone, the set didn't | Review the whole batch side by side, light and dark, before reporting |
| A bell's body, a shackle, a needle hand drew double outlines down their curves | Front-on, a curved part is a flat face (or a clearly deep one); give a hand parallel sides, never a taper |
| Sand drawn on the glass outline made one thick smear | Contents sit inside an inset wall, never on the container's outline |
| A door 0.25 proud of its box doubled the arch | A door the shape of its opening shares one outline at rest |
| A safe door at 32° in isometric looked edge-on | Isometric doors and lids open ~24–26° so their face still reads |
| A key ring lay over the keys instead of through their holes ("the ring is not inside the key ring") | Threaded parts interlace: the ring passes behind each part on one side of its hole and in front on the other (line-style.md) |
| Shrinking an object to its size brought the doubled lines back | Set the default width first, then make strips ≥ 0.5 for objects drawn small |
| A "!!!" badge failed the line check | Draw marks as shapes with clear gaps; avoid gap glyphs in text |
Non-negotiable rules
- True isometric only. Axes at 30° to horizontal, 120° apart, equal scale. Never the 2:1 "game" projection (26.565°).
- Geometry first. Place primitives in world units. Never write a projected screen path by hand.
- One grid. Positions and sizes on 0.5 world units; face details on 0.25.
- One look.
variant="ink"(default) or"line"; never mix looks in one object. 1 px outline, paper walls, no shadow, no glow, no gradient. - Theme from tokens. Colours come only from the user's shadcn theme
through the
--iso-*variables. No hex, no oklch in an object file. The brand mark followstone(defaultprimary). - Props, not forks. Copy, tone, variant, stroke width, motion
switches are props with doc comments (
LineStateProps). Never name a content proptitle: it is the accessible name. - Accessible and embeddable. The art is decorative unless
titleis given; it never contains a<button>, so it is safe inside links and buttons; reduced motion is respected without a hydration error (useReduced, never motion'suseReducedMotionin the first render). - One beat, then still; the user's code is in charge. No idle loops
by default (
loopis opt-in). Every object takesactive(play each time it turns true) andonPlayEnd(called when the beat settles); people sit in front of an empty state.
Using an object (tell the user this)
<Folder /> // plays once when it scrolls into view
<PlayOnHover><Folder /></PlayOnHover> // plays on hover, focus and touch
<Folder active={uploadDone} onPlayEnd={() => setUploadDone(false)} /> // your state
<Folder active={false} /> // still until you say
<Folder heading="" description="" actionLabel="" artClassName="w-16" /> // the art alone, any size
Below about 40 px fine details start to crowd; 48 px and up reads well.
Examples
All ten are complete and pass the checker. Start from the one whose technique is closest to what you need.
| File | State | Technique worth copying |
|---|---|---|
map-pin.tsx | no locations | drop with one bounce; squash and stretch that keeps volume; a level Ring that reacts |
folder.tsx | no files | a hinged flap that opens and shuts without crossing its housing; three pages popping out on arcs (fast rise, slower drift) and pulled swiftly back, hidden by paint order |
gift-box.tsx | no rewards | a lid that lifts, peeks and drops back with one bounce |
mailbox.tsx | no mail | a rounded-top body; a door dropping open about its bottom hinge |
toggle-switch.tsx | blocked: feature off | "tries and stops": a knob that slides partway and returns |
cloud-upload.tsx | nothing uploaded | a non-convex outline with its far edge; a part rising out of another |
chat-bubble.tsx | no messages | a staggered wave across three parts |
hourglass.tsx | nothing yet | a half turn in the front plane, then a flow that ends where it began |
stopwatch.tsx | no time tracked | a press that causes a sweep; a hand on a dial |
sprout-pot.tsx | no projects | a one-way beat (grows) with an again clip that undoes it first; round slices |
Updating this skill
When the user corrects a drawing or a beat, add the rule to
references/line-style.md (or motion.md) with the reason, in the
user's words where possible. Rules here are scar tissue; keep them.