Communitygithub.com

lguidolin/界面工程与无障碍

在构建或设计 UI 时使用——组件、布局、表单、设计令牌,或做出无障碍决策。关键词——a11y、WCAG、键盘导航、焦点状态、对比度、设计系统、极简 UI、组件复用、ARIA、语义化 HTML。

界面工程与无障碍 是什么?

此技能定义了一种通过约束(而非主观审美)来构建高质量、可访问且美观界面的方法。它要求每个交互元素都必须键盘可达并具有可见焦点状态,所有表单控件都必须有可访问名称和关联标签,同时强制使用语义化 HTML 和地标元素而非无意义的 div 堆叠。设计上严格遵循设计系统的令牌(间距、字体、颜色),避免使用“魔数”,并优先复用现有组件库模式而非自定义构建;任何两个相似的 UI 元素都应参数化为一个组件,三次复制即视为缺陷。当出现纯粹的审美决策且令牌或先例不足以确定时,该技能要求将其上报给人类,而非自行猜测。它支持所有主流平台(Claude Code、Cursor、Codex 等),并作为工程文化的一部分被引入,配合 CI 中的 a11y 检查(如 eslint-plugin-jsx-a11y、axe)来确保无障碍规则的可执行性。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/lguidolin/agent-skills/tree/main/skills/interface-craft-and-accessibility

在你喜欢的 AI 中提问

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

文档

界面工程与无障碍 是做什么的?

概述

标准是可访问、极简且美观——通过构造本身实现,而非后期打磨。 品味作为规则是不可操作的,因此应将其转化为约束、先例和上报机制。代理无需发明品味,只需遵守约束,并将剩余部分上报。

无障碍——一项要求,而非收尾工作

可检查的规则:

  • 每个交互元素必须键盘可达并带有可见焦点状态。
  • 每个控件都有可访问名称;每个表单字段都有关联的标签和清晰的错误提示。
  • 语义化 HTML 和地标元素,而非无意义的 div 堆叠。
  • 颜色对比度满足 WCAG AA;绝不能仅通过颜色传达含义。
  • 尊重减少动画偏好。

美观且极简——作为约束,而非感觉

  • 通过约束实现一致性。 使用设计系统的令牌——间距、字体比例、颜色比例。不要使用一次性魔数。一致性本身就是美学。
  • 现有屏幕就是样式指南。 在发明之前,先匹配已有的视觉语言。
  • 克制(UI-YAGNI)。 每个元素都需争取自己的位置;移除直到移除会破坏功能为止。层级和留白优于密集和装饰。
  • 优先使用组件库的模式,然后再构建自定义 UI。
  • 两个相似的 UI 元素 → 一个参数化组件。 差异表现为 props/变体,绝不要复制粘贴。第三次复制就是缺陷。(将 DRY 应用于界面。)

上报规则

审美决策需要上报;绝不可擅自决定。 当选择确实是美学层面的,且令牌或先例不足以确定时,请不要默默猜测:

  1. 遵循最近似的现有先例,或
  2. 提供选项(原型图、对比图),交由人类做出审美判断。

快速参考

情况做法
新组件与现有组件相似将现有组件参数化;不要复制
间距/颜色值不在令牌中使用最近的令牌;不要发明魔数
真正新颖的视觉决策提供选项上报;不要擅自决定
添加一个交互元素从一开始就确保键盘可达 + 焦點 + 可访问名称

强制执行: 在 CI 中对可检查规则进行 a11y 检查/测试(例如 eslint-plugin-jsx-a11y、axe);审美上的克制通过上报规则由审查者判断。

完整原理:参见宪法第七条,捆绑在 engineering-constitution/references/engineering-constitution.md 中。

Individual skills in this repo

This repo contains 18 individual skills — each has its own dedicated page.

lguidolin/change-hygiene-and-code-craft

Use when writing or refactoring code, structuring a commit or PR, or deciding whether to abstract duplication. Symptoms — mixing reorg with logic changes, a PR doing several things at once, a file growing large, the second copy of similar code, or unsure whether to DRY something up.

lguidolin/cloud-delivery-aks

Use when deploying to Kubernetes or Azure Kubernetes Service (AKS), configuring cloud secrets, setting up progressive rollout/canary, per-PR ephemeral environments, or k8s health probes. Keywords — Kubernetes, AKS, Key Vault, Argo Rollouts, Flagger, canary, blue-green, liveness, readiness, PodDisruptionBudget, HPA, rollback, GHCR.

