Index of every page on this site: llms.txt
All skills
a2ui-project avatar

/coding-principles

@6bf4cc2
by A2UIa2ui-project/a2ui18k stars
1,430
Run it yourself

Enforces engineering, architecture, public API, and code quality standards distilled from human reviewer feedback across A2UI pull requests. Use when authoring new code, refactoring, addressing review feedback, or reviewing PR diffs. Don't use for release publishing or spec blueprint generation without code or PR changes.

  • 17 files
  • 75.1 KB
  • Updated 2 weeks ago
  • GitHub
Use this Skill: https://skilld.dev/gh/a2ui-project/a2ui/coding-principles

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

subskillstypescriptaccessibility-semantics.md

≈733 tokens on demand. Your agent reads this file only when SKILL.md points to it.

Subskill: Accessibility (a11y) & Semantic HTML

Activation Criteria

Activate this subskill when:

  • PR adds or updates HTML templates, interactive elements, forms, cards, icons, or buttons.
  • PR modifies accessibility attributes (aria-*, role, alt, tabindex).

Principles

1. Attach role="region" to Generic Containers with Accessibility Labels

  • Problem & Rationale: Per WAI-ARIA guidelines, screen readers ignore aria-label and aria-describedby on generic <div> containers unless the element possesses an explicit landmark role. Containers such as Card must render role="region" whenever accessibility labels are attached.
  • Reviewer Checklist:
    • Check components rendering aria-label or aria-labelledby on <div> elements.
    • Ensure role="region" is dynamically bound when an accessibility label is present.

2. Reference Target Element IDs with aria-describedby (Never Pass Raw Strings)

  • Problem & Rationale: aria-describedby accepts a space-separated list of DOM element IDs, NOT raw descriptive text. Passing text strings causes screen readers to look for nonexistent element IDs, rendering descriptions silent.
  • Reviewer Checklist:
    • Verify that aria-describedby binds to the id of an actual rendered element in the DOM.
    • For multi-item error validation, place the ID on the container wrapper rather than duplicating identical IDs across a loop.

3. Use Nullish Coalescing (??) to Preserve Explicit Empty Strings (alt="")

  • Problem & Rationale: Using logical OR (||) treats empty string "" as falsy, replacing it with fallback text. For images and icons, alt="" is the standard attribute value indicating a decorative image that must be ignored by screen readers. Replacing it with fallback text creates unwanted auditory noise.
  • Reviewer Checklist:
    • Use ?? instead of || when resolving text attributes, alt text, and ARIA labels.
    • Coalesce absent ARIA attributes to null (or nothing in Lit) so template binders omit the attribute rather than outputting empty attributes.
// WRONG: Empty string "" is falsy; decorative images get undesired fallback text
const altText = image.accessibility?.label || image.description || 'Image';

// CORRECT: Nullish coalescing preserves intentional empty string ""
const altText = image.accessibility?.label ?? image.description ?? '';

4. Guard Focus Restoration on Initial Mount

  • Problem & Rationale: Dialogs, dropdowns, or modals that manage focus must not trigger focus restoration logic when first mounted in a closed or hidden state. Stealing focus on page load disrupts keyboard navigation and screen reader users.
  • Reviewer Checklist:
    • Ensure focus restoration checks an isMounted or hasInteracted guard before attempting to restore focus to previously active elements.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 6bf4cc2. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 2 weeks ago
metadata
{
  "internal": true
}

README badge

README badge for a2ui-project/a2ui/coding-principles