Design System¶

This page reflects how the Kartoza Brand Pack v0.1 is applied to the Infrastructure Mapper documentation site. The Brand Pack is the upstream source of truth; this page is a derivative for our specific surface (MkDocs).

The previous in-repo "nature & environment" palette is retired

Earlier versions of this project used a bespoke isometric / nature palette (Forest Green, Moss Green, Earth Brown, Sandstone Beige, Leaf Yellow-Green …). All of those values have been removed in full — per the Brand Pack SRS §1.5, this is removal, not reconciliation. None of those colour names or hex values appear in the new system.

What's "on brand"¶

A page is on brand when a reader who has never seen it can tell within a second that Kartoza made it — from the mark, the blue / amber / grey palette, the Nunito type, and (where space allows) the map motif, with nothing on the page fighting those four signals.

Consistency is the whole point; novelty is not a goal.

Palette¶

The Kartoza palette has two coordinated families — the logo palette (mark, accents, UI chrome) and the map-motif palette (illustration-only). Both share one amber.

Logo palette (UI chrome)¶

Kartoza Blue #54A2CC Primary accent — links, primary actions, headings ≥ 18 pt.

Kartoza Amber #EEB348 Secondary / highlight accent. Subtitles, callouts, structure cues.

Kartoza Grey #8A8B8B Symbol grey loop; structural mid-grey.

Charcoal #383939 Default body text. H1 / H2. The colour that does the reading work.

Secondary Grey #676869 Eyebrows, captions, secondary text.

Light Grey #D1D1D1 Table rules, dividers, disabled states.

Cloud #F5F5F2 Page tint, zebra rows, panel surfaces.

White #FFFFFF Base surface.

Status colours (status-only)¶

Used in admonitions and chips. Always pair with an icon or text label — never colour alone (NFR-002).

Success #3C7D54 On #EAF3EC tint.

Caution #EEB348 On #FCF3E0 tint. (Reuses brand amber.)

Error #B0473C On #FBEFEF tint.

Colour roles — the rule¶

Element	Colour
Body text	Charcoal `#383939` — never Blue or Amber
Headings H1 / H2	Charcoal
Eyebrows (e.g. `KARTOZA · X`)	Secondary Grey, letter-spaced UPPER
Links	Kartoza Blue
Primary CTA fill	Kartoza Blue
Highlight / display headings ≥ 18 pt	Amber (sparing)
Table headers	Charcoal background, white type

Blue and Amber are not body-text colours

Both fail WCAG AA contrast against white at paragraph size. They are accents — for links, fills, ≥ 18 pt headings, icons and chart series. Body copy stays in Charcoal at all times (FR-012, NFR-001).

Map motif¶

Kartoza's signature illustration is a flat, top-down abstract map — cool-grey parcels, amber zones, blue water, white street network, optional meander pattern. It is the only source of visual texture on a Kartoza surface; gradients and stock photography are not (FR-030, FR-033).

On this docs site:

The landing-page hero uses a lightened motif background so Charcoal body type stays legible (FR-031).
Future section divider banners and full-bleed covers will use the full-saturation motif.
The motif PNGs ship in the Brand Pack under visual-elements/; copies live under docs/assets/brand/ for this project to consume.

Logo¶

Use the supplied artwork as-is. Never re-type, recolour part-way, stretch or add effects (FR-002). The variants:

Variant	When
Vertical lockup (primary)	Cover pages, large blocks
Horizontal lockup	Headers, signatures, hero
Symbol	Tight spaces, favicons, app launchers
Reversed (white) lockup	Dark / Charcoal backgrounds
Mono (Charcoal)	Only when colour isn't possible

Minimum sizes: vertical ≥ 90 px wide, horizontal ≥ 120 px wide, symbol ≥ 16 px (FR-005). Maintain clear space around the logo equal to the symbol's central aperture height (FR-004).

Typography¶

