A theme extension that implements the NSW Design System for CKAN.
Originally built as a collection of standalone macros, this extension has been rewritten to provide theme implementations integrated with ckanext-theming. By utilizing ckanext-theming, this extension delivers a decoupled, macro-based UI theme that makes it easy to apply the NSW Design System look and feel to your CKAN portal.
This extension registers the following themes with the ckanext-theming framework:
nds-ui: A base UI library theme containing core macros (buttons, cards, alerts, etc.) structured using NSW Design System HTML and CSS.nsw-design-system: The primary end-user theme that inherits fromnds-uiand applies the complete NSW Design System visual layout, colors, and typography across CKAN pages.
| CKAN version | Compatible? |
|---|---|
| 2.9 | no |
| 2.10 | yes |
| 2.12 | yes |
Note
To use the theme integration features, ckanext-theming must be installed.
Below are placeholders for screenshots of the NSW Design System theme in action. (These will be populated soon!)
Ensure your CKAN virtual environment is activated, then install both ckanext-theming and ckanext-nswdesignsystem:
pip install ckanext-theming
pip install ckanext-nswdesignsystemAdd both theming and nswdesignsystem to the ckan.plugins setting in your CKAN configuration file (e.g., ckan.ini):
ckan.plugins = ... theming nswdesignsystemEnable the NSW Design System theme by specifying it in the ckan.ui.theme config option:
ckan.ui.theme = nsw-design-systemYou can customize the extension behavior by adding the following settings to your CKAN configuration file:
| Config Option | Type | Default | Description |
|---|---|---|---|
ckanext.nswdesignsystem.legacy_enabled |
bool |
true |
Enable legacy templates and components created before the theming integration. (Deprecated; will be removed in a future release) |
ckanext.nswdesignsystem.css_enabled |
bool |
true |
Automatically load NSW Design System CSS assets. |
ckanext.nswdesignsystem.js_enabled |
bool |
true |
Automatically load NSW Design System JavaScript assets. |
ckanext.nswdesignsystem.debug |
bool |
false |
Enable debug options for CSS and JS assets. |
Important
The legacy macros are deprecated and planned for removal. Users are strongly encouraged to migrate to the new ckanext-theming base themes.
If you have enabled ckanext.nswdesignsystem.legacy_enabled = true, you can use the old standalone components:
- Visit the
/nswdesignsystem/componentspage to view implemented components and code examples. - Call components in templates using macro syntax:
Or:
{{ masthead() }}{% call masthead() %} {# additional content for masthead #} {% endcall %}
To install ckanext-nswdesignsystem for development, activate your CKAN virtualenv and run:
git clone https://github.com/DataShades/ckanext-nswdesignsystem.git
cd ckanext-nswdesignsystem
pip install -e .We follow the Conventional Commits specification:
- Features:
feat: <description> - Bug Fixes:
fix: <description> - Maintenance / Chores:
chore: <description>
The extension wraps the official nsw-design-system package. To update the underlying NSW Design System library:
- Update the library using
npm:npm up nsw-design-system
- Copy compiled assets into the vendor folder:
make vendor
- Update source files in the assets directory:
make nsw-source
(Note: Custom behaviors are applied via patches located in the patches/ folder during the build process.)
make vendor and make nsw-source do not replace the locally hosted fonts in
public/nswdesignsystem/fonts. If an NSW Design System update changes the font
family, weights, or icon font requirements, update the font files, fonts.css,
checksums, and licenses together.
Fonts and the optional Chartist chart component are served from this extension's
public/ directory. make vendor and make nsw-source do not replace those
assets. The NSW Design System package assets loaded from unpkg are version-pinned
and include Subresource Integrity metadata.
The conditional Google reCAPTCHA loader remains an exception: its response is
dynamic, so a fixed SRI hash would break the challenge. It is rendered only when
g.recaptcha_publickey is configured.
To execute tests, run:
pytestTo publish a new release of ckanext-nswdesignsystem on PyPI:
- Update the version number in
setup.cfg. - Make sure you have the required release tools:
pip install -U twine build git-changelog -r dev-requirements.txt
- Build and update the changelog:
make changelog
- Create source and binary distributions:
python -m build
- Upload to PyPI:
twine upload dist/* - Commit and push the tag:
git commit -a git push git tag v0.2.19 # Replace with actual version from pyproject.toml git push --tags
---
## License
[AGPL-3.0](https://www.gnu.org/licenses/agpl-3.0.en.html)


