bullframe.css 6.1.0 → 6.2.0

package/dist/skills/bullframe-convert/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: bullframe-convert
+description: Convert existing HTML and CSS to Bullframe CSS. Use when migrating a page off Bootstrap, Tailwind, a hand-rolled stylesheet, or an older Bullframe version, and when asked to remove custom CSS in favour of the framework.
+bullframe: '>=6.1.0 <7.0.0'
+builds: [bullframe.css, bullframe-classless.css, bullframe-utilities.css]
+requires: [bullframe-core]
+docs: ['/migration', '/utilities', '/api-reference']
+---
+
+# Convert to Bullframe
+
+<!-- bf-absent: bf-d-flex, bf-mt-3, bf-text-center, bf-card, bf-btn-primary, bf-col-md-6 -->
+
+This is advisory work, not a codemod. Read the source, rewrite the markup, and report
+what could not be mapped. Never run a blind find and replace: class names from other
+frameworks look similar to Bullframe's and are not the same.
+
+## When to use
+
+Migrating a page or component onto Bullframe, stripping custom CSS that the framework
+already covers, or upgrading markup from Bullframe v5.
+
+## Inputs to gather
+
+The HTML, the stylesheet that styles it, which framework it uses today, the target build,
+and how aggressive to be: replace the reset only, or convert the whole page.
+
+## Rules
+
+1. Work in four passes, in order: base styles, layout, utilities, leftovers.
+2. Pass 1, base. Delete the reset, normalize and base typography rules; link one
+   Bullframe build instead. Most of the deleted CSS is now element styling.
+3. Pass 2, layout. Map the page's container and grid onto `.bf-container`
+   (`--fluid`, `--break-xs|md|lg`), `.bf-row` and `.bf-col-1` … `.bf-col-12`. Per-breakpoint
+   column classes have no equivalent: collapse them to the desktop span and put the
+   breakpoint on the container.
+4. Pass 3, utilities. Map declaration by declaration against `api.json`. Never guess a
+   name from the source framework.
+5. Pass 4, leftovers. Anything with no equivalent stays as project CSS. List it. Do not
+   silently drop a rule.
+6. Upgrade the markup while you are there: a `<div class="header">` becomes `<header>`,
+   `<div class="card-title">` becomes a heading, a clickable `<div>` becomes a `<button>`
+   or `<a>`.
+7. Preserve every accessibility attribute: `alt`, `aria-*`, `for`, `id`, `lang`,
+   `scope`, `tabindex`. Add the skip link if the page lacks one.
+8. Output the converted file plus a mapping table and a residual list. The user needs to
+   see what moved and what stayed.
+
+## Name mapping
+
+Common false friends. The left column does not exist in Bullframe.
+
+| Source                          | Bullframe                                         |
+| ------------------------------- | ------------------------------------------------- |
+| `container`, `container-fluid`  | `bf-container`, `bf-container--fluid`             |
+| `row`, `col-md-6`               | `bf-row`, `bf-col-6` + `bf-container--break-md`   |
+| `d-flex`, `justify-content-end` | `bf-display-flex`, `bf-display-flex--justify-end` |
+| `mt-3`, `mb-4`                  | `bf-m-t-3`, `bf-m-b-4`                            |
+| `p-3`                           | `bf-p-3` (padding-bottom) or `bf-p-t-3`           |
+| `text-center`, `text-start`     | `bf-t-center`, `bf-t-left`                        |
+| `fw-bold`, `font-weight-bold`   | `bf-t-weight-700`                                 |
+| `text-truncate`                 | `bf-t-truncate`                                   |
+| `btn btn-primary`               | `bf-btn bf-btn--primary`                          |
+| `table table-striped`           | `bf-table bf-table--zebra`                        |
+| `visually-hidden`, `sr-only`    | `bf-sr-only`                                      |
+| `card`, `card-body`             | no equivalent: compose `<article>` with tokens    |
+| `badge`, `alert`, `navbar`      | no equivalent: semantic markup plus tokens        |
+
+Spacing steps do not translate by number. Bullframe's `1` … `4` are `0.5rem`, `1rem`,
+`2rem`, `3rem`, and the unsuffixed `.bf-m-N` sets `margin-bottom` only.
+
+## Recipe
+
+1. Inventory: list every class in the source and every rule in its stylesheet.
+2. Decide the target build.
+3. Convert the markup pass by pass.
+4. Diff the result against the original visually, not just structurally.
+5. Emit: converted file, mapping table, residual CSS with a one-line reason for each rule
+   that stayed, and a count of removed declarations.
+
+## Example
+
+[`examples/before.html`](examples/before.html) is a `div`-heavy page on a custom
+stylesheet. [`examples/after.html`](examples/after.html) is the same page converted: two
+stylesheets replaced by one, `div` wrappers replaced by landmarks, card titles promoted to
+headings, inline footer styling replaced by `.bf-t-center` and `<small>`.
+
+## Expected output
+
+The converted markup, plus the mapping table and the residual list. The converted page
+must validate and must reference only classes present in `api.json`.
+
+## Failure modes
+
+- Mechanical prefixing: `mt-3` becoming `bf-mt-3`, `d-flex` becoming `bf-d-flex`,
+  `text-center` becoming `bf-text-center`. All three are wrong.
+- Keeping per-breakpoint column classes with a `bf-` prefix.
+- Dropping rules that had no mapping instead of reporting them.
+- Losing `aria-*`, `alt` or `for` attributes during the rewrite.
+- Linking Bullframe while leaving the old framework's stylesheet in place.
+- Converting a page that only needed the utilities build, and rewriting its base styles
+  for no reason.
+- Treating a `.bf-m-N` class as all-sides margin.
+
+## Do not
+
+- Do not run a regex replace over class attributes.
+- Do not rewrite the project's own component CSS that Bullframe does not cover.
+- Do not change copy, structure or behaviour while converting styles.
+- Do not delete a rule you cannot explain.
+
+## Canonical docs
+
+- Migration from v5: <https://bullframecss.marcopontili.com/migration.md>
+- Utilities overview: <https://bullframecss.marcopontili.com/utilities.md>
+- API reference: <https://bullframecss.marcopontili.com/api-reference.md>
+- Every class and token as JSON: <https://bullframecss.marcopontili.com/api.json>

