# Tehom Design System

The working design system for the **Tehom brand family** — Tehom, Yehi, and YHWH. Tehom AI is the entity that owns and develops agentic AI systems and the infrastructure that supports them; Yehi is its methodology sub-brand; YHWH is its alignment memory layer. The name Tehom is Hebrew (תְּהוֹם, *tehom*, "the deep") — the formless primordial waters of Genesis 1:2 over which the Spirit hovered before creation. **Every brand decision flows from a single image: light hovering above a threshold, order propagating through depth, darkness as medium rather than void.**

This system is **dark-first**. It is **restrained**. It uses **six colors**, **three typefaces**, **one mark**, and **one Name** — YHWH (יהוה) — that founds the family.

> The brand is theologically explicit but visually covert *for Tehom and Yehi.* A layperson sees a clean five-letter abstract word; a reader of Scripture sees the second verse of the Bible. Hebrew script and Genesis framing stay off marketing surfaces, product UI, paid-acquisition, and sales decks.
>
> **YHWH inverts that posture by design** — the alignment memory layer's function *is* to anchor work to the canonical Source, so YHWH wordmarks and surfaces are explicitly theological. The split is intentional and is documented in detail in [`brand_family/yhwh-foundation.md`](brand_family/yhwh-foundation.md) and [`brand_family/v1-4-draft.md`](brand_family/v1-4-draft.md).

---

## Index — what's in this folder

| File / folder | What it is |
|---|---|
| `README.md` | This file. Brand orientation, content fundamentals, visual foundations, iconography. |
| `SKILL.md` | Cross-compatible Agent Skill for use in Claude Code or this environment. |
| `colors_and_type.css` | Locked color tokens, type scale, spacing, motion, button + card patterns. Drop-in. |
| `assets/logos/` | Tehom mark, wordmark, and lockup SVGs — dark + light variants. **The canonical source.** |
| `assets/icons/` | 47 hairline geometric icons (24×24 viewBox, 1 stroke, `currentColor`). |
| `brand_family/` | **The family.** YHWH foundation document, Yehi + YHWH sub-brand kits, v1.4 brand-guidelines draft. |
| `preview/` | Per-card preview HTML files that populate the Design System tab. |
| `ui_kits/marketing/` | High-fidelity recreation of the tehom.ai marketing site as JSX components. |
| `reference/` | Source documents: brand guidelines v1.3, archetype profile, BrandScripts, locked landing page v6. |
| `fonts/` | Empty — fonts load from Google Fonts CDN. See "Font files" caveat below. |

### Sources this system was built from

- **`brand/tehom-brand-assets/`** (local mounted folder) — the canonical asset pack v1.1 + brand guidelines v1.3. Logos, icons, source `.op` (OpenPencil) files, the locked landing page HTML, the brand preview screenshot.
- **`brand/persona/`** (local mounted folder) — archetype profile (Magician 60% / Sage 40%) and BrandScripts for the two first customers, H&J Petroleum and PetroSuites.
- **`uploads/tehom-brand-guidelines-v1.3.md`** — same content as the mounted folder, retained as a paper trail.

All originals copied into `reference/` so this skill remains usable after the mounted folder is detached.

---

## What Tehom is

Tehom AI is an **IP-holding entity**, not a product company. It plays three roles, all under one LLC:

1. **Substrate owner** — holds the canonical standards, the Internal Developer Platform, the operating substrate.
2. **License grantor** — grants operating businesses consumption rights under Platform License Agreements.
3. **Development partner** — delivers full-stack bespoke applications under Development Services Agreements.

The brand surface speaks for all three roles in the same voice.

### Brand family

The family flows from **YHWH (יהוה, the Tetragrammaton)** as the foundation — the I AM, the Source. Three named members carry the work into the world:

- **Tehom (תְּהוֹם)** — *the deep.* Parent brand. Substrate, IP, brand surface. Genesis 1:2. **Stealth-theology posture.**
- **Yehi (יְהִי)** — *let there be.* Methodology sub-brand. The bet-driven execution cadence for agentic teams (Shape Up evolved for agentic teams). Genesis 1:3a. **Glyph mark adopted in v1.4** (dot + dashed descent + short emerging horizon). **Stealth-theology posture.** Phonetically: *YEH-hee*.
- **Or (אוֹר)** — *light.* Alignment-memory sub-brand. The canon, virtue lattice, alignment scoring, Frameworks, Rituals. **Glyph mark adopted in v1.4** (vertical mirror of the Tehom mark — arcs ascending). **Stealth-theology posture.** Operational codename: `YHWH-OS`. Phonetically: *ohr*.

> The Tetragrammaton — **YHWH (יהוה)** — names the Source the brand family serves. It is **not a brand**. The Name appears as a reverent glyph on permitted theology surfaces only (origin docs, business-card backs, about-page footers, internal codenames). Tehom became the brand surface *precisely because* YHWH cannot be reduced to a brand. See [`brand_family/yhwh-foundation.md`](brand_family/yhwh-foundation.md) and [`brand_family/reverent-glyphs/README.md`](brand_family/reverent-glyphs/README.md).

Reserved candidates per v1.3 § Brand Family: **Tov** (טוֹב, "good") — now reserved for the future **agentic testing layer**. **Yom** (יוֹם, "day/cycle") — reserved, no current assignment. Davar (דָּבָר, "the Word") is no longer a sub-brand candidate; it has been elevated alongside YHWH as a reverent glyph above the brand layer.

Read [`brand_family/yhwh-foundation.md`](brand_family/yhwh-foundation.md) for the theological framing, [`brand_family/README.md`](brand_family/README.md) for the family overview, [`brand_family/reverent-glyphs/README.md`](brand_family/reverent-glyphs/README.md) for the permitted-surface rules for YHWH and Davar, and [`brand_family/v1-4-draft.md`](brand_family/v1-4-draft.md) for the proposed brand-guidelines update.

### Archetype mix

**Magician 60% / Sage 40%**, locked per Mark and Pearson's canonical two-archetype structure. Magician supplies the verbs (turn, transform, build, propagate); Sage supplies the qualifiers (considered, rigorous, what the evidence supports). Together they produce copy that *promises something specific that the brand has actually done the work to deliver.* Reference brands in the same family: Apple modern era, DeepMind, Anthropic (mirror), Stripe (mirror), Wolfram Research.

---

## Content fundamentals — how Tehom writes

The brand voice is **restrained, grounded, lucid, patient, reverent**. It is not relentless, never disruptive, never effusive. Confidence shows up as quietness, not volume.

### Tone register

Restrained, considered, transformative. The Magician supplies the verbs; the Sage supplies the qualifiers. Tehom describes; Tehom does not sell. Long sentences are fine when they're earned. Plain language carrying real depth. Never jargon for its own sake.

### Casing

- **Sentence case** for headlines and section titles. Never Title Case. Never ALL CAPS for headlines.
- **Lowercase** for the wordmark, always. "tehom," never "Tehom" as the wordmark; "yehi," never "Yehi" as the wordmark. In prose, the brand name capitalizes normally ("Tehom AI," "Yehi by Tehom").
- **Mono uppercase, tracked** for `.meta` eyebrows (the section labels like `01 — THESIS`, `AGENTIC AI INFRASTRUCTURE`).
- **No em-dashes for emphasis.** Use ` — ` (spaced en dash) when separating clauses with breath.

### Voice (I vs you)

The brand speaks as **we** when describing what Tehom has done or built ("We have built this"), and as a third-person *brand-voice* observer when describing the world Tehom operates in ("Tehom is named for the second verse of Genesis"). It speaks to a **you** that is competent and busy — never patronizing. Never the breezy "we help businesses succeed" register.

### Do-use words

**Magician-side:** build, transform, turn, propagate, unlock, reimagine, vision, possibility, breakthrough, alchemy.
**Sage-side:** research, evidence, framework, principle, considered, rigorous, learn, understand, depth, clarity.
**Tehom-specific:** infrastructure, threshold, substrate, lineage, durable, lucid, deliberate, patient, spoken-into-being.

### Don't-use words

