# Obney.ai Design System

The visual + voice operating system for **Obney.ai**, a Baton Rouge-based
software consultancy that builds greenfield systems for the AI era. This
folder is a self-contained design system: tokens, type, color, components,
brand assets, and a marketing UI kit — usable both as a Claude design
context and as an Agent Skill in Claude Code.

---

## Who Obney is

Obney.ai is a small, opinionated consultancy that specializes in
**greenfield software**: clients come to them with something new to build,
and Obney builds it to last. For the past 18 months they have been paying
close attention to how AI is changing the way software gets built — and
have positioned the firm ahead of it. Their differentiator is _deliberate
architectural decisions made up front_, so the systems they deliver can
absorb new AI tooling as it matures without requiring a rebuild every time
the landscape shifts. They've codified this approach into internal
frameworks that shape every engagement.

The team is small, ships fast, and takes ownership seriously.

## Surfaces represented

| Surface        | Folder               | Status                                                                                                                                   |
| -------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Marketing site | `ui_kits/marketing/` | **Reference application** — no source codebase or Figma was provided, so this is the brand applied to typical consultancy-site patterns. |

> ⚠ **No production codebase, Figma file, or sample slide deck was supplied
> with this brand.** Surfaces here are derived purely from the brand
> guidelines PDF and logo SVGs. Treat the UI kit as a starting point, not
> a faithful copy. (See _Caveats_ at the bottom.)

## Sources

| Source                                                                          | Where it lives                                                                       |
| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `Obney.ai-Brand-Guidelines.pdf` (Feb 2026, 21 pages)                            | `assets/Obney.ai-Brand-Guidelines.pdf` — extracted into design tokens + voice rules. |
| Logo SVGs (midnight, ocean, midnight+ocean, white, green, orange, pink, yellow) | `assets/logos/`                                                                      |
| Figma / codebase                                                                | _None provided._                                                                     |
| Sample slide deck                                                               | _None provided._                                                                     |

---

## Index — what lives where

```
README.md                  ← you are here
SKILL.md                   ← Agent-Skill manifest (for Claude Code)
colors_and_type.css        ← all design tokens as CSS custom properties

assets/
  Obney.ai-Brand-Guidelines.pdf
  logos/
    logo-midnight-and-ocean.svg   ← primary lockup
    logo-midnight.svg              ← single-color (dark on light)
    logo-white.svg                 ← single-color (light on dark)
    logo-ocean.svg                 ← cyan tertiary
    logo-green.svg                 ← accent tertiary
    logo-orange.svg                ← accent tertiary
    logo-pink.svg                  ← accent tertiary
    logo-yellow.svg                ← accent tertiary
    png/  logo-*-2x.png, logo-*-4x.png   ← transparent raster, retina
    jpg/  logo-*.jpg                     ← opaque (white or midnight bg)

components/                ← exported React components (in the bundle)
  Button.jsx + Button.d.ts       ← pill button, 4 variants / 3 sizes
  Label.jsx + Label.d.ts         ← mono-caps pill label + status dot
  Eyebrow.jsx + Eyebrow.d.ts     ← section eyebrow
  button.html, label.html        ← @dsCard previews

preview/                   ← cards that populate the Design System tab
  _card.css
  type-*.html, color-*.html, spacing-*.html,
  components-*.html, brand-*.html
  brand-iconography.html

ui_kits/
  marketing/
    README.md
    index.html             ← mountable demo
    App.jsx                ← Nav, Hero, Work, Values, Method, CTA, Footer
```

## Components — the exported, reusable layer

Three primitives are compiled into `_ds_bundle.js` and exposed on
`window.ObneyAiDesignSystem_019e1d`. Consume them in any page that loads
the bundle:

```js
const { Button, Label, Eyebrow } = window.ObneyAiDesignSystem_019e1d;
```

| Component   | Props                                                                                | Notes                                                     |
| ----------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------- |
| `<Button>`  | `variant` (primary·accent·secondary·ghost), `size` (sm·md·lg), `disabled`, `onClick` | Pill radius, one-step hover shift on the brand scale.     |
| `<Label>`   | `bg`, `color`, `dot`                                                                 | Mono-caps pill for tags / categories / status.            |
| `<Eyebrow>` | `color`                                                                              | The `— Section label` kicker that precedes most headings. |