package/dist/skills/bullframe-convert/examples/after.html

@@ -0,0 +1,43 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Team · Acme</title>
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bullframe.css" />
+  </head>
+  <body>
+    <a class="bf-skip-link" href="#main-content">Skip to content</a>
+
+    <header class="bf-container bf-container--break-md bf-p-t-3">
+      <nav aria-label="Primary"><a href="/">Home</a> · <a href="/team">Team</a></nav>
+    </header>
+
+    <main id="main-content" class="bf-container bf-container--break-md bf-p-b-4">
+      <section class="bf-t-center bf-m-b-4">
+        <h1>The people behind Acme</h1>
+        <p class="bf-lead">Twelve engineers, three time zones, one release train.</p>
+        <p><a class="bf-btn bf-btn--primary" href="/jobs">See open roles</a></p>
+      </section>
+
+      <section class="bf-row">
+        <div class="bf-col-6">
+          <article style="border: 1px solid var(--bf-gray-light); border-radius: var(--bf-spacing-sm); padding: var(--bf-spacing-xl)">
+            <h2 class="bf-m-t-0">Engineering</h2>
+            <p class="bf-m-b-0">Ships the product and keeps the pipeline green.</p>
+          </article>
+        </div>
+        <div class="bf-col-6">
+          <article style="border: 1px solid var(--bf-gray-light); border-radius: var(--bf-spacing-sm); padding: var(--bf-spacing-xl)">
+            <h2 class="bf-m-t-0">Support</h2>
+            <p class="bf-m-b-0">Answers every ticket within one business day.</p>
+          </article>
+        </div>
+      </section>
+    </main>
+
+    <footer class="bf-container bf-container--break-md bf-t-center bf-p-b-4">
+      <p class="bf-m-b-0"><small>© 2026 Acme</small></p>
+    </footer>
+  </body>
+</html>

package/dist/skills/bullframe-convert/examples/before.html

