Imported from 0disoft/mustflow (templates/default/locales/en/.mustflow/skills/html-code-change/SKILL.md). Install upstream with npx skills add 0disoft/mustflow --skill html-code-change. Copyright stays with the author.

HTML Code Change

Purpose

Preserve semantic structure, native controls, keyboard access, focus behavior, form labeling, metadata, and browser-valid markup. Treat non-native interactive markup as suspicious by default; HTML already gives browsers, keyboards, forms, password managers, mobile input, and assistive technology a working contract.

Use When

• .html, JSX, TSX, Vue, Svelte, Astro, or template markup changes.
• The task touches layout landmarks, headings, forms, buttons, links, popovers, dialogs, menus, tabs, accordions, custom selects, composite widgets, tables, media, metadata, canonical links, Open Graph, robots, hreflang, viewport, or JSON-LD.

Do Not Use When

• Only CSS changes and markup semantics are unchanged; use css-code-change.
• The markup is generated and should be changed through a source component or template.

Required Inputs

• Existing page layout, document shell, head/SEO helpers, metadata builders, canonical URL helpers, sitemap or robots config, form components, interactive control components, and tests.
• Target framework conventions for rendering, routing, hydration, and metadata.
• Semantic structure ledger: the intended main, landmark, heading, section, article, nav, time, figure, form group, table, media, and visible-label contracts.
• Visible page content, H1 or primary title, main entity, locale, indexing intent, and data sources for title, description, image, author, date, price, rating, availability, and FAQ content when metadata changes.
• Browser-native behavior expected from the markup: navigation, form submission, validation, autocomplete, input modality, popover behavior, dialog focus, inert background handling, media sizing, lazy loading, and history integration.
• Accessibility and validation tooling declared in the command contract.

Preconditions

• Identify the document structure, interactive controls, form ownership, focus path, metadata source, and verification surface.
• Prefer native HTML elements before adding ARIA or JavaScript behavior.
• Classify every interactive element by user intent before changing markup.
• Do not edit metadata, canonical, Open Graph, robots, hreflang, or JSON-LD from a single file in isolation.

Allowed Edits

• Use semantic landmarks, headings, native links, native buttons, and native form controls where possible.
• Connect labels, help text, error text, required state, autocomplete, and input type explicitly.
• Use native validation, input modes, popovers, dialogs, details/summary, and inert behavior when they fit the intended interaction and browser target.
• Keep metadata and structured data consistent with visible page content.
• Add ARIA only when native semantics cannot express the control and the required role, state, keyboard, and focus behavior are implemented.

Procedure

