mcpField
S
semantic-html-first

semantic-html-first

github.com/kemiljkDevelopment6162 installsUpdated 1w ago
Repository

About semantic-html-first

semantic-html-first is a skill for interface developers that favors native HTML elements for interactions. It provides implementation and review guidance grounded in built-in keyboard, form, and accessibility behavior.

Key features

  1. 01Choose native elements for interactions
  2. 02Use ARIA to refine native semantics
  3. 03Prefer explicit element composition
  4. 04Style states with native pseudo-classes first
  5. 05Verify semantic elements in the DOM

Use cases

  1. 01Choose suitable HTML for buttons and links
  2. 02Build native disclosures or temporary overlays
  3. 03Review keyboard behavior and disabled states
  4. 04Check form submission and screen reader semantics

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/kemiljk/skills --skill semantic-html-first

After installing, type/semantic-html-firstin Claude Code to confirm it loaded.

Details

From the project README

Semantic HTML First

Semantic HTML is interface infrastructure. Native elements carry keyboard support, form participation, disabled behaviour, and accessibility semantics without a second implementation.

Defaults

  1. Start with the native element that matches the interaction.
  2. Use ARIA to refine native semantics, not to rebuild them on div/span.
  3. Prefer explicit composition over magic asChild polymorphism when it obscures the real element.
  4. Style states with native pseudo-classes (:disabled, :checked, :open, :invalid) before parallel data-* state systems.
  5. If a library primitive exists, verify it still renders a real semantic element in the DOM.

Prefer / Reject

PreferReject
<button type="button"><div onClick> / <span role="button"> without need
<a href> for navigationButton-styled divs that only route in JS
<details> / <summary>Custom disclosure with ad-hoc keyboard code
<dialog> / Popover APIModal divs fighting focus and top-layer behaviour
Native <form> controlsClickable rows that ignore Enter/Space/disabled

Decision guide

  • Performs an action: button
  • Goes somewhere: a[href]
  • Toggles visibility of related content: details or disclosure button + controlled region
  • Requires a temporary overlay task: dialog or popover
  • Collects input: native form controls inside form

Review checklist

  • Can this be a native element?
  • Tab focus works without extra code?
  • Enter/Space activate buttons?
  • Disabled state blocks interaction and exposure correctly?
  • Screen reader role matches the visual control?
  • Form controls submit/reset with the form?
  • Custom ARIA is additive, not a rewrite of the platform?

Source essays

  • On the semantic web
  • Why I built a semantic-HTML first library

Comments

Markdown supported