CivicTheme
  • Docs
  • Changelog
  • Getting started
    • Introduction
    • Installation
    • Getting help
    • Security policy
    • Partnerships
  • Installation
    • Drupal theme
  • Contributing
    • Contribution model
    • Contribution basics
    • Small contribution spec
    • Medium contribution spec
    • Major (RFC-level) contribution spec
    • Code of conduct
    • Figma contributions
  • Components
    • Component list
    • Atoms
      • Button
      • Chip
      • Content link
      • Check box
      • Field description
      • Field message
      • Fieldset
      • Label
      • Radio
      • Select
      • Textarea
      • Text field
      • Heading
      • Link
      • Paragraph
      • Popover
      • Quote
      • Table
      • Tag
      • Text list
    • Molecules
      • Accordion
      • Attachment
      • Breadcrumb
      • Callout
      • Event Card
      • Field
      • Figure
      • Group filter
      • Logo
      • Map
      • Navigation card
      • Next step
      • Pagination
      • Promo card
      • Search
      • Service card
      • Single filter
      • Snippet
      • Subject Card
      • Table of Contents
      • Tabs
      • Tag List
      • Tooltip
      • Video Player
    • Organisms
      • Alert
      • Banner
      • Campaign
      • Footer
      • Header
      • List
      • Message
      • Mobile Navigation
      • Navigation
      • Promo
      • Side Navigation
      • Skip link
      • Slider
      • Social links
  • Content Authoring
    • Overview
    • Global settings
      • Favicon
      • Header
        • Site slogan
        • Header logos
        • Primary navigation
        • Secondary navigation
      • Banner
      • Search
      • Link
      • Skip link
      • Side navigation
      • Signup
      • Footer
        • Footer logo
        • Social links
        • Footer navigation
        • Acknowledgement of Country
        • Copyright
      • Colours
    • Content types
      • Page
        • Configure the banner
      • Event
      • Alert
    • Content components
      • Accordion
      • Automated list
      • Attachment
      • Callout
      • Campaign
      • Content
        • Quote
      • iFrame
      • Manual List
        • Event card
        • Event reference card
        • Navigation card
        • Navigation reference card
        • Promo card
        • Promo reference card
        • Publication card
        • Service card
        • Subject card
        • Subject reference card
        • Snippet
      • Map
      • Next step
      • Promo
      • Slider
      • Webform
    • Vocabularies
      • Topics
      • Site sections
    • User accounts & roles
Powered by GitBook
On this page
  • When to use
  • When not to use
  • Best practice guidelines
  • Variations
  • Accessibility
  • Security
  • Sites using this component
  • Component inspiration and uplift
  • User research on this component
  • Known issues
  • More research needed
  • Help improve this component
  • Resources
  • References
  • Changelog
  • Contact us

Was this helpful?

Edit on GitHub
Export as PDF
  1. Components
  2. Molecules

Field

A field component manages form input elements, providing structure for labels, input elements, descriptive text, and validation messages.

When to use

Use the field component when:

  • You need to collect user input in a form

  • You want to present form elements in a consistent, accessible manner

  • You need to provide context or validation feedback for form inputs

  • You want to group related form elements with proper labelling

  • You need to implement required or optional field indicators

When not to use

Do not use the field component when:

  • You need to create a standalone control without a label or context

  • You want to embed interactive elements in flowing text

  • Simple instructions or options would be better presented as plain text or links

  • You need complex, multi-step data collection that would benefit from a wizard-style interface


Best practice guidelines

  • Clear labelling: Use concise, descriptive labels that clearly indicate what information is being requested.

  • Required field indication: Clearly mark required fields with an asterisk (*) and explain this pattern to users at the beginning of the form.

  • Helpful instructions: Provide clear field descriptions that explain the purpose of the field and any formatting requirements.

  • Logical grouping: Group related fields together using the fieldset component.

  • Consistent sizing: Maintain consistent field sizes based on the expected input length.

  • Appropriate validation: Implement inline validation where appropriate, with clear error messages that explain how to correct issues.

  • Responsive design: Ensure fields display correctly and remain usable across all device sizes.

  • Logical tab order: Maintain a logical tab sequence that follows the visual flow of the form.

  • Visual hierarchy: Design form fields with clear visual hierarchy to guide users through completion.

  • Error prevention: Provide clear instructions and constraints to prevent errors before they occur.

Variations

  • Default: Standard field with label above the input.

  • Inline: Field with the label positioned inline/beside the input.

  • With helper text: Field with additional descriptive text below the label.

  • With validation: Field showing validation states (success, error, warning).

  • Required: Field marked as mandatory with an asterisk.

  • Optional: Field explicitly marked as optional.

  • Mobile optimised: Fields that adjust their layout for smaller screens.


Accessibility

This component meets most WCAG 2.2 AA accessibility guidelines, with several tests conducted against the standards.

According to the 'CivicTheme v1.7.0 Accessibility Assessments.pdf', the Field component (formerly called Form Element) was tested against the following WCAG criteria, with these results:

