Skip to content

branding.md

Latest commit

 

History

History
82 lines (66 loc) · 3.58 KB

branding.md

File metadata and controls

82 lines (66 loc) · 3.58 KB
Raw

Branding your reports

An agency can put its own cover, logo, colours, fonts and voice on every report without changing the toolkit. The brand lives in a folder of its own, outside the toolkit, and the toolkit points at it. Updating the toolkit never touches your brand, and your brand never ends up in a pull request.

What a brand folder holds

A complete example ships with the qa-standards skill in brand-example/.

File Required Used by What it holds
brand.json yes exporter Name, colours, logo, fonts, cover fields, footer
logo file no exporter SVG, PNG, WebP or JPEG, named in brand.json
fonts/ no exporter WOFF2, WOFF, TTF or OTF files, named in brand.json
cover.md no exporter Cover page layout with placeholders; a standard cover is used without it
brand.md no agent How reports under this brand read: voice, structure, words to avoid

brand.json:

{
  "name": "Example Agency",
  "colours": { "accent": "#2f5bea", "ink": "#161a23", "muted": "#5b6372", "paper": "#ffffff" },
  "logo": "logo.svg",
  "fonts": {
    "heading": { "family": "Example Sans", "file": "fonts/example-sans-bold.woff2" },
    "body": { "family": "Example Text", "file": "fonts/example-text.woff2" }
  },
  "cover": {
    "prepared_by": "Example Agency QA team",
    "contact": "qa@example.com",
    "confidentiality": "Prepared for the client named on this report."
  },
  "footer": "Example Agency · QA report"
}

Only name is required. Colours are #rgb or #rrggbb. Unknown keys are an error, so a typo does not silently do nothing.

cover.md can use {title} (the report's first heading), {date}, {brand}, {prepared_by}, {contact} and {confidentiality}.

Set one up

  1. Copy skills/qa-standards/brand-example/ to a folder of your own, outside the toolkit. A private repository of its own is a good home if a team shares it.

  2. Replace the files with your own and edit brand.json.

  3. Check it:

    .venv/bin/python skills/qa-standards/scripts/brand_check.py /path/to/your-brand

  4. Point the toolkit at it once, in your shell profile or your agent's environment:

    export QA_BRAND=/path/to/your-brand

From then on the agent reads your brand.md before writing a report, and report_export.py puts your cover, logo, colours, fonts and footer on the HTML and PDF. Use --brand /path/to/other-brand to export one report under a different brand, or --no-brand to export without one.

What a brand cannot change

  • The method. Severity, priority, evidence, coverage and the verdict rule come from qa-standards. brand.md decides how a report reads, not what it concludes.
  • The safety rules. Every brand file must sit inside the brand folder and is inlined into the export, which still loads nothing from the network. An SVG logo is shown as an image, so any script or link inside it does nothing.
  • The layout. A brand sets colours, fonts, the logo, the cover and the footer through brand.json and cover.md. It cannot add its own stylesheet: the screenshot checks only stay trustworthy if nothing a brand supplies can change how a screenshot is shown. A report.css in a brand folder is reported as a problem so nobody thinks it is applied.
  • The screenshot checks. The logo is not counted as a screenshot: the exporter prints the cover on its own first to measure what the logo adds to a PDF. Before printing the report, it checks that every screenshot loads and is visible at a readable size. A report fails if any screenshot is missing or will not load.