disrupt, relentless, hustle, grind, ninja, rockstar, game-changer, revolutionary (without proof), guaranteed, easy, simple (when it isn't), AI-powered (as marketing dust), unleash, supercharge, intelligent, autonomous (as marketing dust).

### Don't-use phrases

- "We help businesses succeed."
- "Empower your team."
- "Take it to the next level."
- "Build the future."
- "Trust the process" (used as hand-wave).
- "We're different because we care."
- Anything that promises transformation without naming what specifically transforms.

### Emoji

**Never.** The brand voice doesn't use them. Not in marketing copy, not in product UI, not in documentation, not in commit messages on the brand surface. Status is communicated with the dot system (idle/active/error/complete circles) — that *is* the emoji vocabulary.

### Calibration examples

> **Wrong:** "Tehom AI is the relentless next-generation autonomous agent platform that empowers developers to ship faster than ever before."
>
> **Right:** "Tehom AI is the harness for agentic development. We build the orchestration layer that turns intent into shipped code."

> **Wrong:** "Praise God, we're so excited to announce we're building AI grounded in biblical principles!"
>
> **Right:** "Tehom is named for the second verse of Genesis. The work it does is the work that name implies."

The first version sells. The second describes. Tehom describes.

### Theology surface discipline

The Hebrew script (תְּהוֹם, יְהִי) and explicit Genesis framing are **permitted** in: origin documentation, internal references, the website about-page footer, business-card backs. They are **not permitted** in: marketing copy, paid-acquisition surfaces, product UI, goal/status/operational documents, anywhere the brand is selling rather than describing. When in doubt, do not lead with theology; if it appears, it appears as undercurrent.

---

## Visual foundations

The brand renders a single image in every surface: *light hovering above a threshold, order propagating through depth.* What follows is how that image translates into UI primitives.

### Color

Six tokens. Six is the maximum.

| Token | Hex | Role |
|---|---|---|
| `--tehom-deep` | `#050A10` | Primary background. The deep. |
| `--tehom-light` | `#FAF7F2` | Primary foreground. The light. |
| `--tehom-deep-elevated` | `#1A2638` | Surface elevation — cards, code blocks, dividers. |
| `--tehom-muted` | `#8A8680` | Tertiary text — captions, metadata, timestamps. |
| `--tehom-signal` | `#C9A961` | **Gold.** Used **sparingly** for meaning, agent active, status, focus on critical inputs. Never routine. |
| `--tehom-utility` | `#3D4F66` | **Slate.** Routine interactive elements — link underlines, hover, secondary buttons. |

Reserved: `#B05B3B` (terracotta) for **error states only.** It is not a sixth accent — it is an exception.

**Color architecture:** gold is for *meaning*, slate is for *function*. They should rarely appear in the same composition. When in doubt, use slate. Reserve gold. Body copy on `--tehom-deep` sits at 78–85% opacity of `--tehom-light` — codified in `--fg-2` / `--fg-3` in `colors_and_type.css`.

**Light-mode rendering** (when context demands it: print, light-mode UI prefs, certain doc types): background becomes `--tehom-light`, marks render in `--tehom-deep`, and **the dot becomes a hollow circle** (cream interior, deep stroke). Light entering darkness, never the reverse. A solid dark dot on a light field is theologically wrong.

### Typography

Three faces. Each stays in its lane.

- **Display — Fraunces Light.** Variable font, optical-size axis pinned at 144 (display character), 300 weight, normal letterspacing. The wordmark and major editorial headlines. Bracketed serifs, true-circle 'o' that echoes the mark's dot. SIL OFL (free). Locked interim — a custom Tehom display face is deferred until the brand earns it.
- **Body — Inter.** Geometric humanist sans. Weights 400 / 500 / 600. **Never 700 or heavier** — the voice is restrained.
- **Mono — IBM Plex Mono.** Code, terminals, agent logs, `.meta` eyebrows, hex codes. Slight humanist warmth; pairs with the serif.

The display serif carries **gravity**. The body sans carries **clarity**. The mono carries **craft**. Never use the serif for body. Never use the sans for the wordmark. Never use the mono for headlines.

### Spacing

Base unit **64px**, 1.5× progression: 16 / 32 / 48 / 64 / 96 / 128. Every spatial decision resolves to one of these values. No arbitrary numbers. See `--space-*` in `colors_and_type.css`.

### Backgrounds

- **Always solid colors.** `--tehom-deep` is default. `--tehom-deep-elevated` for code blocks and elevated panels. `--tehom-light` for light-mode surfaces only.
- **No gradients.** Not in backgrounds, not on the mark, not behind hero copy. Gradients suggest theatrics; the brand does not perform.
- **No photographic backgrounds.** If unavoidable (rare), overlay with `--tehom-deep` at 100% before placing brand elements. The brand never sits on a busy photographic field.
- **No repeating patterns or textures.** The medium is darkness — that's the texture. Adding more is noise.
- **No hand-drawn illustrations.** The mark's geometry is the illustration vocabulary. Hairlines, circles, arcs. Anything else is off-brand.

### Borders, hairlines, and dividers

- **1px hairline strokes everywhere.** Section dividers, card borders, button outlines, the underline on text links. Use `--hairline` (`rgba(250, 247, 242, 0.12)`) on dark.
- **Sharp corners.** `border-radius: 0` on cards, buttons, code blocks. The only rounded element is the dot motif (always a perfect circle).
- **No drop shadows. No inner shadows. No glows.** Surfaces separate via color and hairline, never via shadow.
- **No protection gradients, no capsules around marks.** The mark sits on a solid field, with clear space equal to the dot diameter on all sides.

### Cards

A Tehom card is: hairline-bordered, sharp-cornered, solid-background, no shadow. Either transparent on `--tehom-deep` with a hairline border, or filled with `--tehom-deep-elevated` and no border. Padding lands on a spacing token (typically `--space-three-quarter` = 48px).

### Hover and press states

- **Hover (links):** the underline transitions from `--tehom-utility` slate to `--tehom-light` (160ms quiet ease). Color does not change — only the underline.
- **Hover (nav text):** opacity from 72% → 100% on `--tehom-light` (160ms).
- **Hover (buttons, ghost):** border transitions from hairline → full `--tehom-light`; background picks up `rgba(250,247,242,0.03)` (a barely-there warm wash).
- **Hover (buttons, signal):** gold lightens from `#C9A961` → `#d6b873`.
- **Press:** no shrink, no scale. Brief opacity dip (~0.9) at most. The brand does not bounce.
- **Focus:** `--tehom-utility` slate ring on standard inputs; `--tehom-signal` gold ring on critical inputs only.

### Motion and animation

- **Quiet easing.** `cubic-bezier(0.4, 0.0, 0.2, 1)` for everything. No spring physics, no bounces, no overshoot.
- **Short durations.** `120ms` instant, `160ms` quick, `240ms` settle. Anything longer is reserved.
- **The breath.** The single load-bearing brand animation: the dot in the master mark pulses on a 4-second cycle, opacity `1.0 → 0.82 → 1.0`. This is "the Spirit hovers." It runs on the nav-bar lockup, the agent-thinking indicator, and nowhere else without intent. Respect `prefers-reduced-motion`.
- **No fade-in-on-scroll, no parallax, no scroll-jacking.** Sections appear because they're there.

### Transparency and blur

- **Avoid backdrop-blur.** The nav bar is **solid `--tehom-deep`** — never a frosted-glass translucent strip. On scroll, it gains a hairline divider below; that's all.
- **Text opacity is the only transparency in routine use** — body copy at 78%, supporting text at 66%, captions at the muted token. Surfaces are opaque.

### Imagery vibe

- **Cool, deep, restrained.** If imagery is used (rare), it leans cold-blue-black, never warm sunsets or vivid color.
- **Black and white acceptable, grainy acceptable** as long as it pairs with the deep ground.
- **Never AI-generated abstracts, never "data viz" stock, never team photos in marketing.** The mark is the imagery.

### Layout rules

- **Fixed nav** (sticky, solid, 80px tall, hairline divider on scroll).
- **Container width** maxes at 1160px; gutters scale with viewport (`min(1160px, calc(100vw - 48px))`).
- **Section-header grid:** a 260px meta column on the left, content on the right. This recurs throughout the marketing site and documentation.
- **Sections separate via 1px hairline + generous vertical padding** (`--space-double` typically), not via color blocks.

---

## Iconography

The icon family is defined in `assets/icons/` — **26 hairline geometric icons** drawn from the master mark's vocabulary. The set was copied from the canonical Tehom asset pack; do not redraw.

### Approach

- **System:** custom. The set lives in this design system and the Tehom repo's `web/app/dev/brand/icons` contact-sheet route. Not Lucide, Heroicons, Phosphor, etc. — though their stroke-weight conventions are kinship.
- **Canvas:** `viewBox="0 0 24 24"`.
- **Stroke:** `1.5` weight, `currentColor`, `round` linecaps and linejoins. Inherits the surface text color.
- **Fills:** none, by default. The only filled element is the **dot motif**, reserved for presence / focus / status. A filled small circle means "alive / selected / now."
- **Family principle:** every icon must look like it belongs beside the master mark. Circles, horizons, concentric arcs, radial propagation, dot grids, frame brackets. Diagonal lines and pointed shapes are restrained.
- **No emoji.** The dot vocabulary (idle hairline circle / active filled gold / error filled terracotta / complete filled light) is the brand's emoji equivalent.
- **No unicode glyphs as icons.** No `→`, no `✓`, no `★`. The system has explicit SVG icons for these.

### Inventory (v1.2, iterative)

| Group | Icons |
|---|---|
| Status / state | `idle`, `active`, `error`, `complete` |
| Navigation / frame | `arrow-{up,right,down,left}`, `menu`, `close` |
| Genesis-1 creation arc | `substrate`, `hover`, `yehi`, `threshold`, `tov`, `naming`, `firmament`, `davar` |
| YHWH (alignment memory) | `canon`, `virtue`, `alignment-score`, `void`, `life`, `body`, `ritual` |
| Tehom operational | `governance`, `orchestration`, `memory`, `cycle`, `runtime`, `evaluation`, `audit` |
| Yehi methodology | `bet`, `goal`, `spike`, `harvest`, `wisdom`, `blocker`, `cool-down`, `agreement`, `tenant` |
| Content / tool | `doc`, `code`, `terminal`, `agent`, `link-external`, `search` |

**47 icons total**, all in the substrate/domain group except for status/nav/content. The Genesis-1 creation arc traces YHWH's first utterances in order; the YHWH cluster covers alignment-memory concepts; the operational + methodology clusters cover Tehom and Yehi vocabulary. The remaining substrate icons name the brand's operational vocabulary.

**A brand-level convention has emerged.** Dashed strokes mean *less-solid, more-dynamic* — the `orchestration` cooperation links, the `yehi` descent. Solid strokes are stable artifacts; dashed strokes are acts-in-motion. Apply this consistently as the icon set grows.

**Status of designs.** The upstream pack ships with four locked designs (`active`, `substrate`, `threshold`, `cycle`) and twenty placeholder stubs. **This design system carries v1.1 drafts for all twenty** — designed in this project against the locked spec, family-tested against the master mark on the contact sheet at `preview/icons-contact-sheet.html`. These are not the canonical files yet; they are candidates for promotion into `brand/tehom-brand-assets/icons/` after design review. Until they land upstream, the SVGs in `assets/icons/` are the working drafts.

**Sibling test.** Every icon was checked against the master mark at the same scale per the family rule in `brand/tehom-brand-assets/icons/README.md`. Geometry vocabulary is honored: hairline circles, horizons, concentric arcs, dot grids, frame brackets. The dot motif is reserved for presence / focus / status — the four status icons all share circle-plus-dot geometry, distinguished only by color (idle uses currentColor stroke with no fill; active/complete/error fill the inner dot, with the consuming surface picking `--tehom-signal` / `--fg-1` / `--tehom-error`). The single intentional pointed shape is the `blocker` diamond — the brand allows pointed geometry when it carries the meaning, and a blocker is the icon whose job is to feel arresting.

### Logo and lockup files

`assets/logos/` contains the eight canonical files:

- `tehom-mark-{dark,light}.svg` — favicon, app icon, social avatar.
- `tehom-wordmark-{dark,light}.svg` — running headers, footnotes, continuation surfaces.
- `tehom-lockup-horizontal-{dark,light}.svg` — nav bars, email signatures, headers, footers.
- `tehom-lockup-stacked-{dark,light}.svg` — hero placements, splash screens, business cards.

In **light variants, the dot is a hollow circle.** This is theological, not decorative. Do not modify the geometry. Do not add glow, shadow, gradient, or 3D effects.

---

## Caveats and substitutions

- **Fonts now have a self-hosted path.** `fonts/fonts.css` declares the `@font-face` rules for Fraunces / Inter / IBM Plex Mono, expecting variable TTFs at `fonts/Fraunces.ttf`, `fonts/Inter.ttf`, `fonts/IBMPlexMono.ttf`. Drop the files in (all SIL OFL, free) and swap the Google Fonts `@import` in `colors_and_type.css` for `@import url("./fonts/fonts.css")`. See [`FONTS-AND-WORDMARK-EXPORT.md`](FONTS-AND-WORDMARK-EXPORT.md) for the full procedure. If you ship to a context where Google Fonts is unavailable, download the variable-font TTFs from each project's GitHub and self-host. **Flagged: if you have a preferred local-vendored bundle, drop it into `fonts/` and ask me to wire `@font-face` rules in `colors_and_type.css` so we stop relying on the CDN.**
- **Wordmark outline-paths still need a designer pass.** The Yehi and Or wordmark / lockup SVGs now embed a Google Fonts `@import` so they render correctly when opened directly or inline-loaded, but `<img>`-loaded contexts still fall back to a system serif until the wordmarks are converted to outlined `<path>` data the way `tehom-wordmark-{dark,light}.svg` already is. 14 files; full spec + designer process in [`FONTS-AND-WORDMARK-EXPORT.md`](FONTS-AND-WORDMARK-EXPORT.md).
- **Upstream sync to `brand/tehom-brand-assets/` is staged, not promoted.** All 57 icons + Yehi/Or kit + favicons are in [`promotion/`](promotion/) with copy operations documented in its README. The mounted `brand/` folder is read-only in this environment.
- **Some icons are placeholders upstream** (notably `agent`); see the iconography section.
- **No product UI surfaces exist yet.** Tehom is pre-product. The marketing site, the brand dev-route, and the icon contact-sheet are the only live surfaces. The "marketing" UI kit recreates the locked landing page v6. There is no app, dashboard, or agent console to recreate — those will arrive with the IDP work.
- **No slide template was provided.** I did not create sample slides. If you'd like a Magician/Sage-calibrated deck template, ask.

---

## Quick links

- **Brand family overview:** [`brand_family/README.md`](brand_family/README.md)
- **YHWH foundation:** [`brand_family/yhwh-foundation.md`](brand_family/yhwh-foundation.md) — **read first**
- **Yehi sub-brand kit:** [`brand_family/yehi/README.md`](brand_family/yehi/README.md)
- **YHWH sub-brand kit:** [`brand_family/yhwh/README.md`](brand_family/yhwh/README.md)
- **v1.4 brand-guidelines draft:** [`brand_family/v1-4-draft.md`](brand_family/v1-4-draft.md)
- **Brand guidelines v1.3 (canonical):** [`reference/tehom-brand-guidelines-v1.3.md`](reference/tehom-brand-guidelines-v1.3.md)
- **Archetype profile:** [`reference/tehom-archetype-profile.md`](reference/tehom-archetype-profile.md)
- **Locked landing page (source of truth for marketing kit):** [`reference/tehom_ai_landing_page_v6.html`](reference/tehom_ai_landing_page_v6.html)
- **Marketing UI kit:** [`ui_kits/marketing/index.html`](ui_kits/marketing/index.html)
- **Icon contact sheet:** [`preview/icons-contact-sheet.html`](preview/icons-contact-sheet.html)