ISA-Frontend/.claude/skills/html-template/SKILL.md

name, description

name	description
html-template	This skill should be used when writing or reviewing HTML templates to ensure proper E2E testing attributes (data-what, data-which) and ARIA accessibility attributes are included. Use when creating interactive elements like buttons, inputs, links, forms, dialogs, or any HTML markup requiring testing and accessibility compliance. Works seamlessly with the angular-template skill.

HTML Template - Testing & Accessibility Attributes

This skill should be used when writing or reviewing HTML templates to ensure proper testing and accessibility attributes are included.

When to Use This Skill

Use this skill when:

• Writing or modifying Angular component templates
• Creating any HTML templates or markup
• Reviewing code for testing and accessibility compliance
• Adding interactive elements (buttons, inputs, links, etc.)
• Implementing forms, lists, navigation, or dialogs

Works seamlessly with:

• angular-template - Angular template syntax, control flow, and modern patterns
• tailwind - ISA design system styling for visual design
• logging - MANDATORY logging in all Angular components using @isa/core/logging

Overview

This skill provides comprehensive guidance for two critical HTML attribute categories:

1. E2E Testing Attributes

Enable automated end-to-end testing by providing stable selectors for QA automation:

• data-what: Semantic description of element's purpose
• data-which: Unique identifier for specific instances
• data-*: Additional contextual information

2. ARIA Accessibility Attributes

Ensure web applications are accessible to all users, including those using assistive technologies:

• Roles: Define element purpose (button, navigation, dialog, etc.)
• Properties: Provide additional context (aria-label, aria-describedby)
• States: Indicate dynamic states (aria-expanded, aria-disabled)
• Live Regions: Announce dynamic content changes

Why Both Are Essential

• E2E Attributes: Enable reliable automated testing without brittle CSS or XPath selectors
• ARIA Attributes: Ensure compliance with WCAG standards and improve user experience for people with disabilities
• Together: Create robust, testable, and accessible web applications

Quick Reference

Button Example

<button
  type="button"
  (click)="onSubmit()"
  data-what="submit-button"
  data-which="registration-form"
  aria-label="Submit registration form">
  Submit
</button>

Input Example

<input
  type="text"
  [(ngModel)]="email"
  data-what="email-input"
  data-which="registration-form"
  aria-label="Email address"
  aria-describedby="email-hint"
  aria-required="true" />
<span id="email-hint">We'll never share your email</span>

Dynamic List Example

@for (item of items; track item.id) {
  <li
    (click)="selectItem(item)"
    data-what="list-item"
    [attr.data-which]="item.id"
    [attr.data-status]="item.status"
    [attr.aria-label]="'Select ' + item.name"
    role="button"
    tabindex="0">
    {{ item.name }}
  </li>
}

Link Example

<a
  [routerLink]="['/orders', orderId]"
  data-what="order-link"
  [attr.data-which]="orderId"
  [attr.aria-label]="'View order ' + orderNumber">
  View Order #{{ orderNumber }}
</a>

Dialog Example

<div
  class="dialog"
  data-what="confirmation-dialog"
  data-which="delete-item"
  role="dialog"
  aria-modal="true"
  aria-labelledby="dialog-title"
  aria-describedby="dialog-description">

  <h2 id="dialog-title">Confirm Deletion</h2>
  <p id="dialog-description">Are you sure you want to delete this item?</p>

  <button
    (click)="confirm()"
    data-what="confirm-button"
    data-which="delete-dialog"
    aria-label="Confirm deletion">
    Delete
  </button>

  <button
    (click)="cancel()"
    data-what="cancel-button"
    data-which="delete-dialog"
    aria-label="Cancel deletion">
    Cancel
  </button>
</div>

Common Patterns by Element Type

Interactive Elements That Need Attributes

Required attributes for:

• Buttons (<button>, <ui-button>, custom button components)
• Form inputs (<input>, <textarea>, <select>)
• Links (<a>, [routerLink])
• Clickable elements (elements with (click) handlers)
• Custom interactive components
• List items in dynamic lists
• Navigation items
• Dialog/modal controls

Naming Conventions

E2E data-what patterns:

• *-button (submit-button, cancel-button, delete-button)
• *-input (email-input, search-input, quantity-input)
• *-link (product-link, order-link, customer-link)
• *-item (list-item, menu-item, card-item)
• *-dialog (confirm-dialog, error-dialog, info-dialog)
• *-dropdown (status-dropdown, category-dropdown)

E2E data-which guidelines:

