stageshow

Stageshow

微型产品 UI：一款可信的界面，置于合适的空间中，以静帧或短动画呈现一个动作。观众能认出屏幕，并看到动作发生。

核心理念

它看起来像真实产品，简化到足以满足观众所需，取景有意图，每个动作都有缘由。

五种常见失败：

• 太多。 每一行都是真实文本，到处都是数字，所有内容挤在一起。细节越多，看起来就越像生成的。
• 线框图。 两个灰色块和一个按钮。做得太小，或删掉了让它易于辨认的内容。
• 装进框里。 整个窗口缩成一张卡片，四周留着均匀的边距：这不是产品展示图，而是把截图贴了进去。
• 扁平。 所有对象的分量都一样，还放在同一张带边框的卡片里。视线无处落脚。
• 平淡。 一个灰色窗口配个光标，完全不管简报写了什么。简报要求的外观和能量（蓝图、覆盖在色彩上的玻璃、Dynamic Island、吉祥物）才是重点；按要求取材，并依照规则构建，就像 examples/hero-demo 用带文字的弹窗和终端卫星对象所做的那样（卫星对象是较小的第二对象，可以是收据、手机或详情卡，跨在主视觉边缘上）。

解决方法：构建完整、有结构的屏幕，以安静的灰色为主；只有与故事相关的内容使用真实文字，其余用占位线；留出呼吸空间，并通过裁切将视线引向故事所在之处。简化文字，而不是上下文。空荡的角落、列表下方的空白、为填满窗格而铺开的行、漂浮在底板上的窗口（底板可以是背景或有色区域），这些都显得未完成，而非沉静。

这些是精心制作的插画，不是浏览器自动化：a.click() 绘制光标按下的动作，a.set() 改变场景。

把握尺度

按照产品设计师打造发布页的方式来做，并假设它会受到评判。examples/ 中的优秀范例是衡量标准，不是参考示例：如果和最接近的优秀范例相比，你的作品更空、更扁平或更小，那就是首先要改的地方。然后，用你认识的最严苛的设计师的眼光审视画面——那种会截出一个错误之处并退回来，附上一句“这是什么？”的人：头像上的点偏了一点、单位单独占了一行、岛状组件下方有拖动条、文案贴着卡片。如果你能想象出那张截图，就找到了下一处要改的地方。

工作流

大部分质量在写代码之前就已决定。先写计划：它放在哪里、焦点对象是什么、动作是什么、结果是什么、哪些内容可以省略。

