Identity motion

Organism · draft · v1.0.0 · owner: Site system lead · contract 19 of 20 points (open: figma)

Do and don't

Do: Monochrome repair

Rendered by identity-motion.ts

Open example: Identity motion · Do: Monochrome repair Use the full-page example to follow page links.

The same sequence retains its crossing and gaps without colour.

Do: Eight repair frames

Rendered by identity-motion.ts

Open example: Identity motion · Do: Eight repair frames Use the full-page example to follow page links.

The selected sequence with inspectable frames.

Do: Japanese operations

Rendered by identity-motion.ts

Open example: Identity motion · Do: Japanese operations Use the full-page example to follow page links.

The same illustration with translated controls.

Do: Six assembly frames

Rendered by identity-motion.ts

Open example: Identity motion · Do: Six assembly frames Use the full-page example to follow page links.

The final still and available frame declarations expose the complete assembly sequence; playback remains a separate check.

Do: Fragments to a system

Rendered by identity-motion.ts

Open example: Identity motion · Do: Fragments to a system Use the full-page example to follow page links.

This explanatory kind has its own positive specimen, labelled as an illustration.

Do: Review and realign

Rendered by identity-motion.ts

Open example: Identity motion · Do: Review and realign Use the full-page example to follow page links.

The final static scene retains review as part of the explanation, without claiming a real repair.

Don't: Claim the illustration repaired a real system

Rendered by identity-motion.ts

Open example: Identity motion · Don't: Claim the illustration repaired a real system Use the full-page example to follow page links.

The proposed claim "Your system repaired automatically" would mistake an illustration for execution evidence. Retain the illustration caption and use attributable product evidence for any real repair claim. The adjacent native artwork is the valid illustration reference; this warning describes a misuse, not an executed negative test.

Don't: Treat the final frame as approval to release

Rendered by identity-motion.ts

Open example: Identity motion · Don't: Treat the final frame as approval to release Use the full-page example to follow page links.

The proposed instruction "Release without review" would bypass the human decision represented by Review and realign. Keep that review step and obtain a recorded review decision before release. The adjacent native artwork is the valid drift illustration reference; the bypass is described, not rendered or rejected.

Rules

Rule	Why	Check
Positive specimens declare their rendered initial state and document language; each registered visual variant has a positive example.	Machine and Library consumers need the same examples without turning declarations into execution evidence.	Automated: tests/unit/v4-example-coverage.test.ts
Repeated static instances supply distinct stable instanceKey values; identical inputs are deterministic, and each runtime root scopes all scene/thumbnail masks.	Source exports must be reproducible and simultaneous SVG consumers must not share mask identities.	Automated: tests/unit/identity-instance-identity.test.ts
Every sequence has pause and frame selection and respects reduced motion.	Readers control movement and can inspect the explanation at their pace.	Automated: tests/site/identity.spec.ts
Label the sequence as an illustration, never a product result.	Brand motion cannot stand in for execution evidence.	Automated: tests/unit/site-identity.test.ts

API

Prop	Type	Required	Default	What it does
`instanceKey`	string	No	`"identity-motion"`	Stable caller-owned key: a letter followed by letters/digits/underscore/hyphen, at most 64 characters. Repeated static instances of a sequence in one document require distinct keys; identical inputs render identical bytes.
`tone`	context \| mono	No	`"context"`	Context-aware colour or one-colour geometry proof.
`kind`	repair \| assembly \| hero \| drift \| operations	No	`"repair"`	Which selected sequence to show.
`lang`	en \| ja	No	`"en"`	Caption and controls language.

Contract details

The full contract: identity, anatomy, variants, states, tokens, layout, motion, accessibility, content, tests

Identity

Aspect	Value
Id	`identity-motion`
Layer	Organisms
Category	showcase
Owner	Site system lead
Status	draft
Version	1.0.0
Source	`apps/showcase/site/system/organisms/identity-motion.ts` (private repository; the contract and the render function are this one module)

Version	Date	Change
1.0.0	2026-10-27	Created from the owner-selected V4 direction (D-SITE-019).

Use when

