Skip to content

Building and Maintaining a Visual Identity for Noiz Cybersecurity: A FOSS, Git-Native Brand-System Playbook

  • Treat the brand guide as code. For a one-person, GNU/Linux-comfortable operation, the right substrate is a single Git repository — noiz-brand — containing Markdown documentation, vector source assets (SVG), a W3C-DTCG–conformant tokens.json, and a Hugo or Astro static site that renders the guide as a living micro-site. Version it with SemVer 2.0.0, log changes in a CHANGELOG.md that follows the Keep a Changelog 1.1.0 convention, and tag releases (v1.0.0, v1.1.0).
  • Adopt design tokens now, but lightly. The W3C Design Tokens Community Group’s Format Module reached its first stable version (2025.10) on 28 October 2025. Define colour, type, spacing and radius tokens in a single tokens.json and use Style Dictionary to emit :root CSS custom properties for noiz.co.za / noiz.ie. This is the smallest piece of “design-system” machinery that gives you genuine single-source-of-truth behaviour without enterprise overhead.
  • Model the structure on a proven public reference. Copy the directory shape and governance conventions from alphagov/govuk-frontend (MIT-licensed, SemVer, single-root CHANGELOG.md, docs/contributing/versioning.md, tagged releases). It is the closest realistic template for a small, technically-led brand/system repo, and it does not over-engineer with the monorepo complexity of IBM Carbon.
  1. There is no single ISO or industry-mandated structure for a brand guide, but a strong consensus has emerged across reputable agency, vendor and design-system literature on the components a mature guide contains (strategy, logo system, clear space, misuse, colour, typography, iconography, imagery, voice/tone, accessibility, applications, asset index). ISO 20671:2019 (Brand evaluation — Principles and fundamentals) exists, but it governs how a brand is valued, not how its visual guidelines are authored.
  2. A “brand guidelines PDF” and a “design system” are different artefacts on a continuum. A PDF is a frozen snapshot; a design system is living documentation backed by tokens, components and code. Practitioners increasingly recommend digital, searchable brand guidelines over static PDFs because PDFs go stale and cannot be linked to live assets.
  3. The W3C Design Tokens Community Group (DTCG) Format Module reached its first stable release, 2025.10, on 28 October 2025. This is the right standard to adopt today: it is JSON-based, vendor-neutral, and has reference implementations in Style Dictionary, Tokens Studio and Terrazzo, with broader support across Penpot, Figma, Sketch, Framer, Knapsack, Supernova and zeroheight.
  4. Semantic Versioning (SemVer 2.0.0) is the dominant scheme across public design systems — used by GOV.UK Frontend, IBM Carbon, Atlassian, Morningstar, Twilio Paste and others. Calendar Versioning (CalVer) is a legitimate alternative when the brand guide is treated as a continuously-iterating internal document rather than a dependency consumed by other repos, but SemVer is the more defensible default because most readers already understand it.
  5. Git is the correct substrate for the guide. Multiple public brand/design-system repos (GOV.UK, IBM Carbon, Mozilla, GitHub’s own Brand Toolkit) are maintained in Git. For Noiz, a single repo with a static-site generator (Hugo or Astro) and an automated build (CI emits PDF + CSS + asset zips on tag) is the right shape.
  6. The dominant component methodology is Brad Frost’s Atomic Design (atoms → molecules → organisms → templates → pages), self-published as a book in 2016 (ISBN 9780998296609). It is not relevant to a small static marketing site at the component level, but its mental model — primitives compose into bigger things — maps cleanly onto the way design tokens layer (primitive → semantic → component).
  7. For a one-person operator, a self-hosted DAM (ResourceSpace, Pimcore, Phraseanet) is overkill. Nextcloud plus a Git repo gives you everything a DAM does at this scale: versioned files, sharing, access control, and search.

1. What a complete VI / brand guide contains

Section titled “1. What a complete VI / brand guide contains”

A “mature” brand guide is layered, and the inventory below synthesises the structures published by Bynder, Acquia, Brand Vision, Studio Noel, Spellbrand and the publicly-available brand systems of GOV.UK, IBM, Mailchimp, FedEx, GitHub, Slack, Mozilla and Spotify. Treat each item below as a required section until you have a positive reason to omit it for Noiz:

Brand strategy / essence — mission, vision, values, positioning, single-sentence “elevator description” of Noiz, target audience (Irish/South African SMBs needing managed security and hosting), tone-defining adjectives. This section answers why we communicate the way we do and gives every subsequent rule a reason to exist. Brand Vision specifically warns that “without that foundation, the rules in the rest of the document feel arbitrary” and “teams are far more likely to follow brand guidelines when they understand the reasoning behind them.”

Logo system — primary logo, secondary/horizontal lockups, monochrome and reversed versions, icon/symbol-only mark, favicon, sub-marks. Each variant must ship as SVG (source of truth), PNG (1x, 2x, 3x) and ideally as an inline-embeddable SVG snippet.

Clear space and minimum sizes — defined as a multiple of an internal measure (commonly the cap-height or the height of a glyph in the wordmark); minimum pixel and millimetre sizes for digital and print.

Misuse — explicit “don’t” gallery: do not stretch, recolour, rotate, place on insufficient-contrast backgrounds, add effects, redraw, etc. Slack’s public guide and FedEx’s quick reference are exemplary in how concretely they show this.

Colour palette and specifications — primary, secondary, accent and neutral palettes. Each colour gets HEX, RGB, HSL and ideally Oklch or Display-P3 values (the DTCG 2025.10 spec supports modern colour spaces), plus CMYK and Pantone for any print collateral and WCAG contrast pairings documented as an accessibility matrix.

Typography — typeface families, fallback stacks, type scale (size + line-height + tracking + weight), web-font hosting decisions, licensing notes, do/don’t examples. Use weights that exist in the chosen family — a chronic source of brand drift.

Iconography — line vs filled, stroke width, corner radius, grid, sizing.

Imagery / photography direction — subject matter, colour grading, what not to show, stock-photo policy, AI-generated imagery policy (worth an explicit position for a cybersecurity brand).

Motion — easing curves, default durations, attitude (Noiz: probably “restrained, technical, no bounce”). Mailchimp’s published system covers this well.

Voice and tone — vocabulary, what you call yourself (“Noiz,” not “Noiz Cybersecurity Ltd” in body copy), banned words, sentence-length guidance, register shifts (sales page vs incident-response email vs status-page outage). The Mailchimp Content Style Guide and IBM Carbon’s content guidelines are the canonical public examples.

Accessibility — WCAG 2.2 AA as the floor, contrast pairings, focus-state behaviour, alt-text conventions, motion-reduction commitments. Studio Noel and Acquia both flag accessibility as a section that should sit inside the brand guide rather than be punted to a separate developer document.

Applications / templates — business card, letterhead, email signature, social/OG image, presentation deck, invoice header, status-page styling, customer report cover.

Asset index — a manifest at the end of the guide listing every downloadable asset, its filename, format, intended use and licence. This makes the guide self-describing.

Governance / contact / change process — who decides on changes, how to propose one, where the canonical repo lives. Brandkit calls this “the easiest thing to add to your guidelines—but often overlooked.”

Distinction — guidelines PDF vs design system. A lightweight PDF guide is fine for the strategic, narrative content. A design system — Frontify’s definition, also used by Carbon, GOV.UK and Polaris — adds reusable code components, design tokens, an accessibility contract, a contribution model and versioned releases. For Noiz at one-person scale, the right midpoint is: a living HTML brand-guide micro-site that includes a real tokens.json and a tiny CSS component library used by the marketing site, but not a full per-framework component library.

2. Downstream assets the guide produces, and how it stays the single source of truth

Section titled “2. Downstream assets the guide produces, and how it stays the single source of truth”

