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
  • 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

Attachment

The Attachment component is a content container that groups downloadable files or documents with their metadata, presented in a consistent format for easy access and retrieval.

When to use

Use the Attachment component when:

  • You need to provide downloadable files or documents to users in a consistent, accessible format

  • You want to group related files together in a structured way

  • You need to display essential metadata about the files, such as file type, size, or date updated

  • You need to provide clear visual cues for download functionality

  • You have supporting documents that complement your main content

When not to use

Do not use the Attachment component when:

  • The files need to be interacted with directly on the page rather than downloaded (such as embedded media)

  • You only have one or two simple links that don't require additional metadata or visual treatment

  • You need more interactive file management capabilities like uploading, sorting, or filtering

  • There are large quantities of files that would be better served by a search interface or complex file manager

  • The primary purpose is to display information, not to provide downloadable files


Best practice guidelines

  • Clear labelling: Provide descriptive file names that accurately describe the content to help users understand what they're downloading

  • Essential metadata: Include relevant metadata with each file, such as file type, size, and last updated date to help users make informed decisions

  • Visual cues: Use appropriate icons that indicate file type and download functionality to improve recognition and understanding

  • Consistent structure: Maintain a consistent layout for all attachments to improve usability and scanability

  • Accessible format: Ensure all files are provided in accessible formats or with accessible alternatives where possible

  • Responsive design: Ensure the component adapts appropriately to different screen sizes, maintaining usability on mobile devices

  • Group related files: When possible, group related documents together to help users find connected information

  • File size indication: Always include file size to help users with limited bandwidth or data plans make informed decisions about downloads

  • Last updated date: Include the last updated date to help users identify the most current version of a document

Variations

Desktop

  • Standard view with file icon, name, and metadata displayed in a list format

  • Allows for multiple files to be presented with consistent spacing and styling

  • Provides clear visual hierarchy with file names prominently displayed

Mobile

  • Condensed layout optimised for smaller screens

  • Maintains essential information while adjusting spacing to ensure readability

  • Preserves download functionality and visual cues in a touch-friendly format


Accessibility

This component was assessed against WCAG 2.2 accessibility guidelines as documented in the CivicTheme v1.7.0 Accessibility Assessments.

Based on the assessments, the Attachment component demonstrates strong accessibility compliance in several key areas:

WCAG Guideline
Level
Description

1.3.1 Info and Relationships

A

Information, structure, and relationships conveyed through presentation can be programmatically determined

1.4.4 Resize Text

AA

Text is still visible and readable when resized up to 200%

1.4.12 Text Spacing

AA

Text remains readable with adjusted spacing parameters

2.1.1 Keyboard

A

The component is accessible using keyboard-only navigation

2.4.3 Focus Order

A

Focusable elements receive focus in an order that preserves meaning and operability

2.4.4 Link Purpose (In Context)

A

The purpose of each attachment can be determined from the text alone

2.4.7 Focus Visible

AA

Focus is visible when navigating using a keyboard

2.5.3 Label in Name

A

For fields containing labels, the name contains the visually presented text

4.1.2 Name, Role, Value

A

Name and role of all elements can be programmatically determined

Security

The Attachment component primarily serves static files and does not process user input, which minimises security risks. However, best practices include:

  • Ensure that downloadable files are scanned for malware before being made available

  • Implement appropriate access controls if some attachments should have restricted access

  • Use secure transmission protocols (HTTPS) for file downloads

  • Consider digital signatures for documents where authenticity verification is important

  • Follow organisation-specific policies for document classification and handling

Component inspiration and uplift

This component has been modelled after the Basic Card and Default Link List components from the Australian Government Design System (AGDS).

It has been uplifted by Salsa Digital, as the custodian of the CivicTheme Design System, in the following ways:

  • Combined the design of both the Basic Card and Link components to form a content card that presents a list of downloadable files/documents

  • Added additional labelling (file specifications) below each link item to improve user understanding

  • Added iconography alongside each link list item to provide visual cues about file types

  • Provided additional spacing between each link to more clearly separate each downloadable asset

  • Implemented responsive design considerations to ensure optimal display on mobile devices

These uplifts were based on user research findings that demonstrated the need for clearly distinguishable downloadable assets with appropriate contextual information.


User research on this component

★★★★☆ (4/5) Confidence rating = High (Based on indirect evidence and established patterns)

No direct user research data specific to CivicTheme's Attachment component is available. However, the component's design is informed by established patterns and indirect evidence from similar components in other design systems.

Research on similar attachment components in government websites indicates that users expect:

  • Clear file type indicators

  • File size information to help determine download time

  • Last modified dates to ensure currency

  • Descriptive file names that indicate content

The component addresses these expectations and follows established patterns for document libraries and downloadable content sections.

Known issues

  • Mobile display limitations: On very small mobile screens, lengthy filenames and metadata may cause layout issues or text truncation

  • Accessibility for complex file types: Some downloadable file formats (like certain PDFs or Excel files) may present accessibility challenges for users with assistive technologies

  • Consistent metadata: There's currently no enforced standard for what metadata must be included, which can lead to inconsistency across implementations

  • Download feedback: The component does not currently provide feedback about download progress or completion status

More research needed

More user research is needed in the following areas:

  • User preferences for metadata display and prioritisation (what information is most valuable to users)

  • Mobile user experience, particularly on low-bandwidth connections

  • Performance metrics related to download initiation and completion

  • Accessibility testing with users who rely on screen readers and other assistive technologies

  • User expectations around file grouping and organisation when multiple attachments are present

If you have conducted user research that addresses any of these gaps, you can submit your research findings to help improve this component.

Help improve this component

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

  • Contribute to our Attachment component discussion on GitHub

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

  • Propose a change to the Attachment component

  • Report issues or bugs you encounter when implementing this component


Resources

  • Storybook

  • GitHub

References

  • Australian Government Design System (AGDS) - Cards and Link Lists

  • Australian Government Style Manual - Clear language and writing style

  • Web Content Accessibility Guidelines (WCAG) 2.2

  • Digital Service Standard - Criterion 3: Leave no one behind

Changelog

Version
Date
Changes

v1.8.0

Jul 2024

  • Improved responsive behaviour for mobile displays

  • Added support for multiple file formats

  • Enhanced accessibility features

v1.7.0

Mar 2024

  • Updated styling to improve visual hierarchy

  • Fixed spacing issues between multiple attachments

v1.6.0

Oct 2023

  • Initial release of the component

Contact us

PreviousAccordionNextBreadcrumb

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
Getting Help