Back to Details

component-canvas

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Component canvas

组件画布

Build a canvas that shows the project's existing components as they really behave. The canvas wraps components. It never changes them.
构建一个画布，按实际行为展示项目中现有的组件。画布只负责封装组件，绝不修改组件。

Ground rules

基本规则

  • Do not modify component source, exports, styles, hooks, or behavior to make the canvas work. Components must not import or depend on canvas code.
  • Do not patch libraries, browser APIs, rendered component DOM, or portal roots.
  • Show only the components the user asked for. Adding components, installing dependencies, changing a component's design, or making the canvas public requires permission first.
  • Keep existing access controls.
  • Leave unrelated work alone. If removing an earlier canvas integration, undo only its changes to components.
  • Follow any restrictions on commands, browser access, dependencies, and edits.
  • 不得为了让画布正常工作而修改组件源码、导出、样式、hooks 或行为。组件不得 import 或依赖画布代码。
  • 不得 patch 库、browser APIs、已渲染的组件 DOM 或 portal roots。
  • 只展示用户要求的组件。添加组件、安装依赖、更改组件设计或将画布公开，都必须事先获得许可。
  • 保留现有访问控制。
  • 不要改动无关工作。如需移除之前的画布集成，只撤销它对组件所做的更改。
  • 遵守针对命令、浏览器访问、依赖项和编辑操作的所有限制。

Before building

构建前

Read the repository conventions, routes, component public APIs, design tokens, and test setup. Use the existing framework and libraries.
Ask the user only when the answer changes what gets built or touches shared code: which components are in scope, whether a new dependency is acceptable, or whether a live service may be previewed. For everything else, choose a sensible default, state it in the report, and proceed.
阅读仓库约定、路由、组件 public APIs、design tokens 和测试设置。使用现有框架和库。
仅当答案会改变构建内容或涉及共享代码时，才询问用户：哪些组件在范围内、是否接受新增依赖，或是否允许预览实时服务。其他事项均采用合理默认值，在报告中说明并继续执行。

Build order

构建顺序

  1. Add a minimal canvas route or entry point with one group and one component. Confirm it works.
  2. Add the remaining groups with sample data.
  3. Add variant comparisons, then advanced gestures and persistence, one feature at a time.
Keep canvas code in one place. Check imports and package exports when moving files. Follow the project's language, validation, and test conventions. Do not add architectural layers or directory names the project does not already use.
Keep layout and camera logic separate from sample data and component source.
  1. 添加一个仅包含一个分组和一个组件的最小画布 route 或 entry point，并确认其正常工作。
  2. 添加其余分组和示例数据。
  3. 添加变体对比，然后逐项添加高级手势和持久化功能。
将画布代码集中放在一个位置。移动文件时，检查 imports 和 package exports。遵循项目的语言、校验和测试约定。不要添加项目尚未使用的架构层或目录名称。
将布局和视角控制逻辑与示例数据及组件源码分离。

Layout

