first commit

explanations/user-interface/README.md

@@ -0,0 +1,63 @@
+# 用户界面
+
+## 区块编辑器
+
+区块编辑器的整体布局采用顶部工具栏+内容区域的设计。
+
+![编辑器界面](https://cldup.com/VWA_jMcIRw-3000x3000.png)
+
+**工具栏**包含文档级操作：编辑/选择模式、保存状态、撤销/重做/插入等全局功能、设置开关以及发布选项。
+
+**内容区域**承载文档主体内容。
+
+**设置侧边栏**包含文档相关设置（标签、分类、发布时间等）以及"区块"标签页中的区块设置。工具栏中的齿轮按钮可隐藏设置侧边栏，让用户获得更专注的写作体验。在小尺寸屏幕上，侧边栏默认处于隐藏状态。
+
+## 区块单元
+
+区块是编辑器最基础的构成单元。广义而言，所有内容都是区块。用户通过区块构建文章与页面，这种模式完美复现了底层HTML标记的垂直流式布局。
+
+通过将文档每个部分呈现为可操作的独立区块，我们实现了区块特定功能的场景化调用。这一设计灵感源自桌面应用惯例，既能支持丰富的高级功能，又不会造成界面臃肿。
+
+被选中的区块会显示多项场景化操作：
+
+![区块界面](https://cldup.com/3tQqIncKPB-3000x3000.png)
+
+区块界面提供基础操作功能。区块编辑器致力于提供优质通用的默认设置，用户无需依赖设置侧边栏的高级功能即可完成完整文档创作。
+
+**区块工具栏**突出显示常用功能。**区块图标**位于区块工具栏内，包含针对当前选中区块的顶层控制，主要支持用户将区块转换为其他兼容类型。部分区块还会通过区块图标提供替代样式选择。
+
+**区块格式化**选项用于调整区块层级设置，**行内格式化**选项则用于修饰区块内部元素。当区块内容较长时，随着用户向下滚动页面，区块工具栏会自动固定在屏幕顶部。
+
+通过**区块移动器**图标可实现区块的上下移动。点击省略号菜单可唤出附加功能：删除与复制区块，以及"以HTML编辑"、"转换为可复用区块"等**高级操作**。
+
+未选中的区块不会显示区块工具栏或任何场景化控件，此时区块仅呈现内容预览效果：
+
+![未选中区块](https://cldup.com/DH9HZnEgwH-3000x3000.png)
+
+请注意选择状态与焦点状态可独立存在。例如图片区块被选中时，焦点可能位于标题输入框。
+
+## 设置侧边栏
+
+![设置侧边栏](https://cldup.com/iAqrn6Gc8o-3000x3000.png)
+
+侧边栏包含"文档"与"区块"两个标签页：
+
+-   **文档标签页**显示正在编辑的文章或页面的元数据及设置
+-   **区块标签页**显示当前选中区块的元数据及设置
+
+每个标签页均包含可展开/折叠的**侧边栏分区**编辑字段组。
+
+若区块需要高级配置，相关设置应置于设置侧边栏中。但请注意：区块基础运行所需的设置不应放在侧边栏区块标签页——用户可能为获得沉浸式写作体验而关闭侧边栏。建议设置合理的默认值，并将重要操作置于区块工具栏。
+
+适合放入侧边栏区块标签页的功能包括：
+
+-   文本区块的首字下沉
+-   图库的列数设置
+-   "最新文章"区块的文章数量或分类筛选
+-   所有非基础操作必需的配置项
+
+## 区块库
+
+![区块库](https://cldup.com/7QoQIoLk-A-3000x3000.png)
+
+当用户通过工具栏或内容区场景化菜单插入区块时，**区块库**界面将会启动。库内区块按可展开的分组进行组织，搜索栏会随用户输入实时筛选区块列表。用户可通过选择**区块按钮**或**区块名称**来选用特定区块。

explanations/user-interface/animation.md

@@ -0,0 +1,40 @@
+# 动画设计
+
+动画能够有效强化界面层级感和空间方位感。本文档将阐述添加动画时应遵循的设计原则。
+
+## 核心原则
+
+### 起始原点
+
+- 动画可锚定界面元素，例如菜单可从触发按钮位置缩放展开
+- 动画可构建空间感知，例如侧边栏从屏幕边缘滑入，暗示其始终隐藏于屏幕之外
+- 设计动画时需遵循真实物理规律。想象界面元素由实体材料构成——当它们不在屏幕上时位于何处？用动画来呈现这种空间关系
+
+### 响应速度
+
+- 动画绝不应阻碍用户交互，必须保持快速响应，通常在0.2秒内完成
+- 用户无需等待动画完成即可进行交互操作
+- 确保动画性能优化。优先使用CSS `transform`属性，通过GPU渲染实现流畅效果
+- 若无法实现快速高性能的动画效果，宁可不使用动画
+
+### 简洁克制
+
+- 非弹性材料不做弹跳动画
+- 避免旋转、折叠或曲线路径动画，保持简洁直观
+
+### 统一规范
+
+建立统一的动画物理规则，使所有元素的动效保持协调一致、符合预期。动画应当匹配用户心理预期，否则可能不适配当前场景。
+
+若已有现成动画效果，请直接复用。
+
+## 无障碍考量
+
+- 动画需保持克制，注意可能引发前庭功能障碍用户不适的情况（详见[运动触发前庭障碍研究](https://www.ncbi.nlm.nih.gov/pubmed/29017000)）
+- 避免对正在向辅助技术报告内容的区域（如正在接收更新的`aria-live`区域）添加动画，这可能导致技术解析动态变化区域时产生混乱
+- 杜绝非用户直接触发的动画
+- 确保动画遵循操作系统层级的"减弱动态效果"设置，可通过[`prefers-reduced-motion`](https://developer.mozilla.org/zh-CN/docs/Web/CSS/@media/prefers-reduced-motion)媒体查询实现。Gutenberg提供`@reduce-motion`混合宏，需与含CSS`animate`属性的规则配合使用
+
+## 复用动画库
+
+通用`Animate`组件用于驱动界面各区域的动画效果。具体可用动画请参阅[组件文档](/packages/components/src/animate/README.md)。

explanations/user-interface/block-design.md

@@ -0,0 +1,203 @@
+### 高级区块设置
+
+设置侧边栏中的“区块”标签页可包含额外的区块选项与配置项。请注意用户可能关闭侧边栏且永不使用，不应将关键选项置于侧边栏内。
+
+![段落区块在侧边栏中的高级设置截图](https://developer.wordpress.org/files/2022/01/advanced-settings-do.png)
+**正确做法：**
+首字下沉功能并非区块基础运行的必要功能，可将其作为可选配置置于区块标签页中。
+
+### 移动端适配
+
+尽可能在多设备、多屏幕尺寸下检验区块的视觉呈现、交互体验与功能表现。
+
+### 支持古腾堡深色背景编辑模式
+
+检验区块在编辑器[深色背景](/docs/how-to-guides/themes/theme-support.md#dark-backgrounds)下的视觉呈现效果。
+
+## 示例演示
+
+以下通过古腾堡默认区块的标注示例展示部分实践方案：
+
+### 段落区块
+
+编辑器最基础的构成单元。段落区块即简易输入框。
+
+![段落区块](https://cldup.com/HVJe5bGZ8H-3000x3000.png)
+
+#### 占位状态
+- 简洁提示语“输入/选择区块”，选中区块后提示消失
+
+#### 选中状态
+- 区块工具栏：配备转换器（可切换为标题等）
+- 区块工具栏：提供基础文本对齐功能
+- 区块工具栏：支持行内格式设置（加粗、斜体、删除线及链接）
+
+### 图片区块
+
+基础图片区块。
+
+![图片区块占位状态](https://cldup.com/w6FNywNsj1-3000x3000.png)
+
+#### 占位状态
+- 通用灰色占位区块，支持上传图片、直接拖放图片或从媒体库选取
+
+#### 选中状态
+- 区块工具栏：对齐选项（若主题支持则包含宽幅与全宽对齐）
+- 区块工具栏：编辑图片（打开媒体库）
+- 区块工具栏：链接按钮
+- 图片上传后，下方出现标注输入框及“添加标注…”提示语：
+
+![图片区块](https://cldup.com/6YYXstl_xX-3000x3000.png)
+
+#### 区块设置
+- 描述文本：“一图胜千言！插入单张图片”
+- 提供修改替代文本、添加自定义CSS类等功能
+
+*图片区块的未来改进方向包括取消媒体弹窗，允许用户直接在占位区选取图片。总体而言应尽量避免使用弹窗。*
+
+### 最新文章区块
+
+![最新文章区块](https://cldup.com/8lyAByDpy_-3000x3000.png)
+
+#### 占位状态
+插入即生效，无占位状态。默认显示最近5篇文章。
+
+#### 选中状态
+- 区块工具栏：对齐选项
+- 区块工具栏：列表视图/网格视图切换功能
+
+*注意：因无可切换的相似区块，此时区块工具栏不包含区块标识符*
+
+#### 区块设置
+- 描述文本：“展示最新文章列表”
+- 提供文章排序、按分类筛选、默认显示篇数设置、发布日期显示等选项
+
+*最新文章区块凭借完善的默认配置，插入后即可完整运作。*
+
+## 注意事项
+
+### 区块工具栏
+
+按逻辑分组组织工具栏控件，避免为每个控件单独设置分组。
+
+![对比区块工具栏合理与不合理分组的截图](https://make.wordpress.org/design/files/2021/03/docs__block-toolbar-do-dont.png)
+
+### 区块标识
+
+区块名称应简洁明了，方便用户在区块库中快速定位。例如命名为“YouTube”的区块直观易寻，而命名为“嵌入式视频(YouTube)”则显得冗长难觅。
+
+在文档或界面中提及区块时，区块标题采用首字母大写格式，“区块”描述词保持小写。例如：
+- 段落区块
+- 最新文章区块
+- 媒体与文本区块
+
+区块应配备辨识性图标，建议使用单色设计并避免与现有区块图标重复。核心区块图标基于[Material Design图标集](https://fonts.google.com/icons)，可参考该系列或[Dashicons](https://developer.wordpress.org/resource/dashicons/)获取设计灵感。
+
+![展示简洁区块名称的区块库截图](https://developer.wordpress.org/files/2022/01/blocks-do.png)
+**建议：**
+使用简练的区块名称
+
+![展示多行长名称的区块库截图](https://developer.wordpress.org/files/2022/01/blocks-dont.png)
+**避免：**
+使用冗长的多行区块名称
+
+### 区块描述
+
+每个区块需包含功能说明，该描述将显示在设置侧边栏中。
+
+可通过[registerBlockType函数](/docs/reference-guides/block-api/block-registration.md)的description属性添加描述。
+
+采用“动词+主语”结构的祈使句，例如：
+- 作为所有叙事的基础构建单元
+- 通过内容分节帮助访客（及搜索引擎）理解内容结构
+- 创建项目符号列表或编号列表
+
+![简短区块描述示例](https://developer.wordpress.org/files/2022/01/block-descriptions-do.png)
+**建议：**
+使用简短明晰的区块描述
+
+![包含品牌信息的冗长描述示例](https://developer.wordpress.org/files/2022/01/block-descriptions-dont.png)
+**避免：**
+使用冗长描述及品牌信息
+
+### 占位符
+
+若区块需用户配置后方可显示，应提供指导性占位状态。
+
+![图库区块占位符示例](https://developer.wordpress.org/files/2022/01/placeholder-do.png)
+**建议：**
+提供具指导意义的占位状态
+
+![无说明信息的炫目占位符示例](https://developer.wordpress.org/files/2022/01/placeholder-dont.png)
+**避免：**
+使用品牌元素且仅依赖标题传递指引
+
+### 选中与未选中状态
+
+未选中时，区块预览应最大程度接近前端显示效果。
+
+选中状态下，可呈现输入框或按钮等配置选项，特别是基础操作必需的功能。
+
+![包含行内必控功能的谷歌地图区块](https://developer.wordpress.org/files/2022/01/block-controls-do.png)
+**建议：**
+区块运行必需的控制元件应直接内嵌于编辑视图
+
+![必控元件移至侧边栏的谷歌地图区块](https://developer.wordpress.org/files/2022/01/block-controls-dont.png)
+**避免：**
+将核心控制元件置于侧边栏，否则移动端用户或关闭侧边栏的桌面用户将无法正常操作区块
+
+# 区块设计
+
+以下是设计新区块时的最佳实践，包含相关建议及现有区块的详细说明，以展示我们创建区块的方法。
+
+## 最佳实践
+
+### 区块内容区域是主要交互界面
+
+由于区块本身代表实际显示在网站上的内容，此处的交互最符合直接操作原则，对用户也最为直观。这里应被视为添加和操作内容、调整显示效果的主要界面。交互方式有两种：
+
+1. 区块内容区域中的占位内容可视为引导界面，帮助用户遵循指令或“填空”。例如，嵌入第三方服务内容的区块可能在占位区域包含该服务的登录控件。
+2. 用户添加内容后，选中区块可显示用于调整或编辑内容的附加控件。例如，订阅区块可能显示隐藏/显示订阅者数量的控件。但这类操作应保持最小化，避免用户选中区块时引发区块尺寸与显示的剧烈变化（这可能造成困惑或困扰）。
+
+### 区块工具栏作为次要选项设置区域
+
+基础区块设置并非始终适合放在占位内容界面中。作为次要选择，对区块功能至关重要的选项可置于区块工具栏。区块工具栏仍保持高度情境化，且在所有屏幕尺寸下可见。需注意其图标化界面的特性，因此工具栏中的控件必须能通过图标有效传达信息。
+
+### 按关联性分组工具栏控件
+
+区块工具栏采用分层分段式控件分组：首段包含区块类型控件（如区块切换器、拖拽柄和移动控制器）；次段包含影响整个区块的通用与特定工具，随后是行内格式工具与“更多”菜单；可选设置的“元数据”或“其他”组可将部分工具独立分段。
+
+![区块工具栏分段示意图](https://make.wordpress.org/design/files/2021/03/docs_block-toolbar-structure.png)
+
+### 设置侧边栏仅用于高级三级控件
+
+设置侧边栏在小屏/移动设备上默认隐藏，在桌面视图也可能被折叠。因此不应将区块基础操作所必需的功能置于此处。建议选择合理的默认值，将重要操作置于区块工具栏，并将设置侧边栏视为多数用户无需开启的辅助区域。
+
+若选项超过五项，应使用分区标题帮助用户快速浏览和理解可用选项。
+
+默认情况下每个设置侧边栏都包含“高级”分区，该区域设有“附加CSS类”字段，可用于放置高级用户控件。
+
+## 设置状态与实时预览状态
+
+设置状态（常称为“占位界面”）用于在展示区块实时预览前引导用户完成初始化流程。该过程收集渲染区块所需的用户信息，并通过灰色背景明确标识设置状态。并非所有区块都需要设置状态（如段落区块）。
+
+![图片区块设置状态示例](https://make.wordpress.org/design/files/2021/03/docs__gallery-setup-state.png)
+
+**无需**设置状态的情况：
+- 能提供满足多数需求的优质默认内容
+- 默认内容易于编辑和自定义
+
+**需要**设置状态的情况：
+- 缺乏适用于多数用户的明确默认状态
+- 需收集与区块实时预览无直接关联的用户输入（如要求输入API密钥来渲染内容）
+- 需要更多用户信息才能生成有效的默认内容
+
+对于具有设置状态的区块，用户完成设置流程后，占位界面会被该区块的实时预览状态替代。
+
+![图库实时预览状态示例](https://make.wordpress.org/design/files/2018/12/gallery-live-preview.png)
+
+选中区块时可能显示附加控件用于自定义内容。例如选中图片库时，会显示删除或添加图片的控件。
+
+![选中区块时显示附加控件的示例](https://make.wordpress.org/design/files/2018/12/gallery-additional-controls.png)
+
+多数情况下区块设置状态仅显示一次，后续通过实时预览状态进行优化。但某些场景下需允许用户返回设置状态，例如区块内容被全部删除时，或通过区块工具栏/侧边栏的链接进入。

explanations/user-interface/design-resources.md

@@ -0,0 +1,55 @@
+# 资源
+
+## Figma
+
+[WordPress设计团队](https://make.wordpress.org/design/)使用[Figma](https://www.figma.com/)进行协作与成果共享。若您希望参与贡献，可通过[WordPress Figma设计资源库](https://make.wordpress.org/design/handbook/get-involved/tools-figma/)制作设计原型。您也可以加入[Slack](https://make.wordpress.org/chat/)的[#design频道](https://app.slack.com/client/T024MFP4J/C02S78ZAL)进行咨询交流。Figma提供免费账户，通过该账户您可以使用共享资源库中的组件，或通过复制文件至草稿箱进行编辑。对WordPress资源库的完整编辑权限为付费功能，仅限设计团队使用。
+
+### 如何参与贡献
+
+### Figma使用学习资源
+
+[Figma入门指南](https://help.figma.com/category/9-getting-started)
+
+[UI/UX设计必备：Figma在线教程精选](https://medium.com/quick-design/top-online-tutorials-to-learn-figma-for-ui-ux-design-4e9c6721a72d)
+
+[Figma功能导览](https://help.figma.com/article/12-getting-familiar-with-figma)
+
+### 文件与项目使用指南
+
+[Figma文件与项目入门](https://help.figma.com/article/298-getting-started-with-files-and-projects)
+
+[什么是文件？](https://help.figma.com/article/298-getting-started-with-files-and-projects#files)
+
+[什么是项目？](https://help.figma.com/article/298-getting-started-with-files-and-projects#projects)
+
+[视频教程](https://www.youtube.com/watch?v=c5HS6smhq2E)
+
+[常见问题解答](https://help.figma.com/article/298-getting-started-with-files-and-projects#faq)
+
+### 组件使用指南
+
+[组件功能入门](https://help.figma.com/article/66-components)
+
+[什么是组件？](https://help.figma.com/article/66-components#components)
+
+[视频教程](https://help.figma.com/article/66-components#videos)
+
+### WordPress Figma资源库使用指南
+
+**如何在Figma中启用WordPress组件库**
+
+![启用Figma资源库动态演示](https://wordpress.org/gutenberg/files/2019/08/figma-howtoturnonlibraries.gif)
+
+1. 点击**资源面板**中的**团队资源库**图标：
+
+![悬停显示团队资源库图标](https://wordpress.org/gutenberg/files/2019/08/figma-turn-on-libraries-e1564770916643.png)
+
+2. 开启**资源库**弹窗后，您可查看可用资源库列表。通过切换按钮_启用_或_禁用_特定资源库：
+
+![在Figma中启用WordPress组件库](https://wordpress.org/gutenberg/files/2019/08/figma-libraries-e1564770879415.png)
+
+**如何优化或贡献WordPress组件React库（即将推出）**
+
+Figma中的WordPress组件与实时React组件保持同步。关于如何优化或贡献React版WordPress组件的文档即将发布。
+
+如有疑问，欢迎随时在WordPress社区Slack的#design频道中提出。