Architecture guide

The NSW Email Design System 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.

Tech 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/tokens and custom colour palettes defined inconfig.js

Directory Structure

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.