linejig 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,194 @@
1
+ ---
2
+ name: linejig
3
+ description: Draws interactive 3D line illustrations in three.js. One object is built from a few rounded solids and drawn as 3D line illustrations in an isometric view (2:1 axonometric) with one fine line width, white and black and hierarchy by tone, so all figures keep a consistent illustration style. It builds in (stack or draw-on), then its one hero part (a needle, a lid, the keys of a keyboard) answers hover and click, and the user can drag to turn and zoom it. Illustration only: no captions, leader labels, logos or generated images. Use it whenever someone asks for an interactive 3D illustration, a line-art, line-drawn, technical-drawing or isometric object illustration, an animated three.js line drawing, a draw-on or assembly animation, an illustration for an empty state, 404 page, onboarding step, slide or hero, or to add, change or embed a figure from the Linejig gallery, even if they only say "add a drawing here". For flat pixel illustrations in three steps, use the separate Keyline pixel skill, if installed.
4
+ ---
5
+
6
+ # Linejig
7
+
8
+ <!-- Product name: "Linejig", always one word, capital L. The skill id `linejig` is the front matter `name` and the
9
+ folder name. Site URL: every https://linejig.com link in this folder is the current site; when the main domain
10
+ changes, replace it in every file here. -->
11
+
12
+ Linejig grows out of the Keyline pixel skills, a separate and older family for flat pixel illustrations (`keyline`,
13
+ `keyline-draw`, `keyline-motion`, `keyline-check`). If those skills are installed alongside this one, read them too;
14
+ if not, everything this skill needs is in this folder. It keeps their thinking and changes the medium:
15
+
16
+ | | Keyline pixel skills | Linejig |
17
+ |---|---|---|
18
+ | Medium | one object sampled into square pixel tiles, a JSON scene, the Keyline pixel engine | one object modelled as rounded solids and drawn in fine lines in three.js |
19
+ | What moves | an accent lights one part in each of three steps | the object builds in (`draw` or `stack`), then one hero part makes its move |
20
+ | The user | hovers a step to preview it | turns and zooms the object, and hovers and clicks the hero |
21
+ | Colour | one ink and an accent | white and black, a grey ramp, `hi` for the hero |
22
+
23
+ What it inherits from the Keyline pixel skills, and applies here unchanged:
24
+
25
+ - **Is there one already?** Before drawing, check the gallery manifest (https://linejig.com/illustrations.json; the gallery
26
+ is https://linejig.com/library.html and each figure lives at https://linejig.com/<id>/). Use one only if it shows the thing the page is about, literally.
27
+ - **Concept: one object, three options.** Write three concepts, recommend one in a sentence, and wait for the user
28
+ to pick, unless they said "just draw it". After the pick, do not stop again until the drawing is checked.
29
+ - **A silhouette you can name at thumbnail size,** with features that change the outline, not only sit inside it.
30
+ - **Logical motion.** Everything moves in the real order of cause and effect: parts assemble the way the real
31
+ thing is put together, and the hero does what the real part does.
32
+ - **Name what it shows, never whose it is:** no logos, companies, products or people, in the drawing or its words.
33
+ - **No long dashes** anywhere in the words.
34
+
35
+ The drawing rules follow the Hairline figure kernel by Lucas Marques (MIT): https://hairline.lucasmarkes.com and
36
+ the npm package `@lucasmarkes/hairline`.
37
+
38
+ ## Before you draw: think first
39
+
40
+ The user judges the idea before the execution.
41
+
42
+ 1. Say what the drawing sits beside, in one sentence.
43
+ 2. Write three concepts (`references/metaphors.md`): "Object Z, hero H, because ..., its intro and its one move M."
44
+ If one needs a caption to be understood, drop it. Recommend one and wait for the pick.
45
+ 3. If the user sent references, explain how each works before you build.
46
+
47
+ ## What stays out
48
+
49
+ - **No text in the illustration.** No leaders, pointer dots, numbers on parts, captions, headings, labels or "Fig."
50
+ marks. If the host page needs words, they are the page's job, not the drawing's.
51
+ - **No small detail.** No rivets, bands, hatching, engraving, textures, shading, gradients or glow.
52
+ - **No AI images or video,** and no tracing of generated pictures. Everything is drawn in code.
53
+
54
+ ## The kernel
55
+
56
+ Every figure is built on the shared kernel, https://linejig.com/kernel/linejig.js (MIT; its header comment is the API;
57
+ read it there, or at `site/kernel/linejig.js` when working in the source repo). A figure file
58
+ holds only its model, its `ASSEMBLY` table and its `HERO` handlers, about 100 to 150 lines:
59
+
60
+ ```js
61
+ import { createFigure } from '../kernel/linejig.js';
62
+ createFigure({ id, center, fit: { points }, ASSEMBLY, model(K, st) { ... }, state(K) { ... }, HERO: { onHover, onLeave, onClick } });
63
+ ```
64
+
65
+ The kernel owns the camera and fit, the palette and styles, rounded prisms and painter fill, the line width and
66
+ 0.5 px widths, the tween and spring, both intros, orbit, zoom, hit testing, cursors, reduced motion, capture hooks,
67
+ the embed contract, the **action event** (`HERO.action`, posted when the hero's move reaches its open state, so an
68
+ empty state or onboarding step can hand off to its host page) and `?mode=turntable` (no hand, a slow swing for
69
+ loading screens and recorded loops). Import `https://linejig.com/kernel/linejig.js` and link
70
+ `https://linejig.com/kernel/linejig.css`, with the three.js import map, as `scripts/starter.html` does.
71
+ The Brand and Dots styles are Linejig Pro and live in `linejig-pro.js` beside it: the kernel loads that file by itself,
72
+ once, only when a figure asks for brand or dots, so a line-art page never downloads it.
73
+ To see finished figures, open them from the gallery and read their source.
74
+
75
+ ## Style
76
+
77
+ This skill draws in **line art** (`references/styles.md`), the kernel's default: white and black only, the grey ramp,
78
+ `hi` for the hero, text-free. The Brand and Dots styles (the hero in a brand colour; the drawing as a dot matrix)
79
+ come with Linejig Pro, the `linejig-pro` skill (https://linejig.com/pricing). If it is installed, follow it for
80
+ those styles; if not, draw in line art. Either way the model, the assembly and the hero are the same, so a figure
81
+ made here works in every style.
82
+
83
+ ## The look, in brief
84
+
85
+ Full rules and values in `references/drawing.md`.
86
+
87
+ - **Few rounded solids.** Build the object from a handful of rounded footprints (rounded rectangles, circles)
88
+ extruded into prisms. Each prism shows its silhouette and one crease ring just inside its top edge. Use enough
89
+ parts (usually 8 to 12) that the object reads as that specific object, and carry secondary detail (ticks, seams,
90
+ rose points) as quiet `lo` lines rather than more weight.
91
+ - **One camera.** Orthographic 2:1 axonometric: azimuth 45°, sin(elevation) 0.5. The object is centred and fills
92
+ about 60 to 75% of a 5:4 plate.
93
+ - **Filled with the ground.** Every face is filled with the plate colour and drawn back to front, so near parts
94
+ hide far ones.
95
+ - **One line width.** About 1 px on screen for every line, at any size (three.js `LineMaterial`,
96
+ `worldUnits: false`). When the drawing is dense, use one line in place of two; a second line, if truly needed, is
97
+ about 0.5 px in `lo`.
98
+ - **White and black.** A near-white plate in light, a near-black plate in dark, and a grey ramp. No colour.
99
+ - **Hierarchy by tone only.** Five tones: `plate` (ground and fills), `edge` (silhouettes), `mid` (default lines),
100
+ `lo` (dim and background lines) and `hi`, the one bright highlight on the one part that matters. Plus dashed
101
+ guides and dots. The drawing sets no other colour.
102
+
103
+ ## The hero part
104
+
105
+ Every illustration has **one hero part**, or one family of identical parts that each work the same way (the keys
106
+ of a keyboard): the part that carries the message (a compass's needle, a safe's lid, a
107
+ key, a balance's beam). Decide it while thinking, before you build, and write it down with the object: "Object Z,
108
+ hero H, because ...". The hero is the `hi` part, it makes the one move, and it is the only part that answers the
109
+ user. Everything else stays simple and still, and only moves as the whole object when the user turns or zooms it.
110
+
111
+ ## Interaction, in brief
112
+
113
+ Full rules in `references/interaction.md`. After the intro lands:
114
+
115
+ - **Turn:** drag orbits the camera within limits, then springs back to the rest view after about 2 s.
116
+ - **Zoom:** wheel or pinch, toward the pointer, 0.8× to 2.5×; double-click resets. Lines stay 1 px.
117
+ - **Hero:** hovering makes the hero respond the way the real part would (the needle turns toward the pointer like a
118
+ magnet and springs back on leave); a click gives it a kick. The cursor is the only hint: no text, no UI.
119
+
120
+ ## Motion, in brief
121
+
122
+ Full rules in `references/motion.md`.
123
+
124
+ - **three.js 0.160.0**, Line2 / LineSegments2 fat lines, pinned, with an import map (the kernel does the rest).
125
+ - **The intro is the user's choice, `stack` by default:** `draw` (lines draw on) or `stack` (the object builds from the ground up, one
126
+ layer at a time), with more ideas in `references/motion.md`. One `INTRO` setting, overridable with `?intro=`.
127
+ - **One move that means something,** and it lands once: the intro plays, then the object does the thing it is
128
+ for (a needle settles, a lid lifts, a key turns, a telescope swings) or the camera pushes in or pans.
129
+ - **Timing.** A 700 ms tween on `cubic-bezier(.32,.72,0,1)` for discrete moves; a spring (k 100, c 18, m 1) for
130
+ things that should overshoot a little and settle, like a needle. Draw-on about 1200 ms, left to right.
131
+ - **End on the drawing.** Hold still or idle very slowly (a degree or two over a minute).
132
+ - **Reduced motion** (`prefers-reduced-motion` or `?reduced=1`): show the final state at once.
133
+ - **Capture hooks:** `?freeze=MS` stops the clock MS after the start; `?click=ID@MS` clicks the hero at MS.
134
+
135
+ ## Workflow
136
+
137
+ 1. Think (above): message, object, hero part, its one move and its hover response. For the `stack` intro, also
138
+ write the object's assembly table (type, base, each part's mounting face and `from` direction; see
139
+ `references/motion.md`, "Planning the stack").
140
+ 2. Build on the kernel from `scripts/starter.html`: replace the placeholder model, `ASSEMBLY` and `HERO`
141
+ with yours (mark the hero's row `hero: true`), assign tones, set the move. Never copy kernel code into a figure.
142
+ 3. Render frozen frames at the start, middle and end of the move, in both palettes, at desktop and phone width
143
+ (`references/verify.md`). Look hard; fix and rerender.
144
+ 4. Check the console for errors. Ship with pinned library versions.
145
+ 5. **Lock it into the gallery** (only when working in the source repo) once the user approves it (they say it's
146
+ locked, final or approved). Build it in
147
+ `site/<id>/index.html` in the source repo, then add one entry to the gallery manifest
148
+ `site/illustrations.json` (`id`, `name`, `path`, `category`, `message`, `hero`, `hover`, `click`, `intros`,
149
+ `locked`, `date`, and `action: {id, label}` if the hero hands off) and nothing else; the gallery at
150
+ `site/library.html` groups entries by `category` (the manifest's `categories` list). To show the user a figure
151
+ before approval, add it with `locked: false`: the gallery shows it tagged draft (`?drafts=0` hides drafts). Once
152
+ approved, set `locked: true`, push, and redeploy the site's Vercel project. The kernel keeps the embed contract, so the
153
+ gallery can drive every figure.
154
+
155
+ ## Using it with what you already have
156
+
157
+ Most figures go into a product that already has a look. Full notes in `references/integration.md`.
158
+
159
+ - **On a component library** (shadcn/ui, or any token-based theme): the surface token the figure sits on becomes the
160
+ plate (`?plate=<light>,<dark>`), the ink stays the kernel's grey ramp, the frame sits in a card at 5:4, and a class-based
161
+ dark mode is passed on with `?theme=` and the `theme` message.
162
+ - **From the user's own illustration or SVG:** read it for the object and its parts, rebuild each shape as a kernel
163
+ footprint (the kernel has no SVG import, so nothing is traced automatically), drop small detail and every word,
164
+ choose the hero part, and give it hover and click like any other figure.
165
+
166
+ ## The source repo
167
+
168
+ The gallery, the kernel source and the figure pages live in the Linejig source repo (`site/kernel/linejig.js`,
169
+ `site/<id>/`, `site/illustrations.json`). Steps marked "only when working in the source repo" apply only there;
170
+ everywhere else, import the published kernel from https://linejig.com/kernel/.
171
+
172
+ ## Lessons (do not repeat these)
173
+
174
+ - **Shallow ideas get rejected** however well drawn. Think first.
175
+ - **Detail is not quality.** Early drawings carried rivets, bands and three line weights; the simpler
176
+ line art reads better small and animates cleaner.
177
+ - **No AI generation** for the drawings or their motion; the user rejected it.
178
+ - **Stop what is not on screen.** A drawing left running showed over other slides (a balance figure on a deck). When an
179
+ illustration leaves, hide it and stop its loop.
180
+
181
+ ## References
182
+
183
+ - `references/metaphors.md`: choosing an object for a message, with an example set.
184
+ - `references/drawing.md`: camera, rounded prisms, painter fill, the one width, the five tones, palettes.
185
+ - `references/motion.md`: moves, timings, springs, draw-on, reduced motion, hand-overs.
186
+ - `references/styles.md`: line art, which part is the hero, the floor grid, and where the Pro styles live.
187
+ - `references/interaction.md`: the hero part, hover and click responses, orbit, zoom, hit testing, cursors.
188
+ - `references/verify.md`: headless Chrome capture, frozen frames, console errors.
189
+ - `references/integration.md`: on top of a component library (tokens, cards, dark mode), and from the user's own
190
+ illustration or SVG.
191
+ - https://linejig.com/kernel/linejig.js: the kernel; its header is the API.
192
+ - https://linejig.com/illustrations.json: the gallery manifest; each entry's `path` is a figure page to read.
193
+ - `scripts/starter.html`: a minimal figure on the kernel with a placeholder object. Open it, or capture with
194
+ `?freeze=MS`.
@@ -0,0 +1,93 @@
1
+ # Drawing rules
2
+
3
+ These follow the Hairline figure kernel (Lucas Marques, MIT): https://hairline.lucasmarkes.com, published on npm as
4
+ `@lucasmarkes/hairline`. Its kernel's index comment lists the primitives, and its figures show how small a figure
5
+ is (about 100 lines). Borrow the rules, not the code: this skill draws in three.js.
6
+
7
+ ## 1. Camera and plate
8
+
9
+ - **Orthographic 2:1 axonometric:** azimuth 45°, `k = sin(elevation) = 0.5`. One camera for the whole drawing, so
10
+ any camera move starts and ends in the same projection.
11
+ - World space: x and y on the ground, z up. With this camera the corner with the largest x + y is nearest the viewer.
12
+ - **Plate:** 5:4 (Hairline draws in a 400 × 320 viewBox). The object is centred and its box fills about 60 to 75% of
13
+ the plate's width (Hairline's boxes come out 230 to 310 wide, 180 to 245 tall). Fit with the object's most extreme
14
+ pose (the lid fully open, the needle at its widest swing), so it never leaves the plate mid-move.
15
+ - The plate scales to its container; on a phone it simply gets smaller. Lines stay 1 px.
16
+
17
+ ## 2. Rounded solids
18
+
19
+ - Build from **rounded footprints**: a rounded rectangle (corner radius at most half the shorter side) or a circle,
20
+ extruded from z0 to z1 into a prism.
21
+ - Each prism draws **two things**: its **silhouette** (the outline of the whole solid as seen) and **one crease
22
+ ring** inset slightly (Hairline: 0.6 to 2.2 world units) from the top edge. The crease gives the top a thickness
23
+ without adding edges. Keep the inset under half the shorter side, or the crease turns inside out.
24
+ - **Enough structure to name the object at a glance,** and no more. Usually 8 to 12 solids. Keep the parts that
25
+ make its silhouette specific (a compass's gimbal and yoke, a safe's hinges and handle), not just its generic shape.
26
+ Too few parts reads as a placeholder; the first compass at 3 to 4 solids was "too simple".
27
+ - **Secondary detail lives in `lo`:** tick rings, rose points, panel seams and other flat marks lying on a surface are
28
+ single `lo` (or `mid`) lines, so the drawing stays quiet while it reads as real. Drop the finest marks at small
29
+ sizes if they turn to noise.
30
+ - No rivets, hatching, engraving, texture, shading, gradient or glow.
31
+
32
+ In three.js: a prism is an extruded `Shape` (or a `CylinderGeometry` for a circle) with a ground-coloured fill mesh,
33
+ plus fat-line loops for the silhouette and crease. A silhouette can be taken from `EdgesGeometry` (crease angle
34
+ about 35°) for straight-sided parts, or built from the footprint ring at z0 and z1 plus the two side tangents for
35
+ round ones.
36
+
37
+ ## 3. Hidden lines: fill with the ground
38
+
39
+ Fill every face with the plate colour and draw back to front, so a near part covers a far one exactly. No
40
+ hidden-line maths. In three.js, give fills `polygonOffset` (factor 1, units 2) so lines on their edges win the depth
41
+ test, or order with `renderOrder` by x + y.
42
+
43
+ ## 4. One line width, and fewer lines when dense
44
+
45
+ Every line is the same fine line: about 0.9 to 1 px on screen, non-scaling (`LineMaterial`, `worldUnits: false`,
46
+ `resolution` set to the canvas size in CSS px times the pixel ratio). Round joins and caps. Never thicken a line to
47
+ make it important; change its tone.
48
+
49
+ **When the drawing gets dense** (many repeated parts, such as keycaps, piano keys, windows on a facade or the slats
50
+ of a shutter), use **one line in place of two**:
51
+
52
+ - Drop the crease ring on repeated parts; the outline of the top face is enough.
53
+ - Draw one line per real edge. No parallel lines tracing the same rim three or four times.
54
+ - If a second line is truly needed (a plate band, a dish), draw it at the **minimum width, about 0.5 px** on screen,
55
+ in `lo`, so the drawing stays easy to look at.
56
+
57
+ Check dense areas at 2× zoom: they should read calmly, not as a hatch of parallel lines. (The first keyboard had a
58
+ crease on every cap and four lines on the case rim; it read as noise.)
59
+
60
+ ## 5. Tones
61
+
62
+ | Tone | Use |
63
+ |---|---|
64
+ | `plate` | the ground, and the fill of every face |
65
+ | `edge` | silhouettes |
66
+ | `mid` | the default line: creases, inner edges |
67
+ | `lo` | dim lines: background parts, flat marks, glass |
68
+ | `hi` | the one bright highlight: the part that carries the message (a needle, a key, a door) |
69
+ | dashed | a guide or axis, in `lo` |
70
+ | dot | a small filled dot, in `hi` or `mid` |
71
+
72
+ One `hi` part per drawing. Contrast must step clearly: `hi` > `edge` > `mid` > `lo` against the plate.
73
+
74
+ ## 6. Palette: white and black, the same for every illustration
75
+
76
+ Every illustration uses this one palette (the kernel's `linejig.css`). No per-illustration colours: a near-white
77
+ plate in light, a near-black plate in dark, a grey ramp, and the `hi` tone at the far end of the ramp. An embed may set its plate to the host's surface
78
+ with `?plate=<light>,<dark>` (`integration.md`), and the ramp stays as it is.
79
+
80
+ | Tone | Light | Dark |
81
+ |---|---|---|
82
+ | plate | `#f7f7f8` | `#111111` |
83
+ | hi | `#17171a` | `#e6eaf0` |
84
+ | edge | `#6a6a72` | `#a8aab1` |
85
+ | mid | `#8f8f97` | `#797b82` |
86
+ | lo | `#b6b6bc` | `#4f5056` |
87
+
88
+ Contrast against the plate is about hi 16 to 18, edge 5 to 8, mid 3 to 4.5, lo 2 to 2.5. These are steeper than
89
+ Hairline's own defaults, which are tuned for small figures in cards and read too faint at large sizes (both the
90
+ compass and the camera had to be brightened). The host page around a figure should use the same plate colour, so
91
+ the figure sits seamlessly on it.
92
+
93
+ Switch with `prefers-color-scheme`, or a `data-theme` / `?theme=` override. Grain is not used.
@@ -0,0 +1,106 @@
1
+ # Using it with what you already have
2
+
3
+ Two common starts: a product built on a component library, and an illustration or SVG the user already has. Both
4
+ end in an ordinary figure on the kernel, so every rule in `SKILL.md` still holds. This file names only settings the
5
+ kernel really has; its header comment (https://linejig.com/kernel/linejig.js) is the authority.
6
+
7
+ ## On top of a component library (shadcn/ui and similar)
8
+
9
+ A figure is a small page. Either embed a gallery figure (`https://linejig.com/<id>/index.html`) in an iframe, or
10
+ build a figure page of your own on the kernel and serve it from the project. Either way the host talks to it through
11
+ the address and through messages.
12
+
13
+ ### Theme tokens to plate and ink
14
+
15
+ | Kernel input | Where it comes from | How to pass it |
16
+ |---|---|---|
17
+ | Plate (the ground every face is filled with) | the surface the figure sits on: `--card` inside a Card, `--background` on the page, `--muted` in a muted well | `?plate=<light>,<dark>`: two six-digit hex values without `#`, light then dark (defaults `f7f7f8,111111`) |
18
+ | Ink (`hi`, `edge`, `mid`, `lo`) | nothing: keep the kernel's grey ramp | not an address setting |
19
+ | Style | line art, the default; the Brand and Dots styles, with the brand colour from `--primary`, are in the `linejig-pro` skill | nothing to pass |
20
+
21
+ - Tokens are often OKLCH or HSL (`--primary: oklch(0.205 0 0)`). The kernel takes hex, so convert the computed colour
22
+ (in the browser, `getComputedStyle(el).backgroundColor` on an element that uses the token gives `rgb(...)`; turn
23
+ that into hex) for both the light and the dark theme.
24
+ - **Ink stays grey.** The tones are measured for contrast against the plate, so do not tint them to the page's
25
+ foreground. On a figure page you own, they are the CSS variables `--hi --edge --mid --lo` from `linejig.css`;
26
+ override them only if the user asks, per theme, keeping `hi > edge > mid > lo` in contrast against the plate, and
27
+ measure the rendered pixels.
28
+ - `?plate=` is read once at load, in an iframe page. To change the plate later, reload the frame with a new address.
29
+
30
+ ### Sizing in cards
31
+
32
+ - The drawing fits a 5:4 plate inside whatever box it gets; 400 by 320 is the natural shape and any other shape adds
33
+ margin. In a card, give the frame `width: 100%; aspect-ratio: 5 / 4; border: 0` and let the card's padding frame it.
34
+ - Keep `embed=1` on every embed: the wheel and a vertical swipe then scroll the page instead of zooming the object.
35
+ - Add `loading="lazy"` and a `title` that names the object. Each frame is its own WebGL context, so keep three or
36
+ four live figures per page at most and show a still for the rest.
37
+ - The figure never draws words. Headings, body text and the call to action are the card's: put the label of the
38
+ hero's action on a Button in the card footer, and also run it when the figure posts `action`.
39
+
40
+ ### Dark mode
41
+
42
+ - Without `?theme=` a figure follows the visitor's system setting. shadcn/ui (and most `next-themes` setups) switch
43
+ with a `dark` class on `<html>` instead, so the figure must be told: start it with `?theme=light` or `?theme=dark`
44
+ from the current class, and post `{type: 'theme', value}` whenever the class changes.
45
+ - Post only after the figure has sent `ready`, and always to the origin `https://linejig.com` (or your own origin
46
+ for a self-hosted figure page). Check `e.origin` and `e.source` on everything you receive.
47
+
48
+ ### A React component, as a sketch
49
+
50
+ ```jsx
51
+ import { useEffect, useRef } from 'react';
52
+
53
+ const ORIGIN = 'https://linejig.com';
54
+ const hex = (rgb) => rgb.match(/\d+/g).slice(0, 3).map((n) => (+n).toString(16).padStart(2, '0')).join('');
55
+
56
+ export function LinejigFigure({ id, title, plate = 'f7f7f8,111111', onAction }) {
57
+ const ref = useRef(null);
58
+ const dark = () => document.documentElement.classList.contains('dark');
59
+ useEffect(() => {
60
+ const frame = ref.current;
61
+ const send = (m) => frame?.contentWindow?.postMessage(m, ORIGIN);
62
+ let ready = false;
63
+ const onMessage = (e) => {
64
+ if (e.origin !== ORIGIN || e.source !== frame.contentWindow) return;
65
+ if (e.data.type === 'ready') { ready = true; send({ type: 'theme', value: dark() ? 'dark' : 'light' }); }
66
+ if (e.data.type === 'action') onAction?.(e.data.id);
67
+ };
68
+ const watch = new MutationObserver(() => ready && send({ type: 'theme', value: dark() ? 'dark' : 'light' }));
69
+ watch.observe(document.documentElement, { attributes: true, attributeFilter: ['class'] });
70
+ addEventListener('message', onMessage);
71
+ return () => { removeEventListener('message', onMessage); watch.disconnect(); };
72
+ }, [onAction]);
73
+ const q = new URLSearchParams({ embed: '1', plate, theme: dark() ? 'dark' : 'light' });
74
+ return <iframe ref={ref} src={`${ORIGIN}/${id}/index.html?${q}`} title={title} loading="lazy"
75
+ style={{ width: '100%', aspectRatio: '5 / 4', border: 0 }} />;
76
+ }
77
+ ```
78
+
79
+ Use it inside a Card's content, with the words in the card and the action on a Button:
80
+ `<LinejigFigure id="empty-inbox" title="Letter tray" plate="ffffff,0a0a0a" onAction={openComposer} />`. `hex()`
81
+ turns a computed `rgb(...)` into the six digits the address wants. The `plate` values here are examples:
82
+ read the real ones from the project's tokens.
83
+
84
+ ## Starting from the user's own illustration or SVG
85
+
86
+ The kernel draws only its own primitives: footprints extruded into rounded prisms (`K.rrect`, `K.circ`, `K.box`,
87
+ `K.turn`, then `K.solid`) and raw lines (`K.add`). It has no SVG import and no image tracing, so the user's artwork is
88
+ a reference you read and rebuild by hand, never a file the kernel loads.
89
+
90
+ 1. **Check the source.** Use the user's own drawing, or one they have the right to use. Never trace a generated
91
+ picture (`SKILL.md`, "What stays out").
92
+ 2. **Name the object and its parts.** What is it, what are its 8 to 12 parts, and which outline features make it
93
+ recognisable at thumbnail size? Drop every word, number, logo, texture, gradient and small detail in the source.
94
+ 3. **Rebuild each part as a footprint.** A rectangle or rounded rectangle becomes `K.rrect` (or `K.box` for a part
95
+ with a bevel), a circle becomes `K.circ`, a turned shape gets `K.turn`. For a free-form outline, sample the path
96
+ into points and build a ring of `{ u, v, nu, nv }` (position and outward normal), the footprint format the kernel
97
+ uses. Give each part a height (`w0`, `w1`) and a frame (`K.axes`), since an SVG is flat and the figure is not.
98
+ 4. **Place it in the one camera.** The view is always the 2:1 axonometric; a front-on SVG is redrawn in it, not
99
+ kept front-on. Set `fit.points` to the most extreme pose.
100
+ 5. **Choose the hero part.** The part the message is about (`references/styles.md`, "Which part takes the colour"):
101
+ it is the `hi` part. Drop the source's colours; the drawing is white, black and grey.
102
+ 6. **Give it hover and click.** Register its hit area with `K.hit(id, poly)` (the silhouette `K.solid` returns works),
103
+ give `HERO` its `onHover`, `onLeave` and `onClick` with the move the real part makes (`references/interaction.md`),
104
+ and an `action` with `opened(st)` if a click should hand off to the host page.
105
+ 7. **Plan the intro** with an `ASSEMBLY` table (`references/motion.md`, "Planning the stack"), then render and check
106
+ it like any other figure (`references/verify.md`), side by side with the source so the user can compare.
@@ -0,0 +1,98 @@
1
+ # Interaction rules
2
+
3
+ The illustration plays its intro (draw-on, then the hero's move), then becomes something the user can handle.
4
+ Interaction turns on only after the intro lands.
5
+
6
+ ## One hero, the rest still
7
+
8
+ - Name the hero before building: the one part that carries the message. It is the `hi` part. If the object has a
9
+ control that drives another part (a camera's shutter button drives the lens and shutter), the control is the hero:
10
+ hover is the half-press (the lens hunts focus), click is the full press (the shutter fires).
11
+ - **The hero can be a family** of identical parts that each work the same way: the keys of a keyboard, piano keys,
12
+ buttons on a panel, drawers in a cabinet. Then every member answers the pointer, one at a time (hover presses or
13
+ opens the one under the pointer; click does its full action). One member may carry the `hi` tone as the accent
14
+ (the keyboard's Enter); the rest keep their tones. The frame or case still stays still.
15
+ - Only the hero has its own response. Every other part moves only with the whole object, when the user turns or
16
+ zooms the view.
17
+ - The hero's response is what the real part does when touched or approached:
18
+
19
+ | Object | Hero | Hover | Click or tap |
20
+ |---|---|---|---|
21
+ | Camera | shutter button | half-press: the focus ring hunts | the shutter fires, the lever winds on |
22
+ | Compass | needle | turns toward the pointer, like a magnet, on the spring | swings off about 90° and settles back |
23
+ | Safe / chest | lid | lifts a little, as if unlatched | opens fully, then closes |
24
+ | Key | key | turns a quarter in the lock | turns fully and back |
25
+ | Keyboard | every key (a family), Enter as the `hi` accent | the key under the pointer presses down on the spring | its cap lifts to show the switch, then drops back |
26
+ | Balance | beam | tips toward the side under the pointer | swings and settles level |
27
+ | Theodolite | alidade and telescope | turns to sight the pointer | sweeps a bearing and returns |
28
+
29
+ If the hero has no natural response, choose another hero or another object.
30
+ - On leave, the hero springs back to rest.
31
+
32
+ ## Turning and zooming the view
33
+
34
+ - **Turn:** a click-drag, or a one-finger drag on touch, orbits the camera around the object. Clamp azimuth to ±40°
35
+ and elevation to 15° to 60° around the rest view, and damp it with the spring. On release the view stays for
36
+ about 2 s, then springs back to rest, so the drawing always returns to its composed view.
37
+ - **Zoom:** the wheel or a two-finger pinch, 0.8× to 2.5×, toward the pointer (orthographic zoom plus a pan). Lines
38
+ stay 1 px at every zoom. A double-click or double-tap resets the view.
39
+ - **Do not fight the page.** On a full-screen illustration the wheel may zoom. On an illustration embedded in a
40
+ scrolling page, the wheel zooms only with Ctrl or a pinch (the kernel does this under `?embed=1`), so scrolling still
41
+ scrolls. Put `touch-action: none` on the canvas only.
42
+
43
+ ## Hit testing
44
+
45
+ Raycast against the hero's fill mesh. Give it a generous, invisible hit area (a disc over the compass card, a box
46
+ around a key), so a thin part is easy to catch.
47
+
48
+ ## Hints
49
+
50
+ The cursor is the only hint: `grab` / `grabbing` over the object, `pointer` over the hero. No text, tooltips,
51
+ handles or UI chrome.
52
+
53
+ ## Reduced motion
54
+
55
+ Direct manipulation still works (the user is driving it), but with no springs or overshoot: the hero snaps to its
56
+ target and the view stays where it was left.
57
+
58
+ ## In the kernel
59
+
60
+ Figures are built on the kernel (https://linejig.com/kernel/linejig.js), which wires orbit, zoom, hit testing, cursors and reduced motion.
61
+ The figure registers hit areas while it draws (`K.hit(id, poly)`, nearest last) and names its hero:
62
+
63
+ ```js
64
+ HERO: { onHover(id, p, K) {}, onLeave(id, K) {}, onClick(id, p, K) {}, action: 'compose', opened(st, K) {} }
65
+ ```
66
+
67
+ `id` is the hit area's id, so a family hero gets one per member. `K.hover` and `K.pointer` are there each frame for a
68
+ hero that follows the pointer (the needle, the focus ring).
69
+
70
+ ## The action event
71
+
72
+ A hero's click can hand off to the host page: an empty state's "compose", an onboarding step's "continue". Give the
73
+ hero `action: '<id>'` and `opened(st)`, true once its move reaches its open state (the lid open, the cap lifted).
74
+ At that moment the kernel posts `{type: 'action', id, figure}` to the parent when embedded, and dispatches a
75
+ `linejig:action` CustomEvent on the window when standalone (`keyline3d:action`, the older name, fires as well; listen to one). Without `opened`, it fires one tween (700 ms) after
76
+ the click. The host owns the words (the gallery shows the manifest's `action.label` as a button); the drawing never
77
+ does.
78
+
79
+ ## Turntable mode
80
+
81
+ `?mode=turntable`, or the `mode` message: no hand, and after the intro the object turns slowly about its vertical
82
+ axis, ±35° over 40 s (or one full turn in 40 s with `turntable: 'full'`, only for a figure whose back is finished).
83
+ For loading screens and screen-recorded loops. Reduced motion holds it still.
84
+
85
+ ## Open finished, click from the host, keyboard
86
+
87
+ - `?intro=none` (any figure) opens the figure finished and live, with no intro played. `def.intro: 'none'` and
88
+ `fig.setIntro('none')` do the same. With none, `?freeze=MS` counts from the finished state. `none` is never listed in
89
+ the `intros` the figure reports, so menus built from that list stay as they were.
90
+ - Embed message in: `{type: 'click', id?}` clicks the hero as a pointer press would (id defaults to the hero), and
91
+ `{type: 'intro', value: 'none'}` jumps to the finished figure. The `ready` message carries `click: true`, so a host
92
+ can check for the click message before relying on it.
93
+ - The `createFigure` result has `setIntro(name | 'none')` and `click(id?)`. A def can carry `name` (used for the
94
+ aria-label) and `HERO.label` (the action's wording).
95
+ - Keyboard: a figure with `HERO.action` that is interactive and takes pointer events is a button. Tab focuses it and
96
+ shows the hover state with a 2 px ink focus ring around the object; Enter or Space clicks; Escape or blur leaves.
97
+ Turntable, freeze and `pointer-events: none` hosts get no tab stop. A cross-origin host that disables pointer events
98
+ on the iframe should also set `tabindex="-1"` on it.
@@ -0,0 +1,50 @@
1
+ # Choosing the object
2
+
3
+ ## What makes a good object
4
+
5
+ An object earns its place when it does three jobs at once:
6
+
7
+ 1. **It says the message without words.** Someone who sees only the drawing gets the idea: a safe holds things
8
+ securely, a balance is level, a key opens one door.
9
+ 2. **Its structure echoes the content, silently.** Three service groups become three trays; stages become
10
+ landings. The drawing carries no labels, so the echo has to work without words, or not be needed.
11
+ 3. **It belongs to the brand's world.** Find the brand's own world of instruments, tools and buildings, and draw
12
+ every object in a set from it, so the figures read as one family. A coffee roaster's world is scales, grinders,
13
+ sacks and kettles; a shipping company's is cranes, containers and signal lamps. Do not reuse one brand's set for
14
+ another.
15
+
16
+ Then check:
17
+
18
+ - **Can it be drawn from a few rounded solids?** Objects made of rounded boxes, discs, rings and extrusions
19
+ (chests, instruments, steps, rails) draw cleanly. If it only reads with fine detail, choose something simpler. Soft, organic or figurative subjects (animals, people, cloth)
20
+ do not belong in this system.
21
+ - **Does it have one simple move?** A lid opens, a key turns, a telescope swings, a camera descends a stair. If the
22
+ only way to animate it is a complex choreography, choose something simpler.
23
+ - **A specific object over the stock cliché, and nothing sacred.** For an idea such as saving, growth or payment,
24
+ prefer the object that belongs to this message and this brand (a strongbox, a balance) over the stock picture (a
25
+ piggy bank, a rising arrow, a pile of coins). The stock object is fine when it is the literal subject: the library
26
+ ships `piggy-bank` and `coin-stack` for pages that are about exactly those things. No deity figures, and no icons
27
+ or clip art.
28
+
29
+ Write it down before you build: "Section X says Y. Object Z, because its parts A, B and C are the items P, Q and R,
30
+ and its one move is M."
31
+
32
+ ## An example set
33
+
34
+ An invented brand, to show the shape of the thinking: a freight forwarder whose world is the port.
35
+
36
+ | Section and message | Object | Why it works | Parts and move |
37
+ |---|---|---|---|
38
+ | Services: everything your cargo needs, in one place | **Shipping container** | One box that holds everything is "in one place" | Three stacked crates inside are the service groups; the doors swing open and the crates slide out one after another |
39
+ | The promise: honest weights, no hidden fees | **Platform scale** | A level scale reads at once as fair | Platform and dial; it draws on and the needle settles |
40
+ | Fit: who it is for | **Mooring bollard** with one line | One line made fast to one bollard: the right client, the right firm | The line drops over the bollard and pulls taut |
41
+ | Journey: the stages of a shipment | **Lock gates**, in section | Rising chamber by chamber is a journey with clear stages and an end | Each chamber is a stage; the camera moves along the section |
42
+
43
+ Not every section needs an object. When the copy is a statement, let the type carry it.
44
+
45
+ ## Signs you picked the wrong object
46
+
47
+ - You need a legend to explain it.
48
+ - It only makes sense once labelled.
49
+ - It needs colour, shading, texture or fine detail to be recognisable.
50
+ - The move you want is a dramatic event (an explosion, a transformation) instead of how the object is really used.