• Use unique identifiers: data-which="primary", data-which="customer-list"
• Bind dynamically for lists: [attr.data-which]="item.id"
• Combine with context: data-which="customer-{{ customerId }}-edit"

ARIA role patterns:

• Interactive elements: button, link, menuitem
• Structural: navigation, main, complementary, contentinfo
• Widget: dialog, alertdialog, tooltip, tablist, tab
• Landmark: banner, search, form, region

Best Practices

E2E Attributes

1. ✅ Add to ALL interactive elements
2. ✅ Use kebab-case for data-what values
3. ✅ Ensure data-which is unique within the view
4. ✅ Use Angular binding for dynamic values: [attr.data-*]
5. ✅ Avoid including sensitive data in attributes
6. ✅ Document complex attribute patterns in template comments

ARIA Attributes

1. ✅ Use semantic HTML first (use <button> instead of <div role="button">)
2. ✅ Provide text alternatives for all interactive elements
3. ✅ Ensure proper keyboard navigation (tabindex, focus management)
4. ✅ Use aria-label when visual label is missing
5. ✅ Use aria-labelledby to reference existing visible labels
6. ✅ Keep ARIA attributes in sync with visual states
7. ✅ Test with screen readers (NVDA, JAWS, VoiceOver)

Combined Best Practices

1. ✅ Add both E2E and ARIA attributes to every interactive element
2. ✅ Keep attributes close together in the HTML for readability
3. ✅ Update tests to use data-what and data-which selectors
4. ✅ Validate coverage: all interactive elements should have both types
5. ✅ Review with QA and accessibility teams

Detailed References

For comprehensive guides, examples, and patterns, see:

• E2E Testing Attributes - Complete E2E attribute patterns and conventions
• ARIA Accessibility Attributes - Comprehensive ARIA guidance and WCAG compliance
• Combined Patterns - Real-world examples with both attribute types

Project-Specific Links

• Testing Guidelines: docs/guidelines/testing.md - Project testing standards including E2E attributes
• CLAUDE.md: Project conventions and requirements
• Angular Template Skill: .claude/skills/angular-template - For Angular-specific syntax

Validation Checklist

Before considering template complete:

• All buttons have data-what, data-which, and aria-label
• All inputs have data-what, data-which, and appropriate ARIA attributes
• All links have data-what, data-which, and descriptive ARIA labels
• Dynamic lists use [attr.data-*] bindings with unique identifiers
• Dialogs have proper ARIA roles and relationships
• Forms have proper field associations and error announcements
• Interactive elements are keyboard accessible (tabindex where needed)
• No duplicate data-which values within the same view
• Screen reader testing completed (if applicable)

Example: Complete Form

<form
  data-what="registration-form"
  data-which="user-signup"
  role="form"
  aria-labelledby="form-title">

  <h2 id="form-title">User Registration</h2>

  <div class="form-field">
    <label for="username-input">Username</label>
    <input
      id="username-input"
      type="text"
      [(ngModel)]="username"
      data-what="username-input"
      data-which="registration-form"
      aria-required="true"
      aria-describedby="username-hint" />
    <span id="username-hint">Must be at least 3 characters</span>
  </div>

  <div class="form-field">
    <label for="email-input">Email</label>
    <input
      id="email-input"
      type="email"
      [(ngModel)]="email"
      data-what="email-input"
      data-which="registration-form"
      aria-required="true"
      [attr.aria-invalid]="emailError ? 'true' : null"
      aria-describedby="email-error" />
    @if (emailError) {
      <span
        id="email-error"
        role="alert"
        aria-live="polite">
        {{ emailError }}
      </span>
    }
  </div>

  <div class="form-actions">
    <button
      type="submit"
      (click)="onSubmit()"
      data-what="submit-button"
      data-which="registration-form"
      [attr.aria-disabled]="!isValid"
      aria-label="Submit registration form">
      Register
    </button>

    <button
      type="button"
      (click)="onCancel()"
      data-what="cancel-button"
      data-which="registration-form"
      aria-label="Cancel registration">
      Cancel
    </button>
  </div>
</form>

Remember

• Always use both E2E and ARIA attributes together
• E2E attributes enable automated testing - your QA team relies on them
• ARIA attributes enable accessibility - legal requirement and right thing to do
• Test with real users and assistive technologies - automated checks aren't enough
• Keep attributes up-to-date - maintain as code changes

---

This skill works automatically with Angular templates. Both E2E and ARIA attributes should be added to every interactive element.