The larger marketing compositions (`Nav`, `Hero`, `Work`, …) live in
`ui_kits/marketing/App.jsx` and are _not_ bundled — they're a reference
kit you copy from, layered on top of these three primitives.

---

## CONTENT FUNDAMENTALS

> Source: brand guidelines, _Voice & Tone_ (p. 17), _Values_ (p. 1).

### Three rules of thumb

1. **Approachable expert.** Expert guidance delivered with warmth and
   clarity. The reader should feel "I can do this too."
2. **Tasteful and refined with personality.** Mirror the quality of the
   work. **No emoji**, no overly casual phrasing. Personality is in the
   sharpness of ideas, not in the punctuation.
3. **Uplifting rather than critical.** Lead with encouragement and
   possibility. Talk about what _can_ be achieved, not what's lacking.

### How copy actually reads

- **Sentence case for headlines.** ALL-CAPS only on mono labels / eyebrows
  (e.g. `— GREENFIELD SOFTWARE · BATON ROUGE, LA`).
- **First-person plural.** Obney says "we" — never "I", rarely "you" as a
  command. Reads like a small team explaining what they do.
- **Declarative, short.** Headlines run 5–10 words. Body sentences rarely
  break 20.
- **Specifics over hedging.** "Eighteen months" not "for a while now".
  "Eleven weeks" not "fast". "Five rules" not "a few principles".
- **Tradeoff-acknowledging.** Copy openly names the cost. _"We absorb cost
  or effort rather than lower the standard."_
- **Long-game framing.** _"Build it to last."_ _"Built to absorb what's
  coming."_ _"Partners, not projects."_
- **Em-dashes and periods do the heavy lifting.** Almost no exclamation
  marks. No emoji or unicode decoration in copy.

### What to avoid

- Marketing superlatives ("blazing-fast", "world-class", "supercharge").
- Emoji of any kind — even in CTAs.
- Second-person imperatives that sound aggressive ("Crush your", "Unleash").
- AI-buzzword stacking. Obney talks about _systems that absorb AI tooling_,
  not "AI-native platforms".

---

## VISUAL FOUNDATIONS

### Color

- **Primary pairing:** Midnight `#142C37` + Ocean `#68E4E9`. Almost every
  Obney composition rests on this pairing.
- **Cream / off-white** (`#F5F1EA` or the muted neutral `--midnight-50`)
  is the preferred light surface in marketing contexts; pure `#FFFFFF` is
  reserved for cards and inputs.
- **Accents** (green, orange, pink, yellow) are used **one at a time**, as
  a category signal or a tertiary logo color. Never stacked.
- The **Midnight scale** is the neutral system — there is no separate
  gray. Everything from page background to text inherits from it.
- AA contrast is enforced on every approved pairing (see _Preferred
  pairings_ card).

### Type

- **Figtree** for almost everything (UI, headings, body). Weights light,
  extrabold, and black are **marketing-only** — keep them off product
  surfaces.
- **IBM Plex Mono** for eyebrows, labels, numerics, status pills, code.
  Tracked `0.08em` and uppercased when used as a label.
- **Cal Sans** is display-only. Reach for it on hero headlines and big
  marketing moments; never for body, never below ~48 px.
- Hierarchy: Display → H1 → H2 → H3 → H4 → Subheading 1/2 → Body 1/2/3
  → Helper 1/2. See `colors_and_type.css` for exact sizes.

### Backgrounds & layout

- **Flat fills.** Backgrounds are solid Midnight, Cream, or pure white.
- **No gradients.** The brand explicitly avoids the bluish-purple gradient
  trope. The only acceptable "color shift" is large-area accent fills
  (e.g. ocean-100 section break, midnight section break).
- **No repeating patterns or textures** out of the box. (The brand
  guidelines have a _Visual Motif Exploration_ page but no patterns
  ship with the kit — flag if you need texture.)
- **Generous whitespace.** Marketing sections breathe at `96px` vertical
  padding; product surfaces at 48–64.
