Architecture guide
The NSW Email Toolkit framework is a Node.js project that provides reusable components, layouts, and tooling for building accessible, responsive HTML emails. It leverages the Maizzle framework and NSW Design System tokens to deliver production-ready email templates.
Technology stack
- Runtime and tooling: Node.js (ES modules)
- Core framework: Maizzle (development server and production builds)
- Styling: Tailwind CSS with a custom Tailwind config and
tailwindcss-preset-emailpreset - Design tokens:
@nswds/tokensand custom colour palettes defined inconfig.js
Directory structure
| Path | Purpose |
|---|---|
components/ | Small, reusable HTML partials (e.g., button, image, section) |
blocks/ | Larger content patterns (e.g., headers, footers, galleries) |
layouts/ | Wrappers providing document skeleton; main.html is the default layout |
emails/ | Component demo pages used to generate the documentation site |
templates/ | Starter email templates grouped by purpose (welcome, announcement, etc.) |
images/ | Static assets copied to docs/assets during build |
docs/ | Compiled output for demos and production builds |
lib/ | Utility functions and colour definitions |
config.js | Base Maizzle configuration, design tokens, and build settings |
config.production.js | Production overrides for Maizzle builds |
The config.js file specifies which folders contain components and how static assets are handled during builds.
Configuration and utilities
config.js
- Defines colour palettes (
palettes,theme,semantic) and brand assets (logo,social). - Provides global layout values such as
width,padding, and column layouts generated via utility functions. - Exposes component folders and build settings to Maizzle, ensuring templates and static assets are processed correctly.
tailwind.config.js
- Extends Tailwind with the email preset, points content scanning to component/layout/email files, and safelists responsive/colour utilities.
- Adds a custom plugin that generates colour-based utility classes and mobile helpers.
lib/utils.js
- Helper functions for typography (
toUnitlessLH), layout generation (generateColumnLayouts), colour manipulation (generateTint), and ratios (parseRatio).
Components, blocks, and layouts
Components (components/)
Each component is an HTML partial with an optional <script props> block. Props are processed by Maizzle before rendering. Example: components/button.html exposes style and behaviour settings for different button variants.
Blocks (blocks/)
Blocks combine multiple components into higher-level patterns (e.g., footers, galleries). They also use<script props> to define configurable options, making them reusable in templates and documentation pages.
Layouts (layouts/)
layouts/main.html sets up the document structure, meta tags, font loading, reset styles, responsive behaviour, and an optional preheader. It includes embedded Tailwind styles and a script to adjust theme tokens dynamically.
Templates and emails
- Templates (
templates/): Starter emails grouped by use case (e.g.,welcome,announcement). Each template subfolder contains one or more numbered variations (1/index.html), allowing multiple examples under a category. - Emails (
emails/): Demo pages illustrating individual components and blocks. These are compiled to the documentation site for preview.
Development workflow
Dev server
npm run dev starts Maizzle in watch mode, compiling templates and components into thedocs directory.
Production build
npm run build runs Maizzle with the production configuration, generating minified HTML and copying assets to docs.
Accessibility checks
Optional scripts run automated accessibility testing against compiled output:
npm run a11y(axe CLI)npm run a11y:lighthouse(Lighthouse CI)
Customisation and theming
- Design tokens (colours, typography) are centralised in
config.js. - Tailwind utilities can be extended or safelisted via
tailwind.config.js. - Images placed in
images/are automatically copied to the output during builds. - Template authors can import components/blocks using custom tags (
<x-button>,<x-header>) and override props as needed.
Summary
The NSW Email Framework structures email development around Maizzle, Tailwind, and NSW Design System tokens. A clear separation of components, blocks, layouts, and templates—backed by configurable utilities—enables quick creation of accessible, responsive email HTML. The project's scripts and configuration files orchestrate building, theming, and accessibility testing, making it a robust foundation for NSW Government email communications.