stageshow 是做什么的？
微缩产品UI：一个可信的界面，在其空间中框定，作为一张静态图或一个只有一件事发生的短视频动画。观众能识别出这个屏幕，并看到发生的事件。
核心理念
它看起来像一个真实的产品，简化到观众需要的内容，有意图地框定，并且每个动作都有其原因。
五种失败的情况：
- 信息过载。 每一行都有真实文本，到处是数字，内容塞得满满当当。细节越多，看起来就越像生成出来的。
- 线框图。 两个灰色区块加一个按钮。构建得太小，或者去掉了让它可识别的特征。
- 盒子化。 整个窗口被缩小并居中放入一个卡片中，四周留白均匀：看起来像是粘贴的截图，而不是产品展示图。
- 扁平。 所有对象在同一个带边框的卡片中具有相同的视觉权重。眼睛没有落点。
- 平淡。 一个灰色窗口加一个光标，无论需求是什么都这样。需求中的外观和活力（如蓝图、色彩上的玻璃质感、灵动岛、吉祥物）才是关键；接受需求并按规则构建，就像
examples/hero-demo那样，它有一个打字弹窗和一个终端卫星（卫星是指较小的第二个对象，如收据、手机或详情卡片，跨越主视觉的边缘）。
解决方案：一个完整、结构清晰的屏幕，使用安静的灰色，只在故事所涉及的内容上使用真实文字，其余部分用占位行，留出呼吸空间，通过裁剪将视线引导至故事所在处。简化文字，而不是简化上下文。一个空旷的角落，列表下方的空白，撑满面板的行，漂浮在底板（其背后的背景或半透明场）上的窗口：显得未完成，但并非平静。
这些是精心编排的插画，不是浏览器自动化：a.click() 绘制光标按下的动作，a.set() 改变场景。
标准有多高
按照产品设计师构建一个将受人评判的发布页面那样去构建。examples/ 中的黄金示例是标准，而非参考：如果你的作品与最接近的黄金示例相比显得更空、更平或更小，那这就是首先要修复的问题。然后，像你所认识的最苛刻的设计师那样审视画面，那个设计师会截取一个错误点并回复“这是什么？”：一个偏离头像的点、一个单独成行的单位、灵动岛下出现抓取器、文字接触到卡片边缘。如果你能想象出那张截图，你就找到了下一个需要修复的问题。
工作流程
大部分质量在编写任何代码之前就已决定。首先编写计划：它位于何处，焦点对象是什么，动作是什么，成果是什么，哪些内容可以省略。
- 介质与位置。 静态或动画（循环、进入视野时播放一次、或悬停时触发）。页面、其背景、其宽度。按最终被观看的大小进行设计，对于旁有正文的主视觉（
hero-demo）约为 720 × 340，对于全宽主视觉（linear）为 900 到 1100 宽，对于卡片为 400 × 300，以 1:1 显示；对于演示来说，宽度绝不能低于约 320，尽管bento磁贴或卫星卡片可能更小。每一个可以放在手机列中的演示都需要提供一个适配该列宽度的compact设计（358像素），这是一个重新设计而非单纯挤压（参见references/framing.md，小型格式与页面）。磁贴网格是一个整体：使用references/bento.md进行规划。 - 外观。 手头有产品的代码或网站时，将其设计令牌映射到工具包的令牌（参见
references/looks.md）；如果开发者要求使用他们自己的组件，则在舞台内使用它们，而不是工具包的小部件。否则，选择一个主题（浅色、深色、蓝图、玻璃）、一个调色板（强调色、单色）和一种精细度：minimal全是条状，standard在承载含义的地方使用文字而其他地方使用条状，realistic则所有地方都是真实内容。默认为浅色、强调色、标准精细度；在主视觉规模、针对指定真实产品，或主题为列表或页面的静态图时，使用真实精细度。使用Text filler编写一次占位文字，精细度决定其显示。产品自有的图标、真实的界面装饰、使其可识别的内容。带有风格（如可爱、纸张、海报色彩）的需求则完全按照该风格实现，但仍遵循这些规则。 - 故事。 其形态（参见
references/motion.md，故事部分）：使用感受、操作流程，或系统正在做什么。三到五个节拍和一个成果，持续 10 到 16 秒。没有无法解释的光标移动。没有无缘无故的、在视野中回退的数据。在更丰富的故事和更平静的画面之间，选择画面。 - 从示例开始。 找到最接近的黄金示例（下方的黄金示例表）并拍摄它（
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；没有死角落。在与黄金示例相同的宽度下拍摄一张静态图；如果你的作品显得更空、更平或更像盒子，先修复构图，再进行动画制作。 - 屏幕。 统计真正的字符串数量，通常在 3 到 7 个之间（参见
references/craft.md，克制部分）：这是文字预算，不是元素预算。使用工具包的令牌构建，如Bar、Text和Row。在光标移动之前，确保每个控件内的文本都适应。用data-target和data-cursor标记光标触摸的内容；使用rect()进行测量，切勿硬编码。 - 编排。 使用
ActAPI。保持已挂载的内容可见，并通过切换其状态来使退出动画生效（Bubble和Fly明确交接）。动画化的是关系，而不仅仅是对象：一个新行会携带其下方的行一起移动，一个调整大小的表面绝不应该拉伸其文本。节拍重叠，组交错，成果定格，循环结束时回到起点，或通过一个可见的原因重置。 - 排练。 首先设置
poster：大多数人只看到那个帧（缩略图、减少动画、截图），所以它应该是能独立讲述故事的节拍，绝不能是变化中途的帧，并且结果应留在屏幕上而非被清除（参见references/motion.md，故事部分）。然后拍摄整个循环，而不仅仅是静态图：在显示宽度和 390 宽度下生成接触表，并逐步检查每一次按键、菜单、变形和循环接缝（参见references/rehearse.md）。一张静态图无法展示弹出效果。阅读每一帧，首先修复最大的可见缺陷（构图、然后是层次结构、然后是运动、然后是打磨），重新拍摄。然后将其与最接近的黄金示例并列，并将references/teaching.md中的整体构图和风格对作为关于你静态图的问题来回答（眼睛首先落到哪里，是不是结果？一个窗口、磁贴或设备是否明确领先？）；任何“否”都是最大的缺陷。film.mjs --gate以rehearsal passed结束是必要的，但不是充分的。然后执行references/rehearse.md中的最后一步：新人审查（references/review.md）和组件旁边的REHEARSAL.md（模板见references/verify.md，交接部分）：你复制的黄金示例，你更改的内容，你没有检查的内容。
每轮都会出现的常见缺陷及其修复规则；在交接前检查它们：
- 内容切换 而非移动（参见
references/motion.md，文本和数值的变化部分）。 - 灰色条出现在视线落点处； 填充内容应位于边缘（参见
references/craft.md，克制部分）。 - 窗口背后有底板，或窗口四面留空； 窗口或手机应至少占据舞台三分之二，并在某个边缘处超出画面（参见
references/framing.md，规则 5 和小型格式与页面部分）。 - 空白条带、被截断的控件和阴影（参见
references/craft.md，克制部分；references/framing.md，规则 4）。 - 通用的AI风格和虚构标志： 闪光、紫色、彩色方块中的字母（参见
references/craft.md，图标和标志部分）。 - 拥挤的行和不均匀的缩进（参见
references/craft.md，克制以及间距与对齐部分）。 - 长时间的停顿和无缘无故的重置（参见
references/motion.md，循环部分）。 - 选区不在 I 型光标下方（参见
references/motion.md，拖拽与选区部分）。 - 手绘的状态栏或Home指示器；
Phone组件会绘制这两者（参见references/craft.md，界面装饰和设备部分）。 - 居中金额与货币符号一起居中（参见
references/craft.md，间距与对齐部分）。
示例
在开始前拍摄最接近的示例（步骤 4）。黄金示例是质量标准；产品研究用于借用交互方式，而非借用其他产品的身份；样板表是目录，而非构图。所有示例都通过 npm install 和 npm run dev 运行。teaching/ 目录包含错误/正确配对（references/teaching.md），用于诊断问题；错误的半部分绝不能作为起点。
黄金示例
| 需求 | 示例 | 学习要点 |
|---|---|---|
| 静态图或功能卡片 | static-card | 安静的层次结构，硬裁剪，一个卫星，只有所选客户、其邻居和总数使用真实文字 |
| 深色静态图 | dark-bento | 一个信号只传达一次；专辑封面确保它看起来是音乐应用 |
| 动画主视觉，一个手势 | hero-demo | 五个节拍，命名目标，一个注释，一个向前运动的终端 |
| 编排，无光标 | payout-flow | 缓慢的重叠到达，阅读时间，一个保持状态的成果 |
| 内容原地变化 | choreography | 保留的轨道，软遮罩，依赖时间 |
| AI回答 | ai-chat | 发送的问题，思考中，答案以滚动高度流式输出，来源最后出现；没有闪光，没有紫色 |
| 带卡片的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 | 不同的背景 |
…
[为翻译截断]