Language Pack

html

RULES.md Coding conventions and standards

HTML Rules & Conventions

The standard this codebase writes HTML to. Conventional, readable, and semantic HTML5.

Boilerplate

Every standalone HTML file starts exactly like this:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Page Title</title>
  </head>
  <body>

  </body>
</html>
  • <!DOCTYPE html> is always the very first line. Nothing before it.
  • lang attribute is always present on <html>. Match the primary language of the content.
  • <meta charset> is always the first element inside <head>.

Indentation & Formatting

  • 2 spaces per indent level. No tabs.
  • Each child element is indented one level deeper than its parent.
  • Inline elements (<a>, <span>, <strong>, <em>) that contain only a short text node stay on one line.
  • Block elements always get their own line.
  • Leave one blank line between logically distinct sections at the top level of <body>. Not between every element — only between major blocks.
<!-- Correct -->
<header>
  <nav>
    <a href="/">Home</a>
    <a href="/about">About</a>
  </nav>
</header>

<main>
  <h1>Welcome</h1>
  <p>Content goes here.</p>
</main>

<footer>
  <p>&copy; 2026</p>
</footer>

Letter Case

  • All element names are lowercase: <div>, <section>, <input>.
  • All attribute names are lowercase: class, href, data-value.
  • Attribute values follow their natural case (URLs, IDs, class names as defined).

Attributes

Quoting: Always double quotes. Never single quotes. Never unquoted.

<!-- Correct -->
<input type="text" name="username">

<!-- Wrong -->
<input type='text' name=username>

Ordering: id → class → type → name → value → href or src → everything else.

<input id="email" class="field" type="email" name="email" required>
<a id="logo" class="brand-link" href="/">Home</a>
<img id="hero" class="hero-image" src="hero.jpg" alt="A mountain at sunrise">

Boolean attributes: Name only. No value.

<!-- Correct -->
<input type="checkbox" checked>
<button disabled>Submit</button>

<!-- Wrong -->
<input type="checkbox" checked="true">
<button disabled="disabled">Submit</button>

Semantic Elements

Use the element that matches the meaning of the content:

Purpose Element
Main page header / site header <header>
Primary navigation <nav>
Main content area (one per page) <main>
Self-contained content (blog post, card) <article>
Thematic grouping with a heading <section>
Tangentially related content <aside>
Page footer <footer>
Important text <strong>
Emphasized text <em>
Generic container (no meaning) <div>
Generic inline container <span>

<div> and <span> are not wrong — they are correct when there is no semantic alternative. Do not force semantics where they do not apply.

Headings

  • One <h1> per page. It describes the page's main topic.
  • Heading levels do not skip: <h1> → <h2> → <h3>. Never jump from <h1> to <h3>.
  • Do not use headings to make text large or bold. That is a CSS job.

Links

  • href always has a value. An empty href="" is not a button — use <button>.
  • Descriptive link text. Not "click here". Not "read more" alone.
  • External links that open in a new tab must include rel="noopener noreferrer".
<a href="https://example.com" target="_blank" rel="noopener noreferrer">Example Site</a>

Images

  • alt is always present.
  • Decorative images that carry no information: alt="".
  • All other images: a concise, accurate description of what the image shows.
  • width and height attributes should be set to the image's natural dimensions to prevent layout shift.
<img src="logo.png" alt="Acme Inc. logo" width="200" height="60">
<img src="divider.png" alt="" width="800" height="2">

Forms

  • Every <input>, <select>, and <textarea> is associated with a <label>.
  • Prefer explicit association (for / id) over wrapping.
  • <button type="submit"> for form submission. <button type="button"> for everything else.
  • Group related fields inside <fieldset> with a <legend>.
<form action="/login" method="post">
  <label for="username">Username</label>
  <input id="username" type="text" name="username" required>

  <label for="password">Password</label>
  <input id="password" type="password" name="password" required>

  <button type="submit">Log in</button>
</form>

