transitions-ui-generation

过渡式 UI 生成

在页面任意元素上播放「Agent 正在生成」动画，然后切换为真实 UI。没有任何伪造：绘制内容根据元素本身测量，因此点状轮廓、文本行和图标都能准确落在真实 UI 出现的位置。

适用于所有能读取技能的 Agent（Claude Code、Cursor、Codex 等）：使用 npx skills add Jakubantalik/transitions.dev 安装，或将此文件夹复制到项目中。

绘制内容

在一次构建过程中，按顺序播放（默认绘制时长为 2400ms，总时长约为 2.6s）：

1. 点阵。 小圆点组成的网格从中心向外扩散，矩阵雨沿列落下，并有一条探测线扫过。
2. 构建。 辅助线沿元素边缘延伸并经过各个角，角点手柄弹出，尺寸标签随构建计时器逐渐计数至真实尺寸。
3. 轮廓。 轮廓从顶部中心开始，沿两个方向以流动的小圆点描绘；散落的圆点飞来并落在轮廓上。
4. 部件。 按文档顺序描绘每个框、文本行和图标路径。关键元素（按钮、输入框、最大的框）会有各自的辅助线、手柄和尺寸标签，瞄准准星会在各部件间跳转，并显示坐标读数。
5. 显现。 真实 UI 从上到下在扫描线后方显现，按照 --ease-smooth-out 淡入并变清晰，同时绘制内容被擦除，圆点也随之消散。

选项

模式	效果	适用场景	参考
skeleton	点状绘制和显现效果。	大多数场景：Agent 生成的卡片或面板、逐渐填充的空状态、主视觉时刻。	01-skeleton.md
skeleton-texts	同样的效果，另加生成文本：Agent 日志（每个部件一行，并带进度条）、正在编写的动效 CSS（元素自身的值，采用 transitions.dev 令牌刻度），以及步骤提示行（「规划布局」……「就绪」）。	展示和发布时刻，适用于需要讲述「由 Agent 构建」故事的场景：落地页、演示、引导流程、产品视频。元素旁边或下方需要留出空间；文本只会放在页面的空白区域。	02-skeleton-texts.md

选择规则

• AI 功能返回 UI（生成的组件、图表、摘要卡片、草稿）→ 使用 skeleton，并在结果到达时播放。
• 落地页、演示或视频需要讲述「由 Agent 构建」的故事 → 使用 skeleton-texts，并在内容滚动进入视野时播放。
• 用户要求「文本」「日志」「代码流式输出」「未来感版本」 → 使用 skeleton-texts。
• 同时展示多个元素（结果网格）→ 对每个元素使用 skeleton，并为每项设置约 260ms 的 delay。文本一次只能适配一个元素周围。
• 小型内嵌 UI（徽章、单个按钮、任何小于约 120px 的元素），或频繁出现的 UI（每次路由切换、列表中的每一行）→ 不要使用此效果。改用 transitions-dev 骨架显现效果（14-skeleton-reveal.md）或文本显现效果：生成动画是一个瞬间，而不是加载状态。
• 不确定该用哪种模式 → 使用 skeleton。添加文本前先询问。

命令

transitions generate

触发短语： transitions generate、「添加生成动画」、「让它看起来像 AI 生成的」、「把它动画化，呈现 Agent 构建的效果」。

行为：

1. 找到目标元素：用户指定的元素、打开文件中的组件，或最靠近光标的元素。如果有歧义，请询问具体是哪一个。
2. 按照选择规则选择模式（默认使用 skeleton）和触发时机：挂载时、数据到达时、滚动进入视野时，或按需触发。
3. 用一句话提出方案，例如：「我会在响应到达时，在 <ResultCard> 上播放 skeleton。确认吗？」
4. 确认后，按照下方的 ## Install 和 ## Wiring 操作。尽量缩小差异。

transitions generate texts

与 transitions generate 相同，使用 mode: "skeleton-texts"。请说明文本需要在元素旁边或下方留有空白，没有空白的位置会跳过。

transitions generate preview

打开 demo.html（通过 HTTP 提供此文件夹，例如在此目录中运行 npx serve），即可查看 transitions.dev Community 上发布的三个组件（Heart Rate Monitor、Chart card、Music Player Likes）的两种模式。页面采用单卡片布局，展示侧边面板。每个组件都挂载在独立的 shadow root 中，因此其样式和脚本会保持发布时的原样。

安装

1. 将 ui-generation.js 和 ui-generation.css 复制到项目中（例如 src/lib/ 或 public/vendor/）。这两个文件均独立完整，不依赖其他内容。
2. 全局导入一次 CSS（使用 <link>，或在应用入口处使用 import "./ui-generation.css"）。
3. 在元素所在的位置导入 generate（使用属性 API 时还需导入 auto）。

请勿重写运行时代码或其计时设置。它们经过协同调优：绘制阶段、点间距、流动速度和显示曲线。

接入

在元素完成渲染并具有最终尺寸后，且字体已加载时，调用 generate。它会在显示动画结束前隐藏元素本身，然后恢复其内联 opacity、clip-path 和 filter。

原生 JavaScript

import { generate } from "./ui-generation.js";
await document.fonts.ready;
const run = generate(document.querySelector("#result"), { mode: "skeleton" });
await run.finished; // the real UI is fully in

属性 API（元素滚动到视口中时播放一次）

<section data-t-generate="skeleton-texts" data-t-generate-delay="200">…</section>
<script type="module">
  import { auto } from "./ui-generation.js";
  auto();