- **Eyebrows are part of the rhythm.** A mono eyebrow precedes nearly
  every section heading: `— Eyebrow text`.

### Animation

- **Quiet.** Hover/focus transitions are 120–200 ms on standard easing
  (`cubic-bezier(.2,.7,.1,1)`). No bounce, no spring, no long fades.
- **Motion is for confirmation, not decoration.**

### Hover, press, focus

- **Hover** → step one stop on the Midnight or Ocean scale
  (`midnight-800` → `midnight-700`, `ocean-400` → `ocean-500`).
- **Press** → step two stops, or invert (outline button fills on press).
- **Focus** → 3 px outer ring at `rgba(104, 228, 233, 0.45)` plus a
  `border-focus` color shift on the element itself.

### Borders & shadows

- **Borders are crisp 1 px** in `--midnight-100` for default and
  `--midnight-200` for strong. Borders carry more weight in the system
  than shadows.
- **Shadows are restrained**: `shadow-xs / sm / md / lg` are all
  Midnight-tinted at low alpha. The brand prefers a sharp 1 px edge over
  a soft halo. Avoid bold drop shadows.
- **No inner shadows** in product surfaces.

### Radii

- **Pill (`999px`)** for buttons and labels — non-negotiable.
- **`md` / `lg`** (12 / 16 px) for cards.
- **`sm`** (8 px) for inputs.
- **`xs`** (4 px) for inline code, small chips.

### Transparency & blur

- Used sparingly. The footer's dimmed copy uses 60–85 % white opacity on
  Midnight; that's about as far as transparency goes. **No backdrop blur**
  in default treatments.

### Imagery

- _No imagery shipped with the brand guidelines_ — flag for replacement.
- When sourcing: **cool, considered, slightly desaturated**. Studio /
  architecture / system photography over warm lifestyle. Avoid the warm
  golden-hour palette; lean toward the Midnight + Ocean color story.

### Card pattern

- White fill, 1 px `--border`, `radius-md` (12) or `radius-lg` (14–16),
  internal padding 18–28 px.
- Inverse cards: Midnight fill, no border, same radius. The brand's
  signature dark card.
- Accent cards: `ocean-100` fill with a faint `ocean-200` border.

### What to avoid

- Bluish-purple gradients.
- Emoji as iconography.
- Cards with a colored left-border only.
- Hand-drawn / sketchy SVG illustrations.
- Stacked accents (e.g. pink + green on the same surface).
- Inter or Roboto as a fallback — fall back to system sans, not those.

---

## ICONOGRAPHY

**No icon set shipped with the brand kit.**

