SuperAPI AI 工具集

write-ui-examples

编程与开发

查看项目

更新于 10-29 23:30

技能介绍

Write UI Examples 是面向 Remix UI 文档的写作与评审技能,帮助读者发现 UI 特性、感受其行为并复制合适的用法模式。其定位是:每个公开特性都需要文档;缺少视觉动机的特性通常更适合文字、接线片段(wiring snippet)和 API 参考,而不是再增加一个实时演示。文档同时帮助维护者评估不断演进的库,保留可观察差异与不支持的能力,让读者无需阅读实现即可比较 API 与交互。

文档结构 TSX 文档页面放在 docs/ui/app/pages/ 下,可运行的 .example.tsx 模块放在 docs/ui/app/examples/ 下并按特性分组。使用现有页面辅助工具、显式源码加载和普通 Remix 水合,而非针对打包器的片段机制。文档编写文件不得进入发布包产物。UI 被视为独立且当前不稳定的库:安装、包状态与共享样式或组合概念放在 Getting Started,现有特性归入 Patterns 与 Animation,不引入推测性的系统层。正文中称其为 Remix UI,首次点明后可用“该库”“该包”或代词指代。

覆盖范围与示例设计 需覆盖受支持的有用组合以及专用库选项,并对照相关库示例、既有 UI 库和 WAI-ARIA Authoring Practices 检查缺口,如命名选项组、可见标签与描述。当组合揭示独特交互时加入实时演示;若仅标记本身即可传达要点,则在现有演示旁给出简短说明。为分组选项、菜单项等受支持组合设立具名特性小节,展示使用方编写的语义、标签与键盘入口,包括可聚焦的纯文本标签面板。将有用的帮助文本关联到其控件,并保持可访问名称与描述相互区分。

选择交互先于编码 动手前先阅读公开 API、实现及现有或类似示例;对陌生模式可对照 Base UI 或 Radix 示例与早期仓库演示,借用交互惯例而非框架专属代码。为每个拟议示例写下三种可能的交互模式,优先选择文档特性能在熟悉任务中做有用、可观察工作且上下文最少的那种;同时评估产品体验与实现契合度,拒绝需要无关控件或解释性文案才能成立的情景。真实性指模式契合与可信内容,而非应用细节的数量——一个带标签的开关或填充好的操作菜单即可构成完整示例。

内容需作为集合来审阅:标签、描述、操作与状态应属于同一可识别语境与抽象层级;图标与动作标签须匹配语义(如书签图标应写 Bookmark 而非宽泛的 Save)。基元内部要有足够内容以检验它:搜索需要有用的集合,子菜单需要足以证明嵌套合理,单选与复选菜单需要有意义的选择。将基元与任务匹配:从大量集合中可搜索选择适合 Combobox,少量固定选项通常适合 Select,操作适合 Menu。浮动表面需要有浮出的理由,紧凑设置、过滤器与编辑表单是成熟模式。

应一并审阅重叠的基元,设想一个应用同时使用两个 API 并找出各自职责;若同级页面展示相同交互,应明确解释组合取舍或另找能揭示不同用途的情景。同时与更简单的原生或 CSS 实现比较。先确定抽象层级:行为基元、定位工具与组合配方需要不同框架;低层几何工具可以以聚焦的定位图示为主,让放置、对齐、视口适配或跟踪可观察。

每个示例保持一个主要行为,不为覆盖其他 API 选项而添加无关的禁用、加载或错误状态;变体之间保留规范内容,只改动特性所需之处。可用性状态需在情景内有可信原因(如未满足前置条件、资格规则或工作流状态),并说明为何不可用选项应保持可见而非省略。当可用性依赖不明显上下文时,让原因可见且可访问,但不激活不可用控件或打开其面板;将其放在视觉分组可明确归属该控件的位置(如其标签旁),用字重、颜色与间距建立标签与支持原因之间的排版层级。不可用标签页需区分不支持的能力与应保持可访问的空面板。若没有令人信服的交互,优先用代码示例,勿虚构周边工作流。

受控状态应首先寻找应用状态自然协调控件与其他元素的熟悉交互(如 Show password 开关与密码输入共享一个布尔值)。与原生表单重置比较后再提出 Clear all 或 Reset;受控状态不必是唯一实现,但应是自然的架构选择。没有紧凑有用的视觉交互时改用片段;外部操作仅在具有独立产品目的时加入。

精简组合再打磨 在美化前先比较更简版本,找出能保持可信交互并暴露文档特性的最少控件类型与决策:过滤器弹出层里一个小复选框列表可能就足够,下拉、第二个过滤类别与 Apply 工作流各需独立理由。不要仅为了让演示“像真的”而虚构草稿状态、提交按钮、重置、徽章或结果摘要;即时更改可能是更自然的交互。同时评估视觉与源码密度,移除与所教 API 竞争的机制,再细化层级、间距、对齐与点击区域。

对抗性产品体验审查 每个 UI 示例在宣告完成前必须通过产品体验审查,这与检查代码能否运行不同:像该交互与内容要上线到应用或在产品设计评审会上展示那样审阅。问:产品设计师在不知道示例要演示哪个 API 的情况下,会为该内容选择此交互吗?用户为何打开它,为何优于内联显示或用其他基元?各项及其描述与可用性是否属于同一组?每个变体是否在隔离所教特性时保留该语境?每个操作是否有预期结果?示例是否暗示了它并未实现的工作流?用用户可见的标签与支持文本检查可见内容建立的预期,并验证实际匹配行为;若 API 无法为该情景提供可信交互,应修改情景或单独报告 API 问题,而非在演示文案中辩解。还要检查:主要交互是否无需预览内说明即可明显?这是否为最简单可信版本?能否移除整个控件类型、工作流步骤或内容组而不降低用处或自然度?可见交互边界是否与实际点击区域一致?悬停、按下与焦点状态是否强化视觉设计所暗示的交互——反馈应作用于可操作表面而非笼统作用于外层卡片或表单组;不可用与只读控件不得招示可激活。每个指示器是否描述可用操作或实际状态?读者能否从可见 UI 推断每个不可用控件为何不可用?聚焦、关闭、选中与禁用状态在整个交互中是否一致?键盘与触摸输入、重复操作与快速变化下是否仍合理?审查失败时回到情景选择比较替代方案——缩短文案、改名或打磨无法修复没有可信目的交互;应更改情景或移除演示。将后续用户反馈视为缺失决策标准的证据,把可复用原则更新到本技能,再重估受影响的早期示例。审查记录保留在工作笔记或完成报告中,而非向示例 UI 添加审查机制。

遵循库的真实契约 记录每个组件实际的 props、状态归属、事件负载、属性与默认值,不要为让 API 显得一致而抹平差异。覆盖审计时逐项比较每个公开导出与选项及其实现与测试,包括默认值、匹配规则、事件时机、键盘处理与表单行为;符号出现在参考中不等于其契约已被解释。选择措辞前先复现矛盾,并将库缺陷与文档缺口分开记录;单独报告已确认缺陷、规避方法与意外 API。

适用场景:Remix UI 文档编写、示例审阅、场景与内容设计、产品体验评审、API 契约呈现。限制:UI 目前为不稳定的独立库;不支持能力需如实呈现,不编造应用细节或工作流。