form-design
Skill194 starsChanged 4 months agoMITView on GitHub
Helper text, placeholders, validation and submit behaviour. Use when designing or reviewing a form, input field or data entry UI.
5 other projects use a version of this.
Adopted by
Most recently taken up by
- thewyattbrocato/design-and-copy-skillstheir own version, first seen Oct 17, 2026
- dnfisher/claude-skillstheir own version, first seen Oct 13, 2026
- pengGgxp/skillstheir own version, first seen Oct 11, 2026
- eliabdevweb-svg/opencode-skills-MCPtheir own version, first seen Oct 9, 2026
- miovrag/claude-skillstheir own version, first seen Jun 12, 2026
Other versions5 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 5
- thewyattbrocato/design-and-copy-skills★ 2same name
- miovrag/claude-skills★ 1same name
- pengGgxp/skills★ 1same name
- dnfisher/claude-skills★ 0same name
- eliabdevweb-svg/opencode-skills-MCP★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository44 other files it gives its agents.
- algorithmic-color-paletteSkill
- app-shellSkill
- authentic-product-representationSkill
- brand-visual-languageSkill
- button-statesSkill
- clone-websiteSkill
- color-mode-and-themeSkill
- component-family-consistencySkill
- coordinated-data-viewsSkill
- data-display-and-selectionSkill
- dembrandtSkill
- domain-expert-configurationSkill
- elevation-and-depthSkill
- extract-designSkill
- generate-ui-from-brandSkill
- gestalt-ui-organisationSkill
- global-toolbar-controlsSkill
- information-architectureSkill
- layout-paradigms-and-consistencySkill
- loading-states-and-perceived-performanceSkill
- marketing-vs-product-systemSkill
- micro-interactionsSkill
- modal-and-overlay-patternsSkill
- modular-scale-typographySkill
- motion-and-storytellingSkill
- nielsen-usability-heuristicsSkill
- notifications-and-recoverySkill
- operational-expert-tool-uiSkill
- performance-and-web-vitalsSkill
- real-world-metaphorsSkill
- repeated-component-alignmentSkill
- responsive-paradigmsSkill
- scroll-areasSkill
- semantic-html-and-seoSkill
- sizing-unitsSkill
- status-colors-and-errorsSkill
- sticky-and-fixed-elementsSkill
- surface-separationSkill
- tab-navigationSkill
- ui-context-and-scopeSkill
- ui-densitySkill
- user-flows-and-guided-pathsSkill
- visual-emphasis-and-hierarchySkill
- wcag-accessibilitySkill
The file
We split this skill into the rules it gives an agent
9 rules. 0 are common, 6 are distinctive, and 3 are very specific to this project.
0
Common
Most of the 4 edited versions we read keep these.
6
Distinctive
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 68
Write in plain language from the user's perspective
- Distinctive: line 69
Keep it to one sentence — if you need more, the field is too complex or misnamed
- Distinctive: line 70
Do not repeat the label ("Enter your email" below a label that says "Email" is redundant)
- Very specific: line 80
Use a realistic example, not a description: +358 40 123 4567 not Enter phone number
- Distinctive: line 81
Never use placeholder as a label — it disappears and leaves the user without context
- Very specific: line 82
Keep it grey (--color-text-secondary) and lighter than actual input text
- Distinctive: line 156
Do not rely on colour alone — add a text label ("Required" or asterisk with legend)
- Distinctive: line 157
Place the required/optional indicator in the label, not only in the placeholder or helper text
- Very specific: line 190
Use the correct type — browsers provide free validation, appropriate keyboards, and autofill.
“Common” is measured: kept by at least 6 in 10 of the 4 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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 4567notEnter 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:
<button type="submit" disabled={!isFormValid}>Submit</button>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 ]<div class="field">
<label for="vat">VAT number <span class="optional">Optional</span></label>
<input
id="vat"
type="text"
placeholder="FI12345678"
aria-describedby="vat-helper vat-error"
aria-invalid="true"
>
<p id="vat-helper" class="helper-text">Finnish VAT numbers start with FI followed by 8 digits.</p>
<p id="vat-error" class="error-text" role="alert">Enter a valid Finnish VAT number (e.g. FI12345678).</p>
</div>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
<label>Email <abbr title="Required">*</abbr></label>
<!-- or -->
<label>Phone <span class="badge">Optional</span></label>Grouping with Fieldset
Related fields belong in a <fieldset> with a <legend>. This is semantic HTML and helps screen readers announce the group context.
<fieldset>
<legend>Billing address</legend>
<label>Street</label><input type="text">
<label>City</label><input type="text">
<label>Postal code</label><input type="text">
</fieldset>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 |
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.
<input type="text" autocomplete="name">
<input type="email" autocomplete="email">
<input type="tel" autocomplete="tel">
<input type="text" autocomplete="street-address">
<input type="text" autocomplete="postal-code">
<input type="text" autocomplete="cc-number"> <!-- credit card -->
<input type="password" autocomplete="new-password">Correct autocomplete values reduce friction dramatically for returning users and on mobile.
Copy That Depends on a Count
Any string whose wording depends on a number goes through the message catalogue, with the count as a named placeholder. Never branch on count === 1 in the view. That ternary hard-codes three English facts: two plural forms, the split at one, the number before the noun. Finnish inflects the noun, other languages have three or more forms or trail the count. The bug is invisible until translation, then spread across every view.
Translating UI copy makes every text-based test selector locale-dependent. Pin the locale in the test setup in the same change.
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
<fieldset>with<legend> - Correct
typeattribute on all inputs autocompleteattributes set on address, contact, and payment fields- Count-dependent copy resolved through the catalogue with the count as a placeholder, never a one/other ternary
- Tests that select by text pin the locale
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

