Field description
High level definition
Field Description provides supplementary information below form field labels to help users understand input requirements and context, with configurable sizing to support various form layouts.
When to use
Use Field Description when:
Users need additional context to understand what information to enter in a form field
The field label alone doesn't provide enough guidance
Complex validation rules or input requirements need to be explained
Users may need examples of valid input formats
When not to use
Do not use Field Description when:
The field label is self-explanatory and no additional context is needed
Error messages or validation feedback is required (use Field Message component instead)
Information is critical for completing the field (put this in the label)
Space is extremely limited and the extra text would cause visual clutter
Best practice guidelines
Keep descriptions concise and focused on helping users complete the field correctly
Use plain language and avoid technical jargon
Maintain consistent text styling across all field descriptions
Position descriptions directly under field labels but above input fields
Ensure descriptions remain visible even when error messages appear
Use sentence case and full stops for complete sentences
For non-sentence fragments, omit full stops
Avoid repeating information already present in the field label
Variations
The Field Description component offers two size variations:
Regular: Standard size for most form contexts
Large: Increased size for enhanced visibility or emphasis
Accessibility
Based on the CivicTheme v1.7.0 Accessibility Assessments:
The Field Description component has been tested as part of the Form elements and meets the following WCAG 2.2 criteria:
Accessibility Compliance Results
1.3.1 Info and Relationships
A
Pass
1.4.4 Resize text
AA
Pass
2.4.6 Headings and Labels
AA
Pass
3.3.2 Labels or Instructions
A
Pass
The component maintains adequate colour contrast and remains visible/readable when text spacing is adjusted according to WCAG requirements.
Security
No specific security considerations have been identified for this component as it is a presentational element. However, ensure that any sensitive information is not exposed through field descriptions.
Component inspiration and uplift
This component has been modelled after the Hint Text component from the Australian Government Design System. It has been uplifted by:
Offering two configurable sizes for flexible form layouts
Maintaining description visibility alongside error states
Using darker text colour than standard hint text for improved contrast
Integrated with the CivicTheme design tokens and typography system
Research on this component
Using the scoring system outlined in the guidance document:
Confidence rating: ★★★☆☆ Based on documented testing within form contexts rather than standalone evaluation.
Score breakdown:
Usability: 8/10 - Clear positioning and readability
Aesthetics: 7/10 - Consistent with design system but limited styling options
Accessibility: 9/10 - Strong WCAG compliance
Functionality: 8/10 - Reliable but basic functionality
Innovation: 6/10 - Standard implementation of established pattern
Overall score: 7.6/10
Known issues
Not currently available as a standalone component in the Figma library
Limited configuration options for styling and positioning
May require additional spacing adjustments in dense form layouts
More research needed
Research gaps that need to be addressed:
User comprehension testing of description text across different contexts
Impact on form completion rates compared to forms without descriptions
Optimal length guidelines for description text
Performance with screen readers and assistive technologies
Help improve this component
Contribute to discussion in GitHub repository
Submit research findings via the research submission process
Propose changes through pull requests
Report bugs or issues through the issue tracker
Check out our contributing section to learn more.
Resources
Storybook
GitHub
References
WCAG 2.2 Guidelines
Australian Government Design System documentation
Form design best practices from GOV.UK Design System
Changelog
v1.8.0 (Latest)
Added regular and large size variants
Improved contrast ratios for better readability
Updated documentation structure
Contact us
If you have a question about the CivicTheme design system or need our help, visit the Getting Help page for guidance.
Last updated
Was this helpful?