1. Read the page shell, route layout, metadata helpers, component patterns, and tests before editing.
2. Check document outline, landmarks, source order, and heading levels.
3. Treat semantic HTML as a machine-readable contract, not as styling decoration. Use div for pure wrappers and styling shells.
4. Use section only for a thematic group that has a heading or explicit accessible label. Do not use section as a card, spacing, or script wrapper.
5. Use article only for self-contained content that remains meaningful when syndicated, embedded, or moved out of the list, such as posts, articles, reviews, comments, or complete product entries.
6. Use nav only for major navigation or table-of-contents regions. Do not label every incidental link group as navigation.
7. Keep exactly one active visible main region for the page or current SPA view. Do not put repeated headers, footers, sidebars, or global navigation inside the main content unless that is the actual page task.
8. Treat heading elements as content outline, not font-size controls. Preserve hierarchy by meaning, and use CSS for visual scale.
9. Classify each interactive element by intent. Navigation to a URL uses an anchor with href. Commands, toggles, submit actions, open/close actions, destructive actions, copy actions, disclosure triggers, and modal triggers use buttons.
10. Use native form controls for text entry, selection, checkbox, radio, and file input. Use grouped native radio or checkbox controls with fieldset and legend when the group label matters.
11. Keep interactive elements out of labels. Do not place terms links, help buttons, or other controls inside a label; connect the label with for and id, then place related links or buttons outside the label.
12. Treat composite widgets such as tabs, action menus, comboboxes, listboxes, trees, grids, and custom selects as high-risk. Prefer native HTML or an existing audited component; otherwise implement the complete role, state, focus, and keyboard pattern.
13. Reject clickable div or span controls, clickable icons without buttons, anchors without href, links used as buttons, nested interactive controls, positive tabindex, focusable aria-hidden content, and focus outline removal without a replacement focus style.
14. Use ARIA only when native HTML cannot express the needed semantics. Validate the role is legal for the element, the accessible name exists, required states are present, visual and ARIA states stay synchronized, keyboard behavior matches the widget pattern, and focus behavior is explicit.
15. For custom legacy button-like elements that cannot be replaced, require role, focusability, Enter activation, Space activation, Space scroll prevention, pointer activation, duplicate-event prevention, and visible focus. Use native buttons instead whenever possible.
16. For popovers, prefer the native popover pattern for lightweight anchored disclosure, teaching UI, picker panels, or menus that do not need modal focus trapping. Verify trigger ownership, light-dismiss behavior, focus behavior, accessible name, and fallback or browser target.
17. For dialogs, prefer native dialog when the project can support it. Otherwise implement focus entry, Tab and Shift+Tab containment, Escape behavior, inert or unreachable background content, visible close or cancel control, focus return, and an accessible name.
18. Do not use dialog for every overlay. Use popover for non-modal transient UI, details/summary for simple disclosure, and dialog for modal tasks or interruptions that require focus containment.
19. For tabs, use tablist, tab, and tabpanel semantics only for a real tabbed interface. Require one active tab, panel linkage, roving tabindex, arrow key movement, Home and End where expected, and Enter or Space activation when activation is manual.
20. For menus, do not use ARIA menu roles for ordinary site navigation. Site navigation is a nav landmark with links. Use ARIA menu patterns only for application-style action menus with a button trigger, expanded state, focus strategy, Escape close behavior, and focus return.
21. For forms, verify visible label association, help association, error association, required text, native required state, autocomplete, inputmode, enterkeyhint, validation timing, invalid state, error summary behavior, and submission behavior.
22. Prefer native constraint validation for simple required, type, length, pattern, range, and step rules. Add custom validation only for business rules, cross-field rules, async validation, or localized error ownership the native browser cannot express.
23. Use placeholder, title, aria-label, color, icon, or toast-only feedback only as supplementary affordances, not as the only label, required indicator, or error explanation.
24. Use time with a machine-readable datetime when the content represents a precise date, time, duration, or time-like value that tests, crawlers, calendars, or automation may need to parse.
25. Use figure and figcaption only for self-contained referenced media, code, diagrams, charts, screenshots, or examples whose caption describes the figure. Do not use figcaption for ordinary card titles or unrelated image captions.
26. Use real tables for tabular data. Include a useful caption when the table needs a name, use th for row and column headers, and set scope when it clarifies the header relationship.
27. For meaningful media, prefer img, picture, video, or framework media components that preserve alt text, intrinsic dimensions, responsive candidate selection, and browser discovery. Keep decorative media out of the accessibility tree.
28. For responsive image markup, verify width, height, srcset, sizes, picture art direction, and lazy or eager loading reflect the rendered slot. Route LCP, preload, priority, CDN, or byte-size claims to image-delivery-performance-review.
29. For metadata, read visible content and the metadata generation path first. Keep title, description, canonical, Open Graph, Twitter or X card data, robots, hreflang, and JSON-LD aligned with visible content, locale, URL, and indexing intent.
30. Structured data must describe content visible on the same page. Do not invent ratings, reviews, FAQ items, authors, prices, availability, dates, organizations, product properties, or claims not backed by the page data source.
31. Ensure every HTML page has a valid non-empty language and responsive viewport that does not disable zoom. Mixed-language passages should identify their language when needed.
32. Keep inline script and style minimal; move behavior and styling to the existing project layers unless the framework requires an inline boundary.
33. Choose configured verification intents that cover markup validity, lint, build, accessibility, route rendering, metadata, and docs when available.

Form Accessibility Rules

• Every user-editable native form control needs a persistent visible label, preferably an explicit label whose for value exactly matches the control id.
• Placeholder text, title text, aria-label, icon-only labels, and visual proximity are not substitutes for visible labels unless a strong design constraint is reported and the accessible name remains clear.
• Help text and error text must be real DOM text with stable IDs and connected through aria-describedby when relevant.
• Required native controls should use native required; the required state must also be visible in text or an explained marker. Do not rely on color alone.
• Use aria-required mainly for custom ARIA controls or deliberate compatibility needs; it does not enforce browser validation.
• Do not set aria-invalid before the user has interacted with the field or attempted submission. Set it when validation has determined the field is invalid.
• Error messages must identify what is wrong and how to fix it when the fix is known. Avoid generic text such as "Invalid" with no recovery instruction.
• Multiple submit errors should use an error summary near the top of the form or page when the project pattern supports it. Summary items should link to invalid fields, and inline errors should remain next to fields.
• Use alert or live regions only for dynamic validation or submit feedback that should be announced. Do not spam alerts on every keystroke or place interactive controls inside alerts.
• Inputs collecting information about the current user should use appropriate autocomplete tokens. Do not blindly disable autocomplete on login, checkout, contact, signup, or account forms.
• Use type, inputmode, autocomplete, enterkeyhint, min, max, step, minlength, maxlength, and pattern as contracts for keyboards, password managers, autofill, and native validation. Do not replace them with JavaScript-only parsing when the browser can enforce the basic rule.