Scripts & Styles

  • <link rel="stylesheet"> goes in <head>.
  • <script> goes at the end of <body>, just before </body>, unless defer or async is used — in that case it may go in <head>.
  • No type="text/css" on <link>. No type="text/javascript" on <script>. Both are the default.
  • No inline style="" attributes.
  • No inline event handlers (onclick, onsubmit, etc.).

Comments

Use comments to mark major sections or to explain non-obvious structure. Do not comment every element.

<!-- Navigation -->
<nav>
  ...
</nav>

<!-- Main content -->
<main>
  ...
</main>

Do not leave commented-out code in committed files.

Void Elements

Void elements have no closing tag and no trailing slash.

<!-- Correct -->
<br>
<hr>
<img src="photo.jpg" alt="A photo">
<input type="text">
<meta charset="UTF-8">
<link rel="stylesheet" href="styles.css">

<!-- Wrong (XHTML style — not used here) -->
<br />
<img src="photo.jpg" alt="A photo" />

Character References

  • Use &amp;, &lt;, &gt;, &quot;, &apos; when those characters appear as content or attribute values.
  • Use &copy;, &mdash;, &ndash;, &nbsp; for typographic characters.
  • Do not use &nbsp; for layout spacing. That is a CSS job.
  • Prefer UTF-8 literal characters over numeric references for everything else (accented letters, symbols).
AGENTS.md Agent behavior instructions

HTML Agent Instructions

Instructions for agents writing, reviewing, or editing HTML.

General Behavior

  • Write HTML that a competent developer would recognize as clean and conventional on first read.
  • Default to standard HTML5. Do not reach for frameworks, libraries, or templating syntax unless the surrounding codebase already uses them.
  • Never alter existing code that is outside the scope of the task. Smallest possible change.
  • When editing an existing file, match the indentation and quoting style already in use. Do not reformat the whole file.
  • When creating a new file, follow the conventions in RULES.md exactly.

Structure Tasks

When asked to create an HTML page or component:

  1. Start with the standard HTML5 boilerplate (see RULES.md).
  2. Put the correct <meta charset> and <meta name="viewport"> before anything else in <head>.
  3. Choose semantic elements first. Reach for <div> or <span> only when no semantic element fits.
  4. One logical section per <section> or <article>. Do not nest them arbitrarily.
  5. Every <img> must have an alt attribute. Write a real description, not "image" or "" unless the image is purely decorative — in that case alt="" is correct.

Attribute Behavior

  • Write attributes in this order: id, class, type, name, value, href/src, then everything else.
  • Use double quotes for all attribute values. No exceptions.
  • For boolean attributes (disabled, checked, required, readonly, selected), write the attribute name alone — no ="true" or ="".
  • Never write inline style="" attributes. Use a class instead.
  • Never write onclick="", onchange="", or any inline event handlers. Behavior belongs in a script file.

Editing Tasks

When asked to add, remove, or modify content inside an existing HTML file:

  • Preserve all existing indentation, whitespace, and comment style.
  • Do not reorganize or reorder elements that were not part of the task.
  • Do not add classes, IDs, or attributes beyond what was asked.
  • If a requested change conflicts with a rule in RULES.md, apply the rule and note the conflict in a comment directly above the changed line, then remove the comment once it is reviewed.

What Not to Do

  • Do not use deprecated elements: <font>, <center>, <b> (for emphasis), <i> (for emphasis), <strike>, <marquee>, <frame>, <frameset>.
  • Do not use <br> for spacing. That is a CSS job.
  • Do not write <table> for layout. Tables are for tabular data only.
  • Do not close void elements with a trailing slash: <br />, <img />, <input /> are not HTML5 — write <br>, <img>, <input>.
  • Do not omit required attributes (alt on <img>, lang on <html>, charset in <head>).
  • Do not write type="text/javascript" on <script> or type="text/css" on <link>. Both are the default in HTML5.
Install
mimicode install html