django-cotton-gallery

Drop-in playground for your django-cotton components — annotate them once with @prop comments and get a live, themable, copy-and-paste gallery with auto-generated controls, a lint report, and an insights dashboard.

📚 Docs: https://velezanthony.github.io/django-cotton-gallery/

Install (≈60 seconds)

The gallery is a development-only tool, so the recommended install is as a dev dependency with uv — that way it never ships to production (uv sync --no-dev leaves it out):

uv add --dev django-cotton-gallery

Prefer pip? That works just as well:

pip install django-cotton-gallery

# settings.py
INSTALLED_APPS = [
    # ...
    "django_cotton",            # already there if cotton is set up
    "django_cotton_gallery",
]

# urls.py
from django.conf import settings
from django.urls import include, path

urlpatterns = [...]

# Gate it — the gallery exposes component source code. Do NOT ship to prod.
if settings.DEBUG:
    urlpatterns += [path("", include("django_cotton_gallery.urls"))]

Run your server and open http://localhost:8000/django-cotton-gallery/. That's it — the gallery indexes whatever cotton already finds. The empty state walks you through your first component if the catalog is empty.

Need production access patterns (staff-only, feature flags), asset injection, or per-setting reference? → Getting started · Configuration

What you get

Live playground — every component renders with auto-generated controls from your @prop annotations. Tweak any prop in real time, copy the tag, done.

Lint report — three severity tiers (errors, warnings, hints) for @prop/<c-vars> mismatches, missing descriptions, and undeclared variables. The same engine runs in CI as python manage.py cotton_lint.

Insights dashboard — config health, annotation coverage, zombie components, most-referenced ranking. Spot rot before it ships.

Ctrl+K switcher with structured filters (prop:size, slot:actions, accepts-attrs, has-named-slots, deprecated) — find any component without leaving the keyboard.

Plus: a refactor planner (transitive dependency tree), an annotation builder (form-based @prop editor), a side-by-side compare view, and i18n chrome (English, Spanish, Basque, French). → Full feature tour

Compatibility

CI verifies every valid Python × Django combination on every push (plus Windows + macOS smoke tests).

Contributing & local development

Clone, then make dev && make serve to run the bundled demo at http://localhost:8000/django-cotton-gallery/. Everything else — repo layout, tests, the Python × Django matrix, i18n, releases — lives in docs/contributors/. See also CONTRIBUTING.md and the CHANGELOG.

Support

If this project saves you time, consider sponsoring its development. It helps keep it maintained.

License

MIT — see LICENSE.