Make Piggy part of the product rather than a guest in it

Piggy arrived as a chat panel bolted onto a CRM and then grew a workspace
around it. The layout was already right — the audit found the approval card
to be the best-designed object in the repo, and the account page's empty
panels less finished than anything in the workspace. What was wrong was
vocabulary: nobody had written the small things down, so both halves kept
inventing them.

Piggy was drawn with five different marks — a pig in the dock, a sparkle in
the sidebar and again on the model picker, a speech bubble on the Ask
buttons, and a stock robot glyph on every assistant message, which is the
one people look at most. There is now one mark. The composer, which is the
first control in the product since sign-in lands on /piggy, was the only
un-adapted shadcn field left: 6px radius against a 12px Send button it sat
8px from. A stat tile had been reinvented six times at three numeral scales,
and the same uppercase micro-label existed in five variants, two of them one
tab apart in the same rail. There were 63 hand-written font sizes: not a
scale, sixty-three opinions.

Underneath that, the focus ring was invisible. The global rule used
ring-accent, which Tailwind deliberately aliases onto the hover tint, so the
ring measured 1.01:1 against the light canvas — no visible focus indicator
anywhere in the product, for any accent, in either theme. It is ring-brand
now and measures 17:1. The warning, positive and info tones were darkened
until each clears 4.5:1 on a card, on inset and on its own chip, and the
light canvas moved to 98% so a card lifts without leaning on its shadow.

The mobile work is the part worth reading. A landscape phone gave the
transcript 28% of the viewport and a keyboard-up phone 16%, against a 45%
floor — and the fixed tab bar painted over the composer, covering the safety
sentence and half the Send button, because two source comments asserted the
bar stood down on short viewports and it never had. Both fixed and measured
by hit-testing rather than by screenshot. The composer itself was 64px tall
for a blank second line nobody typed, because the auto-resize effect sizes
to scrollHeight and scrollHeight counts rows — a CSS height could not win
against an inline style, so the attribute was the honest lever.

Verified across both themes driven through the app's own control: no
horizontal overflow on 15 routes at four viewports, 672 stat values that fit,
297 labels at exactly 11px/500, Escape returning focus to its opener rather
than the body on every overlay, and a rejected write no longer reporting
"Succeeded" with a green check.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

apps/web/src/components/ui/form-field.tsx

@@ -0,0 +1,66 @@
+import { cloneElement, isValidElement, useId, type ReactNode } from 'react';
+
+import { cn } from '@/lib/utils';
+import { Label } from '@/components/ui';
+
+type ControlProps = { id?: string; 'aria-label'?: string; 'aria-describedby'?: string };
+
+/**
+ * A labelled control.
+ *
+ * The id is cloned onto the *control*, never onto a wrapper: a `<label for>`
+ * pointing at a `<div>` associates with nothing, and the screen reader then
+ * reads an unlabelled input. Four copies of this wrapper existed, two of them
+ * byte-identical, and all four carried a subtler version of the same bug —
+ * they gave the control `children.props.id ?? id` while pointing the label at
+ * `id` unconditionally, so any control that already had an id of its own ended
+ * up with a label addressing an element that did not exist.
+ *
+ * The hint is wired through `aria-describedby` rather than left as loose text
+ * beneath, because a hint that only sighted users receive is not a hint, it is
+ * decoration.
+ */
+export function FormField({
+  label,
+  hint,
+  children,
+  className,
+}: {
+  label: string;
+  hint?: ReactNode;
+  children: ReactNode;
+  className?: string;
+}) {
+  const generated = useId();
+  const hintId = `${generated}-hint`;
+
+  const element = isValidElement<ControlProps>(children) ? children : null;
+  const controlId = element?.props.id ?? generated;
+
+  const control = element
+    ? cloneElement(element, {
+        id: controlId,
+        // The visible label is the accessible name via `for`/`id`; the
+        // `aria-label` is a belt-and-braces fallback for controls that render
+        // a button rather than a form element (Radix Select, for one) where
+        // `for` does not always carry.
+        'aria-label': element.props['aria-label'] ?? label,
+        'aria-describedby':
+          hint == null ? element.props['aria-describedby'] : (element.props['aria-describedby'] ?? hintId),
+      })
+    : children;
+
+  return (
+    <div className={cn('flex min-w-0 flex-col gap-1.5', className)}>
+      <Label as="label" htmlFor={controlId}>
+        {label}
+      </Label>
+      {control}
+      {hint == null ? null : (
+        <p id={hintId} className="min-w-0 text-xs text-muted">
+          {hint}
+        </p>
+      )}
+    </div>
+  );
+}