# ModelWorks Brand Guidelines

Version 1.0 — October 2026

## 1. Brand Overview

ModelWorks is a platform for building, sharing, and monetizing AI
**circuits** — composable, executable workflows that anyone can run through
a simple API. The brand stands for precision engineering, openness, and
programmer-first simplicity.

The visual identity is deliberately close to the tools our users live in:
a terminal-clean monochrome base with a single signal color. It should feel
like a well-crafted developer tool, not an enterprise suite.

## 2. The Mark

The ModelWorks mark is the **bird** — a single-path vector (viewBox
`0 0 211 174`). It is the primary brand asset.

**Ink rule:** the bird is **black on white** and **white on black** — always
match the ink to the background. No other ink except brand green for
accent use (see 2.1).

### 2.1 Variants

| File | Ink | Use on |
|---|---|---|
| `logos/mark-black.svg` | Black `#000000` | Light backgrounds |
| `logos/mark-white.svg` | White `#FFFFFF` | Dark backgrounds |
| `logos/mark-current-color.svg` | Inherits text color (`currentColor`) | Inline in UIs, print, any single-color context |
| `logos/mark-emerald.svg` | Brand green `#10B981` | Accent use only — never the default |

### 2.2 The Wordmark and Lockup

The wordmark is **"ModelWorks" set in Chakra Petch Bold** — one word,
sentence case. It exists as pre-outlined SVGs (no font needed) and as
font files in `fonts/`:

| File | Contents |
|---|---|
| `logos/wordmark-black.svg` | Wordmark, black ink (light backgrounds) |
| `logos/wordmark-white.svg` | Wordmark, white ink (dark backgrounds) |
| `logos/lockup-black.svg` | Bird + wordmark lockup, black ink |
| `logos/lockup-white.svg` | Bird + wordmark lockup, white ink |

Lockup geometry: bird at left, wordmark vertically centered, gap equal
to ~40% of the bird's height, wordmark cap height ≈ 62% of the bird's
height. The shipped lockups are canonical — do not rebuild them.

### 2.3 Clear space