@@ -0,0 +1,44 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Team · Acme</title>
+    <link rel="stylesheet" href="/css/reset.css" />
+    <link rel="stylesheet" href="/css/site.css" />
+  </head>
+  <body>
+    <div class="page-wrap">
+      <div class="header">
+        <div class="nav-links"><a href="/">Home</a> <a href="/team">Team</a></div>
+      </div>
+
+      <div class="container">
+        <div class="hero text-center mt-4">
+          <div class="hero-title">The people behind Acme</div>
+          <p class="lead-text">Twelve engineers, three time zones, one release train.</p>
+          <a class="btn btn-primary" href="/jobs">See open roles</a>
+        </div>
+
+        <div class="row mt-5">
+          <div class="col-md-6">
+            <div class="card">
+              <div class="card-title">Engineering</div>
+              <p class="card-text">Ships the product and keeps the pipeline green.</p>
+            </div>
+          </div>
+          <div class="col-md-6">
+            <div class="card">
+              <div class="card-title">Support</div>
+              <p class="card-text">Answers every ticket within one business day.</p>
+            </div>
+          </div>
+        </div>
+
+        <div class="footer mt-5" style="text-align: center; color: #666; font-size: 14px">
+          <p>© 2026 Acme</p>
+        </div>
+      </div>
+    </div>
+  </body>
+</html>