lguidolin/commit-history-rewrite

Use when an existing repository has messy commit history that needs to conform to conventional commits before adopting release-please, or when intermediate WIP/fixup/merge commits need to be cleaned up.

lguidolin/conventional-commits-and-releases

Use when committing, writing a commit message, opening a PR that will be squash-merged, or configuring automated versioning/changelogs. Keywords — conventional commits, release-please, semver, feat/fix/chore, breaking change, changelog.

lguidolin/defense-in-depth-security

Use when handling untrusted input, secrets, authentication/authorization, or dependencies — or threat-modeling a new surface. Keywords — STRIDE, threat model, least privilege, secrets management, supply chain, dependency scanning, input validation, audit log, defense in depth.

lguidolin/designing-before-building

Use when starting a feature, fixing a non-trivial bug, or about to write implementation code — before any code exists. Symptoms you need this: "this is simple, I'll just code it", reaching for the editor before a design is approved, or an idea that hasn't been turned into a spec and plan.

lguidolin/engineering-constitution

Use when starting work in a project that follows the engineering constitution, orienting to its rules, or deciding which engineering practice applies to a task — spec writing, commits, testing, security, deploys, database, or UI work.

lguidolin/graphql-contract-testing

Use when writing a GraphQL query/mutation that the UI and a test will share, or building route/schema contract or smoke tests. Symptoms — copying a query into a test, a test asserting on query text, schema change that didn't break the UI build, or RLS/permission drift. Keywords — graphql-codegen, typed document, contract test, route smoke test.

lguidolin/init-repo-CI

Use when setting up a new repository with conventional commits, release-please, and CI automation, or when retrofitting an existing repository that lacks automated versioning and PR validation workflows.

lguidolin/merge-gates-and-automation

Use when setting up or changing CI, pre-push hooks, or a task runner, or deciding what must pass before merge. Symptoms — tempted to put authoritative checks only in a local hook, skip CI, bypass with --no-verify, or unsure what gates a merge vs. runs locally.

lguidolin/observability-and-slos

Use when adding logging, metrics, tracing, health checks, SLOs, or alerting — or when building a service surface that needs to be operable and debuggable. Keywords — structured logs, OpenTelemetry, correlation id, RED metrics, liveness, readiness, SLI, SLO, error budget, alerting.

lguidolin/performance-and-scale

Use when working on hot paths, list endpoints, pagination, data-access in loops, or public interfaces/schemas. Symptoms — unbounded queries, N+1 access, no latency budget, optimizing without measuring, or changing an interface many consumers depend on. Keywords — pagination, N+1, Hyrum's Law, performance budget, bundle size.

lguidolin/postgres-postgraphile-rls-and-sql

Use when writing PostgreSQL, PostGraphile config, Row-Level Security policies, SQL schema files, or working on the Browser→App→PostGraphile→Postgres data path. Keywords — RLS, SECURITY DEFINER, search_path, pgSettings, grants, roles, GraphQL depth limit, query cost, statement_timeout, SQL file organization.

lguidolin/recording-decisions

Use when a design or architecture decision has been made and needs to be captured — writing a decision record or ADR, updating a decision index, noting a deferred idea, or superseding a past decision. Keywords — ADR, decision record, rationale, rejected alternatives, dependency index.

lguidolin/resilience-and-deploy-safety

Use when planning a deploy, designing a rollback, or responding to an incident or writing a postmortem. Keywords — deploy safety, rollback, immutable artifact, progressive delivery, canary, blast radius, incident response, blameless postmortem, error budget.

lguidolin/ship-it

Use when the user wants to ship work — push, PR, archive decision records, merge, and clean up. Handles the full lifecycle from committing final changes through post-merge cleanup including converting specs/plans to compact decision records.

lguidolin/tests-as-a-control

Use when writing or modifying tests, when a test breaks during a refactor, or when testing permission/role rules. Symptoms — tempted to edit a test to make it pass, testing only the happy path, a deny-test that started passing, flaky tests, or unsure what to assert.

lguidolin/zero-downtime-migrations

Use when changing a database schema where data must survive the change — adding/removing/renaming columns, constraints, indexes, or backfilling. Symptoms — a destructive migration bundled with a code deploy, a NOT NULL column with a backfill, a table-locking UPDATE, or a rename. Keywords — expand/contract, parallel change, backfill, NOT VALID, CREATE INDEX CONCURRENTLY, graphile-migrate.

相关技能