agemon 0.1.0 → 6.3.0

package/assets/skills/design/agemon-design/references/finish-bar.md

@@ -0,0 +1,243 @@
+# Finish Bar
+
+Ten finishing passes, each with measurable criteria. Run before shipping. Gated to `CRAFT_LEVEL ≥ 8`, or when the user asks for a full pre-ship pass. The point is not more rules — each pass surfaces a class of failure the others can't catch. Passes share no blind spots by design.
+
+---
+
+## How to Run the Bar
+
+Run passes in order. Earlier passes (hierarchy, type system, surface stack) are foundational — changing them after later passes would invalidate findings downstream. Sequence is not arbitrary.
+
+For each pass: collect findings, assign severity (Critical / Major / Minor), then fix or defer with a written reason. "Defer" without a reason is not a defer, it's a skip.
+
+**Done** means each pass returns zero Critical and zero Major findings. Minor findings are explicitly accepted — write them down and ship anyway, or address them. Unwritten Minor findings are ignored findings.
+
+Time budget: one screen with a single primary action takes 15–30 minutes. A full multi-screen flow takes hours. Don't try to run the bar on the whole app at once — run it on a vertical slice, ship, repeat.
+
+The bar is opinionated about what matters. When a pass conflicts with a recorded project decision (e.g., the project deliberately uses dense data tables that violate Pass 4's spacing rhythm), the pass yields. Cite the principle in `brief.md` that overrides. If no brief principle covers it, the conflict is a finding, not a defer.
+
+---
+
+## Pass 1 — Hierarchy
+
+**Goal:** the surface resolves to one primary thing on first glance. The rest reads as supporting.
+
+**Criteria:**
+- Squint test passes: blur the screen or squint for 200ms. One element dominates. (Perceptual basis in `layout.md` — Squint Test section.)
+- Primary / Secondary / Tertiary / Quaternary named explicitly for this surface before touching pixels. Write them down.
+- Adjacent hierarchy levels differ by ≥1.5× in at least one signal: size, weight, contrast, surface area, or position.
+- One focal point per viewport. Two elements at the same visual weight means one is wrong.
+- Navigation, footers, and sidebars sit below content in perceived weight — they are infrastructure, not content.
+
+**How to verify:** apply `filter: blur(8px)` in DevTools or squint physically. If the layout reads as a flat field of similar shapes, hierarchy failed. If two things fight for dominance, name which one wins and why; the loser gets demoted.
+
+**When it doesn't apply:** purely transactional confirmations (a single action + summary) legitimately collapse to two levels — the action versus everything else. That's correct.
+
+---
+
+## Pass 2 — Type System
+
+**Goal:** typography is a system, not a collection of styles that happen to coexist.
+
+**Criteria:**
+- ≤3 font weights in the visible viewport. More signals indecision, not richness.
+- Tabular numerals on every cell, badge, or display element containing numerical data (`font-variant-numeric: tabular-nums`).
+- OpenType features active where the font supports them: discretionary ligatures off in UI, contextual alternates on for serif headlines, kerning always on.
+- Prose body line-length: 50–75 characters. UI labels, badges, and tables are exempt.
+- Letter-spacing scoped per role: Latin sans-serif display tightens at large sizes; small utility labels widen. Never adjust CJK or Arabic spacing — those scripts have their own optical metrics.
+- One body face, optionally one display face, optionally one mono. No fourth face.
+
+**How to verify:** grep rendered `font-weight` declarations on the surface — count distinct values. Inspect numbers in DevTools computed styles for `font-variant-numeric`. Measure a prose container by pasting its text into a character-count tool.
+
+**When it doesn't apply:** single-screen experiences with no prose (a confirmation dialog, a product card) skip the line-length criterion. The weight and numeral criteria still apply.
+
+---
+
+## Pass 3 — Surface Stack
+
+**Goal:** at least three distinguishable elevation levels, both modes intentional.
+
+**Criteria:**
+- Canvas, raised, and overlay surfaces are visually distinct: ≥2% luminance delta in light mode, ≥4% in dark mode.
+- Semantic naming in tokens: `--surface-canvas`, `--surface-raised`, `--surface-overlay` (or equivalent). No unnamed magic values.
+- Dark mode surfaces are not inverted light primitives. Canvas in dark sits at a near-black with a hue tint — not `#000000`. Raised surfaces add luminance, not just reduce it.
+- `color-scheme` declared so native form controls follow the mode.
+- Shadows fall back to border tints in dark mode where shadow-on-dark loses effect. A 10% opacity drop shadow on a near-black background is invisible — replace it.
+
+**How to verify:** render side-by-side in both modes. Toggle rapidly. Dark should not look like a photo-inverted version of the light surface — it should look like a deliberate reinterpretation. Cross-ref the intentional-dark test in `tokens.md`.
+
+**When it doesn't apply:** single-mode embedded UIs (a terminal panel, an e-ink reader context) where dark mode is not a product requirement.
+
+---
+
+## Pass 4 — Spacing Rhythm
+
+**Goal:** within < between < section, at every nesting level without exception.
+
+**Criteria:**
+- Every spacing value comes from the token scale. No arbitrary px values. (`layout.md` — Spacing Rhythm section.)
+- The rhythm invariant holds at every nesting level: label 4px above its input, inputs 16px apart within the form, form 48px from the next section. Check three nesting levels minimum.
+- Section breaks are ≥2× the inter-block spacing. If they are not, sections blur into blocks.
+- Optical adjustments noted explicitly: icon vertical nudge to optical center, modal vertical offset for visual weight. Document these as intentional, not accidents.
+
+**How to verify:** scroll the surface slowly. At each nested group, check that the surrounding space is visibly larger than the internal space. If you cannot tell which level you are in from spacing alone, the rhythm broke.
+
+**When it doesn't apply:** dense data tables and command palettes deliberately compress. The proportion still holds — the absolute values shrink. Never collapse two adjacent levels to the same value regardless of density.
+
+---
+
+## Pass 5 — Iconography
+
+**Goal:** one icon family, stroke weight matched to type, geometry coherent across the surface.
+
+**Criteria:**
+- Single icon family throughout the surface. No mixing families from different systems.
+- Icon stroke weight visually matches body type weight: 1.5px stroke for `font-weight: 400`, 2px for 500. Mismatched weights read as elements from different UIs.
+- Icon-to-type size ratio is consistent: if a 24px icon appears beside a 16px label, that ratio holds throughout. A 20px icon beside a 16px label elsewhere is a finding.
+- Container shape is one of: circle, rounded square, squircle. Chosen once, held throughout. No surface where some icons have circle containers and others have rounded squares.
+- No non-icon characters standing in for designed icons anywhere outside user-generated content contexts.
+
+**How to verify:** collect every icon instance on the surface in a contact sheet (screenshot + arrange). They should look like siblings from one family. Any that don't match immediately is a finding. Cross-ref `inspiration.md` — "What Mature Interfaces Never Do" section.
+
+**When it doesn't apply:** emoji as user content (chat reactions, message-thread rosters) are content, not icons — they are exempt from family and stroke criteria.
+
+---
+
+## Pass 6 — State Coverage
+
+**Goal:** every state designed, not defaulted or missing.
+
+**Criteria — all eight states must have explicit designs:**
+- **Idle** — the resting state is intentional, not just the absence of everything else.
+- **Loading** — skeleton matches the final layout geometry; shown after ~200ms to avoid flash on fast connections.
+- **Empty** — one line explaining why it's empty + one primary action. Never "No items found" with no next step.
+- **Error** — inline, actionable: what failed + what the user does next. Never a modal for a recoverable field error.
+- **Success** — visible beyond color change: icon swap, position shift, or explicit confirmation text.
+- **Partial** — unknown values rendered as em-dash; never `null`, `N/A`, or `0` for a value that isn't actually zero.
+- **Conflict** — concurrent-edit or stale-data scenarios handled with explicit UI, not silent overwrites.
+- **Offline** — skeleton persists past the loading timeout with an affordance that explains the surface is stale.
+
+**How to verify:** write the eight state names on paper. For each interactive surface, mark which states have explicit designs. Unmarked states are Critical findings. Cross-ref `state-design.md`.
+
+**When it doesn't apply:** read-only static surfaces (an embedded widget, a printed report) genuinely have only idle and loading. Conflict and offline states are not applicable.
+
+---
+
+## Pass 7 — Motion Tuning
+
+**Goal:** every transition is purposeful, sub-400ms for UI, and motion-gap-clean.
+
+**Criteria:**
+- UI transitions use the duration scale's transition band: 100–400ms. Nothing outside this range for interactive state changes.
+- Easings have perceptual basis: no `linear` for spatial motion, no symmetric `ease-in-out` on hover — spatial motion should ease out. (Cross-ref `motion.md` — Duration and Easing Scale.)
+- Motion-gap audit clean: no interactive state changes that snap without a transition where the change is visually significant (appearance, disappearance, repositioning).
+- Reduced-motion contract honored: `prefers-reduced-motion: reduce` collapses durations to ≤80ms or removes entrance animations entirely. The surface must be fully usable without motion.
+- Custom curves where the surface demands character. The four named CSS easing keywords are a starting point, not a destination.
+
+**How to verify:** trigger every interactive state in sequence and watch the transitions. Anything that snaps where a transition is expected is a Pass 7 Critical. Verify `prefers-reduced-motion` in DevTools by emulating the media feature.
+
+**When it doesn't apply:** static surfaces with no state changes have no motion to audit. Skip the motion-gap pass, but the reduced-motion contract still applies if any CSS animation exists.
+
+---
+
+## Pass 8 — Microcopy Voice
+
+**Goal:** every string has voice, specificity, and a single author.
+
+**Criteria:**
+- Verbs consistent across primary actions throughout the surface. Pick one form and hold it.
+- No placeholder copy in production paths: no lorem ipsum, no generic names, no TODO comments, no XXX strings.
+- No generic CTAs — every call to action names the specific outcome of the action.
+- Error messages name what operation failed and offer a concrete next step. "Something went wrong" is not an error message.
+- Empty states contain exactly one primary action — not three suggestions, not a paragraph, not a link list.
+- Voice axes locked per the brief: formality, expertise level, and relationship position documented in `brief.md`. All strings on this surface should sound like the same product.
+
+**How to verify:** extract every visible string from the surface. Read each one out of context — stripped of layout and visual hierarchy. Each should still communicate clearly and sound like the same product. Cross-ref `copy.md` voice matrix and `brief.md`.
+
+**When it doesn't apply:** legal text (terms, privacy notices, regulatory copy) is locked to compliance language and exempt from product voice criteria.
+
+---
+
+## Pass 9 — Pixel Honesty
+
+**Goal:** small details match the resolution intent of the design.
+
+**Criteria:**
+- Borders use sub-pixel approaches where a hairline is intended: `border: 1px solid color-mix(in oklch, var(--text-primary) 8%, transparent)` reads as a separator; a solid `neutral-200` border reads as a structural edge. Use the right one.
+- Shadow stacks use 2–3 layers for depth perception. A single shadow at one blur value looks flat and unconvincing.
+- Corner radii vary by element role: buttons, cards, and inputs each have a distinct radius. Uniform radius on every element is an AI-template tell — the single most recognizable signal of generated UI. (Cross-ref `inspiration.md` — Reference Token Values section.)
+- Overflow handled on every text container: truncation includes a `title` tooltip, no `text-overflow: ellipsis` without a `max-width` set.
+- Icon containers use squircles where the design language calls for it — circle and rounded square are not interchangeable.
+
+**How to verify:** zoom to 200%+ and inspect details. Anything that "looks slightly off" at that zoom is a finding worth naming. The test is not whether it looks perfect at 100% — it's whether the details hold up under scrutiny.
+
+**When it doesn't apply:** utility surfaces (internal tooling, admin dashboards) where the brief explicitly records that polish is deferred in favor of completeness. The decision must be in `brief.md`, not assumed.
+
+---
+
+## Pass 10 — Data Formatting
+
+**Goal:** every number, date, and currency communicates the right thing at the right precision.
+
+**Criteria:**
+- Tabular numerals on all data display: cells, KPIs, badges, inline metrics (`font-variant-numeric: tabular-nums`).
+- Counts abbreviated where the absolute value isn't the point: `1.2k`, `3.4M`, `12.5h`. Unabbreviated where the exact value matters.
+- Relative time where the user cares about recency (`2m ago`, `yesterday`). Absolute time where provenance matters (`Mar 4, 14:32 UTC`). Never use one format everywhere — they answer different questions.
+- Currency formatted to locale. Negative values distinguished by at least two signals: sign + color, or sign + parentheses for accounting contexts.
+- Precision matches the decision granularity the user needs. A percentage to five decimal places is noise. A stock price rounded to the dollar is misleading. Match the precision to the question the number answers.
+
+**How to verify:** inspect every numeric value on the surface. For each: what question does this number answer, and is the format right for that question? A count that could be `1,248` but shows `1.2k` when the user needs the exact number is a finding. Cross-ref `dataviz.md` for number formatting in chart contexts.
+
+**When it doesn't apply:** integer-only surfaces (step counts, indices, item counts) skip currency and decimal precision criteria. Tabular numerals still apply.
+
+---
+
+## How Findings Map to Severity
+
+**Critical — block ship:**
+- Pass 1: no discernible hierarchy (flat field of equal-weight elements)
+- Pass 6: states missing explicit designs (loading, empty, or error undefined)
+- Pass 8: placeholder copy in production paths (lorem ipsum, TODO strings, generic names)
+
+**Major — fix before ship when time allows; document if not:**
+- Pass 3: surface stack incomplete or dark mode is an inverted light layer
+- Pass 7: motion-gap failures on visible state changes; `prefers-reduced-motion` contract not honored
+- Pass 9: uniform border-radius across all element types
+- Pass 2: proportional numerals on tabular data (misaligned columns, impossible to compare)
+
+**Minor — polish; ship-okay if explicitly accepted:**
+- Pass 2: single weight-count violation (four weights, not three)
+- Pass 5: icon stroke weight off by a half-unit
+- Pass 10: currency format missing locale
+- Pass 4: one spacing value that skips a token (an arbitrary 20px in an otherwise clean scale)
+
+---
+
+## When to Skip the Bar
+
+- Internal tools where `brief.md` explicitly defers polish to product completeness. The deferral must be written, not assumed.
+- Throwaway prototypes that will be discarded after a user test. If there is no brief, there is no bar.
+- Single-screen confirmation flows where only 2–3 passes have anything to evaluate. Run those passes only, note the others as N/A.
+
+The bar is a tool, not a ritual. Skipping it without recording why is the only wrong answer.
+
+---
+
+## Convergence mode
+
+When invoked under a loop preset (e.g., `visual-anti-slop` from `loops.md`), the bar re-runs from **Pass 1** after each single highest-impact fix — full, not partial (passes are order-dependent). Repeat until Done (zero Critical, zero Major) or the loop budget is exhausted. The loop controls iteration count and stop conditions; the bar supplies the evaluative lens only.
+
+---
+
+## Cross-References
+
+- `brief.md` — which passes can be deferred and which are non-negotiable for this product; voice axes for Pass 8.
+- `tokens.md` — Passes 3, 4, 7, and 9 require token discipline; intentional-dark test in Pass 3.
+- `layout.md` — Pass 1 (hierarchy and squint test) and Pass 4 (spacing rhythm) primary references.
+- `typography.md` — Pass 2 (type system) primary reference.
+- `motion.md` — Pass 7 (motion tuning) primary reference; duration and easing scale.
+- `state-design.md` — Pass 6 (state coverage) primary reference; state lattice.
+- `copy.md` — Pass 8 (microcopy) primary reference; voice matrix, error copy, empty states.
+- `dataviz.md` — Pass 10 (data formatting) primary reference for numeric display in chart contexts.
+- `inspiration.md` — Pass 5 (iconography) and Pass 9 (pixel honesty); "What Mature Interfaces Never Do" and Reference Token Values sections.
+- `accessibility.md` — every pass assumes a11y is satisfied at the floor. The finish bar is the ceiling, not the floor. Run `accessibility.md` first.

package/assets/skills/design/agemon-design/references/forms.md

@@ -0,0 +1,192 @@
+# Forms — System Design
+
+Holistic form design: timing, placement, progressive disclosure, multi-step flows, autosave, optimistic submit, keyboard contract, and field-specific patterns. Input labels and ARIA requirements live in `accessibility.md`; error message tone lives in `copy.md`. This file is the system that ties those tactical pieces together.
+
+---
+
+## When to Read This
+
+Read when building any form longer than 2 fields, any multi-step flow, any form with conditional logic, any surface with autosave, or any destructive confirmation. A single search input doesn't need this file; a checkout, onboarding, settings page, or record editor does.
+
+---
+
+## Input Basics
+
+Two rules that belong at the input level, before any validation or layout decision:
+
+- **Never block paste.** Full rule and rationale live in `accessibility.md`.
+- **Mobile input text sits at 16px minimum on small viewports.** Below that, Safari on iOS zooms the whole page in the moment the input gets focus, and getting back to the prior zoom level is on the user, not the page. Set 16px as the floor and size down from `sm:` breakpoints upward, never the reverse. Do not "fix" this by capping zoom in the viewport meta (`maximum-scale=1`, `user-scalable=no`) — most mobile browsers actually honor that cap, so the workaround takes the user's own pinch-to-zoom with it. That swaps a minor iOS quirk for a real WCAG 1.4.4 (Resize Text) failure.
+
+---
+
+## Validation Timing
+
+The most-botched decision in form UX. Wrong timing feels punitive; right timing feels invisible.
+
+| Trigger | When to use | When not to |
+|---------|-------------|-------------|
+| On blur | Format-checkable fields (email, URL, credit card, phone) | Required-only check — don't punish leaving a field |
+| On submit | Required fields, inter-field dependencies, server-side uniqueness | Format checks that could fire earlier |
+| Inline (as-you-type) | Password strength, character count, username availability | Email format (too noisy); most other fields |
+| On mount | Never | Ever |
+
+**Rules:**
+- Validate on blur only after the user has interacted with the field at least once. Never validate on mount — nothing is wrong yet, and red borders on a fresh form read as hostile.
+- Inline validation: debounce 300ms before showing error states. **Why:** without debounce, users see flickering error→success cycles as they type. Jittery feedback breaks the typing flow and reduces trust. 300ms is the threshold where users perceive feedback as "after I stopped" rather than "while I'm typing". (See Debounce Timings below.)
+- Server-side uniqueness checks (username, slug) show a tiny spinner in the field during the check, then a green check or red error on resolve.
+- On submit, surface ALL errors at once, not one at a time. Users want to fix everything in one pass.
+
+---
+
+## Error Placement
+
+Where error messages live on the page. Details on copy tone are in `copy.md`.
+
+- **Errors below the input; hints and help text ABOVE it.** Errors appear after typing, so below-field placement follows reading order. Hints are needed *while* typing — below the field they get covered by autofill menus and the mobile keyboard; above the field they stay visible.
+- **Red border on the input itself**, plus message, plus icon (`⚠` or field-specific). Color alone fails WCAG and color-blind users — pair color with shape/text.
+- **Scroll to first error on submit** if not in view. Focus it so screen readers announce it immediately.
+- **Summary at the top is additive, not a replacement.** For long forms, an aria-live summary box ("3 fields need attention") helps — but every field still has its own inline error.
+
+---
+
+## Field Layout
+
+- **Single column.** Multi-column forms break downward momentum, create fill-order ambiguity, and screen-magnifier users miss the second column entirely. Exception: short, intrinsically paired fields (MM/YY + CVC) sit side by side.
+- **Labels above inputs, within ~16px.** Top labels eliminate the zig-zag eye path of side labels; more distance than that and the label detaches from its field.
+- **Selection widgets by option count:** 2-5 → radios or segmented control, stacked vertically (horizontal invites mis-taps); 6-10 → radios if vertical space allows, dropdown if tight; >10 → autocomplete/type-ahead; huge taxonomies (1000+ occupations) → cascade two fields (category → item) to avoid choice paralysis. Numeric nudges → stepper with horizontal +/- and 48px targets, never a dropdown of numbers.
+- **Checkbox vs toggle:** checkbox = applies on submit; toggle = applies immediately. Label checkboxes positively ("Allow automatic updates", never "Don't allow…") — test by replacing the checked box with "yes": the sentence must still make sense.
+- **Submit button aligns with the fields' left edge** in stacked forms — the eye travels straight down the column and lands on it. Exception: single inline field (search, newsletter) → button attached to the field's right.
+- **Never remove an error until the user changes the field.** Clearing it on re-focus without re-validation hides the problem.
+
+---
+
+## Progressive Disclosure
+
+Show fields only when relevant. A form with 20 visible fields reads as homework; the same form with 6 visible and 14 revealed-on-relevance feels considerate.
+
+- **Conditional fields appear smoothly** — use a 200ms height/opacity transition (`interpolate-size: allow-keywords` enables height-to-auto), not a pop-in. See `modern-css.md`.
+- **Group related fields under a shared section header** — billing address separate from shipping address separate from payment.
+- **Optional fields behind a "More options" toggle** if there are more than 2. Most users don't need them; showing them upfront adds cognitive load for no gain.
+- **Never make users guess which fields are required.** Two valid schools: mark only the optional minority with "(optional)" (lighter), or mark both — asterisk on required plus "(optional)" (most explicit; favors scanners and screen-reader users). Pick per audience and form length — but never rely on intro text ("all fields required unless noted"): users scan forms, they don't read preambles. If you use asterisks, they're black/neutral, never red — red is reserved for error states. Skip marking entirely in single-field familiar forms (login, newsletter).
+- **Field width hints at expected content length** — postal code and CVC narrow, full name and address wide. Uniform full-width fields discard a free affordance.
+- **Inputs sit on solid surfaces** — never semi-translucent fills over imagery; legibility collapses for low-vision users and in bright ambient light.
+- **Mobile multi-step forms: max 5-7 fields per step.** **Why:** Hick's Law — decision time grows logarithmically with options on-screen, and mobile reading width amplifies the effect. Forms longer than 7 fields exceed the page-scanning time (~7 seconds) before the user begins typing. Desktop tolerates higher density when the form has a clear scan structure (left-aligned labels, grouped fieldsets).
+- **Conditional reveal is one-way** until submit — don't hide a field the user has filled, even if the condition changes. Instead, disable it with a note.
+
+---
+
+## Multi-Step / Wizard Patterns
+
+When a form is too long for one screen, or the steps represent logical phases (account → plan → payment → confirm).
+
+- **Progress indicator.** Numbered steps + current/total + short label per step. Not just "Step 3 of 5" — "Step 3 of 5: Payment."
+- **State the cost upfront.** "3 steps, about 2 minutes, you'll need your ID" before step 1 — unknown length is why users abandon at step 2.
+- **Order steps easy → hard.** Name and email before payment details: early wins build completion momentum; opening with the hardest ask maximizes abandonment.
+- **Back button always available.** Moving back preserves all state; never re-fetch or reset.
+- **Prefer an always-enabled "Next" that validates on press.** A disabled button can't say why it's disabled, gives no feedback when pressed, and is invisible to some assistive tech. If you do gate, the explanation must be visible inline — never tooltip-only, never silent.
+- **Save draft automatically** between steps. See Autosave below.
+- **Resume on return.** If the user leaves and comes back, restore to the last completed step, not step 1.
+- **Review step before final submit.** Summary of all entries grouped by section, with an "Edit" link per section that jumps back to that step and returns. Users catch their own errors cheaper than servers do.
+- **Never more than ~5 steps.** See Miller's Law in `heuristics.md` — beyond 5, the user loses the map.
+
+---
+
+## Save-Draft / Autosave
+
+For any form that takes longer than ~30 seconds to fill.
+
+- **Autosave debounce: 1-2s** after the last keystroke across the form, not per keystroke. (See Debounce Timings below.)
+- **Visible "Saved" indicator with timestamp** — "Saved 2s ago" near the fields, quiet typography. Match `copy.md` restraint: "Saved" beats "Your draft has been saved successfully!"
+- **Network loss.** Show "Reconnecting… Your draft is safe locally" and queue the save. When back online, sync and update the indicator.
+- **Conflict resolution.** If another tab or user edited the same resource, offer "Keep mine / Keep theirs / Merge." See `state-design.md` for the conflict-state pattern.
+- **Never show a spinner for autosave.** The whole point is invisibility. A check mark or timestamp is enough.
+
+---
+
+## Debounce Timings
+
+Two debounces, two purposes:
+
+- **Validation debounce: 300ms.** Triggers after the user pauses typing in a field. Prevents flicker; lets the user see the field's final state before judging it.
+- **Autosave debounce: 1-2s.** Triggers after the user pauses across the form. Reduces network cost; lets the user settle on a value before persisting.
+
+These never share the same timer. Validation runs per-field; autosave runs per-form.
+
+---
+
+## Optimistic Submit
+
+Forms that look instant. Use for low-risk writes (likes, toggles, comment posts, small field edits).
+
+- **Show success state immediately on submit** — don't wait for server ack.
+- **Roll back with a clear undo prompt if the server rejects.** "Couldn't save — undo or retry?" Never silently revert.
+- **Queue on offline; sync on reconnect** with a visible indicator.
+- **Never double-submit.** Disable the button OR swap its label to "Sending…" with a spinner inside. Both — belt and suspenders.
+- **Non-optimistic submits** (payments, destructive actions, high-stakes writes) — always wait for server confirmation before showing success.
+
+---
+
+## Keyboard Affordances
+
+Basics most forms miss. The keyboard contract is non-negotiable on any form a user will fill more than once.
+
+- **Enter submits from any single-line input.** Textareas get `Cmd/Ctrl + Enter` for submit; plain Enter inserts a newline.
+- **Tab order matches visual order.** No DOM-order surprises. Never `tabindex > 0` to hack the order — fix the DOM.
+- **Submit button is focus-reachable** without `tabindex` tricks.
+- **Escape closes form modals** and prompts a "Discard changes?" if the form is dirty.
+- **Autofocus the first field on form open** — but with caveats on mobile (may trigger the keyboard to pop up before the user sees the form). Test on real devices; consider autofocus only on desktop.
+- **Cmd/Ctrl + S saves** on long-form editors. Common expectation from native apps.
+
+---
+
+## Field-Specific Patterns
+
+The fields that AI-generated forms get wrong.
+
+| Field | Pattern |
+|-------|---------|
+| Phone | Country code picker + mask + formatted display. Store E.164 internally; display local format ("(415) 555-1234") |
+| Date | Prefer native `<input type="date">` where UX is tolerable. For ranges or complex pickers, a dedicated accessible component |
+| Time zone | Pre-fill from browser (`Intl.DateTimeFormat().resolvedOptions().timeZone`); let user override; display user-facing name ("9:00 AM PT") not IANA ID |
+| Credit card | Autoformat with a space every 4 digits; detect brand from first digits; move focus to expiry when card number is valid |
+| Currency | Format per locale via `Intl.NumberFormat`; never let users type the currency symbol — render it as a prefix affordance |
+| Password | Show/hide toggle (eye icon + `aria-label`). Strength indicator relative, not absolute. Skip the "1 uppercase, 1 number, 1 special" dance unless compliance requires it — long is better than complex |
+| Magic link | "Check your email" state with explicit "Didn't receive? Resend in 30s" countdown; cooldown visible |
+| File upload | Drag-and-drop with dashed border indicator on drag-over; per-file progress (bar + filename + size + cancel); per-file retry on failure; `accept` hints + descriptive copy ("PDF, PNG, JPG up to 10MB") |
+
+---
+
+## Destructive Actions Inside Forms
+
+Deleting accounts, subscriptions, workspaces, or data from within a settings form.
+
+- **Separate section** — a "Danger zone" block, visually distinct, at the bottom. Never primary-button-style for the delete action; Cancel is the primary.
+- **Type-to-confirm** for irreversible deletions: require the user to type the resource name.
+- Copy tone and confirmshaming rules: see `copy.md` — Banned Patterns (Dark UX).
+
+---
+
+## Anti-Patterns
+
+Form sins that invalidate the rest of the work:
+
+- **Placeholder as the only label.** Disappears on focus → user forgets what the field was. Accessibility and memory fail.
+- **Red required asterisks, or marking convention explained nowhere.** Red is the error color — a field can't be "in error" before the user touches it. Asterisks are black; the marking scheme is self-evident or legended. See Progressive Disclosure for the optional-vs-required marking decision.
+- **Red validation on mount.** Nothing is wrong yet — don't punish arrival.
+- **Disabled submit button with no explanation.** User can't fix what they can't see. Tooltip or inline hint explains what's missing.
+- **Clearing the whole form on one error.** Preserve every valid field; only reset the invalid one.
+- **Captcha before form submission.** Captcha runs after the user expressed intent, not before.
+- **"Are you sure?" after every step** in a wizard. Users desensitize and click through; save the confirm for the last, destructive moment.
+- **Reset button next to submit.** Users accidentally click it. Almost never worth shipping.
+- **Two password fields** ("confirm password") without a show/hide toggle. Everyone types the same typo twice.
+- **Blocking paste** on any field — especially password confirm, order IDs, credit cards. See `accessibility.md`.
+
+---
+
+## Cross-References
+
+- `accessibility.md` — ARIA, label requirements, keyboard non-negotiables, `aria-describedby` for errors.
+- `copy.md` — voice/tone across form states, reading level, locale-aware strings, inclusive language, error message tone, empty states, CTA discipline.
+- `state-design.md` — form states (idle / submitting / success / error / partial / offline); autosave conflict state.
+- `heuristics.md` — Error Prevention heuristic, Miller's Law for step counts, Tesler's Law for progressive disclosure.
+- `modern-css.md` — `interpolate-size: allow-keywords` for revealed fields, `<dialog>` for confirm modals, Anchor Positioning for inline help popovers.