Skip to main content
Glama
jhn-kim

motionworks

by jhn-kim

MotionWorks

一个为使用 AI 编码代理构建的项目提供的直接操作式动效设计层。

MotionWorks 运行在你的本地应用之上,让你可以选中真实元素、凭感觉调整动效、回放、与原始版本对比,并应用结果。可调值存放在 CSS 自定义属性中,因此浏览器可以立即预览,本地守护进程可以将精确的更改写回源码。

用描述来创建。用操作来打磨。

快速开始

安装单个包并初始化项目:

npm install -D motionworks
npx motionworks init

init 会将 .motionworks/ 添加到 .gitignore,移除过期的 MotionWorks MCP 条目(如果存在),并写入一份生成的 MOTIONWORKS.md 指南,以及一段供 Claude Code 和 Codex 使用的简短引用片段。在 React 项目中,它还会在需要时确认包的安装。

在单独的终端中启动你的应用和 MotionWorks 守护进程:

npm run dev
npx motionworks

对于 React,请按照生成的指南,在仅用于开发的独立 React 根节点中挂载一次 MotionWorksProvider。对于任何其他页面,请在 </body> 之前加载独立覆盖层:

<script src="http://127.0.0.1:52340/motionworks.js"></script>

MotionWorks 还可以托管静态目录并自动注入覆盖层:

npx motionworks serve .

Related MCP server: convey

CSS 契约

每个可调值在已注册元素规则对应的真实样式表中都有一条规范声明:

.card {
  --mw-radius: 120px;
  --mw-response: 0.18;
}

React effects 只注册 schema。hook 从 CSS 读取基线值;effect 代码通过 readParams 消费这些值,并通过 onParamsChange 响应 motionworks:change:

import { useEffect, useRef } from 'react';
import { onParamsChange, readParams, useMotionWorks } from 'motionworks/react';

const schema = {
  name: 'Magnetic card',
  params: {
    radius: { type: 'spatial-radius', label: 'Radius', unit: 'px' },
    response: { type: 'temporal-response', label: 'Response' },
  },
} as const;

function MagneticCard() {
  const ref = useRef<HTMLDivElement>(null);
  useMotionWorks(ref, schema);

  useEffect(() => {
    const el = ref.current;
    if (!el) return;
    const effect = createMagneticEffect(el, readParams(el, schema.params));
    const sync = () => effect.update(readParams(el, schema.params));
    const stop = onParamsChange(el, sync);
    return () => {
      stop();
      effect.destroy();
    };
  }, []);

  return <div ref={ref} className="card" />;
}

纯 HTML 可以通过 data-motionworks 注册相同的 schema,并使用 window.MotionWorks.readParams / window.MotionWorks.onParamsChange。

点击 Apply 后会发生什么

Apply 是先持久化,再自动化:

  1. 覆盖层向 .motionworks/changes.json 追加一条记录。

  2. 守护进程直接编辑唯一匹配的 CSS 声明。

  3. 如果声明有歧义,守护进程会在可用时运行 Claude 或 Codex。

  4. 如果没有代理能完成,该记录将保持待处理状态,等待 Copy prompt 和 npx motionworks changes。

代理只修改列出的声明,并通过 npx motionworks ack <id> 确认手动写回。当设计师提到"这个"时,npx motionworks status 会报告当前选中的 effect。

包导出

该仓库有一个可发布的包 motionworks:

导出

用途

motionworks

浏览器安全的 schema 和日志类型

motionworks/react

useMotionWorks、MotionWorksProvider 和浏览器辅助函数

motionworks/browser

无框架的 CSS 绑定和事件辅助函数,包括 DEFAULT_VAR_PREFIX

motionworks/node

编程式守护进程、日志、设置、配置和静态托管 API

motionworks/motionworks.global.js

独立浏览器 bundle

motionworks CLI

守护进程、静态托管、日志命令、设置和状态

React 和 ReactDOM 是可选的 peer 依赖;非 React 页面使用独立 bundle。

CLI

npx motionworks                          Start the local daemon
npx motionworks serve <dir>              Serve a static site with the overlay
npx motionworks changes [--json|--brief] Show pending journal entries
npx motionworks ack <id>|--all           Acknowledge manual writebacks
npx motionworks status                   Show daemon and current selection
npx motionworks revert <id>              Revert an applied entry
npx motionworks init                     Set up the project and agent guide

当找到 claude 或 codex 时,自动代理执行会被启用。使用 --no-agent 进行手动交接,或使用 --agent=claude|codex|off 显式选择。守护进程绑定到 127.0.0.1:52340;MOTIONWORKS_PORT 或 --port 可以更改端口。

开发

该仓库是一个 npm workspace,在 packages/motionworks 下有一个包。它使用 tsup 构建,使用 Vitest 测试。

npm install
npm run build
npm run typecheck
npm test

已完成的 0.5.0 桥接重建记录在 docs/plans/bridge-rebuild.md 中;维护中的架构和契约位于 docs/ 中。

许可证

MIT © John Kim

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    D
    maintenance
    Enables designing, modifying, and bug reporting in web apps, sending changes to coding agents via MCP.
    5 npm
    46
    MIT
  • A
    license
    Not graded
    quality
    A
    maintenance
    Enables AI agents to create and manage consistent multi-screen UI designs through a token-efficient MCP interface, with design system tokens, components, flows, and visual review.
    564 npm
    2
    AGPL 3.0
  • A
    license
    Not graded
    quality
    B
    maintenance
    Provides AI coding agents with structured access to design research, component libraries, motion systems, design DNA extraction, visual search, and production workflows through MCP and SDK interfaces.
    2 npm
    Apache 2.0