布局

  • Fill the viewport with a plain background.
  • If the project already supports light and dark themes, add an accessible toggle using its existing theme API. Apply the selected theme to the canvas and native portals. If theme support is absent, omit the toggle. Do not invent themes or change component styles.
  • Give every group the same padding, radius, and thin dashed border, subtle but visible in both themes. Use an existing muted color at roughly 25% opacity for borders. Place its plain title 8px above the border, using the muted text color without opacity.
  • Use wide groups with equal-width example slots filling each row. Wrap when needed and keep generous horizontal and vertical gaps within and between groups. Spread the layout without enlarging components.
  • Groups cannot be dragged. Their positions need not be hard-coded. Measure their actual bounds, including title, border, and padding. Ignore rendering-containment placeholders (empty boxes that reserve space before content renders), since they do not reflect real content size.
  • Omit background dots, decorative cards, page menus, instruction banners, selection tools, and block editing. Component cards and menus may appear as examples.
  • 使用纯色背景填满视口。
  • 如果项目已支持浅色和深色主题，请使用其现有 theme API 添加具备无障碍支持的主题切换按钮。将选定主题应用到画布和原生 portals。若项目不支持主题，则省略切换按钮。不要自创主题或更改组件样式。
  • 为每个分组设置相同的 padding、radius 和细虚线边框，使其在两种主题下都低调但清晰可见。边框使用现有 muted color，透明度约为 25%。
  • 将朴素标题放在边框上方 8px 处，使用 muted text color，且不设置透明度。
  • 让各分组横向展开，每行使用等宽示例槽位并铺满整行。必要时换行，并在分组内部和分组之间保留充足的水平与垂直间距。均匀分布布局，但不要放大组件。
  • 分组不可拖动。其位置无需硬编码。
  • 测量分组的实际边界，包括标题、边框和 padding。忽略渲染占位符（即在内容渲染前预留空间的空盒子），因为它们并不反映真实内容尺寸。
  • 省略背景圆点、装饰性卡片、页面菜单、说明横幅、选择工具和区块编辑。组件卡片和菜单可以作为示例出现。

Variants

变体

  • Show every supported named variant and useful state within the requested scope. Read the public APIs for styles, text and icon sizes, orientation, placement, alignment, modality, and collapse modes.
  • Include useful content and composition examples.
  • Do not invent variants or generate every prop combination. List what was omitted and why.
  • Compare one prop or feature at a time. Hold everything else constant: same wrapper, same sample data, same text, icons, theme, and spacing.
  • Change the style variant only in style comparisons. Size, state, placement, and other comparisons use a single style, usually the default.
Example: in a size comparison, every button reads "Continue" and uses 
variant="default"
. Only 
size
changes. The style comparison changes 
variant
and keeps size and text the same.
  • Keep the component's own state styling (disabled opacity, checked color). Examples respond to input unless they show a disabled or read-only state.
  • Test hover, focus, and pressed states through real pointer and keyboard input, not added classes.
  • For portal examples, use the same trigger each time. Do not force several modals open at once.
  • Keep a variant list and coverage tests. Use types if the project supports them.
  • If a component cannot show a responsive or visual case, explain the limit. Do not change the component to fake it.
  • 在请求范围内展示每个受支持的命名变体和实用状态。读取 public APIs，了解样式、文字和图标尺寸、方向、放置方式、对齐方式、模态类型和折叠模式。
  • 包含实用的内容和组合示例。
  • 不要虚构变体，也不要生成每一种 prop 组合。列出省略的内容及其原因。
  • 每次只对比一个 prop 或功能。其余条件保持不变：使用相同的 wrapper、示例数据、文字、图标、主题和间距。
  • 仅在样式对比中更改 style 变体。尺寸、状态、放置方式及其他对比均使用单一 style，通常为默认值。
示例：在尺寸对比中，每个按钮都显示“Continue”，并使用 
variant="default"
。只有 
size
发生变化。样式对比则更改 
variant
，并保持 size 和 text 不变。
  • 保留组件自身的状态样式，例如 disabled opacity 和 checked color。示例应响应输入，除非其目的是展示 disabled 或 read-only 状态。
  • 通过真实指针和键盘输入测试 hover、focus 和 pressed 状态，而不是添加 class。
  • 对于 portal 示例，每次使用相同的 trigger。不要同时强制打开多个 modals。
  • 维护变体清单和覆盖率测试。如果项目支持类型，则使用类型。
  • 如果组件无法展示响应式或视觉场景，请说明限制。不要修改组件来伪造效果。

Interactions