- **Substitution:** [Lucide](https://lucide.dev) is used as a stand-in
  (see `preview/brand-iconography.html`). Lucide's 1.75-stroke outlined
  style matches the brand's restrained, technical feel and pairs cleanly
  with IBM Plex Mono labels.
- Render at **24 px on a 24 px grid**, **stroke-width 1.75**, color set to
  `--fg-1` (Midnight) on light surfaces, `--color-ocean` on dark.
- Always paired with a label — icons in Obney never carry meaning alone.
- **Emoji are not used.** The brand guidelines explicitly avoid them.
- **Unicode characters** appear _only_ as eyebrow dashes (`—`) and
  middle dots (`·`). Never as icons.
- Logo SVGs (`assets/logos/`) are the only first-party visual marks.

> 🚩 **Flagged for the user:** please drop a finished icon set (SVG sprite,
> font, or Figma library) into `assets/icons/` so the substitution can be
> retired. If Lucide is fine as-is, just confirm and we'll bake it in.

---

## TYPOGRAPHY FONTS — substitution flag

Per the brand guidelines (_Resources_, p. 21), all three typefaces are
available on Google Fonts; `colors_and_type.css` imports them from there.

> 🚩 **No locally-hosted font files were provided.** If Obney wants to
> ship the system inside a product that needs self-hosted fonts (for
> privacy or perf), drop `.woff2` files into `fonts/` and we'll swap the
> `@import` for `@font-face`. The exact Google releases used are:
>
> - Figtree (weights 300–900)
> - IBM Plex Mono (weights 300–500)
> - Cal Sans Regular (via `@fontsource/cal-sans`)

---

## Caveats — what's missing

1. **No codebase / Figma.** The UI kit is brand-applied, not brand-copied.
2. **No icon set.** Lucide substituted; flagged above.
3. **No locally-hosted font files.** Google Fonts CDN used; flagged above.
4. **No production imagery.** The brand guidelines have a _Visual Motif
   Exploration_ page but no exported assets accompanied it.
5. **No sample slide deck.** Slides folder intentionally omitted — see
   project brief: "If no sample slides were given, don't create them."
6. **Color shades + secondary palette inferred.** The brand PDF previews
   shades and accent colors visually, but exact hex values for shade
   stops were not text-extractable. The Midnight + Ocean scales here are
   _derived_ from the brand hexes using OKLCH-balanced steps — they
   match the _visual intent_ of the guidelines' shade swatches but are
   not pixel-confirmed.

---

## Quick start (for designers / prototypers)

```html
<!-- Drop this into <head> -->
<link rel="stylesheet" href="path/to/colors_and_type.css" />

<!-- Use tokens via CSS vars -->
<h1 style="font-family: var(--font-display); color: var(--midnight-800)">
  Build it to last.
</h1>
<button
  class="o-btn"
  style="background: var(--color-ocean); color: var(--midnight-800)"
>
  Get started
</button>
```

Cards in `preview/` show every token in context. The marketing UI kit
in `ui_kits/marketing/` shows them composed.

---

_Last assembled: May 12, 2026_

---

## Local additions (obney-internal — added 2026-06-25)

This folder is the canonical brand home at `~/dev/branding/`. On top of the official export above:

- **[`index.html`](index.html)** — the **design system catalog**: a proper, natively-rendered site (no iframes) with a dark sidebar, scrollspy, and click-to-copy tokens. Color, type, space, and components are rendered live from `colors_and_type.css` via [`catalog.css`](catalog.css) + [`catalog.js`](catalog.js). Built to live at `obney.ai/design`. All paths are relative, so it works under any base path.
- **[`gallery.html`](gallery.html)** — the original card-by-card specimen gallery (every `preview/` + `components/` card embedded as an iframe). Kept for reference; the catalog supersedes it.

### Deploy (Cloudflare Pages)

The catalog is pure static — no build step. Two ways to put it at `obney.ai/design`:

1. **Own Pages project** — point Cloudflare Pages at this folder (no build command, output dir = repo root). It serves at `/`; route `obney.ai/design/* → ` the project at the zone level. [`_headers`](_headers) ships sane caching + security headers.
2. **Nested in the main site** — drop this folder in at `/design` of the obney.ai Pages repo. Relative paths resolve under the prefix; serve with a trailing slash (`/design/`).

> Note: directory links (e.g. `targets/`) rely on an autoindex that Cloudflare Pages doesn't provide — add an `index.html` there if you want it browsable on the deployed site. The Python dev server (`python3 -m http.server 8090`) autoindexes locally.
- **[`design.md`](design.md)** — the [DESIGN.md](https://github.com/google-labs-code/design.md)-format file (YAML tokens + rationale) that coding agents read. The entry point. Includes a _Consuming this design system_ section for our three build targets.
- **[`targets/`](targets/)** — how to consume the DS in **static HTML**, **minimal React**, and **Grain** apps. `targets/grain/` has a ready `tokens.css` + `main.css` bridge (Tailwind v4 `@theme`), plus the migration note for `obney-ops-workshop`.
- **`assets/favicon/`** — favicon + web-manifest kit (not in the original export).
- **`assets/motifs/`** — `FactoryPipeline.tsx` + `circuit-bg.svg` from the live marketing site. Reuse for set-pieces; **not** canonical DS assets (see `assets/motifs/NOTE.md`).
- **[`examples/client-application.md`](examples/client-application.md)** — applying the brand to client product work.

**Canonical-color note (2026-06-25):** this official export is the source of truth — cream `#F5F1EA` + ocean `#68E4E9`, no `#18ABB8`. The live obney-ai site (and an early client mockup) currently ship a drift variant (warm paper `#FAF8F4` + `#18ABB8`); reconcile those back to this over time.