A well-designed guide is the upstream node of a dependency graph. Penpot’s documentation frames this well: tokens become “a centralized repository that bridges the gap between design intent and code implementation.” The artefacts the Noiz guide should govern are:

  • Logo export packs — generated from the assets/logo/*.svg sources via a Makefile/just/CI step into PNGs at 1x/2x/3x, favicons, social-share images at 1200×630, app icons.
  • Design tokens — tokens.json in DTCG 2025.10 format, transformed by Style Dictionary into dist/css/tokens.css, dist/scss/_tokens.scss, and dist/js/tokens.js.
  • CSS / theme — colour, type and spacing variables consumed by noiz.co.za and noiz.ie.
  • Email-signature template — a generated HTML snippet.
  • Document templates — LibreOffice/Markdown templates for invoices, proposals, incident reports, with brand colours pulled from tokens by build script.
  • OG / social images — generated programmatically (e.g. via resvg or satori) so that a colour change in tokens.json rebuilds all social cards on the next CI run.
  • Component fragments — a handful of styled HTML snippets (button, card, alert) for landing-page work.

The single-source-of-truth discipline rests on one rule: nothing on the website or in collateral should hard-code a brand value. Every colour, font and spacing should resolve back to a token. This is what Penpot, Salesforce (whose design-system team originated the concept) and the DTCG describe as the “single source of truth” property — change color-brand-primary in tokens.json, run the build, and noiz.co.za, the email signature, the report cover and the proposal template all update.

Specification status. The Design Tokens Community Group (DTCG) — a W3C Community Group — published its first stable specification, Design Tokens Format Module 2025.10, on 28 October 2025. The W3C announcement states verbatim: “The Design Tokens Community Group today announced the first stable version of the Design Tokens Specification (2025.10) … the specification provides a production-ready, vendor-neutral format for sharing design decisions across tools and platforms.” DTCG co-chair Kaelig Deloumeau-Prigent is quoted in the same release: “The specification unlocks interoperability across design tools and code. Design systems teams can now maintain one source of truth that works everywhere — from design to production code across iOS, Android, and web.” The stable spec is at https://www.designtokens.org/tr/2025.10/, the JSON schema at https://www.designtokens.org/schemas/2025.10/format.json, and files use the .tokens.json extension and application/design-tokens+json media type.

Important caveat to flag honestly: A DTCG Community Group Report is not a W3C Recommendation. The spec’s own draft page carries the standard W3C disclaimer: “This specification was published by the Design Tokens Community Group. It is not a W3C Standard nor is it on the W3C Standards Track.” That said, with reference implementations in Style Dictionary, Tokens Studio and Terrazzo and adoption across Penpot, Figma, Sketch, Framer, Knapsack, Supernova and zeroheight, it is the de facto industry standard. For a small operator there is no better choice today.

What tokens are. A token is a named variable storing a design decision. color.brand.primary = #1A73E8 becomes --color-brand-primary in CSS, UIColor in iOS, an XML colour resource in Android. The DTCG 2025.10 JSON format uses $value, $type, $description keys; supports inheritance, aliases ({path.to.token}), modern colour spaces (Display P3, Oklch, CSS Color Module 4) and theming/multi-brand variants.

Three-tier architecture. The token convention every mature system uses is primitives → semantics → component tokens:

  • Primitives — raw values: color.blue.600 = #1A73E8, space.4 = 16px.
  • Semantics — intent: color.brand.primary = {color.blue.600}, color.text.body = {color.grey.900}.
  • Component tokens — application: button.bg.primary = {color.brand.primary}.

Changing the brand colour means editing one primitive; everything downstream updates. Dark mode is achieved by redefining semantic tokens for a second theme. The most-cited writing on this architecture is Nathan Curtis (EightShapes), “Versioning Design Systems: Communicating Change Clearly to People Using Systems” (EightShapes/Medium, August 2018, https://eightshapes.com/articles/versioning-design-systems/), which opens: “Every discussion about versioning design system outputs begins and ends with the industry standard Semantic Versioning (SemVer).”

Tooling. Style Dictionary is the dominant transformer: it ingests tokens.json and emits per-platform output (CSS custom properties, SCSS variables, JS module, iOS Swift, Android XML). It was created by Danny Banks, a design technologist at Amazon’s Seller Mobile team, and open-sourced in summer 2017 per the AWS Open Source Blog; in August 2023 the Tokens Studio team, led by Joren Broekema, officially joined the maintenance effort. It has first-class DTCG support from v4 with v5 work in progress for full 2025.10 coverage. Alternatives: Terrazzo (PostCSS-friendly, by Drew Powers), Theo (Salesforce, lighter). All are free and open source.

Assessment for a small operator. Adopt tokens now, but small. A tokens.json with ten colours, a six-step type scale, a six-step spacing scale and four radii is ~80 lines of JSON. A 20-line Style Dictionary config emits tokens.css. This is two evenings of work and saves you forever from “what was the exact hex of the brand blue again?” The DTCG stable release of October 2025 removed the previous risk that you would adopt a moving target.

Use Semantic Versioning 2.0.0. Every serious public design system uses SemVer: GOV.UK Frontend, IBM Carbon, Twilio Paste, Atlassian, Morningstar Design System. GOV.UK Frontend’s docs/contributing/versioning.md is an excellent precedent — verbatim: “We follow Semantic Versioning but a UI library often has subjective changes such as visual spacing changes. … Breaking changes correspond to a major (1.X.X) change. New features or deprecations correspond to a minor (X.1.X) change. Bug fixes correspond to a patch (X.X.1) change.” The contract adapts cleanly to a brand guide:

  • MAJOR (X.0.0) — breaking changes: new logo, primary palette change, typeface change, anything that invalidates printed collateral.
  • MINOR (0.X.0) — additive: a new secondary palette, a new template, a new icon set, a new application section.
  • PATCH (0.0.X) — corrections: typo fixes, clarified wording, new misuse example, asset re-export with same visual output.

Calendar Versioning (CalVer) is a defensible alternative if you prefer dates (e.g. 2026.05.0), but it loses the severity-of-change signal SemVer carries. CalVer makes sense when the guide is changing on a fixed cadence and downstream consumers care more about “how fresh is this” than “did anything break.” For Noiz, SemVer is the recommended default; the brand changes irregularly and the breaking-vs-additive distinction is meaningful.

Changelog. Keep a single CHANGELOG.md at the root, following the Keep a Changelog 1.1.0 convention. The standard header (verbatim) is: “All notable changes to this project will be documented in this file. The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.” Sections per release: Added, Changed, Deprecated, Removed, Fixed, Security. The IBM Carbon ecosystem (e.g. carbon-icons-svelte) uses this verbatim convention; so does the wider GOV.UK ecosystem (e.g. the govuk-frontend-jinja port). GOV.UK Frontend’s own CHANGELOG.md bins entries as Breaking changes, New features, Fixes under an Unreleased section.

Draft vs ratified. Reserve 0.x.y for the pre-public draft (you are iterating; nothing is locked). 1.0.0 is the moment you say “this is the brand.” From that point, anything that lands on main and is tagged is ratified. Use Git branches (draft/<topic>) and pull requests to yourself for changes — the PR template forces you to think about which SemVer category the change belongs to and write the changelog line before merging.

Governance cadence (one-person scaled).

  • Weekly: trivial fixes land directly on main, batched into the next patch release.
  • Quarterly: review the full guide end-to-end; cut a minor release.
  • Annually: sign off the current state, archive a frozen PDF export, audit for drift between guide and live website. This is the moment a one-person business should treat as “board sign-off.”
  • Ad-hoc: a major release for any rebrand or palette change, never silently.

Git substrate. Yes — a Git repository is the right home. It gives you atomic history, blameable change attribution, branchable drafts, signed tags (git tag -s), CI hooks, and offline-first workflow. The GOV.UK Frontend repository (https://github.com/alphagov/govuk-frontend) is the canonical small-team reference: MIT-licensed, SemVer-tagged (v6.1.0 was released 2 March 2026), single root CHANGELOG.md, contribution docs under docs/contributing/, source under packages/ and built outputs under dist/. Top-level layout from the current main branch: .github/ bin/ dist/ docs/ packages/ shared/ tests/ CHANGELOG.md CODEOWNERS CONTRIBUTING.md LICENSE.txt README.md.

Comparison of practical options, weighted for a single FOSS-oriented operator:

Option Pros Cons Verdict for Noiz
Git repository (self-hosted Gitea/Forgejo or GitHub) Atomic history, diffable Markdown/JSON/SVG, tags & releases, CI, free Binary files (PNGs, PDFs) bloat history if not careful — use git-lfs or keep them out and rebuild from sources Primary store
Static micro-site (Hugo or Astro) generated from the repo Living, searchable, linkable, accessible, indexable. Build artefact deployable anywhere Needs a domain (e.g. brand.noiz.co.za) and a tiny build pipeline Public face of the guide
Nextcloud (self-hosted) Operator already runs it; good for distributing finished assets to partners/contractors with link-sharing & expiry Not a source of truth — it stores exports. Versioning model is per-file, not project-level Distribution mirror only
Open-source DAM (ResourceSpace, Pimcore, Phraseanet, AtroDAM) Rich metadata, search, approval workflows, brand portals All require ongoing maintenance; significant overkill for a one-person business; another LAMP-stack to patch Avoid at this scale
Proprietary brand-portal (Frontify, Bynder, Brandfolder) Polished, fast Subscription cost, vendor lock-in, conflicts with FOSS preference Avoid
PDF only Familiar, portable, can sit in Nextcloud Stale within months; cannot link to live assets; cannot diff As an export, not as the source

Recommended layered model. Source of truth is the Git repo. CI publishes (a) a static brand-guide micro-site to brand.noiz.co.za, (b) a versioned tarball of the export pack on each tag, mirrored into Nextcloud at Public/Brand/v<n.n.n>/, (c) a stamped PDF generated by pandoc + WeasyPrint (or Paged.js) for partners/print houses who insist on PDF. The PDF is a derivative — never edit it directly.

Sync hygiene. The Nextcloud copy is one-way pull from CI; you never upload to it manually. This is what keeps the locations from diverging.

6. Recognised standards, frameworks, methodologies and reference systems

Section titled “6. Recognised standards, frameworks, methodologies and reference systems”

Standards:

  • W3C Design Tokens Format Module 2025.10 — covered above; the only widely-adopted formal-ish standard touching this space.
  • ISO 20671:2019 — Brand evaluation — Principles and fundamentals — exists but governs brand valuation, not authoring. (Notably, ISO itself did not have consistent brand guidelines until they engaged the studio Motherbird to build them — a wry counterpoint to the absence of an ISO-authored brand-guideline standard.)
  • WCAG 2.2 (W3C) — referenced by every reputable brand-system author as the accessibility floor.
  • Keep a Changelog 1.1.0 — the de facto convention for human-readable changelogs.
  • Semantic Versioning 2.0.0 (semver.org) — the de facto convention for version strings.

Methodologies:

  • Brad Frost’s Atomic Design — atoms → molecules → organisms → templates → pages. Originally published as a blog post in 2013 and self-published as a book in 2016 (ISBN 9780998296609); widely cited and used as the underlying model in design-token tiering, in Storybook hierarchies and in Carbon/Polaris/Material. Relevant to Noiz as the mental model for component composition, not as a literal directory structure.
  • Style Dictionary methodology (Salesforce origin for the token concept; Amazon for the tool) — primitive/semantic/component token tiering.
  • EightShapes (Nathan Curtis) versioning patterns — most-cited writing on applying SemVer to design systems, specifically “Versioning Design Systems: Communicating Change Clearly to People Using Systems” (August 2018).

Reference brand/design systems to mine for ideas:

  • GOV.UK Design System (https://design-system.service.gov.uk/) and the underlying repo alphagov/govuk-frontend — the cleanest small-team template; SemVer, MIT-licensed, clear governance documents. Their community model is also instructive: governance is explicit (contribution validation process, community manager role, Slack channel, annual user survey, public roadmap).
  • IBM Carbon Design System (https://carbondesignsystem.com/) — comprehensive but a Yarn-workspaces + Lerna monorepo; useful for reading the content guidelines and accessibility patterns rather than copying the structure. Tokens kept as SCSS variables in @carbon/themes with JavaScript exports.
  • Mailchimp Content Style Guide (https://styleguide.mailchimp.com/) — gold standard for voice and tone documentation as a public micro-site.
  • GitHub Brand Toolkit (https://brand.github.com/) — small, tightly-scoped, well-suited as a stylistic reference for a tech brand.
  • Mozilla Brand Portal (https://mozilla.design/firefox/) — well-organised public brand portal with trademark and usage rules; relevant to how Noiz might publish customer-facing brand-asset terms.
  • Shopify Polaris — for a thinking-out-loud rationale alongside each component.

7. Final recommendation — the Noiz adoption plan

Section titled “7. Final recommendation — the Noiz adoption plan”

Repository: one repo, named noiz-brand, hosted on whichever Git provider you already trust (self-hosted Forgejo is fine).

Recommended layout:

noiz-brand/
├── README.md
├── CHANGELOG.md # Keep a Changelog 1.1.0 format
├── LICENSE # All-Rights-Reserved on logo; CC-BY on docs
├── VERSION # Plain text, e.g. "1.2.0"
├── docs/ # The guide content, in Markdown
│ ├── 00-strategy.md
│ ├── 01-logo.md
│ ├── 02-clearspace.md
│ ├── 03-misuse.md
│ ├── 04-colour.md
│ ├── 05-typography.md
│ ├── 06-iconography.md
│ ├── 07-imagery.md
│ ├── 08-motion.md
│ ├── 09-voice-and-tone.md
│ ├── 10-accessibility.md
│ ├── 11-applications.md
│ ├── 12-governance.md
│ └── 99-asset-index.md
├── tokens/
│ └── tokens.json # W3C DTCG 2025.10
├── assets/
│ ├── logo/
│ │ ├── noiz-primary.svg
│ │ ├── noiz-mono.svg
│ │ ├── noiz-mark.svg
│ │ └── favicon.svg
│ ├── icons/ # SVG sprite + individual files
│ └── photography/ # placeholder, mostly empty
├── templates/
│ ├── email-signature.html
│ ├── invoice.odt
│ ├── proposal.md
│ └── incident-report.md
├── site/ # Hugo or Astro source for brand.noiz.co.za
│ ├── config.toml
│ ├── content/ # symlinked from ../docs/
│ ├── layouts/
│ └── static/
├── build/ # Build scripts
│ ├── style-dictionary.config.mjs
│ ├── Makefile
│ └── ci.sh
└── .github/ # or .forgejo/ — workflow files
└── workflows/
└── release.yml

Versioning: SemVer 2.0.0; start at 0.1.0 while drafting, cut 1.0.0 when you sign off on the brand. Use signed Git tags (git tag -s v1.0.0).

Changelog: CHANGELOG.md at repo root, Keep a Changelog 1.1.0 format. Header: “All notable changes to this project will be documented in this file. The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.”

Design tokens: Adopt DTCG 2025.10 from day one. tokens/tokens.json is the source. Style Dictionary v4+ emits dist/css/tokens.css (CSS custom properties on :root), dist/scss/_tokens.scss, and dist/js/tokens.js. The noiz.co.za / noiz.ie websites consume tokens.css directly. No hard-coded brand values anywhere downstream.

Build / publish workflow:

  1. Edit Markdown / SVG / tokens locally on Linux in your editor of choice.
  2. make build runs Style Dictionary (tokens → CSS), inkscape/rsvg-convert (SVG → PNG export pack), hugo/astro build (micro-site), pandoc + WeasyPrint (Markdown → PDF).
  3. CI on tag push: build all of the above, publish the micro-site to brand.noiz.co.za, copy the export pack tarball to Nextcloud, attach the PDF and zip to the Git release.
  4. The websites noiz.co.za and noiz.ie pull tokens.css from the brand repo (vendored on their own build, pinned to a tag — not an unstable live link).

Tooling stack — all FOSS:

  • Git + Forgejo (self-hosted) or GitHub (public).
  • Hugo (Go, single binary, fast — best fit for a sysadmin) or Astro (modern, more flexible, more dependencies). Recommend Hugo for this use case.
  • Style Dictionary (Node, Apache-2.0) for token transformation.
  • Penpot (self-hostable, MPL-2.0) if you want a design tool with native W3C-DTCG token support — relevant if you ever bring in a contractor.
  • Inkscape / rsvg-convert for raster export.
  • Pandoc + WeasyPrint or Paged.js for HTML→PDF.
  • Forgejo Actions / GitHub Actions / Drone for CI.
  • Nextcloud for distribution-only mirroring.

Governance cadence:

  • Trivial fixes: patch release within a week.
  • Quarterly: end-to-end review; cut a minor release if anything is added.
  • Annually: signed major review; reconcile guide against the live website; archive a stamped PDF.
  • Any logo or palette change: forces a new major version with a written rationale in the changelog.

What not to do:

  • Don’t put the brand guide in a Google Doc, Notion page or Figma file as the source of truth. Those are fine as scratchpads but cannot be tagged, signed, or diffed.
  • Don’t adopt an open-source DAM at one-person scale. The maintenance cost is higher than the benefit.
  • Don’t author components per framework. Ship one CSS file derived from tokens; let the website consume it.
  • Don’t ship un-versioned brand assets. Every export should carry the SemVer string in either the filename or an embedded metadata field.

Stage 0 — Now (1 evening):

  • Create noiz-brand repo. Add README.md, empty CHANGELOG.md with the Keep a Changelog 1.1.0 header, LICENSE, and the directory skeleton above.
  • Tag v0.1.0.

Stage 1 — Within 2 weeks:

  • Write docs/00-strategy.md through docs/12-governance.md in plain Markdown. Don’t optimise for design yet — just capture the rules.
  • Vector the logo into assets/logo/*.svg. Confirm the SVGs render correctly in browsers and in rsvg-convert.
  • Write tokens/tokens.json covering colour, type scale, spacing scale, radii. Validate against the DTCG 2025.10 schema (https://www.designtokens.org/schemas/2025.10/format.json).
  • Tag v0.5.0.

Stage 2 — Within 1 month:

  • Add Style Dictionary; emit dist/css/tokens.css.
  • Stand up the Hugo micro-site; deploy to brand.noiz.co.za.
  • Update noiz.co.za and noiz.ie to consume tokens.css from the brand repo (vendored at a pinned tag). Replace every hard-coded colour and font-size in those sites with var(--*).
  • Cut v1.0.0 — this is the moment the brand is “ratified.”

Stage 3 — Within 3 months:

  • Add CI: on push of a v*.*.* tag, build all artefacts, deploy micro-site, mirror export pack to Nextcloud, attach release assets.
  • Generate the email signature template from tokens.
  • Generate OG/social images from tokens via resvg.

Stage 4 — Ongoing:

  • Quarterly review + minor release.
  • Annual signed major review.
  • Any new application (a new template, a new partner-facing artefact) is added under templates/ and documented in the next minor release.

Benchmarks that would change the recommendation:

  • If Noiz grows past ~5 people: consider promoting from a single repo to a multi-package monorepo (Carbon-style with Yarn workspaces + Lerna) and adding Storybook for the component layer.
  • If you start producing significant photography or video: introduce a self-hosted DAM (ResourceSpace is the most mature FOSS option) as a mirror of assets/photography/, not a replacement for the Git repo.
  • If you take on contractors: Penpot (self-hosted) becomes worthwhile because it natively reads/writes the same tokens.json you already maintain — it was the first design tool to implement native W3C-DTCG support.
  • If you ever need iOS/Android brand assets: Style Dictionary already emits them — add the platform config; the tokens don’t change.
  • The DTCG spec is a Community Group Report, not a W3C Recommendation. The 2025.10 release is explicitly described by the DTCG as production-ready and is backed by reference implementations, but the W3C boilerplate disclaimer remains: “It is not a W3C Standard nor is it on the W3C Standards Track.” In practice this is now the industry standard, but be aware that the formal status sits one rung below ISO/W3C-Rec.
  • There is no ISO or industry standard prescribing what a brand-guideline document must contain. The section list above is a synthesis of reputable practitioner consensus, not a ratified standard. ISO 20671 governs brand valuation, not brand-guideline authoring.
  • Cost of token tooling. Style Dictionary v5 work for full 2025.10 coverage is ongoing; v4 has first-class DTCG support but does not yet implement every modern colour-space feature of 2025.10. For Noiz’s needs (sRGB hex colours) this is irrelevant today.
  • GOV.UK Frontend is a template for structure, not for content. Its scope (a UI component library shipped as an npm package) is broader than a brand guide. Borrow the repo conventions, the docs/contributing/versioning.md model, and the SemVer + CHANGELOG discipline; do not feel obliged to copy its build complexity. Notably, GOV.UK Frontend does not yet publish its tokens in DTCG JSON — they remain SCSS variables — so on that one point Noiz will actually be ahead.
  • CalVer remains a legitimate alternative. If after six months you find SemVer’s MAJOR/MINOR/PATCH distinction doesn’t fit because the guide is changing on a fixed cadence, CalVer (YYYY.MM.PATCH) is a defensible switch. SemVer remains the recommended default for the reasons above.
  • Some sources behind this report (vendor blogs from Frontify, Bynder, Brandfolder, Spellbrand etc.) have a commercial interest in larger, more elaborate brand systems. Their structural advice is sound, but their implicit recommendation to adopt a SaaS brand portal should be discounted for a one-person FOSS-oriented operator — Nextcloud + Git replaces them at this scale.