交互

  • Clicks, text selection, typing, button and switch activation, focus, and nested scrolling must keep working.
  • Canvas shortcuts (Space, arrows, Escape, native undo) apply to the canvas shell only. They must not take those keys away from preview controls.
  • Handle preview navigation in the canvas host. Links to canvas groups move the camera instead of scrolling the page. Define what happens to links that leave the canvas, including links inside portals. Do not change component links or router internals.
  • Portals stay in their native roots at screen-space size. Let the library handle positioning and modal focus. Use public container options only when needed. Check positioning and clickable areas under canvas transforms. If they break, report it or propose a separate preview document. Do not patch components.
  • The canvas has no undo/redo, editing shortcuts, or history.
  • 点击、文本选择、输入、按钮和开关激活、焦点以及嵌套滚动必须保持正常工作。
  • 画布快捷键（
    Space
    、方向键、
    Escape
    、原生 undo）仅适用于画布 shell，不得让预览控件失去这些按键。
  • 在画布 host 中处理预览导航。指向画布分组的链接应移动视角，而不是滚动页面。明确离开画布的链接（包括 portals 内部链接）会如何处理。不要更改组件链接或 router internals。
  • Portals 保持在原生 roots 中，并以 screen-space 尺寸呈现。让库自行处理定位和 modal focus。仅在确有需要时使用 public container options。检查画布 transform 下的定位和可点击区域。如果出现问题，请报告或提议使用单独的预览文档。不要 patch 组件。
  • 画布没有 undo/redo、编辑快捷键或历史记录。

Safety for previews

预览安全

Make each preview safe before it mounts:
  • Use providers with test data, mock services, or existing callback props to block live calls and real writes.
  • Static demo assets and local fixtures are fine.
  • Never use production credentials or data.
  • If safe isolation is not available, omit the live example and explain why. A separate document alone does not make a preview safe.
在每个预览挂载前确保其安全：
  • 使用带有测试数据的 providers、mock services 或现有 callback props，阻止实时调用和真实写入。
  • 可以使用静态演示资源和本地 fixtures。
  • 绝不要使用生产凭据或生产数据。
  • 如果无法提供安全隔离，请省略实时示例并说明原因。单独的文档本身并不能确保预览安全。

Camera

视角控制

  • Mouse and trackpad: pan, and zoom around the cursor. Touch: pan and pinch.
  • Start ordinary pan on empty canvas space. Keep native gestures inside previews and portals.
  • Do not cancel events broadly, and do not put 
    touch-action: none
    on interactive content.
  • Handle pointer count changes, cancellation, lost capture, window blur, and hidden tabs. Release captures and clean up listeners, observers, timers, and animation frames on teardown.
  • Apply gesture transforms at most once per animation frame. Avoid alternating layout reads and writes.
  • Prevent group overlap when content expands or the viewport resizes. Avoid layout loops and unnecessary movement. Fit after layout settles. Fitting never rearranges groups.
  • Move the camera to reveal keyboard focus outside the visible area. Native page scrolling must not move the canvas.
  • Keyboard camera navigation works, with visible focus on canvas controls.
  • Provide fit-all and reset icon buttons with accessible names. Keep them reachable even when the view is lost.
  • Validate camera values and keep them within bounds.
  • 鼠标和触控板：平移，并以光标为中心缩放。触摸：平移和双指缩放。
  • 普通平移从画布空白区域开始。预览和 portals 内部保留原生手势。
  • 不要广泛取消事件，也不要在交互内容上设置 
    touch-action: none
    。
  • 处理 pointer 数量变化、取消、丢失 capture、window blur 和 hidden tabs。拆卸时释放 captures，并清理 listeners、observers、timers 和 animation frames。
  • 每个 animation frame 最多应用一次手势 transform。避免交替执行 layout reads 和 writes。
  • 当内容扩展或 viewport 尺寸变化时，防止分组重叠。避免布局循环和不必要的移动。布局稳定后再执行适配。适配操作绝不重新排列分组。
  • 移动视角，以显示可见区域之外的键盘焦点。原生页面滚动不得移动画布。
  • 支持键盘视角导航，并在画布控件上显示焦点。
  • 提供带无障碍名称的 fit-all 和 reset 图标按钮。即使当前视图丢失，也必须能够访问这些按钮。
  • 验证视角数值，并将其限制在有效边界内。

