# Shimmer Brand Guidelines

> How to use the marks. What not to do. Why each rule exists.

---

## Brand at a glance

| | |
|---|---|
| **One-line** | A sovereign chief-of-staff that owns your context and comes to you. |
| **Aesthetic** | Refractive · sentient · observational. *Annihilation* membrane, not silicon valley swoosh. |
| **Mark** | v6 — Recraft-generated S-form, prism-gradient reskin. Locked 2026-05-28. |
| **Wordmark** | `shimmer` — PP Hatton lowercase, weight 500, slight negative tracking. |
| **Voice** | Sharp colleague. Warm but not cheesy. Quiet when nothing useful to say. |

---

## Logo

### The mark

The mark is a four-ribbon S-form rendered with a refractive prism gradient. The shapes overlap with low opacity + blend modes so light *passes through* the surface — never sits flat on top.

It comes in six modes (see [`README.md`](./README.md) for the full list). The three that matter most:

- **`dark`** — vivid iris on void. Default for `/app/*` chrome and most digital surfaces.
- **`light`** — deeper iris on parchment. For docs, letterhead, and any white-surface placement.
- **`mono-dark` / `mono-light`** — single-color gradient. Use anywhere chromatic isn't possible: single-color print, embroidery, watermarks, very-small contexts.

### Clear space

Always leave clear space around the mark equal to **20% of the mark's height** on all sides. No text, ornament, or other elements within that margin.

```
┌───────────────────┐
│  ░░░░░░░░░░░░░░  │   ← 20% clear space
│  ░░  ▓▓▓▓▓▓  ░░  │
│  ░░  ▓ MK ▓  ░░  │
│  ░░  ▓▓▓▓▓▓  ░░  │
│  ░░░░░░░░░░░░░░  │
└───────────────────┘
```

### Minimum sizes

| Context | Minimum |
|---|---|
| Digital — full chromatic mark | **24 px** (below this, the chromatic refraction muddies; switch to mono) |
| Digital — mono mark | **16 px** (favicon-safe) |
| Print — full chromatic | **0.5 in / 12 mm** |
| Print — mono | **0.25 in / 6 mm** |

Below these sizes, use the wordmark alone or omit the mark entirely.

### Lockups

The mark and wordmark have **two approved lockups**:

- **Primary (horizontal)** — `logo/primary/*`. Mark on the left, wordmark on the right. Default for landings, headers, social cards.
- **Stacked (vertical)** — `logo/stacked/*`. Mark above wordmark, centered. Use for app splash screens, square contexts, mobile.

The mark can also stand alone (favicons, in-app chrome) and the wordmark can stand alone (footers, secondary placements). **Don't** invent new lockups.

### The glass mode

`logo/mark/shimmer-mark-glass.svg` is for **premium moments only** — app splash screens, hero animations, "this is special" placements. It carries a specular highlight + rim shadow that reads as polished glass. Don't use it for everyday UI; the visual weight is too high.

### The animated loader

`logo/mark/shimmer-mark-loader.svg` is an SVG with an embedded SMIL animation: the prism gradient sweeps across the mark continuously over 6 seconds. Drop it in via `<img src="...">` or inline `<svg>` — animation runs automatically in modern browsers.

Use cases:
- Page load / route transitions
- Long-running operation indicators
- "Agent thinking" status moments

Don't loop it visibly during user interaction — it's a *waiting* affordance.

---

## Color

The full palette is in [`colors/palette.svg`](./colors/palette.svg). Machine-readable: [`colors/colors.json`](./colors/colors.json) and [`colors/colors.css`](./colors/colors.css).

### Core principle: the spectral palette is *overlay vocabulary, not fill vocabulary*

The iris colors (rose · coral · amber · green · teal · cold · mid · warm · magenta) are for **interaction states, gradient stops, and the shimmer effect itself**. They are *never* used as the dominant fill of a surface. The moment one iris color becomes the brand color of a card or button, the prism stops being a prism and becomes a tint.

Govern surfaces with `void`, `surface`, `surface-raised`, `surface-float`, `text-primary`, `text-secondary`. Let the iris colors *appear* in motion and *recede*.

### Reserved meanings inside the prism

