Introduction
============

Motivation
~~~~~~~~~~

The `U.S. Web Design Standards <https://standards.usa.gov/>`_ are awesome, but there's a
few barriers that make it difficult to use with 
:class:`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 <https://www.deque.com/blog/aria-group-viable-alternative-fieldset-legend/>`_ to be accessible.

We implemented solutions for the above issues in
`CALC <https://github.com/18F/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 :mod:`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.
