# Form Design > 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 reviewing any form, input field, or data entry UI. - **Type:** Skill - **Install:** `agentstack add skill-dembrandt-dembrandt-skills-form-design` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [dembrandt](https://agentstack.voostack.com/s/dembrandt) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [dembrandt](https://github.com/dembrandt) - **Source:** https://github.com/dembrandt/dembrandt-skills/tree/main/skills/form-design ## Install ```sh agentstack add skill-dembrandt-dembrandt-skills-form-design ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Form Design Forms 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. --- ## The Three Guidance Layers Each layer serves a distinct purpose. Do not collapse them. ### Layer 1 — Helper Text Explains *what* to enter. Appears below the input, always visible, in small secondary text. ``` Email address [ ] Use the email you signed up with. ``` - Write in plain language from the user's perspective - Keep it to one sentence — if you need more, the field is too complex or misnamed - Do not repeat the label ("Enter your email" below a label that says "Email" is redundant) - Helper text is not a replacement for a label — the label is still required ### Layer 2 — Placeholder Shows the *format* or an example value. Appears inside the input, disappears on typing. ``` [jane@example.com ] ``` - Use a realistic example, not a description: `+358 40 123 4567` not `Enter phone number` - Never use placeholder as a label — it disappears and leaves the user without context - Keep it grey (`--color-text-secondary`) and lighter than actual input text - Optional — not every field needs a placeholder ### Layer 3 — Validation Confirms whether the input is correct. The most important layer. ``` Email address [jane@ ] ← invalid ✗ Enter a valid email address. ``` **Validation timing:** - **On blur** (leaving the field): default for most fields — validates once the user has finished - **Real-time** (on input): use when the format is complex or the error is likely — password strength, IBAN, VAT number, URL, regex-heavy fields - **On submit**: catches anything missed, scrolls to the first error Real-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. --- ## Submit Button State The 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. ``` [Submit] ← disabled, low contrast, cursor: not-allowed (fields incomplete or invalid) [Submit] ← enabled, full colour, cursor: pointer (all required fields valid) ``` **Implementation:** ```html Submit ``` For 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. **Loading state on submit:** Replace label with spinner, disable the button. Prevent double-submission. --- ## Field Anatomy ``` [Label] [Optional badge if optional] [Input field ] [Helper text — what to enter, format, constraints ] [Error message — appears below helper text on validation fail ] ``` ```html VAT number Optional Finnish VAT numbers start with FI followed by 8 digits. Enter a valid Finnish VAT number (e.g. FI12345678). ``` --- ## Required vs Optional Mark the minority. If most fields are required, mark the optional ones. If most are optional, mark the required ones. - Do not rely on colour alone — add a text label ("Required" or asterisk with legend) - Place the required/optional indicator in the label, not only in the placeholder or helper text ```html Email * Phone Optional ``` --- ## Grouping with Fieldset Related fields belong in a `` with a ``. This is semantic HTML and helps screen readers announce the group context. ```html Billing address Street City Postal code ``` Use fieldsets for: - Address groups - Payment details - Radio button groups - Checkbox groups --- ## Input Types Use the correct `type` — browsers provide free validation, appropriate keyboards, and autofill. | Data | Input type | |---|---| | Email | `type="email"` | | Phone | `type="tel"` | | URL | `type="url"` | | Number | `type="number"` | | Password | `type="password"` | | Date | `type="date"` | | Search | `type="search"` | | Colour | `type="color"` | On mobile, `type="email"` shows the email keyboard, `type="tel"` shows the numpad. These are free UX improvements. --- ## Autofill Support Allow browsers to autofill. Do not disable it unless there is a security requirement. ```html ``` Correct `autocomplete` values reduce friction dramatically for returning users and on mobile. --- ## Review Checklist - [ ] Every field has a visible label (not just placeholder) - [ ] Helper text is below the input and explains what to enter - [ ] Placeholder shows format or example, not a description - [ ] Validation triggers on blur for simple fields, real-time for complex ones - [ ] Error message is adjacent to the field that failed - [ ] Error message is associated via `aria-describedby` - [ ] Required/optional marked on the minority of fields - [ ] Submit button is disabled when form is invalid (for short forms) - [ ] Submit button shows a loading state and prevents re-submission - [ ] Related fields are grouped in `` with `` - [ ] Correct `type` attribute on all inputs - [ ] `autocomplete` attributes set on address, contact, and payment fields ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [dembrandt](https://github.com/dembrandt) - **Source:** [dembrandt/dembrandt-skills](https://github.com/dembrandt/dembrandt-skills) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-dembrandt-dembrandt-skills-form-design - Seller: https://agentstack.voostack.com/s/dembrandt - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.