Communitygithub.com

介面工藝與無障礙設計

用於構建或設計 UI——元件、版面、表單、設計代碼——或做出無障礙決策。關鍵字——a11y、WCAG、鍵盤導航、焦點狀態、對比度、設計系統、極簡UI、元件重用、ARIA、語意化HTML。

介面工藝與無障礙設計 是什麼?

此技能提供一套完整的規範,確保 AI 代理在協助開發者構建使用者介面時,能產出既無障礙又美觀的程式碼。其核心原則是「設計即約束」:將抽象的「品味」轉化為可檢查的規則與升級流程,避免代理隨意猜測視覺決策。技能涵蓋四大面向:無障礙(鍵盤可達性、可見焦點、語意化 HTML、WCAG AA 色彩對比、尊重減少動畫設定)、極簡美學(強制使用設計系統代碼、遵循現有畫面、UI-YAGNI 原則、偏好元件庫)、以及最重要的升級規則——當美學選擇無法由現有規則決定時,必須提供選項交由人類決策。支援所有常見的開發平台與 AI 代理框架,並建議在 CI 中整合 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 中進行無障礙 linting/測試(例如 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.

相關技能