{"id":"e8b78ede-12f6-4cfa-ad2e-14dd859dc526","shortId":"jQSDCL","kind":"skill","title":"form-design","tagline":"Forms have three layers of guidance: helper text below the input explains what to enter, placeholder shows the expected format, and validation confirms correctness. Real-time validation for complex inputs. Submit enables only when the form is valid. Use when designing or reviewin","description":"# Form Design\n\nForms are where users give the product data. Every unnecessary obstacle between the user and a completed form is a failure. The design goal is to make correct input easy and incorrect input obvious — before the user submits.\n\n---\n\n## The Three Guidance Layers\n\nEach layer serves a distinct purpose. Do not collapse them.\n\n### Layer 1 — Helper Text\nExplains *what* to enter. Appears below the input, always visible, in small secondary text.\n\n```\nEmail address\n[ ]\nUse the email you signed up with.\n```\n\n- Write in plain language from the user's perspective\n- Keep it to one sentence — if you need more, the field is too complex or misnamed\n- Do not repeat the label (\"Enter your email\" below a label that says \"Email\" is redundant)\n- Helper text is not a replacement for a label — the label is still required\n\n### Layer 2 — Placeholder\nShows the *format* or an example value. Appears inside the input, disappears on typing.\n\n```\n[jane@example.com ]\n```\n\n- Use a realistic example, not a description: `+358 40 123 4567` not `Enter phone number`\n- Never use placeholder as a label — it disappears and leaves the user without context\n- Keep it grey (`--color-text-secondary`) and lighter than actual input text\n- Optional — not every field needs a placeholder\n\n### Layer 3 — Validation\nConfirms whether the input is correct. The most important layer.\n\n```\nEmail address\n[jane@ ] ← invalid\n✗ Enter a valid email address.\n```\n\n**Validation timing:**\n- **On blur** (leaving the field): default for most fields — validates once the user has finished\n- **Real-time** (on input): use when the format is complex or the error is likely — password strength, IBAN, VAT number, URL, regex-heavy fields\n- **On submit**: catches anything missed, scrolls to the first error\n\nReal-time validation must be forgiving at the start — do not show an error the instant the user starts typing. Show it after a short debounce (300–500ms) or after the first character that makes the input definitively wrong.\n\n---\n\n## Submit Button State\n\nThe submit button enables when the form is valid. This is one of the clearest affordance signals in form design — the user sees the goal and knows when they have reached it.\n\n```\n[Submit] ← disabled, low contrast, cursor: not-allowed\n (fields incomplete or invalid)\n\n[Submit] ← enabled, full colour, cursor: pointer\n (all required fields valid)\n```\n\n**Implementation:**\n```html\n\n```\n\nFor long or complex forms where real-time validation is not practical, do not disable the submit — validate on submit and scroll to errors instead. Disabled submit on a long form frustrates users who cannot tell what is missing.\n\n**Loading state on submit:** Replace label with spinner, disable the button. Prevent double-submission.\n\n---\n\n## Field Anatomy\n\n```\n[Label] [Optional badge if optional]\n[Input field ]\n[Helper text — what to enter, format, constraints ]\n[Error message — appears below helper text on validation fail ]\n```\n\n```html\n
\n \n \n
Finnish VAT numbers start with FI followed by 8 digits.
\n
Enter a valid Finnish VAT number (e.g. FI12345678).
\n
\n```\n\n---\n\n## Required vs Optional\n\nMark the minority. If most fields are required, mark the optional ones. If most are optional, mark the required ones.\n\n- Do not rely on colour alone — add a text label (\"Required\" or asterisk with legend)\n- Place the required/optional indicator in the label, not only in the placeholder or helper text\n\n```html\n\n\n\n```\n\n---\n\n## Grouping with Fieldset\n\nRelated fields belong in a `