1. 媒介与展示位置。 静态画面或动画（循环播放、进入视野时播放一次，或悬停时播放）。页面、页面底色及宽度。按最终展示尺寸设计：与文案并排的主视觉约为 720 × 340（hero-demo），全宽主视觉宽 900 至 1100，卡片为 400 × 300，按 1:1 展示；演示宽度通常不得小于约 320，但 Bento 网格单元或卫星卡片可以更小。每个可放入手机列的演示都要提供适配该列宽度（358）的 compact 设计，这是重新设计，不是挤压布局（references/framing.md，Small formats and the page）。网格中的多个单元是一组：用 references/bento.md 规划。
2. 外观。 如果能看到产品的代码或网站，就将其设计令牌映射到工具包的令牌（references/looks.md）；如果开发者要求使用自己的组件，就在舞台中使用这些组件，替代工具包的小部件。否则，选择主题（浅色、深色、蓝图、玻璃）、调色板（强调色、单色）和保真度：minimal 全部使用色条，standard 在文字能传达含义时用文字，其余用色条，realistic 则全程使用真实内容。默认采用浅色、强调色、standard；主视觉尺寸、指定的真实产品，或主体是列表或页面的静态画面，采用 realistic。用 Text filler 一次性填写占位内容，由保真度决定其呈现方式。使用产品自己的图标、真实界面框架，以及能让产品易于辨认的内容。简报若指定了风格（可爱风、纸张风、海报色），就完整采用该风格，同时遵守这些规则。
3. 故事。 选择故事形式（references/motion.md，Story）：呈现使用感受、一个流程，或系统的工作方式。用 3 到 5 个节拍讲述，并以结果收尾，时长 10 至 16 秒。不要加入无法解释的光标移动。画面中数据的变化必须有因由，不得无故倒退。丰富的故事和沉静的画面二选一时，选沉静的画面。
4. 从示例开始。 找到最接近的黄金示例（见下方的 Gold 表），并将其录制下来（node scripts/film.mjs "<preview>/?capture=<gold>" --select '#example' --still --out gold.png；npm run dev 会提供预览）。将其文件夹复制到你的项目中作为起点；不要只看一眼就重写。最快的迭代方式：先复制到这里的 examples/<yours>/，预览会自动载入，使用 ?capture=<yours> 即可录制；通过检查后，再移入宿主项目并修正其工具包导入路径。保留其结构：舞台尺寸、裁切与出血、行和字体大小、间距、脚本节拍及工具包部件。现在完整阅读 references/craft.md：内容很短，其中包含黄金示例无法呈现的静态画面规则，以及你的黄金示例恰好不包含的情况。然后用简报中的产品外观和内容替换原有内容：第 2 步中的设计令牌、产品自己的图标、界面框架和文案。仅修改名称不算完成：最终效果应当让人一眼认出是简报中的产品，而不是黄金示例。如果没有黄金示例符合你的故事，分两步选择：先确定布局（从 references/framing.md 中选择；每种布局都列出了对应示例），复制该示例，即使它的故事不同；然后从故事最接近的示例中借鉴动画来呈现你的节拍，并以相同风格自行构建两者都没有的部分。接着调整取景：裁切到故事发生的面板，并以最终可见的裁切效果为准（references/framing.md 中有规则和布局表）。简而言之：只留一道边距，要么完整保留，要么大幅超出；只有占位内容可以出血；已展开的内容要保持展开；窗口保持原有形状；页面就是底色，因此白色或深色页面上的主视觉下方不得加底板，也不要让整个窗口四周都留出空白；只有开发者要求时才使用 unframed；不要留下空角。将你的静态画面与黄金示例并排，以两种宽度各录制一张；如果你的画面更空、更平或框架感更重，就先修正取景，再制作动画。
5. 屏幕内容。 统计真实字符串，通常为 3 到 7 个（references/craft.md，Restraint）：这是文字预算，不是元素数量。使用工具包的令牌、Bar、Text 和 Row 构建界面。让每个控件的文字都能完整显示，再开始移动。用 data-target 和 data-cursor 标记光标会触及的内容；用 rect() 测量，绝不硬编码。
6. 编排动画。 使用 Act API。让需要显示的内容保持挂载，通过切换来触发退出动画（Bubble 和 Fly 要显式交接）。动画要表现元素之间的关系，而不只是元素本身：新增行时，其下方的行也要随之移动；调整大小的界面不能拉伸其中的文字。各个节拍要相互衔接，组内动画依次错开，结果要停留足够长时间；循环结束时要回到起点，或在重置时呈现明确的触发原因。
7. 反复演练。 先设置 poster：大多数人只会看到这一帧（缩略图、减少动态效果时或截图），因此它本身就要讲清楚故事；不能是变化过程中的中间画面，结果应留在屏幕上，而不是被整理掉（references/motion.md，Story）。然后录制完整循环，而不只是静态画面：检查展示宽度和 390 宽度下的联系表，并逐一检查每次按下、菜单、变形及循环衔接处（references/rehearse.md）。静态画面无法呈现弹出效果。逐帧检查，先修复最明显的问题（取景、层级、动画、润色），然后重新录制。接着将其与最接近的黄金示例并排，依据 references/teaching.md 中关于整体构图和风格的问题审视你的静态画面（视觉焦点首先落在哪里？那里呈现的是结果吗？是否有一个窗口、单元或设备明显占主导地位？）；任何一个问题的答案为“否”，都是最明显的问题。film.mjs --gate 显示 rehearsal passed 是必要条件，但并不足够。最后，按 references/rehearse.md 完成最后一轮检查：由未参与制作的人复核（references/review.md），并在组件旁放置 REHEARSAL.md（模板见 references/verify.md，Hand over）：记录你复制的黄金示例、做出的修改，以及未检查的事项。 每轮都会反复出现的故障，各自都有对应规则；交付前先检查：

• 内容在切换，而不是移动（references/motion.md，Changing text and values）。
• 视线落点出现灰色条带； 填充内容应放在边缘（references/craft.md，Restraint）。
• 窗口后面有底板，或窗口漂浮，四周留白；窗口或手机至少占据舞台的三分之二，并延伸到舞台边缘（references/framing.md，rule 5 and Small formats and the page）。
• 空白色带、被裁切的控件和阴影（references/craft.md，Restraint；references/framing.md，rule 4）。
• 千篇一律的 AI 风格和虚构的徽标： 闪光、紫色、彩色方块里的字母（references/craft.md，Icons and logos）。
• 拥挤的行和不一致的内边距（references/craft.md，Restraint and Spacing and alignment）。
• 停留过久，以及没有缘由的重置（references/motion.md，Loops）。
• 选区不在 I 形光标下方（references/motion.md，Drags and selection）。
• 手绘的状态栏或主屏幕指示条； Phone 会绘制这两者（references/craft.md，Chrome and devices）。
• 居中金额的同时也将货币符号居中（references/craft.md，Spacing and alignment）。