Persistence

持久化

  • Save only the camera, in a versioned format, under a storage key per project or workspace.
  • Handle malformed or oversized data, unavailable storage, and quota errors.
  • Migrate known older formats. For unknown formats, use safe defaults and discard old group positions and history.
  • Reset restores the camera only. It does not clear preview state or drafts.
  • 仅保存视角，并使用版本化格式，存储在每个项目或 workspace 对应的 storage key 下。
  • 处理数据格式错误、数据过大、storage 不可用和配额错误。
  • 迁移已知旧格式。对于未知格式，使用安全默认值，并丢弃旧分组位置和历史记录。
  • Reset 仅恢复视角，不会清除预览状态或草稿。

Checks

检查

Run the repository's checks when allowed. Then, in the browser, confirm:
  • The route mounts, imports and exports resolve, and the console shows no errors.
  • Component source is unchanged.
  • Listed variants appear, omissions are explained, groups have dashed borders, and non-style comparisons use one style.
  • Keyboard camera navigation and visible focus work. Preview controls keep their native shortcuts and gestures.
  • Nested scrolling, portal positioning, clickable areas, and modal focus work at several zoom levels and viewport sizes.
  • Pan and pinch survive pointer changes and cancellation. Teardown releases resources.
  • Groups do not overlap after expansion or resize. Fit works, and offscreen focus reveals correctly.
  • Camera persists across reload. A storage failure falls back safely. Reset keeps preview drafts. Drafts need not survive reload unless requested.
  • Groups cannot be dragged. The canvas has no undo/redo.
  • Previews use safe test data and make no real project or account writes.
A check counts as passing only if it was run. If a check was skipped, say so.
在允许的情况下运行仓库检查，然后在浏览器中确认：
  • route 正确挂载，imports 和 exports 能够解析，且 console 中没有错误。
  • 组件源码未发生变化。
  • 列出的变体均已出现，省略内容已有说明，分组带有虚线边框，并且非样式对比使用同一种 style。
  • 键盘视角导航和可见焦点正常工作。预览控件保留其原生快捷键和手势。
  • 嵌套滚动、portal 定位、可点击区域和 modal focus 在多个缩放级别及 viewport 尺寸下正常工作。
  • 平移和双指缩放在 pointer 变化及取消后仍能正常工作。拆卸过程会释放资源。
  • 内容扩展或尺寸变化后，分组不会重叠。适配功能正常工作，屏幕外焦点能够正确显示。
  • 视角在重新加载后仍然保留。storage 失败时会安全回退。Reset 会保留预览草稿。除非明确要求，否则草稿无需在重新加载后保留。
  • 分组无法拖动。画布没有 undo/redo。
  • 预览使用安全的测试数据，不会对真实项目或账户执行写入。
只有实际运行过的检查才能计为通过。如果跳过了某项检查，请明确说明。

Report

报告

End every build or review with these headings:
  • Changed: files and what changed in each. Note any component changes (there should be none).
  • Checks run: each check and its result.
  • Not working or not tested: known gaps, omitted variants and why, and anything unverified.
  • Decisions made: defaults chosen without asking.
Do not describe the implementation as verified or the template as ready unless every check above passed.
每次构建或审查结束时，都必须使用以下标题：
  • 变更内容： 列出文件以及每个文件中的更改。注明任何组件变更（正常情况下应没有组件变更）。
  • 已执行的检查： 列出每项检查及其结果。
  • 未工作或未测试： 列出已知缺口、省略的变体及其原因，以及所有尚未验证的内容。
  • 已作出的决策： 列出未询问用户时自行采用的默认决策。
除非上述所有检查均已通过，否则不得声称实现已验证或模板已准备就绪。