home-icon-motion

Generate and integrate a polished semantic Home icon motion — a flat house constructs into a crisp faux-3D home, illuminates its windows, emits a short warm beam, and collapses cleanly back to rest.

License: Apache-2.0 Validate Agent Skills

No Figma. No Lottie. No runtime dependency in the Web Component core.

→ Open the interactive demo

Home icon motion preview

What it does

home-icon-motion is an Agent Skill for creating a specific, production-ready Home interaction. It can:

  • generate standalone HTML, MP4, WebM, GIF, and poster assets;
  • integrate into an existing React, Next.js, Remix, Vue, or Nuxt Home control;
  • provide a framework-neutral Shadow DOM Web Component for other frontends;
  • replay on every Home activation without moving the button, label, or navigation layout;
  • respect prefers-reduced-motion by holding the resting flat house;
  • validate timing continuity, replay behavior, fixed bounds, SSR safety, and completion events.

The skill is intentionally Home-only. Delete, Search, and unrelated icon meanings are outside its scope.

Quick start

Codex

Install it in your user skills directory:

git clone https://github.com/youwenjiujiu/home-icon-motion.git ~/.agents/skills/home-icon-motion

Then invoke it explicitly:

$home-icon-motion Integrate the polished Home motion into this React navigation button.

Or describe the task naturally. Codex can select the skill when the request matches its description:

Animate the existing Home icon and replay the motion on every activation.

If the skill does not appear immediately, restart Codex.

Install with Codex skill-installer

$skill-installer Install home-icon-motion from https://github.com/youwenjiujiu/home-icon-motion

Generate an artifact

python3 scripts/generate_home_motion.py \
  --label Home \
  --target all \
  --exports mp4,webm,poster \
  --output ./home-motion-output

The default animation is five seconds at 60 fps. Generated developer output includes:

developer/
├── web-component/
│   ├── icon-motion.js
│   └── icon-motion.d.ts
├── react/
├── vue/
├── index.html
└── USAGE.md

Integrate into an existing frontend

Scan first:

python3 scripts/prepare_project_integration.py \
  --project /path/to/project \
  --scan-only

Generate project-local source:

python3 scripts/prepare_project_integration.py \
  --project /path/to/project \
  --label Home \
  --accent '#247CFF' \
  --light '#F3FF0B'

The integration workflow preserves the real button or link, its route/state action, focus behavior, accessible name, label, and layout allocation. Only the static Home glyph is replaced.

Motion language

One coordinated timeline drives the complete sequence:

rest → aligned construction → illuminated hold → causal light-off → structural fold → rest

The flat glyph and front plane align before a continuous crossfade. Light retracts before windows close; windows and doorway close before the roof and side plane fold. Inline mode keeps the host fixed at 24–48 px and never scales or moves the surrounding control.

See references/motion-language.md for geometry, layer order, timing, easing, and color rules.

Quality gates

The developer validator checks:

  • visible response within 250 ms;
  • dense 0.5%-timeline continuity sampling with no hard opacity cut;
  • monotonic construction and collapse;
  • exact opening/closing resting-state match;
  • fixed host bounds at narrow and wide viewports;
  • repeat activation and exactly one non-loop completion event;
  • play, pause, restart, seek, and setProgress APIs;
  • prefers-reduced-motion behavior;
  • SSR-safe module evaluation;
  • zero browser console and page errors.

Run it against the generated developer demo:

python3 -m http.server 4173 --directory ./home-motion-output/developer

node scripts/validate_component.mjs \
  --url http://127.0.0.1:4173/ \
  --output ./home-motion-validation

Requirements

  • Python 3.9+ for generation and project scanning.
  • Node.js and Playwright for browser rendering and component validation.
  • FFmpeg for MP4, WebM, and GIF export.
  • No runtime dependency for the generated Web Component.
  • React and Vue wrappers use those frameworks as optional peer dependencies.

Project structure

SKILL.md                          Skill entry point
assets/                           Motion and framework templates
references/                       Motion language and integration contracts
scripts/generate_home_motion.py   Standalone/developer generator
scripts/prepare_project_integration.py
scripts/render_motion.mjs         Video and poster renderer
scripts/validate_component.mjs    Browser QA harness
docs/                             Interactive GitHub Pages demo

Roadmap

The project stays deliberately focused on Home semantics. Planned improvements are listed in ROADMAP.md.

Contributing

Motion-quality fixes, browser compatibility improvements, framework adapters, and stronger validation gates are welcome. See CONTRIBUTING.md.

License

Apache License 2.0. See LICENSE.