示例

开始前先拍摄最接近的示例（第 4 步）。金色示例是质量标杆；产品研究用于借鉴交互，绝不能借用其他产品的身份标识；样张表是目录，不是构图。用 npm install 和 npm run dev 运行所有内容。teaching/ 中有用于诊断问题的坏/好示例对（references/teaching.md）；坏示例绝不能作为起点。

金标示例

需求	示例	学习要点
静态画面或功能卡片	static-card	安静的层级、硬裁切、一个卫星元素；只有选中的客户、其相邻客户和总数使用真实文字
深色静态画面	dark-bento	一个信号只表达一次；专辑封面让它看起来像音乐应用
动画主视觉，一个手势	hero-demo	五个节拍、明确命名的目标、一条注释、向前移动的终端
编排，无光标	payout-flow	缓慢重叠地出现、留出阅读时间、让结果停留片刻
内容原地变化	choreography	保留轨迹、柔和遮罩、依赖式计时
AI 回答	ai-chat	发送问题、显示 Thinking、答案连同其高度一同逐步显现，最后显示来源；不要闪光效果，也不要紫色
带卡片的 AI	ai-cards	回答并保留一张多选卡片作为记录，在对话中展开选项卡片，并通过卡片自身的按钮完成预约
表单验证	form-error	在导致错误的字段上显示错误，修正后清除，然后由按钮自身确认
拖动排序	reorder	通过拖拽把手提起一行，其他行让出空间，再将其放到位
图表拖动查看	chart-scrub	跟随指针的细线和圆点，标题数值滚动到对应日期
在表格中编辑	table-edit	原地编辑单元格，然后其影响的总数稍后滚动更新
从加载到内容	loading	骨架屏与内容自身的几何结构一致，行从上到下逐步显现，始终显示真实界面
深色主视觉	dark-hero	通过黑色背景上的表面层次营造深度，使用一种亮色，状态在自身的胶囊标签上变化
实时协作者	presence	每个人在所有位置都使用同一种颜色，姓名随光标移动，并通过文档自身的标记展示工作内容
系统故事	subscriptions	一个标签飞入一行，MRR 滚动更新，第二幕负责重置
特写	close-up	将一个控件放大到 1.4 倍并保留所在窗口的界面元素，行保持完整，配上相称的大光标
众多同类元素	many-of-one	网格铺满同一种元素并延伸到画面边缘，一个图块通过深度获得焦点，且只有它带有文字
渐隐裁切	fade-crop	窗口底部逐渐淡出，叠在填充内容上，而不是从边缘伸出去
产品上的面板	panel-annotation	设置面板覆盖在产品边缘的留白上，用一条引线从设置指向其改变的内容
重叠窗口	overlap	窗口前方放一张卡片，其边缘与窗口的侧边栏线对齐
堆叠卡片	stacked-cards	两个同宽组件，留出小间距，下方组件从底部露出一部分
对角布局	opposite-corners	Bento 图块：文案位于左下角，产品固定在右上角
倾斜堆叠	tilted-stack	一叠随意摆放的纸张，以小角度交替倾斜，只有顶层卡片带有文字
角落标签	corner-chip	小标签居中放在窗口角上，一半露在外面
单色	monochrome	将其他公司的产品排成一行，转为灰度，并在底部淡出
窗口横排	window-row	并排展示等高会话：通过深度突出焦点，舞台裁切相邻窗口，只裁切填充内容
窗口与手机	device-pair	仪表板和锁屏共同讲述一个事件；手机跨在留白上方，绝不遮住主体
相关对象	story	发票、套餐、连接器和滚动更新的总数
拖动日历事件	calendar	内容充实的一周、一个焦点事件、幅度克制的拾取动作
自由拖动	freeform-drag	抓取偏移、适度的网格、可吸附的放置槽
手机应用	phone-touch	卡片作为一个整体展开为其屏幕，循环再折回
灵动岛	dynamic-island	一个黑色形状，其内容为独立图层
消息	messages	输入框、正在输入状态、送达回执、气泡的生命周期
光标	cursors、cursor-morph、cursor-resize	五种样式、由元素驱动的类型、调整大小的边和角，以及完全不显示光标
注释	annotations	引线、尺寸、流程和移动目标；references/annotations.md
功能网格	bento	一个主视觉、一个窗口、一个统计数据、一个对象、一张示意图
深色网格线网格	ruled-bento	共用网格线和技术风格图像
消费级网格	staggered-bento	错位图块、图形艺术、实体物件
图片主导的主视觉网格	hero-grid	用不同背景和材质构成一幅整体画面
上传	upload	从桌面拖入文件，显示带进度的上传行，并在完成后转为文件行
分享	share	在文档上方显示分享弹出框：将电子邮件转换为标签，显示角色菜单，并将人员添加到列表
滑动	swipe	在手机上滑动归档：按下、滑动、以手指的速度甩出、间隙闭合

