division-ds 0.1.2 → 0.2.1

package/public/docs/components/footer.md

@@ -0,0 +1,397 @@
+# Footer
+
+> The bottom of a site: where else to go, one more thing to say, the small print, and the name. Link groups sit on the left and a section of your own on the right. Under them is the wordmark, as wide as the footer and cut off by its bottom edge. One nav holds every group, so a screen reader meets one navigation landmark (a labelled region it can jump to), not six.
+
+- **Best for:** The bottom of a site: link groups, a section of your own, the small print and the wordmark.
+- **Not for:** A copy of the main navigation, or the only route to a page: use Navbar.
+- Organism. Source: `src/components/organisms/footer/Footer.tsx`
+- Rendered docs page: `/components/footer`
+
+## Import
+
+```tsx
+import { Footer } from 'src/components/organisms/footer/Footer'
+```
+
+Paths are from the Division DS repository root. Installed with shadcn they start `src/division-ds/` instead of `src/` (`src/division-ds/components/...`); import them relative to your file.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `string` |  | Required. The name of the nav landmark. |
+| `columns` | `FooterColumn[]` |  | Required. Each has a title, links and an optional defaultOpen. A link can be external. The grid is laid out for up to six groups; more wrap onto extra rows. |
+| `aside` | `{ title: string; content: ReactNode }` |  | The second section, such as a sign-up form, an address or opening hours. The footer draws the title as a heading at headingLevel, with the slash. |
+| `wordmark` | `string` |  | The name, drawn across the whole width at the bottom edge. It's a string, not a node, because the footer sizes the line from its letters and uses it to name the image. |
+| `backdrop` | `ReactNode` |  | Decoration behind the wordmark. Position it with absolute inset-0. It's hidden from assistive technology (screen readers and similar tools) and takes no pointer input, so it mustn't hold content or anything focusable. |
+| `brand` | `ReactNode` |  | A small brand mark above the groups, for a footer with no wordmark. |
+| `tagline` | `string` |  | A line under the brand, or on its own above the groups. |
+| `legal` | `ReactNode` |  | The small print, such as a copyright line or a legal link. |
+| `headingLevel` | `2 \| 3 \| 4` | `2` | The level of the group headings and the aside's heading. Match the page's heading outline. |
+| `renderLink` | `(props: LinkRenderProps) => ReactNode` | `a plain anchor` | Internal links only. An external link always renders through the Link atom. Pass your router's link component here, mapping href to its own prop and passing className through. |
+| `className` | `string` |  | Merged with the root classes. Later Tailwind utilities win. The side spacing is the page gutter, --page-gutter (1rem unless a shell sets it). The wordmark and the backdrop ignore it. |
+| `ref` | `Ref<HTMLElement>` |  | The footer element. |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+export type FooterLink = { label: string; href: string; external?: boolean }
+```
+
+```ts
+export type FooterColumn = {
+  title: string
+  links: FooterLink[]
+  /** Whether this group starts open where the groups are an accordion. Ignored where they are a
+   *  grid, because nothing collapses there. @default false */
+  defaultOpen?: boolean
+}
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Store footer: four groups, a small brand and no wordmark
+
+```tsx
+const STORE_COLUMNS: FooterColumn[] = [
+  {
+    title: 'Shop',
+    links: [
+      { label: 'Replicas', href: '#replicas' },
+      { label: 'Optics', href: '#optics' },
+      { label: 'Parts', href: '#parts' },
+      { label: 'Care', href: '#care' },
+    ],
+  },
+  {
+    title: 'Support',
+    links: [
+      { label: 'Shipping', href: '#shipping' },
+      { label: 'Returns', href: '#returns' },
+      { label: 'Warranty', href: '#warranty' },
+      { label: 'Contact', href: '#contact' },
+    ],
+  },
+  {
+    title: 'Company',
+    links: [
+      { label: 'About', href: '#about' },
+      { label: 'Field notes', href: '#field-notes' },
+      { label: 'Careers', href: '#careers' },
+    ],
+  },
+  {
+    title: 'Elsewhere',
+    links: [
+      { label: 'Site finder', href: 'https://example.com/sites', external: true },
+      { label: 'Field guides', href: 'https://example.com/field-guides', external: true },
+    ],
+  },
+]
+
+const LEGAL = '© 2026 Hexline. A demo brand for this design system.'
+
+const BRAND = (
+  <span className="font-display font-bold uppercase tracking-[0.14em] text-[var(--color-text-primary)]">
+    Hexline
+  </span>
+)
+
+<Footer label="Store footer" headingLevel={4} brand={BRAND} tagline="Airsoft replicas, optics and parts." columns={STORE_COLUMNS} legal={LEGAL} />
+```
+
+### Six groups: four across, then two
+
+```tsx
+const STORE_COLUMNS: FooterColumn[] = [
+  {
+    title: 'Shop',
+    links: [
+      { label: 'Replicas', href: '#replicas' },
+      { label: 'Optics', href: '#optics' },
+      { label: 'Parts', href: '#parts' },
+      { label: 'Care', href: '#care' },
+    ],
+  },
+  {
+    title: 'Support',
+    links: [
+      { label: 'Shipping', href: '#shipping' },
+      { label: 'Returns', href: '#returns' },
+      { label: 'Warranty', href: '#warranty' },
+      { label: 'Contact', href: '#contact' },
+    ],
+  },
+  {
+    title: 'Company',
+    links: [
+      { label: 'About', href: '#about' },
+      { label: 'Field notes', href: '#field-notes' },
+      { label: 'Careers', href: '#careers' },
+    ],
+  },
+  {
+    title: 'Elsewhere',
+    links: [
+      { label: 'Site finder', href: 'https://example.com/sites', external: true },
+      { label: 'Field guides', href: 'https://example.com/field-guides', external: true },
+    ],
+  },
+]
+
+const SIX_COLUMNS: FooterColumn[] = [
+  ...STORE_COLUMNS,
+  {
+    title: 'Account',
+    links: [
+      { label: 'Sign in', href: '#sign-in' },
+      { label: 'Orders', href: '#orders' },
+      { label: 'Settings', href: '#settings' },
+    ],
+  },
+  {
+    title: 'Legal',
+    links: [
+      { label: 'Terms', href: '#six-terms' },
+      { label: 'Privacy', href: '#six-privacy' },
+    ],
+  },
+]
+
+const LEGAL = '© 2026 Hexline. A demo brand for this design system.'
+
+const BRAND = (
+  <span className="font-display font-bold uppercase tracking-[0.14em] text-[var(--color-text-primary)]">
+    Hexline
+  </span>
+)
+
+<Footer label="Six-group footer" headingLevel={4} brand={BRAND} columns={SIX_COLUMNS} legal={LEGAL} />
+```
+
+### In a narrow container: an accordion (groups that open and close), with the second group open to start
+
+```tsx
+const COMPACT_COLUMNS: FooterColumn[] = [
+  {
+    title: 'Help',
+    links: [
+      { label: 'Shipping', href: '#compact-shipping' },
+      { label: 'Returns', href: '#compact-returns' },
+    ],
+  },
+  {
+    title: 'Legal',
+    links: [
+      { label: 'Terms', href: '#terms' },
+      { label: 'Privacy', href: '#privacy' },
+    ],
+    defaultOpen: true,
+  },
+]
+
+const LEGAL = '© 2026 Hexline. A demo brand for this design system.'
+
+<div className="max-w-sm">
+  <Footer label="Compact footer" headingLevel={4} columns={COMPACT_COLUMNS} legal={LEGAL} />
+</div>
+```
+
+### With an aside: below the groups at this width, and to their right once there's 64rem (rem is a unit based on the page's text size) of room
+
+```tsx
+const STORE_COLUMNS: FooterColumn[] = [
+  {
+    title: 'Shop',
+    links: [
+      { label: 'Replicas', href: '#replicas' },
+      { label: 'Optics', href: '#optics' },
+      { label: 'Parts', href: '#parts' },
+      { label: 'Care', href: '#care' },
+    ],
+  },
+  {
+    title: 'Support',
+    links: [
+      { label: 'Shipping', href: '#shipping' },
+      { label: 'Returns', href: '#returns' },
+      { label: 'Warranty', href: '#warranty' },
+      { label: 'Contact', href: '#contact' },
+    ],
+  },
+  {
+    title: 'Company',
+    links: [
+      { label: 'About', href: '#about' },
+      { label: 'Field notes', href: '#field-notes' },
+      { label: 'Careers', href: '#careers' },
+    ],
+  },
+  {
+    title: 'Elsewhere',
+    links: [
+      { label: 'Site finder', href: 'https://example.com/sites', external: true },
+      { label: 'Field guides', href: 'https://example.com/field-guides', external: true },
+    ],
+  },
+]
+
+const LEGAL = '© 2026 Hexline. A demo brand for this design system.'
+
+const ASIDE = {
+  title: 'Visit',
+  content: (
+    <p className="font-body text-sm text-[var(--color-text-secondary)]">
+      Unit 4, Fieldside Yard. Weekdays, nine to five. Bring your replica in a bag.
+    </p>
+  ),
+}
+
+<Footer label="Aside footer" headingLevel={4} columns={STORE_COLUMNS.slice(0, 3)} aside={ASIDE} legal={LEGAL} />
+```
+
+### With a wordmark: the name is the last thing in the footer, edge to edge
+
+```tsx
+const STORE_COLUMNS: FooterColumn[] = [
+  {
+    title: 'Shop',
+    links: [
+      { label: 'Replicas', href: '#replicas' },
+      { label: 'Optics', href: '#optics' },
+      { label: 'Parts', href: '#parts' },
+      { label: 'Care', href: '#care' },
+    ],
+  },
+  {
+    title: 'Support',
+    links: [
+      { label: 'Shipping', href: '#shipping' },
+      { label: 'Returns', href: '#returns' },
+      { label: 'Warranty', href: '#warranty' },
+      { label: 'Contact', href: '#contact' },
+    ],
+  },
+  {
+    title: 'Company',
+    links: [
+      { label: 'About', href: '#about' },
+      { label: 'Field notes', href: '#field-notes' },
+      { label: 'Careers', href: '#careers' },
+    ],
+  },
+  {
+    title: 'Elsewhere',
+    links: [
+      { label: 'Site finder', href: 'https://example.com/sites', external: true },
+      { label: 'Field guides', href: 'https://example.com/field-guides', external: true },
+    ],
+  },
+]
+
+const LEGAL = '© 2026 Hexline. A demo brand for this design system.'
+
+<Footer label="Wordmark footer" headingLevel={4} columns={STORE_COLUMNS.slice(0, 2)} legal={LEGAL} wordmark="Hexline" />
+```
+
+### With a wordmark and a backdrop: a layer behind the letters, with headroom over them
+
+```tsx
+const STORE_COLUMNS: FooterColumn[] = [
+  {
+    title: 'Shop',
+    links: [
+      { label: 'Replicas', href: '#replicas' },
+      { label: 'Optics', href: '#optics' },
+      { label: 'Parts', href: '#parts' },
+      { label: 'Care', href: '#care' },
+    ],
+  },
+  {
+    title: 'Support',
+    links: [
+      { label: 'Shipping', href: '#shipping' },
+      { label: 'Returns', href: '#returns' },
+      { label: 'Warranty', href: '#warranty' },
+      { label: 'Contact', href: '#contact' },
+    ],
+  },
+  {
+    title: 'Company',
+    links: [
+      { label: 'About', href: '#about' },
+      { label: 'Field notes', href: '#field-notes' },
+      { label: 'Careers', href: '#careers' },
+    ],
+  },
+  {
+    title: 'Elsewhere',
+    links: [
+      { label: 'Site finder', href: 'https://example.com/sites', external: true },
+      { label: 'Field guides', href: 'https://example.com/field-guides', external: true },
+    ],
+  },
+]
+
+const LEGAL = '© 2026 Hexline. A demo brand for this design system.'
+
+const BACKDROP = (
+  <div
+    className="absolute inset-0"
+    style={{
+      backgroundImage: 'radial-gradient(var(--color-text-muted) 1px, transparent 1.5px)',
+      backgroundSize: '14px 14px',
+      maskImage: 'linear-gradient(to bottom, transparent, black 70%)',
+    }}
+  />
+)
+
+<Footer label="Backdrop footer" headingLevel={4} columns={STORE_COLUMNS.slice(0, 2)} legal={LEGAL} wordmark="Hexline" backdrop={BACKDROP} />
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves through each link, group by group, then into the aside. In the accordion, it moves through each group button and the links of the open groups. The wordmark and the backdrop aren't tab stops (places the Tab key lands). |
+| `Enter` | Follows the link. On a group button, opens or closes the group, and focus stays on the button. |
+| `Space` | On a group button, opens or closes the group. |
+
+## Do
+
+- Keep groups short: four to six links each, and six groups at most.
+- Set headingLevel so the headings carry on the page's outline.
+- Mark links that leave the site as external.
+- Leave the accordion closed unless one group is where most readers are heading. Then give that one defaultOpen.
+- Say the name once: a wordmark or a brand, not both.
+- Give the backdrop a still version for people who've asked for reduced motion, and pass none where it can't draw.
+
+## Don't
+
+- Don't repeat the whole navbar here.
+- Don't put the only route to a page in the footer.
+- Don't shrink the small print below 12px.
+- Don't type the slash into a title. The footer draws it, and a typed one would be read out.
+- Don't put anything under the wordmark. The footer ends on it.
+- Don't put a control, a link or anything a reader needs in the backdrop. It's aria-hidden, so a focusable element there fails axe, the automated accessibility checker (rule aria-hidden-focus).
+- Don't switch to the accordion with a JavaScript width check. The component does it in CSS, so the accessibility tree is right on the first paint and after every resize.
+
+## Anatomy
+
+- **footer**: On a real page, it's the contentinfo landmark at the top level (the region screen readers know as the page footer). The examples here sit inside <main>, so they aren't. It's a CSS container, so the two sections sit side by side based on the footer's own width, not the browser window's (the viewport).
+- **Link section**: On the left. It's a container of its own: the grid below and the switch to an accordion both measure this section, so next to an aside the groups respond to the space they really have.
+- **Brand and tagline**: Optional, above the groups. Leave brand out when there is a wordmark, since the wordmark is the name.
+- **nav**: Named by label, holding every group. It's one column while the link section is under 28rem wide (rem is a unit tied to the base text size), then two, three from 42rem and four from 48rem.
+- **Group title**: A heading in the monospaced face, in capitals, at the 11px (pixel) label size, followed by a slash. The slash is decoration and isn't part of any accessible name (the name a screen reader announces).
+- **Group title, below 28rem**: The same heading holds a button instead of text, with aria-expanded, aria-controls, a 44px height and a chevron. (ARIA, Accessible Rich Internet Applications, is a set of attributes that tell screen readers what a control does.) CSS shows one form and removes the other from the accessibility tree, the page structure screen readers read, so from 28rem up there's no button to announce.
+- **List**: Named by its title. Below 28rem a closed group's list is display: none, so it's out of the accessibility tree and out of the Tab order. Every group starts closed unless its defaultOpen says otherwise.
+- **Corner mark**: Before each link: one corner of the crosshair, 7px in size with a 1px line, in text.muted, sitting on the text baseline. When the link's hovered it takes the signal colour. It's aria-hidden, so screen readers skip it.
+- **Link**: The Link atom's quiet tone at 14px, with a 24px target. An external link says it opens a new tab.
+- **Aside**: Only with aside. A heading drawn like a group title, then whatever you pass. It sits under the link section, and moves to its right at 21rem wide once the footer is 64rem wide. It isn't a landmark, because a form inside it already is one.
+- **Small print**: In text.muted at 12px, under a hairline and above the wordmark.
+- **Wordmark**: Only with wordmark. The name in the display face, bold and in capitals, exactly as wide as the footer at every width, with its foot cut off by the bottom edge. Nothing sits under it. It's an image named by the string, so it's announced once. Its box is sized from the letters alone, so it's already at its final size before the font loads.
+- **Backdrop layer**: Only with backdrop. A layer the full width of the footer behind the wordmark, with room above the letters so it can be seen. It's aria-hidden and ignores the pointer. Its height comes from the footer's width, so the space is there before the backdrop draws.

package/public/docs/components/form-field.md

@@ -0,0 +1,216 @@
+# FormField
+
+> The label, help text and error text for one form control. They're connected so a screen reader reads all three, in that order, when the control gets focus. The atoms (the smallest components) never label themselves. This is where it happens.
+
+- **Best for:** The label, help and error for an Input, Textarea, Select, MultiSelect or QuantityStepper.
+- **Not for:** Search or RatingInput, which name themselves. Switch, Checkbox and Radio take an id and a label with htmlFor instead.
+- **Also on this page:** `ErrorSummary`
+- Molecule. Source: `src/components/molecules/form-field/FormField.tsx`
+- Rendered docs page: `/components/form-field`
+
+## Import
+
+```tsx
+import { FormField } from 'src/components/molecules/form-field/FormField'
+import { ErrorSummary } from 'src/components/molecules/form-field/ErrorSummary'
+```
+
+Paths are from the Division DS repository root. Installed with shadcn they start `src/division-ds/` instead of `src/` (`src/division-ds/components/...`); import them relative to your file.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `string` |  | The field label. Required. |
+| `help` | `string` |  | Instruction text, read out before any error. |
+| `error` | `string` |  | Sets invalid on the control and adds the error line. |
+| `required` | `boolean` | `false` | Adds the asterisk (hidden from screen readers) and the built-in required attribute on the control. That attribute is what assistive technology actually announces. |
+| `children` | `ReactElement` |  | Exactly one control: Input, Textarea, Select or QuantityStepper. A label set on a Select or QuantityStepper child is replaced by the FormField label. An id you give the control is kept (point an ErrorSummary entry at it); without one, FormField makes one up. |
+| `className` | `string` |  | Extra CSS classes, merged with the outer element's own. When two Tailwind classes clash, the later one wins. |
+| `ref` | `Ref<HTMLDivElement>` |  | Passed through to the outer element. |
+| `errors (ErrorSummary)` | `{ fieldId: string; message: string }[]` |  | What stopped the form from submitting, in the order of the fields. Each entry links to its field and moves focus there. An empty list shows nothing. |
+| `title (ErrorSummary)` | `string` | `'There is a problem'` | The heading. It's what a screen reader reads first when the form moves focus to the summary. |
+| `headingLevel (ErrorSummary)` | `2 \| 3 \| 4` | `2` | The heading level, so the summary fits the outline of headings on its page. |
+| `className (ErrorSummary)` | `string` |  | Extra CSS classes, merged with the outer element's own. When two Tailwind classes clash, the later one wins. |
+| `ref (ErrorSummary)` | `Ref<HTMLDivElement>` |  | The summary itself. A form moves focus to it after a submit that failed. |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+export type FormError = {
+  /** The id of the control to focus, the one its FormField labels. */
+  fieldId: string
+  message: string
+}
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Label only
+
+```tsx
+<div className="max-w-xs w-full">
+  <FormField label="Callsign">
+    <Input placeholder="Anvil" />
+  </FormField>
+</div>
+```
+
+### With help
+
+```tsx
+<div className="max-w-xs w-full">
+  <FormField label="Callsign" help="Four to eight letters.">
+    <Input placeholder="Anvil" />
+  </FormField>
+</div>
+```
+
+### Required, with an error
+
+```tsx
+function RequiredWithErrorExample() {
+  const [value, setValue] = useState('')
+  const [error, setError] = useState<string>()
+
+  const validate = (next: string) => {
+    if (next.length === 0) return 'Callsign is required.'
+    if (next.length < 4) return 'Use four to eight letters.'
+    return undefined
+  }
+
+  return (
+    // Field errors sit on a form's own opaque surface.base, as every form in this system does.
+    // Contrast: "accent.hostile.text on surface.base".
+    <div className="max-w-xs p-4 bg-[var(--color-surface-base)]">
+      <FormField label="Callsign" help="Four to eight letters." error={error} required>
+        <Input
+          value={value}
+          onChange={event => {
+            const next = event.target.value
+            setValue(next)
+            if (!error) return
+            if (validate(next) === undefined) setError(undefined)
+            else if (error === 'Callsign is required.' && next.length > 0) setError(undefined)
+          }}
+          onBlur={() => setError(validate(value))}
+        />
+      </FormField>
+    </div>
+  )
+}
+
+<RequiredWithErrorExample />
+```
+
+### Wrapping a Textarea
+
+```tsx
+<div className="max-w-sm w-full">
+  <FormField label="Dispatch notes" help="Visible to the whole depot.">
+    <Textarea placeholder="Depot code, and anything the next shift needs to know." />
+  </FormField>
+</div>
+```
+
+### A form with an error summary
+
+```tsx
+const RESERVE_COUNTRIES = [
+  { value: 'ro', label: 'Romania' },
+  { value: 'ie', label: 'Ireland' },
+  { value: 'de', label: 'Germany' },
+]
+
+function ReserveExample() {
+  const [country, setCountry] = useState('')
+  const [magazines, setMagazines] = useState(0)
+  const [errors, setErrors] = useState<FormError[]>([])
+  const [attempt, setAttempt] = useState(0)
+  const summary = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    if (attempt > 0) summary.current?.focus()
+  }, [attempt])
+
+  const countryError = errors.find(current => current.fieldId === 'reserve-country')?.message
+  const magazinesError = errors.find(current => current.fieldId === 'reserve-magazines')?.message
+
+  return (
+    <form
+      noValidate
+      onSubmit={event => {
+        event.preventDefault()
+        const next: FormError[] = []
+        if (!country) next.push({ fieldId: 'reserve-country', message: 'Choose a country.' })
+        if (magazines < 4) next.push({ fieldId: 'reserve-magazines', message: 'Order at least 4 spare magazines.' })
+        setErrors(next)
+        if (next.length > 0) setAttempt(value => value + 1)
+      }}
+      className="flex flex-col gap-4 w-full max-w-sm p-5 bg-[var(--color-surface-base)]"
+    >
+      <ErrorSummary ref={summary} errors={errors} headingLevel={4} />
+      <FormField label="Country" required error={countryError}>
+        <Select
+          id="reserve-country"
+          label="Country"
+          options={RESERVE_COUNTRIES}
+          value={country}
+          onValueChange={value => {
+            setCountry(value)
+            if (value) setErrors(current => current.filter(item => item.fieldId !== 'reserve-country'))
+          }}
+        />
+      </FormField>
+      <FormField label="Spare magazines" help="Four per replica." error={magazinesError}>
+        <QuantityStepper
+          id="reserve-magazines"
+          label="Spare magazines"
+          max={40}
+          value={magazines}
+          onValueChange={value => {
+            setMagazines(value)
+            if (value >= 4) setErrors(current => current.filter(item => item.fieldId !== 'reserve-magazines'))
+          }}
+        />
+      </FormField>
+      <Button type="submit">Reserve</Button>
+    </form>
+  )
+}
+
+<ReserveExample />
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves to the control. FormField adds no keyboard stops of its own. |
+
+## Do
+
+- Pass an id to the control when something else has to point at it (an ErrorSummary entry, a link). FormField keeps an id you give it and only makes one up when you don't.
+- Keep help text to the one thing people get wrong.
+- Write the error as what to do next: 'Use four to eight letters', not 'Invalid'.
+- Check the value when someone leaves the field (on blur) or submits, not on every keystroke.
+- Wrap a Select or a QuantityStepper: FormField hands it the id, the description, the invalid state and its own label.
+
+## Don't
+
+- Don't wrap Search or RatingInput. Each is named by its own label and takes no help or error text.
+- Don't hide the help text when an error appears. That's when people need the instruction most.
+- Don't use placeholder text as the label. It disappears the moment someone types.
+- Don't show a field error on a raised panel. Field errors sit on surface.base.
+
+## Anatomy
+
+- **Label**: A real label element that points at the control's id. Monospaced, 11px (pixels), uppercase.
+- **Required mark**: A signal-orange asterisk that screen readers skip (aria-hidden). Assistive technology, such as screen readers, announces the built-in HTML required attribute instead.
+- **Control**: The single child, copied with id, aria-describedby, invalid and required added. aria-describedby is an ARIA (Accessible Rich Internet Applications) attribute that links the control to its help and error text.
+- **Help**: Optional. Read out first.
+- **Error**: Optional. Read out after the help, with an icon so the error isn't shown by colour alone. It isn't a live region, so it isn't announced the moment it appears.