# Malleable AI — brand guidelines

The **mi** mark, the colour, the type, and how to use them.

Derived 2026-09-01 from `business_ops/travel/Vietnam 2026/merch/v2/brand.md`, which
vectorised the mark from a reference render Brian supplied. The apparel-specific
content of that document — print sizes, garment, screens, placement, the Hanoi
quote — is **not** repeated here; it stays in the merch folder.

Every number below is either **measured** (and says so) or a **decision** (and says
that too). Nothing is estimated silently. That convention is inherited from the
source and is worth keeping: it tells you which numbers you may adjust and which
you may not.

---

## 1. The mark

A lowercase **mi** drawn as one continuous blob — three descending arches with a
free-standing tittle over the last one.

| Property | Value | |
|---|---|---|
| Ink box | 1000 × 497.504 | measured |
| Aspect | **2.01003 : 1** | measured |
| Outline | Closed uniform periodic cubic B-spline, 46 control points | fitted |
| Emitted as | 46 cubic Béziers, closed, plus one circle | |
| Tittle | centre (917.100, 82.900), r **82.900** — tangent to the top and right of the ink box | measured |
| Fit deviation | 0.07 reference px RMS, 0.27 px max | measured |
| Rendered agreement | **IoU 0.9933** against the reference | measured |

The tittle is a true circle, not an ellipse: the extracted contour's radius has a
standard deviation of 0.94 in 102 — under 1%.

### ⚠️ There is no stroke width, and asking for one means you are rebuilding it wrong

The obvious reading of this mark is a brush stroke — a centreline carrying a
varying width. The first fit did exactly that and scored IoU 0.980, which looked
fine in a difference map and was **wrong at print size**. A union of discs turns a
sharp change of direction into a *cusp*; the reference has a smooth rounded fillet
at both inner notches. That is not a sampling error, it is the wrong shape class,
and area agreement hides it.

The shipped mark is an outline model with no centreline at all. **If you ever find
yourself needing a stroke-width figure for this mark, stop — use the asset.**

### How it was fitted

`merch/v2/designs/_src/fit_mark.py`. The flat lockup tile is upsampled 8× and
contoured at the 50% coverage level rather than colour-thresholded, so the edge
lands sub-pixel instead of half a pixel fat. The contour is resampled to 3000
points by arc length, then control points are solved by least squares with every
data point re-projected onto the current curve each round, fourteen rounds.
`verify_mark.py` re-renders the emitted path through Chrome and scores it against
the same 50% mask — that is where the IoU above comes from.

---

## 2. Assets

All logos use the original mi symbol. Downloadable lockups use **Nunito Bold 700**,
“Malleable AI” in title case, at **−0.035em** tracking, matching the website.
Their lettering is converted from the actual font to vector paths: no live text,
font downloads, or font substitution is required when placing an SVG.

The 2026-09-24 update replaces the legacy uppercase Arial Regular lettering.
The original symbol's path data and proportions are unchanged. Old merchandise
artwork remains a historical record, not the source for current wordmarks.

| File | What | Aspect |
|---|---|---|
| `malleable-mi-mark.svg` · `-charcoal.svg` · `-white.svg` | Original mark alone | 2.0100 : 1 |
| `malleable-mi-lockup-compact.svg` | Compact Nunito lockup | 8.745 : 1 |
| `malleable-mi-lockup.svg` | Full Nunito lockup | 6.9525 : 1 |
| `malleable-mi-lockup-white.svg` | Full Nunito lockup | 6.9525 : 1 |
| `malleable-mi-lockup-charcoal.svg` | Full Nunito lockup | 6.9525 : 1 |
| `malleable-mi-stack.svg` | Stacked Nunito lockup | 1.4511 : 1 |
| `malleable-mi-stack-charcoal.svg` | Stacked Nunito lockup | 1.4511 : 1 |

`social/` holds square derivatives built from the same symbol — see §7.
`tokens/` holds the palette and typography as CSS/JSON. `logos/manifest.json`
records the generated dimensions and lettering provenance for each lockup.

### Which one to use

- **Compact lockup** is the default for headers, slides, and anything wide and
  small. The full lockup's strapline stops resolving into letters below about
  40 px tall and becomes a grey smear.
- **Full lockup** where it will be rendered large: a title slide, a cover, a
  poster, print.
- **Stack** where the space is squarer than it is wide.
- **Mark alone** where the name is already present — favicons, avatars, a
  repeated corner element, apparel.

---

## 3. Colour