产品研究

知名产品（Figma、Linear、Slack、Raycast、Finder、Spotify、Notion、Gmail、Google 的应用、Office、Wikipedia、Telegram、iMessage）：先阅读 references/products.md。借鉴交互方式，而不是照搬其他产品的身份标识。

需求	示例	学习内容
设计工具	figma	画布选择、颜色选择器、第二个光标
问题跟踪器	linear	命令菜单和任务分配
聊天	slack	消息、表情回应、线程回复
启动器	raycast	模糊桌面上的搜索和剪贴板历史
文件	finder、finder-glass	文件列表上的快速查看；将文件移入文件夹；同一窗口的磨砂玻璃效果
音乐，深色	spotify	带专辑封面的深色桌面应用
文档和编辑器	notion、google-docs	斜杠命令；评论及其回复
电子邮件	gmail	悬停操作、归档、撤销提示
日历，真实应用	google-calendar	拖动以创建活动、快速创建弹窗
Office	powerpoint、excel	幻灯片编辑；自动求和和图表
浏览器页面	wikipedia	浏览器中的搜索建议
手机对话	telegram、imessage	iPhone 上的原生聊天应用

样件与参考图

组件和背景目录详见 references/kit.md（样件图）。在此查找组件；根据优秀示例进行组合。

需求	示例	学习内容
工具包样件	chrome、phones、controls、parts、kit-extras	每个画框和组件
玻璃效果	glass	彩色背景上的磨砂表面
背景	backgrounds	一个界面搭配二十种背景；references/backgrounds.md
标志	brand-marks	真实标志，按视觉效果调整尺寸，适用于浅色和深色背景；references/brands.md
产品外观	looks	字体、形状和色彩的搭配

工具包

将 kit/ 复制到项目中，并从 kit/index.ts 导入。依赖 React、react-dom 和 lucide-react（用于 Icon，Field 和 Chip 会用到）；每个组件都自带 CSS。它能处理那些手工难以做好的部分，并将产品外观留给你。references/kit.md 列出了每个组件的属性和规则；请阅读你要使用的组件对应条目。

• 舞台。 Stage：设计尺寸和适配缩放、compact、场景状态、播放、外观、光标。脚本会接收一个 Act（set、wait、move、click、type 等：references/kit.md，Act）。
• 画框。 Window、带有 LockScreen 和 Notification 的 Phone、Keyboard、带有 Bubble 的 Thread、Stamp、Receipt。几何尺寸真实；绝不要手工绘制窗口、设备或气泡。
• 动效。 Collapse、Roll、Swap、Count、Connector、Fly、Follow、States、Stream、Popover、Scroll、Camera、Expand。它们能处理生手容易做错的画面。
• 小组件。 Bar、Text、Row（所有列表都由它构成）、Avatar、Pin、Icon、Menu、Field、Segmented、Toggle、Tabs、Badge、Chip、BrandMark、Code、Chart。它们是克制的起点；请根据产品风格调整样式，不要从外部改变工具包组件的几何形状。
• stageshow.css：设计令牌、外观、边缘渐隐、浏览器框架、手机、键帽。

参考资料

references/framing.md：取景规则和布局表。references/craft.md：静态画面（克制、字体、间距、图标、色彩、浏览器框架）。references/motion.md：故事、循环、节奏、光标和拖动。references/verify.md：包含「你看到／你操作」表格的检查清单。references/rehearse.md：拍摄方法，以及那些绝非有意为之的影片线条。