django-showroom 0.1.0a1

Django-native component development environment for building design systems

Django Showroom

A Django-native component development environment for building design systems. Develop, document, and test atomic UI components in isolation – with multi-framework rendering, shared story contracts, and side-by-side comparison.

Why this project

Most teams with Django + frontend islands struggle with two recurring issues:

1. Story drift across rendering frameworks.
2. Styling drift across implementations.

This architecture solves both by making contracts and styling framework-agnostic first, then implementing thin adapters.

Installation

pip install django-showroom

Then add it to your Django project:

# settings.py
INSTALLED_APPS = [
    ...
    "django_cotton",
    "showroom",
]

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

urlpatterns = [
    path("showroom/", include("showroom.urls")),
]

You'll also need Node.js (>=20) for the build step:

npm install
npm run build

Then start your Django dev server and open /showroom/.

How it differs from Storybook.js

	Django Showroom	storybook-django (Torchbox)
Architecture	Django-native – single server	Storybook.js wrapper – requires Django + Node servers
Story format	JSON contracts (component.json, stories.json)	JavaScript CSF (Component Story Format)
Multi-framework	Cotton, React, Alpine, HTML, vanilla JS – simultaneously	Django templates only (rendered via API)
Split view	Built-in side-by-side framework comparison	Not available
Design tokens	Built-in recipe engine for variants and CSS tokens	External (BYO)
Focus	Atomic design system components	Template previews

Adding components

Create a new directory under components/cotton/ds/your_component/ with:

your_component/
├── component.json            # Metadata (slug, label, adapter paths)
├── stories.json              # Story definitions with defaults
├── stories/
│   ├── controls.json         # Control field definitions
│   ├── default.html          # Django/Cotton story template
│   └── react.preview.ts      # React story renderer (optional)
└── index.html                # Cotton component template

Then run npm run build to validate and regenerate the registry.

Example components

The repo ships with 3 example components demonstrating a complexity gradient:

• Button – simple, static component with variant/size controls
• Badge – medium complexity with data-attribute-driven styling
• Text Field – complex form input with label, icons, error states

Each component includes a component.json contract, stories, controls, a Cotton template, and a React preview – showing how one story definition renders identically across frameworks.

Development setup

python3 -m venv .venv
source .venv/bin/activate
pip3 install -e ".[dev]"
npm install
npm run build
python3 manage.py runserver

Open: http://127.0.0.1:8000/showroom/

Docs

• Architecture overview
• Contract details
• Adapter boundary
• Recipe model
• Split mode behavior
• Adding components

License

MIT