Introduction

Motivation

The U.S. Web Design Standards are awesome, but there’s a few barriers that make it difficult to use with django.forms.Form. For example:

  • The CSS classes used by Django’s default renderer for things like errors and help text are not the same as those used by USWDS.
  • Individual checkboxes and radio buttons have different HTML markup than that rendered by Django forms.
  • Dates are split up into three separate month/day/year fields.
  • Dates and sets of checkboxes and radios need to use either <legend> or ARIA group roles to be accessible.

We implemented solutions for the above issues in CALC but wanted to factor them out for reuse by other Django projects, so we created this package.

Philosophy

This package has the following core values:

  • Low cognitive overhead. Where possible, this package aims to build upon the shoulders of the django.forms.renderers API introduced in Django 1.11. This means that, aside from understanding that API, developers should have to learn as few new concepts as possible to build forms that follow the U.S. Web Design Standards.
  • Extensibility. The HTML markup generated by the package’s components should be easy to modify and extend, when possible.
  • Accessibility. Forms generated by the package should work across a variety of accessible technologies (ATs), such as screen readers and voice recognition systems, with a minimal amount of work on the part of the developer.