Beside the idea the sequence explains. Why: Motion makes the relationship between pieces and rules visible.

Do not use when

As evidence of a real audit or repair. Why: These are explicitly labelled illustrations; product demonstrations retain their own evidence.

Anatomy

Part	What it is
root	Named figure
scene	SVG geometry
steps	Eight repair frames, six assembly frames or four explanation frames
controls	Play, previous, next, replay and frame slider

Made of: identity-art, caption.

Used in: pages directly.

Variants

Variant	When	Why
repair	Break and repair	Uses the same tokens and geometry for a different explanatory job.
assembly	Logo assembly	Uses the same tokens and geometry for a different explanatory job.
hero	From fragments to a system	Uses the same tokens and geometry for a different explanatory job.
drift	Drift, seen and resolved	Uses the same tokens and geometry for a different explanatory job.
operations	A question finds its owner	Uses the same tokens and geometry for a different explanatory job.

States

State	Rendered or not applicable
default	default
hover	Not applicable: The illustration is not interactive, so it has no hover state.
focus-visible	Visible focus on every playback control.
active	Play becomes Pause.
disabled	Not applicable: The illustration has nothing to disable.
loading	Not applicable: The illustration is rendered at build time and is complete when the page loads.
empty	Not applicable: The illustration is not rendered without content; the builder skips it.
error	Not applicable: The illustration shows no data that can fail.
current	The current frame has its label and aria-current.
visited	Not applicable: The illustration is not a link.
expanded	Not applicable: The illustration does not open or close.

Tokens

Part	Token
--identity-motion-surface	`var(--cotton)`
--identity-motion-ink	`var(--ink)`
--identity-motion-ink-muted	`var(--ink-2)`
--identity-motion-control-surface	`var(--surface)`
--identity-motion-control-hover	`var(--surface-2)`
--identity-motion-line	`var(--line-strong)`
--identity-motion-rule	`var(--rule-hair)`
--identity-motion-focus-width	`var(--rule)`
--identity-motion-focus	`var(--focus)`
--identity-motion-focus-offset	`var(--space-2)`
--identity-motion-title	`var(--type-h3)`
--identity-motion-caption	`var(--type-small)`
--identity-motion-mono	`var(--font-mono)`
--identity-motion-accent	`var(--indigo-ink)`
--identity-motion-route	`var(--madder-ink)`
--identity-motion-gap	`var(--space-4)`
--identity-motion-gap-small	`var(--space-3)`
--identity-motion-gap-section	`var(--space-6)`
--identity-motion-padding	`var(--space-8)`
--identity-motion-scene-space	`var(--space-9)`
--identity-motion-status-gap	`var(--space-5)`
--identity-motion-target	`var(--space-11)`
--identity-motion-scene-unit	`var(--space-13)`
--identity-motion-duration	`var(--dur-weave)`
--identity-motion-easing	`var(--ease-standard)`

Layout

Aspect	Value
breakpoints	Required review at 390, 768, 1024 and 1440 px; execution is not implied by this declaration; columns stack under 768 px; the wrap keeps a 16 px gutter on phones.
wrapping	Text wraps; nothing scrolls sideways.
textExpansion	Japanese runs 20 to 40% longer; headings break between phrases (jaBreaks) and blocks grow downwards.

Spacing and rhythm

Aspect	Value
internal	--space-8 scene and --space-6 controls
external	--space-9 block spacing
rhythm	One explanatory moment after the section's claim.

Motion

Aspect	Value
moves	Individual threads, bars or geometric modules.
trigger	Once on entering the viewport, or Play; Replay restarts. No infinite autoplay.
duration	4 seconds per authored frame; geometric interpolation over --dur-weave with --ease-standard. One owned animation frame callback; manual frame selection remains immediate.
easing	--ease-standard
interruptible	Pause, step controls and slider stop immediately; leaving view or hiding the tab pauses.
reduced	Final frame, no autoplay or transitions. Manual frame selection and explicitly requested timed playback remain available without transitions. Changing the preference pauses playback and restores the final frame.
why	The owner selected the V4 sequences; controlled playback keeps them readable and optional.