WCAG Criterion
Level
Status

1.3.1 Info and Relationships

A

Pass

1.3.5 Identify Input Purpose

AA

Pass

1.4.4 Resize text

AA

Pass

1.4.12 Text Spacing

AA

Pass

2.1.1 Keyboard

A

Pass

2.1.2 No Keyboard Trap

A

Pass

2.4.3 Focus Order

A

Pass

2.4.7 Focus Visible

AA

Pass

2.5.3 Label in Name

A

Pass

2.5.8 Target Size (Minimum)

AA

Fail

3.2.1 On Focus

A

Pass

3.2.2 On Input

A

Pass

3.3.2 Labels or Instructions

A

Pass

3.3.3 Error Suggestion

AA

Pass

4.1.2 Name, Role, Value

A

Pass

4.1.3 Status Messages

AA

Pass

Note: The component fails the 2.5.8 Target Size (Minimum) criterion, which requires that the size of the target for pointer inputs is at least 24 by 24 CSS pixels.

Security

Form fields handle user input, which presents several security considerations:

  • User input validation should be implemented both client-side and server-side

  • Proper sanitisation of input must be implemented to prevent injection attacks

  • Error messages should be helpful but avoid revealing sensitive system information

  • Care should be taken with autocomplete attributes to balance user convenience with security

Note that this component itself doesn't implement security measures, but developers implementing forms must consider these aspects when deploying the component in production.

Sites using this component

The Field component is a fundamental building block used across numerous government, corporate, higher education and healthcare sites that implement CivicTheme. Due to its foundational nature, it appears on virtually any site with forms.

[Specific site examples would be added here by documentation author]

Component inspiration and uplift

This component has been modelled after the Form component in the former Australian Government Design System (AGDS). It has been uplifted by Salsa Digital, as the custodian of the CivicTheme Design System, in the following ways:

  • The Labels element is styled using Lexend's "SemiBold" font type for improved visibility and hierarchy

  • The Hint Text element (Field Description) sits below the Label in a smaller font size with lighter shade

  • Error messages are featured below the input field within a prominent background colour

  • The component has been renamed from "Form Element" to "Field" in version 1.8.0 for more intuitive naming

  • Recategorized from Forms to Molecules in version 1.8.0 to better reflect its role in the atomic design system


User research on this component

★★★★☆ Confidence rating = High (Informed by indirect evidence and heuristic evaluation)

See list of confidence ratings and how they are defined

No direct user research data specifically for CivicTheme's Field component is available. However, form fields are extensively studied UI elements with well-documented usability patterns. The design of this component follows established best practices derived from broader form usability research.

Research from other major government design systems indicates that:

  • Users expect clear labelling and consistent positioning of form elements

  • Validation messages placed below inputs are most visible to users

  • Required field indicators are most effective when explained at the form beginning

  • Descriptive helper text significantly reduces form errors and abandonment

Further user testing specifically on CivicTheme's implementation would help validate these patterns in context.

Known issues

  • Target size limitations: The component fails WCAG 2.2 criterion 2.5.8 for minimum target size, as noted in the accessibility section.

  • Mobile responsiveness: Some implementations may encounter layout issues on very small screens when using the inline variation.

  • Long label handling: When labels are exceptionally long, they may cause layout inconsistencies, particularly in the inline variation.

More research needed

More user research is needed in the following areas:

  • Performance with assistive technologies: Further testing with screen readers and other assistive technologies to ensure the component works effectively for all users.

  • Mobile usage patterns: Detailed research on how users interact with form fields on mobile devices to optimise the mobile experience.

  • Error recovery strategies: Understanding how users process and respond to validation messages to improve error recovery.

  • Field grouping effectiveness: Research on the most effective ways to visually and semantically group related fields.

  • Inline vs. stacked labels: Comparative research on user performance and preference between inline and stacked label presentations.

Help improve this component

To help make this component useful and up-to-date, you can:

  • Contribute to our Field component discussion on GitHub

  • Submit your user research findings to help improve the Field component

  • Propose a change to address the target size accessibility issue

  • Report any bugs or issues you encounter when implementing this component


Resources

  • Storybook

  • GitHub

References

  • Wroblewski, L. (2008). "Web Form Design: Filling in the Blanks." Rosenfeld Media.

Changelog

Version
Date
Changes

1.8.0

Jul 2024

Renamed from "Form Element" to "Field" and recategorized from Forms to Molecules

1.7.0

Mar 2024

WCAG 2.2 compliance update

1.6.0

-

Initial component documentation

Contact us

PreviousEvent CardNextFigure

Last updated 1 month ago

Was this helpful?

Check out our to learn more.

If you have a question about the CivicTheme design system or need our help, visit the page for guidance.

contributing section
Figma
Nielsen Norman Group. (2016). "Form Design Guidelines"
Web Content Accessibility Guidelines (WCAG) 2.2
Digital Service Standard
Australian Government Style Manual
Getting Help