Three base colours anchor formal marks and the website. White is also available for reversed formal marks. The UI separates core display colour from readable functional roles below; textured illustrations follow §9.

| Role | Hex | | |
|---|---|---|---|
| **Terracotta** | `#B64539` | Formal mark and primary buttons. | measured |
| **Charcoal** | `#22252E` | Wordmark, rule, strapline, body type. | decision — see below |
| **Natural** | `#EAE1D9` | The ground. | measured |

### Where terracotta came from — measured

| Instance | Median of the eroded core |
|---|---|
| Flat lockup tile (vector) | `#B84A3E` |
| Back print (on fabric) | `#B64438` |
| Front chest (on fabric) | `#B54134` |

`#B64539` is the mean of the three. The spread is about 3 units per channel, which
is fabric and lighting, not disagreement.

### On the charcoal — a decision

The reference's lettering measures `#050505` on the flat tile — effectively black.
Brand charcoal `#22252E` is used instead. At size the two are indistinguishable,
and `#22252E` is the colour every other Malleable artefact already uses.

### On Pantone — don't quote one

Checked against fifteen common coated brick reds, the nearest are 180 C and 173 C
at ΔE76 ≈ 7.7 — both visibly off. Give a printer the hex and a printed chip. The
mark is a warm brick red, not a spot-critical corporate colour; a small shift will
not read as an error.

### ⚠️ Contrast — computed, and one combination is disallowed

| | Ratio | |
|---|---|---|
| Charcoal on natural | 11.86 : 1 | ✅ any size |
| Charcoal on white | 15.31 : 1 | ✅ any size |
| Natural on charcoal | 11.86 : 1 | ✅ any size |
| Terracotta on white | 5.39 : 1 | ✅ body text |
| Terracotta on natural | 4.17 : 1 | ✅ large text and graphics · ❌ body text |
| **Terracotta on charcoal** | **2.84 : 1** | **❌ fails the 3:1 graphics floor** |

**Never put the terracotta mark on a charcoal or near-black ground.** Use
`malleable-mi-mark-white.svg`. This combination is not in the source document
because apparel never needed it — it comes up the moment anyone builds a dark UI,
a dark slide master, or a dark-mode avatar, so it is written down here.

Exact Terracotta does not meet the 4.5:1 body-text threshold on Natural. Use the UI accent-text roles for small text, links and interface icons.

### Implemented website roles — decisions, September 2026

`tokens/tokens.json` is the source of truth. `scripts/generate-brand-tokens.mjs`
generates the downloadable `tokens/colours.css` and the identical website CSS.
Nunito remains the heading/website-wordmark face; Instrument Sans is the body and
interface face. UI roles do not authorize recolouring supplied SVG marks.

Core Terracotta `#B64539` is the display accent, decorative detail colour and primary button fill. There is
no lighter Terracotta tint. Dark header wordmark, menu/theme icons, small links,
hero eyebrow and focus indicators use white `#FFFFFF`.

Section dots, punctuation, checkmarks, quotation marks, supporting arrows and
hover borders restore the core Terracotta accents. These details do not carry
information alone. Contact icons, sector arrow tiles and team initials use white
on a Terracotta fill (5.39:1), preserving readable symbols while adding colour.
Standalone meaningful icons retain the readable UI role.

**Display contrast exception for Brian’s review:** core Terracotta on Charcoal
is **2.84:1**, below the **3:1** large-text threshold. Brian requested this colour
for display emphasis, including “enterprise.”. This preview choice is not an
accessible text role and does not change the formal-mark rules. On Natural,
Terracotta is **4.17:1**, sufficient for large display text but not normal text.
Small light-mode accent text retains the darker `#963A32` role.

| Role | Light | Dark |
|---|---|---|
| background | `#EAE1D9` | `#22252E` |
| text | `#22252E` | `#EAE1D9` |
| panel | `#F3EDE8` | `#2D3039` |
| muted | `#5D5A60` | `#BEB7B4` |
| border | `#B2A7A3` | `#5D5962` |
| control-border | `#7B6C70` | `#999098` |
| accent-text | `#963A32` | `#FFFFFF` |
| accent-hover | `#92362D` | `#FFFFFF` |
| button | `#B64539` | `#B64539` |
| button-hover | `#92362D` | `#92362D` |
| on-button | `#FFFFFF` | `#FFFFFF` |
| focus | `#963A32` | `#FFFFFF` |
| display-accent | `#B64539` | `#B64539` |
| header-ink | `#22252E` | `#FFFFFF` |
| accent | `#B64539` | `#B64539` |