Use	Family	Notes
Body, headings, eyebrows	Nunito	Loaded via Google Fonts. Stack: Nunito, "Helvetica Neue", Arial, sans-serif (FR-020).
Code, monospace	JetBrains Mono	Variable weight; for code blocks, inline code, terminal output (FR-021).
Accent / display	Nunito Italic in Amber	The "Key Objectives" style. Used sparingly.

Line height ≈ 1.45 for body. Heading colours: H1 / H2 in Charcoal; eyebrows in Secondary Grey, letter-spaced UPPER; links in Blue (FR-024).

Flat — no shadows, gradients or bevels¶

The system is flat. No drop shadows on logos, no gradients on buttons, no glows, no bevels. Depth and texture come only from the map motif (FR-033).

This is enforced in extra.css: hero blocks, grid cards, admonitions, tables — none of them carry box-shadow or background: linear-gradient(...).

Components used on this site¶

`.kz-hero`¶

Landing-page hero. Cloud surface with a lightened slant-title motif behind it. Charcoal type. Blue primary CTA. Flat.

Material `grid cards`¶

Section index cards. Hairline Light-Grey border, Cloud-on-hover, Blue border on hover. No shadow.

`.kz-domain-grid`¶

A subclass of .grid.cards used on the Data Model index for the capture-domain entries (image + name + summary).

`.kz-swatches`¶

The palette swatches you're looking at on this page.

`.kz-eyebrow`¶

The KARTOZA · X eyebrow above hero titles — Secondary Grey, spaced UPPER (FR-024).

`.kz-ai`¶

Inline badge marking AI-assisted content (per FR-095 / NFR-022): icon + bold short label, on amber tint.

Tokens (one source of truth)¶

Every colour and font lives in docs/stylesheets/kartoza-tokens.css (copied from the Brand Pack tokens/tokens.css). All other CSS consumes those tokens via var(--kartoza-blue) etc. To update the palette, update the tokens file — nothing else (NFR-020).

/* docs/stylesheets/kartoza-tokens.css */
:root{
  --kartoza-blue:  #54A2CC;
  --kartoza-amber: #EEB348;
  --kartoza-grey:  #8A8B8B;
  --text-default:  #383939;
  --text-muted:    #676869;
  --rule-line:     #D1D1D1;
  --surface-cloud: #F5F5F2;
  --surface-white: #FFFFFF;
  --font-sans: 'Nunito','Helvetica Neue',Arial,sans-serif;
  --font-mono: 'JetBrains Mono',monospace;
  --status-success: #3C7D54; --status-success-tint: #EAF3EC;
  --status-warn:    #EEB348; --status-warn-tint:    #FCF3E0;
  --status-error:   #B0473C; --status-error-tint:   #FBEFEF;
}

Iconography note¶

The Brand Pack specifies a single flat icon style: two-weight line/solid, Charcoal + one accent matching the symbol (FR-040). Domain PNG icons under docs/assets/ (vegetation, water, electricity …) are the project's legacy bespoke set and are scheduled for redrawing in the Kartoza style (FR-041 SHOULD). They render as-is for now.

AI-assisted authoring (FR-095, NFR-022)¶

Per the Brand Pack governance rule, machine-generated artefacts on Kartoza surfaces are marked with and the prompt is retained alongside the output, with a human validating the result. On this site, that takes the form of:

A .kz-ai inline badge next to AI-drafted prose where appropriate.
PROMPT.log at the repo root capturing every session prompt.
A separate AI Assistance Policy page covering scope.

Brand Pack location¶

The full Kartoza Brand Pack — including the SRS, Brand Guidelines PDF, logo masters, motif PNGs and the token source — lives outside this repository:

Internal Kartoza staff: request access from the brand owner.
Repo working copy: a snapshot is dropped into Kartoza_Brand_Assets_v0_1/ at the project root for local development. The folder is gitignored and not part of project history; assets actually used by the docs site are copied into docs/assets/brand/ and committed.