django-cotton-uswds

USWDS components as Django Cotton templates.

Use the U.S. Web Design System in your Django projects with a clean, declarative component syntax.

Installation

git clone https://github.com/iversondiles/django-cotton-uswds.git
cd django-cotton-uswds
pip install -e .

Then add both django_cotton and django_cotton_uswds to your INSTALLED_APPS:

INSTALLED_APPS = [
    # ...
    "django_cotton",
    "django_cotton_uswds",
]

Usage

Components follow the <c-component> naming convention:

<c-alert type="info" heading="Informative status">
    This is an informative alert.
</c-alert>

Attributes pass through to the underlying USWDS markup, so you can use the same options documented on the USWDS component pages.

USWDS Assets

This package provides markup only — no CSS or JavaScript is bundled. You need to add USWDS assets to your project separately.

See the USWDS getting started guide for instructions on compiling and including the USWDS stylesheet and scripts.

Available Components

This project is in early development. Components are being added incrementally. See the USWDS components page for reference on what's planned.

Form Rendering

The package includes a USWDS form renderer that automatically styles Django forms with USWDS markup — labels, hints, error messages, and all standard widget types.

Per-form via mixin

from django import forms
from django_cotton_uswds.mixins import USWDSFormMixin

class ContactForm(USWDSFormMixin, forms.Form):
    name = forms.CharField(label="Full name")
    email = forms.EmailField()
    message = forms.CharField(widget=forms.Textarea)

Globally via settings

# settings.py
FORM_RENDERER = "django_cotton_uswds.renderer.USWDSFormRenderer"

Widget attribute passthrough

USWDS-specific attributes can be passed through widget attrs:

class MyForm(USWDSFormMixin, forms.Form):
    name = forms.CharField(
        widget=forms.TextInput(attrs={"width": "md"}),
    )
    resume = forms.FileField(
        widget=forms.ClearableFileInput(attrs={"accept": ".pdf,.doc"}),
    )

Supported widget mappings

Django widget USWDS rendering
TextInput, EmailInput, NumberInput, etc. usa-input text field
Textarea usa-textarea
Select usa-select dropdown
RadioSelect Fieldset with usa-radio buttons
CheckboxSelectMultiple Fieldset with usa-checkbox items
CheckboxInput (boolean) Single usa-checkbox
ClearableFileInput usa-file-input

MCP server

An optional MCP server exposes component docs and a form scaffolder to AI assistants. Install with the mcp extra and point your MCP client at django-cotton-uswds-mcp:

pip install "django-cotton-uswds[mcp]"

See django_cotton_uswds/mcp/README.md for client configuration and tool details.

Demo

A demo project is included to showcase components. Requires just and uv.

# Install the package with demo dependencies
just install

# Run the development server at http://127.0.0.1:8000/
just demo

# Build a static site into demo_project/dist/
just build

Requirements

  • Python 3.10+
  • Django 4.2+
  • django-cotton 1.2.1+

Domain Language

See UBIQUITOUS_LANGUAGE.md for a glossary of canonical domain terms used in this project.

License

MIT

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for mkalish from gravatar.com mkalish

License expression

MIT
View SPDX License List

Requires

Python >=3.10

Provides Extra

demo dev eval mcp test

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django_cotton_uswds-1.3.1.tar.gz (216.9 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

django_cotton_uswds-1.3.1-py3-none-any.whl (180.5 kB view details)

Uploaded Python 3

File details

Details for the file django_cotton_uswds-1.3.1.tar.gz.

File metadata

  • Download URL: django_cotton_uswds-1.3.1.tar.gz
  • Upload date:
  • Size: 216.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for django_cotton_uswds-1.3.1.tar.gz
Algorithm Hash digest
SHA256 3f8c29faba851bfca0be6d47964a06232bd1271ea8c8851543916e1aa52e9f36
MD5 826015ca30d9a2db7d66973d93719487
BLAKE2b-256 cb0b1f73ddb9243fc0e3f0dd1220df3469501ff3fd58904250c23ea80f653842

See more details on using hashes here.

Provenance

The following attestation bundles were made for django_cotton_uswds-1.3.1.tar.gz:

Publisher: publish.yml on focusconsulting/django-cotton-uswds

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file django_cotton_uswds-1.3.1-py3-none-any.whl.

File metadata

File hashes

Hashes for django_cotton_uswds-1.3.1-py3-none-any.whl
Algorithm Hash digest
SHA256 bd797762f8294a4ff814ca3259e42f28845d9be3a1b56376ece3f2ec1f33fd5c
MD5 3162ccddb695e5147505cb391648e4e9
BLAKE2b-256 ad586e2b394a0cc45d73f5ad6938cdc94a93bf1557fabf4b3803d02b157c4e20

See more details on using hashes here.

Provenance

The following attestation bundles were made for django_cotton_uswds-1.3.1-py3-none-any.whl:

Publisher: publish.yml on focusconsulting/django-cotton-uswds

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

1.3.1 This release

2 files

1.3.0

2 files

1.2.0

2 files

1.1.3

2 files

1.1.2

2 files

1.1.1

2 files

1.1.0

2 files

1.0.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page