- `iris-teal` → **live**: agent currently writing, real-time data, present-tense activity
- `iris-green` → **success / confirmation**
- `iris-amber` → **caution** (rare; use only for genuine warnings)
- `iris-rose` / `iris-magenta` → **high-emphasis moments only** — earned, not casual

### Dark vs. light

Both palettes are in the JSON. Light-mode iris values are deepened ~10–15% for contrast on white surfaces. The mark, wordmark, and lockup files come in both — use the file that matches the surface, don't try to invert manually.

---

## Typography

Full reference: [`typography/README.md`](./typography/README.md) + [`typography/type-scale.svg`](./typography/type-scale.svg).

| Use | Family |
|---|---|
| Display / headings | **PP Hatton** (Pangram Pangram) — serif, weighted, deliberate |
| Body | **Suisse Intl** (Swiss Typefaces) — neutral, readable, unhurried |
| Mono | **Suisse Intl Mono** — data, timestamps, system output |

Both are licensed fonts. Until purchased, the fallback chain (Georgia, system-ui, ui-monospace) is honest stand-in — don't try to substitute "free fonts that look like" them.

### Discipline

- Don't go above weight **500** outside `display` / `heading-*` contexts.
- Type hierarchy alone establishes structure. Color is not required.
- The mark and wordmark co-exist in the lockups via PP Hatton — the same serif personality runs through both.

---

## Do

- Use the mark + wordmark side-by-side at hero scales (the primary lockup).
- Use the mark alone in chrome ≥ 24 px.
- Use the mono variants when printing single-color, embroidering, or rendering at very small sizes.
- Use the loader for genuine *waiting* states.
- Apply the wordmark over the prism halo (`docs/design/PRINCIPLES.md` #1) for hero moments.
- Match the file's theme to the surface's theme (dark mark on dark, light mark on light).

## Don't

- **Don't change the colors of the mark.** The iris gradient is locked. If a surface demands a different color, use the mono variant.
- **Don't add a stroke or outline** to the mark. The fill is the form.
- **Don't add a drop shadow** to the mark. The internal refraction is the depth.
- **Don't rotate or skew the mark.** It's been balanced; rotation breaks the asymmetry intentionally.
- **Don't crop or partially mask the mark.** Use it whole or use the wordmark alone.
- **Don't place the mark on photography.** It needs a clean ground; use a solid surface (void / parchment / themed background).
- **Don't mix the chromatic mark with the mono wordmark** (or vice versa). Match modes within a single lockup.
- **Don't use the glass variant as a default.** It's an accent. Default to the standard chromatic mark.

---

## Voice & tone (paired with the visual brand)

The design system enforces visual restraint; the voice does the same in language. Both pull from [`SOUL.md`](../SOUL.md):

| Voice rule | Visual parallel |
|---|---|
| Sharp colleague, not a bot | No skeuomorphic chrome. Precise type, restrained color. |
| One sentence when one works | One CTA per view. One headline per section. One spectral accent per surface. |
| Warm but not cheesy | Glows are cold by default; warmth is rare and earned. |
| Quiet when nothing useful to say | Empty states default to silence. Ambient animation pauses when user is interacting. |
| Names not handles | UI copy uses the user's name; system identifiers only in mono. |

When a marketing surface, error message, or in-product copy doesn't match this voice, the visual brand is doing the harder work alone. The whole experience reads as inconsistent. Fix the copy.

---

## Lineage note

The mark's geometry was derived from [Silk](https://github.com/holonym-foundation/brand-kit_silk) (a retired Holonym Foundation product), passed through Recraft's vector AI for an S-form pass, then re-skinned with shimmer's prism gradient + blend modes. The visual kinship to Silk is intentional — Shimmer is Silk's iridescent successor — and disclosed in the design history (`docs/design/exploration/glyph/`).

---

## Questions / changes

The brand kit is generated from `scripts/build-brand-kit.py`. To propose a change:

1. Edit the source — either the geometry (`docs/design/exploration/glyph/recraft/v6-recraft-original.svg`) or the palette (the THEMES table at the top of the script).
2. Re-run the script.
3. Open a PR. Include before/after composite previews.

Major brand-direction changes (new mark, new color system) go through the design-system tag process: bump the next minor version, write a migration note, mirror to shimmer-saas in the same PR or immediately after.