Soft surfaces mix 6% core Terracotta with the theme background; hover surfaces mix
10%. These are surface treatments, not new accent inks. Decorative borders need
not define controls. Form boundaries use control-border; focus uses a visible
ring with offset. Primary buttons use white on exact Terracotta, darker
Terracotta on hover, and no border in either theme. The shared `mal-primary-button` class uses the primary-button component tokens from `tokens/tokens.json`, published in `tokens/colours.css`. Resting shadows are `0 4px 8px rgb(35 24 16 / 12%), 0 10px 24px rgb(35 24 16 / 14%)`; hover shadows are `0 6px 12px rgb(35 24 16 / 16%), 0 14px 30px rgb(35 24 16 / 20%)`, with a 3px lift. Keyboard focus retains a visible 2px ring with 4px offset; reduced-motion preferences disable the lift and transition. Disabled states retain
their existing disabled semantics and reduced opacity.

| Tested functional UI role | Theme | Contrast | Minimum |
|---|---|---|---|
| text on background | light | 11.86:1 | 4.5:1 |
| muted on background | light | 5.25:1 | 4.5:1 |
| muted on panel | light | 5.84:1 | 4.5:1 |
| accent-text on background | light | 5.52:1 | 4.5:1 |
| accent-text on panel | light | 6.14:1 | 4.5:1 |
| accent-hover on background | light | 5.84:1 | 4.5:1 |
| on-button on button | light | 5.39:1 | 4.5:1 |
| on-button on button-hover | light | 7.53:1 | 4.5:1 |
| focus on background | light | 5.52:1 | 3:1 |
| control-border on panel | light | 4.29:1 | 3:1 |
| text on background | dark | 11.86:1 | 4.5:1 |
| muted on background | dark | 7.74:1 | 4.5:1 |
| muted on panel | dark | 6.67:1 | 4.5:1 |
| accent-text on background | dark | 15.31:1 | 4.5:1 |
| accent-text on panel | dark | 13.18:1 | 4.5:1 |
| accent-hover on background | dark | 15.31:1 | 4.5:1 |
| on-button on button | dark | 5.39:1 | 4.5:1 |
| on-button on button-hover | dark | 7.53:1 | 4.5:1 |
| focus on background | dark | 15.31:1 | 3:1 |
| control-border on panel | dark | 4.27:1 | 3:1 |
| accent-text on soft | light | 5.13:1 | 4.5:1 |
| accent-text on hover | light | 4.85:1 | 4.5:1 |
| on-button on icon-panel | light | 5.39:1 | 3:1 |
| accent-text on soft | dark | 14.64:1 | 4.5:1 |
| accent-text on hover | dark | 14.24:1 | 4.5:1 |
| on-button on icon-panel | dark | 5.39:1 | 3:1 |
| header-ink on background | dark | 15.31:1 | 4.5:1 |

The functional roles above meet their listed thresholds. Dark Terracotta display
emphasis is recorded separately in `displayContrast` with `meetsMinimum: false`.
Do not generalize that display exception to small text, links, meaningful icons,
focus indicators or supplied formal marks.

---

## 4. Type

**Nunito** for headings. **Instrument Sans** for body text and interface copy.
This typography decision was updated on 2026-09-22 to match malleable.ai.

| Role | Family | Weights |
|---|---|---|
| Headings | Nunito | 500, 600, 700 |
| Body text | Instrument Sans | 400; 500–700 for emphasis |
| Navigation, buttons, and labels | Instrument Sans | 400–700 as needed |
| Website and logo wordmark | Nunito | 700 |

Use `Nunito, ui-rounded, sans-serif` for headings and the website wordmark, and
`'Instrument Sans', sans-serif` for body text and interface copy. The website
hosts both font families locally.

### One wordmark across website and downloads

All current wordmarks read **Malleable AI** in **Nunito Bold 700**, with
**−0.035em** tracking. The website renders live text; downloadable compact,
full, monochrome and stacked lockups contain outlines from the same licensed
Nunito font used by the site. No widely tracked uppercase Arial variant remains
in the current kit.

The compact horizontal layout follows the website: a 40-unit-wide original
symbol, an 11-unit gap, and a 23-unit Nunito wordmark, optically centered.
The full layout adds **STRATEGIZE / ADOPT / BUILD / SCALE** below the wordmark
in Instrument Sans Regular. The stack centers the same lettering under a larger
symbol. The old divider and rule are retired along with the old lettering.

