How to contribute

How to propose and contribute components, layouts, utilities, templates, docs and examples to the NSW Government email framework.

Scope and goals

The NSW Email Toolkit helps teams build brand-safe, accessible and reliable emails quickly. This guide explains who can contribute, what qualifies, and how to design, code, test and document proposals.

What you can contribute

• Components (headers, hero, feature blocks, buttons, dividers, footers)
• Layouts (single-column, two-column, newsletter index)
• Utilities (spacing helpers, colour tokens, table patterns)
• Templates (announcement, transactional, receipt, newsletter)
• Documentation and examples (guides, snippets, usage notes)

Access and roles

Downloading the framework (all users)

• Sign in with NSW Government Microsoft SSO.
• Go to Dashboard → Downloads and fetch the latest release package.
• Unzip locally, then run npm install.

Contributing code (private GitHub)

• The GitHub repository is private; external forks are disabled.
• Two contribution paths:
  • With repo access (approved): create a branch and open a PR directly.
  • Without repo access: submit a Contribution Proposal. A maintainer will mirror your change into a PR or grant temporary access.

Roles

• Contributors author changes and docs.
• Maintainers review, request changes, merge and publish releases.
• Stakeholders (brand, accessibility) provide expert sign-off as required.

Inclusion criteria (what we accept)

Meet real user needs (Useful)

• Address a need shared by multiple NSW services or products, not a one-off.
• Show versatility with examples across different contexts; link to research or discussion.

Avoid duplication (Unique)

• Do not duplicate existing components unless you are clearly replacing them.
• Prefer extending or improving what exists.

Distinctly NSW (Brand)

• Use NSW Design System tokens for colour, spacing and typography.
• Lead with brand clarity: approved logo, Public Sans (with fallbacks) and masterbrand palette.

Accessibility

• Aim for WCAG 2.1 AA (and 2.2 AA where feasible).
• Semantic HTML, meaningful alt text, clear link text, logical headings.
• Interactive patterns must support keyboard or provide a non-interactive fallback.

Cross-client reliability

• Prove rendering in Outlook (Win/Mac/365), Apple Mail, Gmail (Web/Android/iOS), Yahoo.
• Test at common widths and with images disabled.

Versatility and robustness

• Responsive within email constraints (max width ≈ 640px; fill parent width where appropriate).
• Handle varied content lengths gracefully.

Evidence before publication

• Prefer task-based testing or evidence from a live/beta environment.
• Provide a brief rationale and known trade-offs.

Coding standards (emails)

Technologies and structure

• Maizzle + Tailwind CSS + PostHTML components.
• Favour table-based layouts; inline CSS where required for client support.
• Keep components small, focused and composable.

Tokens and theming

• Use NSW tokens for colour, spacing and type; don't hard-code brand values.
• Prefer existing utilities before adding new rules.

Component API and naming

• Kebab-case folders and clear names (e.g. x-button.solid).
• Expose minimal, meaningful props with sensible defaults.

JavaScript

• Avoid JS in emails; if unavoidable, degrade gracefully with JS disabled.

Linting and checks

• Follow formatting and style rules.
• Add/update automated a11y checks (e.g. npm run a11y:*) where applicable.

Folder layout (illustrative)

components/
  button/
    index.html    # component markup
    README.md     # usage, props, a11y notes
  layouts/
    single-column.html
  templates/
    announcement/
    index.html
images/
config/
  tailwind.config.js
  maizzle.config.js

Best practices (design)

Lead with brand clarity

Use the NSW logo, approved typography and colour tokens for immediate recognition. The Footer restates identity with contact details and required legal links.

Compose from proven parts

Build emails by combining components (headers, hero, feature blocks, buttons, dividers, footers). Each solves a specific layout need without overlap.

Keep it accessible

Ensure sufficient contrast, descriptive alt text, meaningful link text and predictable layout.

Keep it simple

Avoid decorative imagery that doesn't serve the task. Prefer concise copy and clear hierarchy.

How to propose a contribution (no repo access needed)

• Describe the problem — user, task, and why existing components aren't enough.
• Show the solution — screenshots, example HTML, or a small prototype built on the downloaded package.
• Prove reusability — list at least 2–3 contexts where it will be reused.
• Accessibility notes — how you've met WCAG; email-client constraints.
• Cross-client evidence — attach Litmus/Email on Acid results or screenshots.
• Attach code — minimal component folder (markup + README) or a diff against the latest release.

Contact us using our contact form or email us at appsupport@customerservice.nsw.gov.au and a maintainer will review and either request changes, create a PR on your behalf, or grant temporary collaborator access.

Standard PR process (approved contributors)

• Create a branch — feat/component-<name>, fix/<area>-<summary>, or docs/<topic>.
• Build your change — add files under the correct folder; include a README.md (purpose, props, examples, a11y notes, limitations).
• Tests and checks — run build, a11y checks, and render tests; include screenshots of key clients.
• Docs — update guides/ or docs/ with usage notes and sample markup.
• Open a Pull Request — describe user need, rationale, screenshots, test matrix, breaking changes, migration notes.
• Review — maintainers assess usefulness, uniqueness, brand, a11y, reliability, versatility and code quality.
• Merge and release — on approval, maintainers merge and include in the next release; changelog credits contributors.

Documentation requirements

• Usage notes, limitations and example markup (compose in a typical email).
• Behaviour with long content, images off, or multiple CTAs.
• Any required build steps or dependencies.
• Guidance on tokens (what can be customised safely).
• Accessibility considerations (reading order, alt text guidance, contrast).

Testing requirements

• Rendering matrix — Outlook (Win/Mac/365), Apple Mail, Gmail (Web/Android/iOS), Yahoo.
• Scenarios — default, long content, images off, high DPI, dark mode (where supported).
• Graceful degradation — no-JS fallback; images-off is usable; table structure intact.
• Accessibility checks — headings, alt text, link text, contrast, focus order (if interactive).

Attach screenshots or a brief report to the PR or proposal.

Governance and decision criteria

We are caretakers of the system on behalf of NSW Government teams. Reviews aim to keep the system useful, unique and consistent; protect brand clarity and accessibility; and avoid bloat and overlapping patterns.

Outcomes may be accept, accept with changes, incubate (ship as a template/example first), or decline (with rationale and alternatives).

Credit and releases

• Contributors are credited in the CHANGELOG and release notes.
• Significant additions may trigger a minor release; breaking changes include migration notes.

Quick checklists

Questions

If you're unsure whether your idea fits, submit a proposal anyway. The worst that can happen is we'll politely ask for changes or suggest a better home for it. We value and thank you for all well-intentioned contributions.