Metadata And Structured Data Rules

Before editing page metadata, identify the rendered route, canonical production URL, visible H1 or main title, visible primary entity, locale, indexing intent, and source of page facts.

• Titles must match the visible primary topic, avoid repeated keyword stuffing, avoid stale boilerplate, and use the page's visible language.
• Descriptions must summarize the actual visible page and must not fabricate claims, guarantees, prices, ratings, dates, or features.
• Canonical URLs must be absolute production URLs for the preferred version of the same or near-duplicate content. Do not point canonical to staging, localhost, unrelated pages, wrong locale pages, redirects, 404s, noindex pages, or parameter URLs unless explicitly intended.
• Canonical, sitemap, hreflang, internal links, and social URL metadata should not contradict each other.
• Open Graph and Twitter or X title, description, URL, and image should come from the same source of truth as page metadata unless a campaign override is documented. Social images must be absolute, crawlable, and representative of the visible page.
• Prefer JSON-LD for structured data. Validate JSON syntax and ensure required properties for the chosen rich result type are present when rich-result eligibility matters.
• Robots directives such as noindex, nofollow, nosnippet, or restrictive crawl hints need explicit intent. Before removing one, check whether the page is intentionally private, duplicated, thin, internal, staged, or blocked.

Review Rejection Criteria

Reject or revise the patch when any of these appear without strong justification and verification:

• New div or span interaction where a native link, button, or form control would work.
• Anchors without href, buttons implemented as links, links implemented as buttons, nested interactive controls, clickable icons without native controls, or site navigation using ARIA menu roles.
• Decorative section, card-only article, incidental-link nav, multiple active main regions, headings chosen for visual size, labels containing nested interactive controls, or data tables rebuilt as non-table grids.
• Custom controls without complete accessible name, role, state, keyboard, focus, and hidden-content behavior.
• Popovers, dialogs, or overlays that replace native behavior without trigger, focus, light-dismiss, inert, or fallback review.
• Positive tabindex, hidden content that remains tabbable, focusable aria-hidden content, or invisible focus.
• Form controls without visible labels, placeholder-only labels, disconnected help or error text, color-only required or error state, premature aria-invalid, or autocomplete removed without reason.
• Meaningful dates without parseable time datetime, figures used for ordinary card content, tables without header relationships, or meaningful media that lacks alt, intrinsic dimensions, or responsive candidate review.
• Metadata or JSON-LD that contradicts visible content, fabricates facts, points canonical or social URL at the wrong page, disables zoom, omits page language, or accidentally noindexes a public page.

Postconditions

• Markup communicates the intended structure without relying on visual styling alone.
• Sections, articles, navigation, main regions, headings, forms, figures, tables, time values, and media expose truthful document semantics.
• Keyboard and focus behavior are preserved.
• Forms have labels and errors connected.
• Metadata and structured data reflect visible content.
• Hidden content is not reachable by keyboard when it should be inactive.
• Native controls are used unless a complete custom interaction pattern is justified.

Verification

Use configured oneshot command intents when available:

• lint
• build
• test_related
• test
• docs_validate_fast
• mustflow_check

Report missing accessibility, browser, or HTML validation intents when relevant.

When configured or manual verification is available, cover keyboard-only navigation with Tab, Shift+Tab, Enter, Space, Escape, Arrow keys, Home, and End where applicable. Confirm visible focus, accessible name, role, value, state, hidden-content behavior, form errors, metadata consistency, and structured data truthfulness.

Failure Handling

• If a custom control cannot meet keyboard and focus requirements, replace it with a native element or report the blocker.
• If metadata source of truth is unclear, inspect the framework route and SEO helpers before editing.
• If form validation timing or error ownership is unclear, keep native validation behavior and report the unresolved custom validation boundary.
• If structured data facts cannot be traced to visible content or a trusted page data source, do not add them.
• If accessibility verification is unavailable, report the manual keyboard and focus checks that remain.

Output Format

• Boundary checked
• Semantic, form, focus, and metadata notes
• Files changed
• Command intents run
• Skipped checks and reasons
• Remaining HTML risk