Generate these assets with `node scripts/generate-brand-lockups.mjs` in the
website repository. The generator reads the canonical typography tokens and
installed licensed font files; it preserves the original symbol geometry and
outlines the type. Do not manually retype, trace or re-space the exported SVGs.


---

## 5. Clear space and minimum size

Both are **decisions**, not measurements — the reference gives no guidance on
either. They are set off the mark's own geometry so they scale with it.

### Clear space

**One tittle diameter on all four sides.** The tittle is the free-standing dot;
its diameter is 165.8 units in the 1000-wide mark, so clear space is **0.166 × the
mark's ink width**. In a lockup or stack, measure the tittle in that file and use
the same rule — it scales automatically.

Nothing sits inside that band: no type, no rule, no image edge, no crop.

### Minimum size

| Asset | Floor | Why |
|---|---|---|
| Full lockup | **60 px tall** (≈417 px wide) — hard floor 40 px | Below 40 px the strapline is a grey smear |
| Compact lockup | **36 px tall** (≈315 px wide) | Clear, readable lettering at document/header sizes |
| Stack | **140 px tall** (≈203 px wide) | Strapline again |
| Mark alone | **24 px wide** | Below this the tittle stops reading as separate |

Below the full lockup's floor, switch to compact rather than shrinking further.

---

## 6. Formal mark rules

- **Don't recolour the mark.** Terracotta, charcoal, or white. Nothing else.
- **Don't put terracotta on charcoal or near-black** — 2.84:1, see §3. Use white.
- **Don't add a stroke to the mark.** It is a filled outline; a stroke thickens
  the arches unevenly and rounds the notches wrongly. See §1.
- **Don't rebuild the mark as a brush stroke.** There is no centreline and no
  stroke width. See §1.
- **Don't re-space a lockup.** Preserve the supplied symbol and lettering proportions.
- **Don't retype a supplied logo lockup as live text.** Use the asset, so tracking
  and outlines stay exact. The website uses the same Nunito Bold lettering, described in §4.
- **Don't stretch, rotate, skew, or apply effects** — no shadows, gradients,
  bevels, or outer glows.
- **Don't crop the mark** or let anything intrude on the clear space of §5.
- **Don't use the full lockup below 40 px tall.** Use the compact one.

---

## 7. Square derivatives

The supplied social assets retain their existing geometry. The mark's path data
is copied unchanged, so these are geometrically identical to the source — only
scaled and positioned. The website browser/app icons are generated by
`scripts/generate-brand-icons.mjs` using the same paths, with a Natural tile and
the existing 81.25% mark width / 21.875% tile corner radius. The supplied kit
favicon below keeps its own existing 90% / 17.04% treatment.
`scripts/generate-og-images.mjs` generates every sharing card from the same JSON
palette, with Nunito headings/wordmark and Instrument Sans supporting copy.

| File | Ground | Ink | Contrast |
|---|---|---|---|
| `avatar-512.svg` | Natural | Terracotta | 4.17 : 1 |
| `avatar-512-terracotta.svg` | Terracotta | Natural | 4.17 : 1 |
| `avatar-512-charcoal.svg` | Charcoal | White | 15.31 : 1 |
| `favicon.svg` | Natural, 17.04% corner radius | Terracotta | 4.17 : 1 |

Avatars apply the §5 clear space exactly, which puts the mark at 75% of the
square's width. Use `avatar-512.svg` by default; `-charcoal` where the platform
renders avatars small or badly and you want maximum legibility.

**The favicon cuts clear space to a third of a tittle** so the mark fills 90% of
the tile — otherwise it disappears at 16 px. Even so, at 16 px the tittle is
about 2.4 px across and nearly merges with the last arch. It is legible at 32 px
and up. That is a limitation of a 2:1 mark in a square, not a fixable bug.

---

## 8. Apparel

Not covered here. The print art, sizes, placements, screen counts and printer
spec live in `business_ops/travel/Vietnam 2026/merch/v2/` — `README.md` for the
order, `brand.md` for the workings.


## 9. Textured illustrations

See [illustration-guidelines.md](illustration-guidelines.md). Terracotta and
Natural are material anchors rather than flat pixel fills. Clay grain, shading,
highlights and cast shadows remain. The sculpted mi in the hero is an illustration,
including on dark scenery; it does not replace the flat formal mark in navigation,
lockups or icons. Existing olive foliage/material accents remain for this first
preview, explicitly pending Brian’s visual review. Skin/hair and partner identities
are preserved. Do not reinterpret geometry or change animation registration.