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:
Newer release available (1.3.1)

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.0.tar.gz (216.8 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.0-py3-none-any.whl (180.3 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: django_cotton_uswds-1.3.0.tar.gz
  • Upload date:
  • Size: 216.8 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.0.tar.gz
Algorithm Hash digest
SHA256 eb66054c0241a608159b98ccb14f9452de4c8982d478c7a3edb9a57b99f9141c
MD5 c9625752ced3d71d5908ae0af72924e4
BLAKE2b-256 262a73225ebbf4bf6ab158ccbd25793b2e959516b2290ac69c05eff23235526f

See more details on using hashes here.

Provenance

The following attestation bundles were made for django_cotton_uswds-1.3.0.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.0-py3-none-any.whl.

File metadata

File hashes

Hashes for django_cotton_uswds-1.3.0-py3-none-any.whl
Algorithm Hash digest
SHA256 b2d79fae85b35a8228f2673936ee977d00a0d4ba83d608c2c21f620cebe2d7df
MD5 854fefb567a4303b485fcb7c56733749
BLAKE2b-256 2699a8b9c70a71b3b6e70491eaed6a64942559a4a69ede799fab9f369a9fc71f

See more details on using hashes here.

Provenance

The following attestation bundles were made for django_cotton_uswds-1.3.0-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

1.3.1

2 files

This release

1.3.0 This release

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