Keep a margin around the mark of at least **half the mark's height**
(≥ 87px at the mark's native 174px height) free of other elements,
text, or page edges.

### 2.4 Minimum size

- Digital: **24px** height
- Print: **8mm** height

Below these sizes the bird's detail collapses; use a plain favicon
instead.

### 2.5 Do's and Don'ts

✅ Do:
- Use the black or white variant on matching-contrast backgrounds
- Scale proportionally (the viewBox ratio is 211:174 ≈ 1.21:1)
- Use `mark-current-color.svg` when embedding in colored UI elements

❌ Don't:
- Stretch, rotate, skew, or add shadows/outlines to the mark
- Recolor outside the palette (black / white / brand green)
- Place the mark on busy photographic backgrounds without a solid
  backing plate
- Recreate or redraw the mark; always use the official SVG
- Use the emerald variant as the default — it is an accent

## 3. Color

### 3.1 Palette

| Role | Name | Hex | RGB | Notes |
|---|---|---|---|---|
| Core | Ink | `#171717` | 23 23 23 | Primary dark / text on light |
| Core | Paper | `#FAFAFA` | 250 250 250 | Primary light / text on dark |
| Core | White | `#FFFFFF` | 255 255 255 | Backgrounds on dark theme, mark ink |
| Core | Black | `#000000` | 0 0 0 | Mark ink on light |
| Surface scale | Zinc | `#09090B` → `#F4F4F5` | — | Tailwind zinc scale; backgrounds, borders, muted text (zinc-950 page background, zinc-800 borders, zinc-500 muted text) |
| Signal | Brand Green | `#10B981` | 16 185 129 | Primary accent: buttons, links, success, earned states |
| Signal | Highlight Green | `#00FF00` | 0 255 0 | High-emphasis highlight states only (rare) |
| Signal | Deep Green | `#005500` | 0 85 0 | Highlight backgrounds / borders on dark |

### 3.2 Usage ratio

Approximately **90% monochrome / 8% brand green / 2% highlight green.**
The identity is monochrome first; green signals action or success. If a
screen reads as "green brand," there is too much green.

### 3.3 Themes

- Dark theme (default product): zinc-950 background, white and zinc text,
  brand green accents.
- Light theme (docs, print): paper background, ink text, brand green
  accents.

### 3.4 Accessibility

- Ink on Paper: 16.8:1 ✅
- Brand green `#10B981` on dark zinc `#09090B`: ~7.5:1 ✅ (AA/AAA text)
- Brand green on white: ~2.5:1 ❌ — never use green for body text on light
  backgrounds; large graphics only, or darken to `#047857` for text links
- Highlight green `#00FF00` is display-only; never body text

## 4. Typography

### 4.1 Brand typeface — Chakra Petch

**Chakra Petch** (SIL Open Font License) is the primary brand typeface. It
sets the wordmark and the app navbar. Font files live in `fonts/`
(weights 300–700, plus italics) and in the web app at
`web/src/assets/fonts/`.

### 4.2 UI typeface — SF Pro Display

Body copy and UI chrome use the Apple system stack:

```css
font-family: SF Pro Display, SF Pro Icons, "Helvetica Neue", Helvetica, Arial, sans-serif;
```

Do not load a webfont substitute for UI text.

### 4.3 Hierarchy

| Level | Face / weight | Size (web) | Tracking |
|---|---|---|---|
| Wordmark | Chakra Petch Bold | 20px (navbar) | 0 |
| H1 / display | SF Pro Semibold 600 | 35–48px | -0.02em |
| H2 / section | SF Pro Semibold 600 | 24–28px | -0.01em |
| Body | SF Pro Regular 400 | 14–16px | 0 |
| Code / labels | Medium 500 | 12–13px | 0, monospace optional |

### 4.4 Wordmark treatment

"ModelWorks" — Chakra Petch Bold, one word, sentence case. Never
all-caps, never two words, never a different weight. When possible use
the pre-outlined SVGs in `logos/` rather than live text.

## 5. Applications

- **Web app**: dark theme defaults; mark in the navbar uses
  `mark-white.svg`; favicon is the mark.
- **Docs**: light theme, `mark-black.svg`.
- **Social**: `social/og_1200_600.png` for Open Graph / Twitter cards.
  For any social graphic needing the full lockup, use
  `logos/lockup-black.svg` / `logos/lockup-white.svg` as-is — never
  rebuild the lockup by hand.
- **Terminal / CLI (quack)**: ASCII-safe rendering; use the wordmark only.

## 6. Asset Index

| File | Purpose |
|---|---|
| `logos/mark-black.svg` | Bird, black ink — light backgrounds |
| `logos/mark-white.svg` | Bird, white ink — dark backgrounds |
| `logos/mark-current-color.svg` | Bird, inherits CSS text color |
| `logos/mark-emerald.svg` | Bird, brand-green ink — accent use |
| `logos/wordmark-black.svg` | Wordmark, Chakra Petch Bold outlined — black ink |
| `logos/wordmark-white.svg` | Wordmark, Chakra Petch Bold outlined — white ink |
| `logos/lockup-black.svg` | Bird + wordmark lockup — black ink |
| `logos/lockup-white.svg` | Bird + wordmark lockup — white ink |
| `fonts/` | Chakra Petch family (300–700 + italics, OFL) + CSS |
| `social/og_1200_600.png` | Open Graph / social card (1200×600) |
| `preview.html` | One-page visual sheet of all of the above |

## 7. Changes

Brand assets and guidelines live in `brand_kit/`. Propose changes the same
way as code: open a PR. The canonical sources are the bird mark in
`web/public/logo_white.svg` (black ink) and `web/public/logo_dark.svg`
(white ink) and the Chakra Petch brand fonts in
`web/src/assets/fonts/` — if either changes there, regenerate this kit.