djust-designer 0.1.0

Visual design collaboration layer for djust / Django — point at the page, edit the source.

djust-designer

⚠️ Contributors: read docs/HANDOFF.md before starting new work — the scope is being reconsidered (Framer-style no-code builder vs. current class editor), and the feat/regions branch is local-only.

Visual design collaboration layer for djust / Django apps. Point at any element on your running page → see its source template + line → edit its Tailwind classes with automatic write-back → undo with one click. No terminal, no code editor. Ships with a Claude Code MCP bridge so an AI assistant can act on whatever the designer just clicked.

Runs on DEBUG=True only. No traces in production.

Install

Plain Django project:

pip install djust-designer

With Claude Code MCP bridge:

pip install 'djust-designer[mcp]'

Targeting a djust app (pulls djust too):

pip install 'djust-designer[djust,mcp]'

Local development:

pip install -e '.[dev,mcp]'

Wire it up

Distribution name is djust-designer (hyphen) on PyPI; the Python module is djust_designer (underscore) — standard Django-package convention.

# settings.py
INSTALLED_APPS = [..., "djust_designer"]
MIDDLEWARE = ["djust_designer.middleware.DjustDesignerMiddleware", ...]

TEMPLATES = [{
    "BACKEND": "django.template.backends.django.DjangoTemplates",
    "DIRS": [BASE_DIR / "templates"],
    "APP_DIRS": False,
    "OPTIONS": {"loaders": [(
        "djust_designer.instrument.loader.InstrumentedFilesystemLoader",
        [str(BASE_DIR / "templates")],
    )]},
}]

# urls.py
urlpatterns += [path("", include("djust_designer.urls"))]

Using APP_DIRS = True

If your project relies on per-app templates/ directories, use InstrumentedAppDirsLoader instead (or in addition to) the filesystem loader:

TEMPLATES = [{
    "BACKEND": "django.template.backends.django.DjangoTemplates",
    "DIRS": [BASE_DIR / "templates"],
    "APP_DIRS": False,
    "OPTIONS": {"loaders": [
        ("djust_designer.instrument.loader.InstrumentedFilesystemLoader",
         [str(BASE_DIR / "templates")]),
        "djust_designer.instrument.loader.InstrumentedAppDirsLoader",
    ]},
}]

Every template — whether from DIRS or an installed app — is edit-eligible.

Try the demo

cd demo && python manage.py runserver 8737
# open http://localhost:8737

Hover → highlight. Click → panel. Edit class → Apply → source rewritten → hot-reloaded. Undo → previous state.

Panel niceties

• Tailwind autocomplete — the class input suggests ~1,600 common Tailwind utilities as you type. Arrow keys navigate, Enter/Tab inserts.
• Tag label — the panel header shows the selected element's tag name (e.g. <button>) so you always know what you're editing.
• Toast — Apply/Undo produce a small feedback toast so failures are visible.

Claude Code (MCP)

The overlay mirrors the designer's current selection to the server so an MCP client can act on it. Install and register:

pip install -e '.[mcp]'
claude mcp add djust-designer python -m djust_designer.mcp

Then, with the demo (or any djust-designer-wired app) running, ask Claude Code:

"Restyle whatever I just clicked to be rounder with a dark background."

Claude Code calls the MCP tools:

• get_current_selection() — what the designer just clicked (zd_id, file, line, tag, class)
• resolve_id(zd_id) — source location for any data-zd-id visible in the DOM
• edit_class(zd_id, new_class) — rewrite the class attribute (backup-safe)
• undo_last() — restore the most recent snapshot

If the app is on a non-default port, set DJUST_DESIGNER_URL or pass --url when registering:

claude mcp add djust-designer -- python -m djust_designer.mcp --url http://127.0.0.1:9000

Publishing to PyPI

Sanity check first, then build and upload:

pip install -e '.[dev]'
pytest -q && ruff check . && ruff format --check . && ty check
rm -rf dist/
python -m build         # produces dist/*.whl and dist/*.tar.gz
twine check dist/*
twine upload dist/*     # or `twine upload --repository testpypi dist/*` first

Version bumps live in pyproject.toml ([project].version). Tag the release in git before uploading (git tag v0.1.0 && git push --tags).

License

MIT — see LICENSE.

Design docs

• Design: docs/superpowers/specs/2026-07-09-djust-designer-design.md
• Plan: docs/superpowers/plans/2026-07-09-djust-designer-p1-mvp.md