Skip to content

Settings Reference

All configuration for Django Design System is defined in your Django settings.py file within the DJ_DESIGN_SYSTEM dictionary.

DJ_DESIGN_SYSTEM = {
    "DESIGN_SYSTEM_NAME": "Django Design System",
    "ENABLE_GALLERY": True,
    # ... other settings
}

Below is a comprehensive list of all available settings and their default values.

General Settings

DESIGN_SYSTEM_NAME

Type: str
Default: "Django Design System"
The name of your design system, displayed in the gallery's navigation bar and page titles.

Type: bool
Default: True
Whether the gallery UI is enabled. If False, the gallery views will return 404 Not Found.

Type: bool
Default: True
If True, the gallery is accessible to anyone. If False, only logged-in staff users (is_staff=True) can view it.

Type: list[NodeType] | str
Default: [NodeType.FOLDER, NodeType.COMPONENT, NodeType.DOCUMENT]
Controls the sorting order of the gallery sidebar navigation. Can specify the order in which folders, components, and documents appear.

Global Assets

GLOBAL_CSS

Type: list[str]
Default: []
A list of global CSS static file paths to include in the gallery canvas and when using {% global_stylesheets %}.

GLOBAL_JS

Type: list[str]
Default: []
A list of global JavaScript static file paths to include in the gallery canvas and when using {% global_scripts %}.

GLOBAL_CSS_BUNDLES

Type: list[tuple[str, ...]]
Default: []
A list of Webpack CSS bundles to load globally. Ignored if django-webpack-loader is not installed. Each entry is a tuple passed to get_files, e.g., ("main",).

GLOBAL_JS_BUNDLES

Type: list[tuple[str, ...]]
Default: []
A list of Webpack JavaScript bundles to load globally.

Canvas Backgrounds

Type: str
Default: "light-grey"
The slug of the default background used for the component preview canvas.

Type: dict[str, dict]
Default: Built-in backgrounds (White, Light Grey, Dark Grey, Black, Checkerboard)
A dictionary completely overriding the available canvas backgrounds. Each value must be a dictionary with label and color keys.

Type: dict[str, dict]
Default: {}
A dictionary of backgrounds merged into GALLERY_CANVAS_BACKGROUNDS. Useful for adding custom backgrounds without removing the built-ins.

Type: dict
Default: {}
Extra HTML attributes applied to the <html> and <body> tags of the canvas iframe globally. Example: {"html": {"class": "govuk-template"}, "body": {"class": "govuk-template__body"}}.

Theming

Type: dict[str, dict]
Default: {"default": {"label": "Default", "html_attrs": {}, "css": [], "js": [], "css_bundles": [], "js_bundles": []}}
A dictionary of available themes. See the Themes documentation for more details.

Themes can also include an optional canvas_background setting to specify a dedicated background colour for the preview iframe when that theme is active. This is highly recommended for dark themes. You can use a built-in slug or a custom dictionary.

Example:

"dark": {
    "label": "Dark Theme",
    "canvas_background": "dark-grey",  # Complements the default light-grey background
    "html_attrs": {"html": {"data-theme": "dark"}},
}

Type: str
Default: "default"
The slug of the default theme selected when loading the gallery.

Type: str
Default: "monokai"
Pygments style used for syntax highlighting in markdown fenced code blocks and canvas code previews. Set to "" to disable highlighting.

App-Specific Configuration

APP_THEMES

Type: dict[str, list[str]]
Default: {}
Restrict the available themes for components in specific apps. Keys are app labels, values are lists of theme slugs.

APP_CSS

Type: dict[str, list[str] | str]
Default: {}
App-specific CSS static file paths loaded when rendering components from that app.

APP_CSS_BUNDLES

Type: dict[str, list[tuple[str, ...]]]
Default: {}
App-specific Webpack CSS bundles loaded when rendering components from that app.

APP_JS

Type: dict[str, list[str] | str]
Default: {}
App-specific JavaScript static file paths loaded when rendering components from that app.

APP_JS_BUNDLES

Type: dict[str, list[tuple[str, ...]]]
Default: {}
App-specific Webpack JavaScript bundles loaded when rendering components from that app.

APP_CANVAS_HTML_ATTRS

Type: dict[str, dict]
Default: {}
App-specific HTML attributes applied to the <html> and <body> tags of the canvas iframe when rendering components from that app.

COMPONENT_NAMESPACES

Type: dict[str, dict]
Default: {}
Configure folder-based namespacing for your components to override the default app-based naming. Keys are app labels, values are dictionaries mapping dotted directory paths to alias strings or configuration dicts.

Example:

DJ_DESIGN_SYSTEM = {
    "COMPONENT_NAMESPACES": {
        "myapp": {
            "": "ui",               # Top-level components map to 'ui' prefix
            "button": "btn",        # button directory maps to 'btn' prefix
            "card": {"prefix": "cards", "flatten": True}, # Flattens subfolders (e.g. cards__hero instead of cards__layouts__hero)
        }
    }
}

When mapping to a simple string, subfolders are preserved by default (flatten: False). Set flatten: True to discard subfolder paths in the resulting tag names.