feat: add explained assembly pattern with offline example and QA
This commit is contained in:
1 parent
50eab114ae
commit
563aaf4757
17 files changed
+341
-3
No files matched your search
@@ -0,0 +1,53 @@
|
||||
# Explanatory mechanisms: assemble, explode, inspect, reassemble
|
||||
|
||||
## When to read this reference
|
||||
|
||||
Read **before storyboarding or coding** when an audience needs to understand how parts form a whole: architecture decomposition, product internals, modularity, ownership boundaries, or a user request for a mechanical/exploded-view animation. Also read when a simple stagger feels decorative rather than explanatory. Do not load it merely to add motion to a factual table.
|
||||
|
||||
## Evidence and source boundaries
|
||||
|
||||
The following Anime.js showcase recordings were inspected on 2026-10-21 via Awwwards after the live Anime.js homepage timed out. These are observations of recorded visuals, **not verification of live scroll/input behavior, implementation source, or the 3D rendering engine**.
|
||||
|
||||
| Reference | Observed lesson | Use when |
|
||||
|---|---|---|
|
||||
| [The complete animator’s toolbox](https://www.awwwards.com/inspiration/the-complete-animator-s-toolbox-anime-js) | A shaded mechanical assembly opens into an exploded arrangement and a technical drawing with callouts. Preserve object identity while changing explanatory depth. | Explain internals of a system already introduced as a whole. |
|
||||
| [Lightweight and modular](https://www.awwwards.com/inspiration/lightweight-and-modular-anime-js) | Separated parts become a compact assembly beside a bundle-size display. Motion connects modular composition to an outcome. | Explain optional modules, assembly, or contribution to a total. |
|
||||
| [Scroll scrubber](https://www.awwwards.com/inspiration/scroll-scrubber-anime-js) | Navigation reference listed on the showcase; live interaction was not tested in this research. | Investigate reversible progress control; verify actual input behavior separately before adopting it. |
|
||||
| [Anime.js showcase](https://www.awwwards.com/sites/anime-js) | Credits Julian Garnier; records Site of the Day, May 6, 2025. | Recover attribution and the recording catalog, not implementation evidence. |
|
||||
|
||||
No license to redistribute the showcase artwork or recordings was established. Keep these as links and observations; do not package downloaded videos, screenshots, logo paths, or reconstructed branded art as reusable skill assets. The MIT library license is not permission to copy the showcase's artwork.
|
||||
|
||||
## Original reusable asset
|
||||
|
||||
- Editable source: [`assets/mechanism.html`](../assets/mechanism.html).
|
||||
- Offline builder: [`scripts/build-mechanism.py`](../scripts/build-mechanism.py).
|
||||
- Runnable output: `dist/mechanism-demo-0.2.0.html`.
|
||||
- Browser acceptance suite: `scripts/test-mechanism.mjs`.
|
||||
|
||||
This is an **original abstract 2D SVG assembly**, not a reproduction of the photographed/shaded mechanism and not a 3D renderer. Interface, Processing and Storage keep their DOM identity as they separate and recombine. Four native buttons expose assemble → explode → inspect → reassemble. All three components support click, Enter and Space; their details explain responsibility boundaries. Original source is covered by the package MIT license. Anime.js and font notices are embedded in the build.
|
||||
|
||||
Use `terminal` in the copied package directory:
|
||||
|
||||
```text
|
||||
python3 scripts/build-mechanism.py
|
||||
node scripts/test-mechanism.mjs
|
||||
```
|
||||
|
||||
Reuse the component groups, stable coordinates, state transitions and lifecycle cleanup together—not only the animation call. Set `CHROMIUM_EXECUTABLE` if the package's Playwright browser is not installed. Never copy machine-local browser paths into the shared skill.
|
||||
|
||||
## Adaptation contract
|
||||
|
||||
1. Write the explanation first: whole → parts → responsibility → whole. Use the original assembly only where its three responsibilities actually fit the subject.
|
||||
2. Maintain stable component IDs, color and relative order. Do not replace the object with an unrelated diagram mid-transition.
|
||||
3. Use callouts outside moving geometry for lengthy details. Assembled overlap is intentional; exploded labels must all be readable.
|
||||
4. Interruption is a supported action: settle the previous animation before starting another. Repeated clicks must converge on the last selected state.
|
||||
5. Prefer explicit state buttons for a talk. If a scrubber is justified, add a keyboard-accessible range input and test reversible progress; **the included example has no scrubber**.
|
||||
6. On reduced-motion changes, page departure and print, settle motion. Print expands all components. On Reveal `slidechanged`, explicitly settle the outgoing mechanism; do not let Reveal Auto-Animate and Anime own the same transform.
|
||||
7. Reveal owns presentation steps and sizing; Anime coordinates part movement. The bundled mechanism is standalone so it can be studied without Reveal. When integrating, preserve the host deck's fullscreen, navigation, offline packaging and QA contract.
|
||||
8. For genuine perspective, occlusion and camera orbit, select and validate a separate 3D layer. Do not claim Anime alone renders 3D from an observed video.
|
||||
|
||||
## Acceptance and limits
|
||||
|
||||
Test all four controls, all three parts by mouse/Enter/Space, intermediate motion, reverse/repeated input, reduced motion and runtime preference changes, print expansion, offline requests, console errors and exploded text bounds. Inspect assembled, exploded and selected screenshots personally. Hash the exact tested output.
|
||||
|
||||
The standalone demo is not a full slide deck. Its tests do not prove Reveal integration, live scrubbing, Safari/Firefox, screen-reader output, projector readability or a native 3D implementation. Run the full deck suite after embedding it.
|
||||
Reference in new issue
Block a user