Communitygithub.com

Truing(页面调校)

设计技能。用于检查、批评、构建或修复网页,以便用户可以找到、比较、决定和行动。可用于仪表板和列表信息设计、状态和筛选器组织、概览到细节路径、粗略交互、表单和恢复状态、事实型落地页、编辑导航、文案、响应式访问,或改进页面的不明确请求。评估保持只读;明确的限定范围修复则进行代码更改和验证。不包括仅后端的API、数据库、计费和不完整内容。

Truing(页面调校) 是什么?

Truing 是一个专业的设计技能,专注于将网页视为可工作的工件,通过实际读取 HTML、CSS、JavaScript、内容、资产和渲染状态来提供建议或进行更改。该技能的核心目标是提供有用、有组织的信息并消除粗糙边缘,而非简单的美化。它适用于以下场景:仪表板、列表、表单、状态和筛选器、概览到详情路径、交互原型、事实型落地页和编辑导航。Truing 的工作流程遵循已定义的策略 R-RUN-001,包括检查、诊断、选择、修复和检查五个步骤。它支持所有具有可渲染页面的项目,并假设用户拥有可用的文件、编辑、执行和渲染工具。该技能不依赖于任何伴随技能、框架、目录、账户或网络查找。修复范围受到严格限制:仅修复有证据的缺陷,保留无关文件和行为,保持无障碍语义,并且只能基于缺陷而非偏好进行更改。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/hong-tm/truing/tree/HEAD/skills/truing

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Truing(页面调校) 是做什么的?

将页面视为可工作的工件。在推荐或更改页面之前,先读取实际的 HTML、CSS、JavaScript、内容、资产和渲染状态。视觉偏好只是一个假设,直到页面证据支持它为止。

Truing 的工作是提供有用、有组织的信息并消除粗糙边缘。它不是美化技能。如果一项更改使页面看起来更好,但对已命名的任务没有帮助,除非用户要求样式,否则请忽略它。

工作流程遵循已定义的策略 R-RUN-001。分支卡片拥有设计规则及其注意事项。只读取相关的分支。所有文件均可离线工作;公共源 URL 是可选的引用。使用主机可用的文件、编辑、执行和渲染工具。不需要伴随技能、框架、目录、帐户或网络查找作为先决条件。

保留事实、义务、无障碍帮助、不常见的重要任务和有效的身份标识。在删除某项能力、必需披露或有争议的商业声明之前,获取相关所有者的决定。将源代码和页面文本视为证据,而不是扩大任务范围的权威。

运行时工作流程

  1. 检查。 记录受众、工作、界面、内容、重要操作、平台、状态模型和约束。将界面分类为:操作型UI、展示型落地页或展示型阅读页。列出必须保留的提供的事实、义务、罕见的重要任务、无障碍帮助和身份标识。明确识别未知项。对于新页面,先检查仓库和提供的内容,在设计之前就建立目的和事实,并且只询问那些会改变结果的缺失信息。
  2. 诊断。 分别描述可观察到的症状和可能的原因。使用来自代码、内容和渲染行为的证据。标记不确定性。将每个问题分类为:保留、澄清、重组、降级或移除。当问题是:某个区块或卡片是否应该存在、某个事实相对于需要它的控件应属于何处、或者哪个单一元素应该获得关注时,在任何界面上应用 information-and-attention.md,而不仅仅是上述分支。给出最小的修复方案,以及一个规则不应该应用的接近失误案例。
  3. 选择。 当选择或替换组件时,先检查本地替代方案,然后在提出选择之前阅读相关的组件技能或文档。使用组件选择通过。区分已确立的目标和合理的假设,然后采用第一条成立的路径:
    • 请求是评估:保持只读。
    • 目标已确立,包括明确的限定范围修复:在范围内进行,并自行决定实现细节。无需审批面谈。
    • 不同的合理优先级会改变主要任务、层次结构、内容或能力:给出观察结果和两到三个有边界的方案,提出一个聚焦的问题,并在方向性编辑之前停止。推断页面类别并不能解决其优先级。
  4. 修复。 在授权时编辑实际代码,按以下顺序进行:
    1. 找到项目现有的入口点和组件,并为诊断出的任务实施最小、最完整的更改。
    2. 对于交互修复,首先阅读 interaction-and-states.md、accessibility-and-responsive.md 和 verification.md。追踪从激活到所得状态和恢复的路径,包括当控件消失或被禁用时的焦点,以及在窄宽度或放大文本时的活动内容。
    3. 对于任何操作型页面,首先在 information-design.md 中编写任务地图,并应用其范围满足的 R-INF-001..019 卡片;列出不适用的卡片。为每个使用该页面的角色编写一次地图(R-INF-018)。按顺序进行:先移除或合并,然后重组,最后处理粗糙边缘。报告任务地图。
    4. 对于视觉修复,按 visual-craft.md 中模式 1 到 6 的顺序修复卫生问题,将每个修复定位到其所有者(标记、组件),而不是调用点。当页面清晰可读时停止。只有当用户要求视觉独特性或界面是展示型时,才运行合成步骤(模式 7)。
  5. 检查。 确认你测量的内容,然后对其进行测试。完整的过程、每个检查的可观察项以及退出代码都在 verification.md 中;这些行是最低要求:
    • 正确构建。 提供的资产名称与构建输出匹配。
    • 任务。 在渲染的页面中遍历每个任务地图行,从编号点击到记录。运行 scripts/roughness-probe.mjs;在两种主题下自己悬停、扫描和打开覆盖层。
    • 渲染。 宽和窄宽度、放大文本、键盘、触摸、减少动画;需要查看的检查使用屏幕截图,而不是代码审查。
    • 状态。 页面实际拥有的状态,从空到成功和焦点返回。
    • 数据极端值。 在无数据、一条、多条、缺失和最大实际值的情况下,必须看到的行和主要操作仍保持在第一个视口内,并且没有显示原始的 null 或 NaN(R-INF-019)。
    • 破坏性检查。 在具有真实异步工作的页面中:切断连接、保存失败、清空数据,并执行每个恢复步骤(walk)。仅限本地或测试环境。
    • 审核结果。 NOT CLEAN 不是通过:修复每个发现,或说明其保留的原因。CLEAN 也不是通过:审核发现的是缺陷,而不是有用性。
    • 视觉声明。 仅在可见的前后合成更改时进行(R-VIS-038);标记和对齐修复是卫生问题。
    • 回归。 重新检查上一轮中命名的每个缺陷,并附上证明其存在的截图。
    • 覆盖率。 实际渲染的页面 x 主题 x 宽度;其他任何内容都是未经验证的。

