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.
- package/LICENSE +16 -0
- package/README.md +89 -2
- package/bin/cli.mjs +331 -0
- package/lib/bundle.mjs +98 -0
- package/lib/names.mjs +10 -0
- package/package.json +42 -4
- package/skill/linejig/SKILL.md +194 -0
- package/skill/linejig/references/drawing.md +93 -0
- package/skill/linejig/references/integration.md +106 -0
- package/skill/linejig/references/interaction.md +98 -0
- package/skill/linejig/references/metaphors.md +50 -0
- package/skill/linejig/references/motion.md +119 -0
- package/skill/linejig/references/styles.md +33 -0
- package/skill/linejig/references/verify.md +37 -0
- package/skill/linejig/scripts/starter.html +65 -0
|
@@ -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.
|