package/dist/skills/bullframe-core/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: bullframe-core
+description: Core conventions for writing HTML styled with Bullframe CSS. Use before any other Bullframe skill, and whenever choosing a build, scaffolding a page, theming with tokens, or deciding whether to write custom CSS.
+bullframe: '>=6.1.0 <7.0.0'
+builds: [bullframe.css, bullframe-dark.css, bullframe-system-default.css, bullframe-classless.css, bullframe-classless-dark.css, bullframe-classless-system-default.css, bullframe-utilities.css]
+requires: []
+docs: ['/getting-started', '/variables', '/theming', '/api-reference']
+---
+
+# Bullframe core conventions
+
+<!-- bf-absent: bf-col-md-6, bf-col-sm-12, bf-d-flex, bf-mt-3, bf-text-center, bf-card -->
+
+Bullframe is one stylesheet of plain CSS. No build step, no JavaScript, no components to
+import. It styles semantic HTML, then adds `.bf-*` utilities on the class-based builds.
+
+Read [`_shared/conventions.md`](../_shared/conventions.md) and
+[`_shared/builds.md`](../_shared/builds.md) alongside this file. They hold the rule list
+and the build table this skill applies.
+
+## When to use
+
+Any task that writes or edits HTML in a project that links Bullframe. Every other
+Bullframe skill assumes these rules.
+
+## Rules
+
+1. Link exactly one base build. Two base builds cascade over each other and produce
+   wrong colours in dark mode.
+2. Do not invent classes. Check `api.json` (shipped at
+   `node_modules/bullframe.css/dist/skills/api.json`, published at
+   <https://bullframecss.marcopontili.com/api.json>). 179 classes, 47 tokens, and nothing
+   else exists.
+3. Prefer the element over the class. `<button>` is already styled; `.bf-btn` is for
+   links that must look like buttons and for buttons that need the framework's chrome.
+4. Prefer a utility over a declaration. Before writing `style="margin-bottom: 2rem"`,
+   use `.bf-m-b-3`.
+5. Prefer a token over a literal. `var(--bf-gray-light)`, not `#ccc`; the dark builds
+   rebind those tokens, a literal does not follow.
+6. Keep custom CSS in one project stylesheet, loaded after Bullframe, and confine it to
+   `:root` token overrides plus genuinely project-specific rules.
+7. The root font-size is `62.5%`, so `1rem` is about `10px`. `--bf-body-font-size-rem` is
+   `1.6rem`, which renders as 16px.
+
+## Page scaffold
+
+Class-based, light. Every generated page starts here.
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Page title</title>
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bullframe.css" />
+  </head>
+  <body>
+    <a class="bf-skip-link" href="#main-content">Skip to content</a>
+    <main id="main-content" class="bf-container bf-container--break-md">
+      <h1>Page title</h1>
+      <p class="bf-lead">One sentence that says what this page is for.</p>
+    </main>
+  </body>
+</html>
+```
+
+Classless, same page:
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Page title</title>
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bullframe.css/dist/css/bullframe-classless.min.css" />
+  </head>
+  <body>
+    <main>
+      <h1>Page title</h1>
+      <p>One sentence that says what this page is for.</p>
+    </main>
+  </body>
+</html>
+```
+
+There is no skip link on a classless build: `.bf-skip-link` is not in that stylesheet.
+
+## Layout
+
+`.bf-container` caps width at `114rem` and adds gutters. `.bf-container--fluid` is full
+width. `.bf-row` is a flex row with negative gutters, `.bf-col-1` … `.bf-col-12` are
+twelfths.
+
+```html
+<main id="main-content" class="bf-container bf-container--break-md">
+  <section class="bf-row">
+    <div class="bf-col-8">Main column</div>
+    <div class="bf-col-4">Sidebar</div>
+  </section>
+</main>
+```
+
+Columns in one row sum to 12 or less. Responsiveness is a container modifier:
+`--break-xs` stacks below 576px, `--break-md` below 768px, `--break-lg` below 992px.
+Use `--break-md` unless there is a reason not to.
+
+## Theming
+
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bullframe.css" />
+<style>
+  :root {
+    --bf-blue: rgb(84 47 194);
+    --bf-blue-light: rgb(64 32 160);
+    --bf-focus-ring-color: rgb(84 47 194);
+  }
+</style>
+```
+
+That restyles links, primary buttons and focus rings across the page. Check contrast:
+the shipped blues are WCAG AA (4.5:1) on white, and a replacement has to clear the same
+bar.
+
+## Do not
+
+- Do not link `bullframe.css` and `bullframe-dark.css` together, or any two base builds.
+- Do not write `.bf-col-md-6`, `.bf-col-sm-12`, `.bf-d-flex`, `.bf-mt-3`, `.bf-text-center`
+  or `.bf-card`. None exist. The real names are `.bf-col-6`, `.bf-display-flex`,
+  `.bf-m-t-3`, `.bf-t-center`, and a card is composed markup.
+- Do not add a theme-toggle script to get dark mode; pick a `-system-default` build.
+- Do not set `outline: none` anywhere.
+- Do not reimplement the grid, the spacing scale or the type scale in project CSS.
+- Do not add a CSS framework alongside Bullframe.
+
+## Canonical docs
+
+- Getting started: <https://bullframecss.marcopontili.com/getting-started.md>
+- Variables: <https://bullframecss.marcopontili.com/variables.md>
+- Theming: <https://bullframecss.marcopontili.com/theming.md>
+- API reference: <https://bullframecss.marcopontili.com/api-reference.md>
+- Every class and token as JSON: <https://bullframecss.marcopontili.com/api.json>

package/dist/skills/bullframe-docs-page/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: bullframe-docs-page
+description: Build a documentation, article or reference page with Bullframe CSS. Use for docs, guides, changelogs, help center articles, blog posts, or any prose-first page.
+bullframe: '>=6.1.0 <7.0.0'
+builds: [bullframe-classless.css, bullframe-classless-dark.css, bullframe-classless-system-default.css, bullframe.css]
+requires: [bullframe-core]
+docs: ['/typography', '/getting-started', '/examples']
+---
+
+# Documentation page
+
+<!-- bf-absent: bf-prose, bf-article, bf-toc -->
+
+Prose is where the classless builds win. Semantic HTML with no class attributes at all
+renders as a finished document: headings, lists, tables, quotes, code blocks and figures
+are styled by element.
+
+## When to use
+
+Documentation, a guide, a changelog, a help center article, a blog post, an API page, or
+any page that is mostly text.
+
+## Inputs to gather
+
+Title, section outline, whether a table of contents or breadcrumb is needed, code sample
+languages, and the theme. Default to the classless light build and say so.
+
+## Rules
+
+1. Default to `bullframe-classless.css`. Write zero class attributes. Escalate to the
+   class-based build only when the page needs a real multi-column layout, and state why.
+2. `.bf-*` classes do not exist in a classless build. Writing them there produces
+   unstyled markup.
+3. One `<h1>`, then `<h2>` sections in order. Give every heading that is a link target an
+   `id`.
+4. The body is `<article>` inside `<main>`. A table of contents is a `<nav>` with an
+   `aria-label` and an ordered list.
+5. Code samples are `<pre><code>`. Inline code is `<code>`. Do not add a highlighter
+   unless the task asks for one.
+6. Tables carry a `<caption>` and `<th scope="col">` headers.
+7. Use `<blockquote>`, `<figure>` with `<figcaption>`, `<dl>`, `<abbr>` and `<time>` where
+   they fit. All of them are styled.
+8. A skip link needs `.bf-skip-link`, which only exists on class-based builds. On a
+   classless page, a `<main>` landmark plus ordered headings is the accessible structure.
+
+## Recipe
+
+1. Confirm the page is prose. If it needs a sidebar with independent scroll, it is a
+   layout page, not this.
+2. Emit the classless scaffold from `bullframe-core`.
+3. Breadcrumb `<nav>` in `<header>` if the page sits inside a hierarchy.
+4. `<article>` with the `<h1>`, a lead paragraph, then the sections.
+5. Table of contents as a `<nav aria-label="On this page">` with anchors matching the
+   heading ids.
+6. Close with a `<footer>` carrying the review date or edit link.
+
+## Example
+
+[`examples/docs-page.html`](examples/docs-page.html) is a complete classless page:
+breadcrumb, table of contents, code block, captioned table and a quote. It contains no
+class attribute.
+
+## Expected output
+
+An HTML file whose class attribute count is zero on the classless path, and which reads
+correctly with stylesheets disabled.
+
+## Failure modes
+
+- Reaching for `.bf-container` or `.bf-lead` on a classless build, where neither exists.
+- Wrapping every paragraph in a `<div>`.
+- Restating framework typography in a `<style>` block.
+- Heading levels chosen for size rather than structure; use `.bf-h1` … `.bf-h6` on a
+  class-based build when the visual level must differ from the semantic one.
+- A table of contents built from `<div>`s instead of a `<nav>` and a list.
+- Anchors that do not match any heading id.
+
+## Do not
+
+- Do not add a JavaScript table of contents generator for a static page.
+- Do not mix a classless build with utility classes; add the utilities sheet if you need
+  them, or move to the class-based build.
+- Do not put a skip link on a classless page; the class is not in that stylesheet.
+
+## Canonical docs
+
+- Typography: <https://bullframecss.marcopontili.com/typography.md>
+- Getting started: <https://bullframecss.marcopontili.com/getting-started.md>
+- Examples, including the classless blog: <https://bullframecss.marcopontili.com/examples>

package/dist/skills/bullframe-docs-page/examples/docs-page.html

@@ -0,0 +1,72 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Installing Fieldnote · Docs</title>
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bullframe.css/dist/css/bullframe-classless.min.css" />
+  </head>
+  <body>
+    <header>
+      <nav aria-label="Breadcrumb"><a href="/docs">Docs</a> › <a href="/docs/install">Install</a></nav>
+    </header>
+
+    <main>
+      <article>
+        <h1>Installing Fieldnote</h1>
+        <p>Fieldnote runs as a single binary. This page covers install, first run and the two configuration files it reads.</p>
+
+        <nav aria-label="On this page">
+          <h2>On this page</h2>
+          <ol>
+            <li><a href="#requirements">Requirements</a></li>
+            <li><a href="#install">Install</a></li>
+            <li><a href="#configuration">Configuration</a></li>
+          </ol>
+        </nav>
+
+        <h2 id="requirements">Requirements</h2>
+        <p>Node 20 or newer, and 200 MB of free disk space.</p>
+
+        <h2 id="install">Install</h2>
+        <pre><code>npm install --global fieldnote
+fieldnote init</code></pre>
+        <p>The <code>init</code> step writes <code>fieldnote.json</code> into the current directory and never overwrites an existing file.</p>
+
+        <h2 id="configuration">Configuration</h2>
+        <table>
+          <caption>
+            Configuration files, in load order
+          </caption>
+          <thead>
+            <tr>
+              <th scope="col">File</th>
+              <th scope="col">Scope</th>
+              <th scope="col">Wins</th>
+            </tr>
+          </thead>
+          <tbody>
+            <tr>
+              <td><code>~/.fieldnote.json</code></td>
+              <td>User</td>
+              <td>No</td>
+            </tr>
+            <tr>
+              <td><code>fieldnote.json</code></td>
+              <td>Project</td>
+              <td>Yes</td>
+            </tr>
+          </tbody>
+        </table>
+
+        <blockquote>
+          <p>A missing configuration file is not an error. Fieldnote falls back to its defaults and says so on first run.</p>
+        </blockquote>
+      </article>
+    </main>
+
+    <footer>
+      <p>Last reviewed 26 September 2026.</p>
+    </footer>
+  </body>
+</html>

package/dist/skills/bullframe-forms/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: bullframe-forms
+description: Build accessible forms with Bullframe CSS. Use when creating a contact form, login, signup, checkout, search box, filter bar, or any page with input controls.
+bullframe: '>=6.1.0 <7.0.0'
+builds: [bullframe.css, bullframe-dark.css, bullframe-system-default.css, bullframe-classless.css]
+requires: [bullframe-core]
+docs: ['/forms', '/components/forms', '/accessibility']
+---
+
+# Forms
+
+<!-- bf-absent: bf-form-group, bf-input, bf-label, bf-form-control, bf-checkbox -->
+
+Bullframe styles form elements directly. A plain `<label>` plus `<input>` is already
+sized, spaced and focus-ringed on every build, classless included. Classes appear only
+for state (`.bf-invalid`, `.bf-disabled`) and layout.
+
+## When to use
+
+Any task that adds or edits a form, a single control, or validation feedback.
+
+## Inputs to gather
+
+The field list with types and required flags, the submit label, the form action and
+method, whether the layout is stacked or two-column, and whether errors are rendered
+server-side or client-side.
+
+## Rules
+
+1. Every control has a `<label for>` whose value is the control's `id`. A placeholder is
+   not a label, and `aria-label` is a fallback for controls with no visible text, not the
+   default.
+2. Pick the narrowest input type: `email`, `tel`, `url`, `number`, `date`, `search`. It
+   changes the mobile keyboard and gives free validation.
+3. Set `autocomplete` with the standard token (`name`, `email`, `street-address`,
+   `cc-number`, `current-password`, `new-password`). Checkout and sign-in forms are the
+   main reason users abandon a page.
+4. Mark a required field with the `required` attribute. Do not use a class for it.
+5. Group related controls, especially radios and checkboxes, in `<fieldset>` with a
+   `<legend>`.
+6. Hints go in an element referenced by `aria-describedby`, not in the label.
+7. Error state is `.bf-invalid` on the control plus a message referenced by
+   `aria-describedby`. Colour alone never carries the meaning.
+8. A disabled control gets the `disabled` attribute; `.bf-disabled` is for styling
+   elements that cannot take the attribute, such as a link styled as a button.
+9. Two-column layouts use `.bf-row` with `.bf-col-*`. The form itself needs no wrapper
+   class.
+10. The submit control is `<button type="submit" class="bf-btn bf-btn--primary">`.
+
+## Recipe
+
+1. Choose the build. A form-only page on a classless build works and needs no classes;
+   any two-column layout needs the class-based build.
+2. Emit the page scaffold from `bullframe-core`.
+3. Write the form: `action`, `method`, then label and control pairs in source order.
+4. Add `fieldset`/`legend` around each radio or checkbox group.
+5. Add the submit button last, inside the form.
+6. Check every control has a label, a type and, where applicable, an autocomplete token.
+
+## Example
+
+[`examples/contact-form.html`](examples/contact-form.html) is a complete two-column contact
+page: labelled controls, a select with an empty first option, a described textarea, a
+radio fieldset, and an aside composed from tokens.
+
+## Expected output
+
+Markup where every control is labelled and typed, which passes html-validate with the
+`input-missing-label` rule set to error. No form framework, no validation library, no
+custom control CSS.
+
+## Failure modes
+
+- A placeholder standing in for a label.
+- `<div>` or `<a>` used as a submit control.
+- `outline: none` or a custom focus style that drops contrast.
+- Inventing `.bf-form-group`, `.bf-input`, `.bf-label` or `.bf-form-control`. None exist;
+  the element selectors do the work.
+- Custom checkbox and radio CSS when `src/css/utilities/form-custom-radio-checkbox.css`
+  already ships it on the class-based builds.
+- Missing `autocomplete` on address, payment and password fields.
+- A select whose first option is a real value, so the user cannot express "not chosen".
+- Client-side validation messages that replace, rather than supplement, the `required`
+  attribute.
+
+## Do not
+
+- Do not remove or restyle the focus ring; tune `--bf-focus-ring-color`,
+  `--bf-focus-ring-width`, `--bf-focus-ring-offset`.
+- Do not use `.bf-invalid` as a permanent style; it is a state.
+- Do not nest a form inside another form.
+- Do not add JavaScript unless the task explicitly asks for client-side behaviour.
+
+## Canonical docs
+
+- Forms: <https://bullframecss.marcopontili.com/forms.md>
+- Form patterns: <https://bullframecss.marcopontili.com/components/forms.md>
+- Accessibility: <https://bullframecss.marcopontili.com/accessibility.md>
+- Live examples: <https://bullframecss.marcopontili.com/examples>