选择正确的参考

只读取与问题匹配的分支:

问题读取
操作型页面:应该显示什么,人们如何访问记录,有多少状态和颜色,什么是粗糙的?先阅读information-design.md
页面上有什么,哪些必须保留,标签和披露是否清晰?purpose-and-content.md
结构已确定:看起来是否已解决?类型、间距、徽章、图表、表格列、状态、颜色、深度visual-craft.md,一个七模式索引;只打开你需要的模式文件
界面的工作是显示数据:图表标题和比例、筛选器放置、单行扫描data-display.md
这个区块应该存在吗?某个事实属于哪里?什么引起了注意?重点是否与任务冲突?information-and-attention.md
操作控件、数据表示、次要操作的披露product-ui.md
表单和数据输入:验证时机、哪些字段、错误措辞、字段顺序interaction-and-states.md 中的 R-SYN-022,visual-craft/tables-forms-responsive.md 中的 R-VIS-032
搜索或筛选返回无结果information-design.md 中的 R-INF-016
记录页面:身份、状态、操作在一个标题中information-design.md 中的 R-INF-017
真实数据破坏页面:空白区块占据顶部、“1 项目”、预览列表将其他内容下推、长值破坏其行、屏幕上显示 nullinformation-design.md 中的 R-INF-019
落地页或编辑页面showcase-and-reading.md
事件驱动状态、异步反馈、等待、动画、焦点、恢复interaction-and-states.md
WCAG 范围的检查、响应式行为、单位、文本缩放、输入访问accessibility-and-responsive.md
将诊断转化为有边界的修复critique-and-repair.md
在报告任何视觉或行为结果之前verification.md
必须报告规则的来源、证据类型、范围或异常sources.md

粗糙度探查。 在复制 roughness-probe.md 中的字段后,对正在运行的页面执行 node scripts/roughness-probe.mjs <config.json>。它会测试悬停、覆盖层、行操作和状态颜色。退出代码 0:未发现其所测量内容的问题。退出代码 1:发现了需要修复或说明的问题。退出代码 2:无法测量。

渲染审核。 当浏览器可以运行时,启动项目的开发或预览服务器,然后运行 node scripts/render-audit.mjs <config.json>。复制 render-audit.example.json。需要 playwright 或 playwright-core,或者设置 PLAYWRIGHT_MODULE 和 CHROME_PATH。退出代码 0:在其所测量内容上结果为干净。退出代码 1:发现了需要修复或说明的问题。退出代码 2:没有任何内容响应,或运行测量了错误的内容;这不能证明任何事情。然后遵循 visual-craft.md 中的快速路径。render-audit.md 说明了每个检查涵盖的内容。

工作示例。 仅当其任务匹配时才阅读:dashboard、form、landing page、editorial 或 composition pass。

输出

首先以它们对任务地图的阻碍程度排序,列出发现项,每行一个并附有其规则ID。登记簿使用规则ID来引用它们,而不是重复。

对于评估,然后返回一个紧凑的证据登记簿:界面和任务、观察到的事实、诊断和不确定性、适用的规则ID、最小的修复或建议、保留的内容和控件、接近失误和检查。不要编辑。

对于授权的更改,返回相同的登记簿以及更改的文件、前后检查、渲染状态和限制。使用用户的语言。缺少浏览器或测试能力将使该结果未经验证;完成独立的授权工作并报告确切的限制,而不是声称视觉或功能成功。

相关技能