Runtime and reuse

stylesheet: /css/site.css. Built Site tokens, core and registered element CSS; preserve modes, focus and responsive rules.
stylesheet: /css/demos.css. Existing legacy demo styles where the rendered specimen uses them.
font: /fonts/. Self-hosted files referenced by Site @font-face, with licences; Japanese locale overrides remain applicable.
Static fallback: Original build-time specimen remains readable before loading and after chunk/initialization failure; enhancement controls retain authored hidden state.
Configured initializer: apps/showcase/site/interactives/identity-motion.ts#init. The host owns transactional static-markup restoration and runtime state.

Consumer module (imports relative to the configured source root):
import { createRuntimeHost } from "./src/workflows/runtime-host";
import { SITE_RUNTIMES } from "./apps/showcase/site/runtime-registry";
const definition = SITE_RUNTIMES.find(entry => entry.binding.id === "identity-motion");
if (!definition || definition.binding.lifecycle.kind !== "managed") throw new Error("Managed runtime binding unavailable");
const host = createRuntimeHost([definition]);
export function mountRuntime(container: ParentNode) { return host.mountAll(container); }

After inserting the rendered markup, call mountRuntime(container) for the container holding [data-demo="identity-motion"]. Retain the returned disposal function and call it before removing, replacing or remounting, including every Storybook args render. The configured host restores captured static markup/attributes on disposal or caught load/initialization failure; retry starts a fresh managed remount.

Accessibility passport

Aspect	Value
role	figure
name	Visible caption
keyboard	Tab to buttons; Space or Enter activates; range arrows and Home/End choose frames.
focus	--focus ring
screenReader	Frame slider has the current description; only manual changes are announced politely.
contrast	Text uses ink on cotton; dyes encode geometry with a written description.
target	Controls at least --space-11 tall.

Content

Slot	Length	Voice
caption	Two sentences	Label the sequence as an illustration.

Good: “Illustration of the idea; not a live system result.”

Bad: “Your system repaired automatically.”

Japanese: 全キャプション、フレーム、操作に日本語を用意。 Native language review remains pending.

Icons and illustrations

art:v4-repair-1
art:v4-repair-2
art:v4-repair-3
art:v4-repair-4
art:v4-repair-5
art:v4-repair-6
art:v4-repair-7
art:v4-repair-8
art:v4-assembly-1
art:v4-assembly-2
art:v4-assembly-3
art:v4-assembly-4
art:v4-assembly-5
art:v4-assembly-6
art:v4-hero-1
art:v4-hero-2
art:v4-hero-3
art:v4-hero-4
art:v4-drift-1
art:v4-drift-2
art:v4-drift-3
art:v4-drift-4
art:v4-operations-1
art:v4-operations-2
art:v4-operations-3
art:v4-operations-4

Decisions and exceptions

D-SITE-019: V4 identity, break and repair, and the supporting family

Usage

290 uses across the built pages (measured by npm run site:system).

Tests

Aspect	Value
unit	tests/unit/site-system.test.ts: renders every do and don't example through the registry and checks the classes it owns
visual	Not yet: there are no screenshot baselines; the Library page is checked for sideways scroll at 1440 px by tests/site/system.spec.ts
a11y	tests/site/system.spec.ts: axe (0 serious or critical) on the element's Library page in light and dark
parity	scripts/site/system/check.ts: Library examples are rendered by the same render function the site imports

Figma

not-yet: The Loom Site Figma library is the last stage of the plan; this element is not mapped yet.

Open in Storybook

Do and don't

Do: Monochrome repair

Do: Eight repair frames

Do: Japanese operations

Do: Six assembly frames

Do: Fragments to a system

Do: Review and realign

Don't: Claim the illustration repaired a real system

Don't: Treat the final frame as approval to release

Rules

API

Contract details

Identity

Use when

Do not use when

Anatomy

Variants

States

Tokens

Layout

Spacing and rhythm

Motion

Runtime and reuse

Accessibility passport

Content

Icons and illustrations

Decisions and exceptions

Usage

Tests

Figma

More organisms

Start with a conversation about your system.