</script>

React / Next.js（客户端组件）

"use client";
import { useLayoutEffect, useRef } from "react";
import { generate } from "@/lib/ui-generation.js";

export function GeneratedCard({ data }) {
  const ref = useRef(null);
  useLayoutEffect(() => {
    if (!ref.current) return;
    const run = generate(ref.current, { mode: "skeleton" });
    return () => run.cancel();
  }, [data]); // replays when new data arrives
  return <div ref={ref} className="card">{/* … */}</div>;
}

Vue

import { onMounted, onBeforeUnmount, ref } from "vue";
import { generate } from "@/lib/ui-generation.js";
const el = ref(null); let run;
onMounted(() => { run = generate(el.value, { mode: "skeleton" }); });
onBeforeUnmount(() => run && run.cancel());

Svelte（action）

import { generate } from "$lib/ui-generation.js";
export function generating(node, mode = "skeleton") { const run = generate(node, { mode }); return { destroy: () => run.cancel() }; }
// <div use:generating={"skeleton-texts"}>…</div>

API

generate(element, options) 返回 { finished, cancel, element }。当真实 UI 完全显示时，finished 会完成。cancel() 会立即停止，并按当前状态显示元素。再次对同一元素调用 generate 会取消上一次运行。

选项	默认值	说明
mode	"skeleton"	"skeleton" 或 "skeleton-texts"。
duration	2400	绘制时长，单位为 ms。整个运行时长约为 duration × 1.09。请保持在 1600 到 3600 之间。
delay	0	开始前的等待时间，单位为 ms（可用于错开多个元素的动画）。
steps	["Planning layout", "Drawing structure", "Writing styles", "Adding motion"]	步骤行（skeleton-texts）。
done	"Ready"	最后一个步骤，在 UI 显示时出现。可使用组件名称，例如 "Invite modal ready"。
code	自动生成	动态 CSS 面板中的代码行。默认使用元素自身的圆角、字体和颜色，以及 transitions.dev 动效令牌。
title	自动生成	动态 CSS 标题栏中的名称（否则使用 aria-label 或第一个标题）。
maxParts	60	最多追踪的部件数；优先保留较大的部件。
keys	5	获得辅助线、控制柄和尺寸标签的关键元素数。
onDone	null	运行结束时调用，并传入该元素。

将任意子元素标记为 data-t-generate-skip，即可在绘制中跳过该元素。

可调变量

变量定义在 ui-generation.css 中。此处显示浅色模式的值；深色模式下会根据 prefers-color-scheme 或 [data-theme="dark"] 切换。

变量	默认值	说明
--gen-line	#9a9a9a	点状线条：轮廓、部件和辅助线。
--gen-strong	#6c6c6c	移动的点状端点、控制柄、瞄准标记、亮点和标签。
--gen-ink	rgba(13, 13, 13, 0.32)	静止的点阵。
--gen-surface	#ffffff	角部控制柄的填充色（与页面背景匹配）。
--gen-text / --gen-muted	#0d0d0d / #8b8b8b	面板标题和文本（skeleton-texts）。
--gen-dot	2.1px	追踪线上的点大小。
--gen-font	Roboto Mono, monospace	标签和面板的字体。

绘制效果应保持单色。灰色圆点呈现出“Agent 工作层”的效果；真实 UI 出现时再带来色彩。

无障碍

• prefers-reduced-motion: reduce 会完全跳过绘制：元素会在 200ms 内淡入，finished 也会照常解析。切勿移除这一行为。
• 覆盖层带有 aria-hidden，且不会接收指针输入。元素始终保留在无障碍树中。
• 不要以此为条件限制交互：finished 解析后（约 2.6s）即可使用元素。对于用户会反复等待的内容，请改用骨架屏加载器。

应避免的常见错误

• 布局稳定前就运行。 在字体或图片加载完成前测量，会导致文本行和方框绘制位置错误。请先等待 document.fonts.ready（如果图片尺寸会影响布局，也请等待图片加载）。
• 在 display: none 时运行。 隐藏的元素没有尺寸；请先显示它。在标签页和折叠面板中，请等面板展开后再生成。
• 同时自行给元素添加动画。 不要为元素添加自己的入场过渡；运行期间，运行时会控制其 opacity、clip-path 和 filter。
• 运行期间，父元素设置了 overflow: hidden 且内容正在滚动。 覆盖层位于页面上，而非滚动容器内；如果元素在这 2.6s 内滚动，绘制效果就会偏移。请等元素进入视口后再播放（属性 API 会处理这一点）。
• 将其用作加载状态。 它只会播放一次，覆盖在真实 UI 之上。数据仍在加载时，请显示骨架屏；数据到达后再播放生成效果。
• 将文本强行塞进紧凑布局。 skeleton-texts 只会在页面空白处绘制其面板。在密集网格中，它会退回到阶梯线效果，或不绘制任何内容。这是预期行为；此类场景请使用 skeleton。
• 在服务端导入。 它需要 window 和 DOM。在 Next.js 或 Nuxt 中，请在客户端组件或 effect 内导入。

参考文件

• 01-skeleton.md：分阶段介绍骨架模式。
• 02-skeleton-texts.md：生成文本及其显示位置。
• ui-generation.js：运行时（ES 模块；也可通过 window.UIGeneration 使用）。
• ui-generation.css：覆盖层样式和变量。
• demo.html：在三个 Community 组件上演示两种模式。