# YardFlow by FreightRoll — Design System

> **Industrial Fluidity.** Stop the Variance Tax.

This is the design system for **YardFlow by FreightRoll** — the supply chain's first **Yard Network System (YNS)**, automating the loop from gate, to dock, to departed for every site in a network. Not a YMS; a **standardized operating protocol** that turns 50 disconnected yards into one calculable network.

The product positioning, voice, and visual language captured here are lifted directly from the production codebases — not invented — so designs you build on top of this system will feel native to the brand.

---

## Source repositories

This system was distilled from two GitHub repos the user attached. Explore them for deeper context, route copy, ROI logic, sprint plans, and component implementations:

- **`caseyglarkin2-png/Flow-State`** — earlier prototype (Next.js 16) with the Genesis genetic-layout optimizer, telemetry pipeline, and the original "Flow State by FreightRoll" framing. Aesthetic is cyan-on-void with a red Singularity map.
  https://github.com/caseyglarkin2-png/Flow-State
- **`caseyglarkin2-png/Flow-State-`** — the **production marketing site** (`flow-state-site/`) plus an enormous library of sprint plans, copy guidelines, brand audits, and ROI math. This is where the current YardFlow voice, the 7-step homepage spine, and the **flowDRIVER / flowBOL / flowSPOTTER / flowTWIN / flowAI / flowNETWORK** protocol modules live.
  https://github.com/caseyglarkin2-png/Flow-State-

If you have access, the highest-signal files for design work are:
- `flow-state-site/lib/branding.ts` (logo variants, copy lockup)
- `flow-state-site/lib/tokens.ts` (colors, motion, radii)
- `flow-state-site/styles/globals.css` (utility classes — `.section-shell`, `.surface-feature`, `.neon-glow`, `.text-flow`)
- `flow-state-site/components/icons/FlowIcons.tsx` (50+ custom SVG icons)
- `flow-state-site/components/homepage/HomepageContent.tsx` (canonical 7-step "Variance Tax" homepage)
- `docs/COPY_GUIDELINES.md`, `docs/BRAND_AUDIT.md` (voice, terminology, anti-patterns)

---

## Index — what's in this folder

```
README.md                 ← you are here
SKILL.md                  ← agent-skill manifest (drop into Claude Code as-is)
colors_and_type.css       ← CSS variables for color + type (semantic + raw)
assets/                   ← logos, OG image, favicons, hero artwork
preview/                  ← Design-System-tab cards (700×N specimens)
ui_kits/
  marketing-site/         ← yardflow.ai marketing site recreation
  operator-app/           ← flowTWIN / flowNETWORK operator console (in progress)
```

There are **no slides** in this system — the source repos didn't ship a deck template, so we don't speculate. Add `slides/` later if a real template is provided.

---

## Product context

**One company, two surfaces:**

1. **Marketing site (yardflow.ai)** — public-facing. Sells the YNS thesis: the yard is the leak; standardization is the fix; Primo Water is the proof. Hero, problem, protocol modules, evidence, ROI calculator, network audit CTA. Heavy on motion, glow, and dense data callouts.
2. **Operator app (flowNETWORK / flowTWIN)** — internal kiosk + console. Live yard topology, dwell alerts, BOL signatures, chain-of-custody timestamps. Designed to be readable on a 1500-nit kiosk under glove/resistive touch (`html.kiosk` mode in the prototype repo).

Both share the same dark-canvas + cyan-accent vocabulary, but the operator app skews more monospaced, more data-dense, and more functional.

**Six protocol modules** (the product's actual feature surface):
- `flowDRIVER` — digital gate check-in, FreightRoll ID, QR/wallet
- `flowBOL` — touchless BOL creation, immutable timestamp trail
- `flowSPOTTER` — spotter app: move queue, dispatch, completion
- `flowTWIN` — machine-vision + GPS digital twin of the yard
- `flowAI` — orchestration agent
- `flowNETWORK` — cross-site command view + simulation

---

## CONTENT FUNDAMENTALS — how to write for YardFlow

This is a **B2B logistics product sold to operations VPs and yard managers.** Copy is data-driven, operational, and direct. **Zero hype.**

### Voice attributes
- **Data-driven** — Specific numbers, not adjectives. "63% variance reduction" beats "amazing results."
- **Action-oriented** — What you (the customer) can do, not what we hope.
- **Operational** — Speaks the audience's language: dwell, gate time, detention, throughput, dock, yard, BOL.
- **Confident** — "We deploy in 90 days," not "we usually try to deploy."
- **No BS** — Transparent about timelines, costs, and the math.

### Person + tone
- **You / your.** Always second-person. "Variance costs **you** $8.4M per year."
- **We / our** sparingly, when describing the team or the product action ("We deploy in 90 days").
- **Imperative verbs in CTAs.** "Book a Network Audit." "Run ROI." Never "you can learn more" or "click here."

### Casing
- **Brand names compound, no spaces:** `FreightRoll`, `YardFlow`. Never "Freight Roll" or "Yard Flow."
- **Full lockup:** `YardFlow by FreightRoll` (lowercase "by").
- **Wordmark:** white `Yard` + neon `Flow` (split-color). The split is the brand.
- **Acronym:** `YNS` (Yard Network System). All caps. No periods.
- **Module names:** `flow` lowercase, module ALL CAPS — `flowDRIVER`, `flowBOL`, `flowAI`. In running text the neon-accent prefix renders just the `flow` in neon and the suffix in white/current.
- **Sentence case for headings.** Title Case only for proper nouns and module names.
- **Eyebrows:** ALL CAPS, letter-spaced (`0.3em`), neon @ 70% opacity. Always above hero/section titles.

### Terminology — preferred vs avoid
| Concept       | Use                          | Avoid                                  |
| ------------- | ---------------------------- | -------------------------------------- |
| Problem       | **variance** / Variance Tax  | chaos, inefficiency, waste             |
| Solution      | **standardized flow**, **standardized protocol** | efficiency, optimization, improvement |
| Network value | **network compounding**      | network effect, viral, going viral     |
| Location      | **yard**, **facility**       | site, warehouse, location              |
| Product class | **Yard Network System (YNS)**| YMS, yard management                   |
| Tagline       | **Industrial Fluidity.**     | "smart yards", "AI for yards"          |
| Customer evidence | **Ground Source Truth**, **chain of custody** | data, analytics, insights      |

### Length rules (from production COPY_GUIDELINES.md)
- **Sentences:** max 25 words, ideal 15–20. Operations leaders scan; long sentences lose attention.
- **Paragraphs:** max 3 sentences, ideal 2.
- **Hero headlines:** ≤ 16ch per line. Headlines wrap intentionally — `The First / Yard Network System` is the canonical homepage hero, broken in exactly that place.

### Emoji
- **Avoid in production UI and marketing copy.** The brand audit explicitly flags emoji as off-brand.
- The earlier prototype repo (`Flow-State`) does use `✦`, `→`, `✓`, `×` as inline markers — **these are unicode, not emoji**, and they ARE on-brand. Use the arrow `→` after CTAs, `✓`/`×` in checklists, `✦` for callouts.
- No 🚀, 🎉, 🧬, 📡, 🔒, etc. The Flow-State repo's old README leans on these — that file is legacy, not the canonical voice. Do not copy that emoji usage forward.

### Vibe — what to channel
- The cockpit of a modern container ship. The status board of a NASA mission control on quiet ops. A Bloomberg terminal at 3am.
- **Not:** a SaaS landing page with a lottie illustration. **Not:** a startup pitch deck. **Not:** a "logistics is hard, we make it easy" website.

### Concrete copy examples (lifted from production)
> **Variance costs you $8.4M per year.**
> Standardized flow eliminates variance. Primo reduced variance by 63% in Year 1.
> [Book a Network Audit] [Run ROI Calculator]

> The First **Yard Network System.**
> A standardized operating protocol — not a YMS — that made each of over 20 sites at least $1M+ more profitable.

> **Defensible Evidence from Day One.**
> We do not deal in projected savings. We deal in Ground Source Truth.

---

## VISUAL FOUNDATIONS

### The canvas
- **Background is always near-black.** Default is `#050505` ("the void"). Carbon `#1A1A1A` is the elevated-surface tone. There is a `.light-mode` override in production CSS but the brand lives in the dark.
- **No marble, no gradient-explosion hero backgrounds.** The canvas is matte, sometimes lit by a single soft radial glow (`bg-neon/5 rounded-full blur-3xl`) positioned behind a hero or section break.
- **Optional grid overlay** — a 50×50px line grid at `rgba(0,180,255,0.10)` line color, sometimes animated drifting via `grid-move` keyframe (20s linear infinite). Used on hero sections under the `.grid-background` / `.signal-grid` (44×44 variant) classes. **Use sparingly.**

### Color usage rules
- **One primary accent: `--neon` (#00B4FF).** Used for CTAs, links, eyebrows, KPI numbers, the "Flow" half of the wordmark, the neon-glow keyframe text shadow.
- **One alert/problem accent: `--ember` (#FF2A00).** Used **only** for the Variance Tax / problem section, ember radial glow, the red Singularity map dots, validation errors, "×" markers in the "typical reality" checklist.
- **Variance Tax pairing:** when comparing chaos→order, use **`--freightrollRed` (#D91411)** for cost/variance and **`--cerulean` (#05ACEB)** for savings/fluidity. This is a documented WebGL-shader-tested pairing.
- **Steel grays** for body copy — `--steel #9CA3AF` at 100/90/80/70/60/50% opacity is the entire body-text scale. The site never uses pure white for paragraph copy.
- **Never** invent purple, teal, or green. The palette is locked.

### Typography
- **Inter** for everything UI + display. Weights in use: 400, 500, 600, 700, **900 (Black)**. Hero headlines are always Black/900 with `letter-spacing: -0.04em` (extra-tight).
- **JetBrains Mono** for KPI digits, timestamps, codes, BOL signatures, dwell metrics — anything that should read as "raw operational data."
- **No serif.** No display alternates. No script.
- **Eyebrow → headline → lead → body** is the canonical type rhythm for every section.

### Imagery
- **Cool-toned, technical.** When real photos are used, they skew night-ops: night-shift yard lighting, lit dock doors, lit kiosks, screens. Warm-tone sunset/sunrise photography is off-brand.
- **No stock-illustration characters.** No "people working at laptops with floating chart icons." The product surface itself (yard topology, kiosks, signed BOLs) is the imagery.
- **Full-bleed imagery is rare** — the brand prefers product-surface mockups inside `.surface-card` containers over hero photography.
- See `assets/feature-yardflow-network.png` and `assets/og-proof-beats-promises.png` for canonical brand imagery samples.

### Animation
- **Subtle. Always.** Easing is `cubic-bezier(0.4, 0, 0.2, 1)` (standard material curve).
- **Durations:** instant 100ms, fast 200ms, normal 300ms, slow 500ms, slower 800ms. Never longer than 800ms for UI feedback.
- **Three signature motions:**
  1. **`wave` text-shadow ebb** (3s ease-in-out infinite) on the wordmark `Flow` and key hero accents — neon glow softly breathes.
  2. **`signalPulse`** — a 3.2s pulsing ring + dot used for "system is live" status (`<StatusPulse>`).
  3. **`flow-shimmer`** — a linear gradient sweep used inside `.text-flow` and `.flow-border` to suggest flowing water/data.
- Framer Motion is used in production for stagger reveals on scroll (`staggerContainer` + `staggerItem`, fade + 20px translateY).
- **Respect `prefers-reduced-motion`.** The production CSS kills all animation under that media query — match.

### Hover states
- **Links:** color shifts `steel → neon`. No underlines added.
- **Cards (`.section-shell` / `.surface-card`):** `-translate-y-1`, border opacity bumps from `0.12 → 0.35`, and a subtle `shadow-neon/15` appears. Never grow.
- **Primary CTA (neon-fill):** background `neon → white`, text stays `void`. Plus `shadow: 0 0 25px rgba(0,180,255,0.7)`.
- **Secondary CTA (neon outline):** background fills `neon`, text inverts to `void`.
- **Wordmark / text glow** (`.neon-glow-hover`): text-shadow intensifies from a 10px halo to a 40px halo.

### Press / active states
- No shrink. Buttons keep their footprint and slightly dim or hold the hover glow. Tap targets are always ≥ 44×44 px (kiosk + mobile baseline from the production a11y tests).

### Borders
- **Hairline neon.** `1px solid rgba(0, 180, 255, 0.12)` is the default. It bumps to `0.16` for "feature" surfaces and `0.20–0.30` for "alert" / focus surfaces.
- **Never thick borders, never colored borders other than neon or ember.** A red `border-ember/20 bg-ember/5` pair is the only non-neon border.
- **Ember bordered cards** are exclusively for "the typical reality / what's broken" callouts.

### Shadows
- **Outer:** layered. `--sh-lg: 0 18px 60px rgba(0,0,0,0.22)` for cards; `--sh-xl: 0 24px 80px rgba(0,0,0,0.28)` for tool surfaces.
- **Inner:** `inset 0 1px 0 rgba(255,255,255,0.05)` is the top-edge highlight on every "tool" surface — it's what gives the operator-app cards their CRT-glass feel.
- **Neon glow shadow:** `0 0 20px rgba(0,180,255,0.3)` for CTA hover, doubled (`0 0 25px + 0 0 50px`) at full intensity.
- **Text-shadow** is used heavily on hero titles via the `wave` keyframe. Multi-layered: `0 0 10px / 20px / 30px` cyan stack.

### Transparency + blur
- **Glassmorphism, restrained.** `.glass-card` is `background: rgba(255,255,255,0.08); backdrop-filter: blur(12px); border: 1px solid rgba(255,255,255,0.12);` — used for header (`bg-void/80 backdrop-blur-md`), sticky CTA bar, and overlay panels.
- **Never** the iOS-control-center-style heavy frosted look. Always paired with a neon hairline border to stay on-brand.

### Layout rules
- **Max content width:** `max-w-7xl` (80rem / 1280px). Heros use `max-w-5xl`; section copy `max-w-3xl`; lead paragraphs `max-w-2xl`.
- **Padding:** sections `py-20 md:py-24`. Container side padding `px-6` desktop, `px-4` mobile.
- **Grid:** `gap-6` to `gap-8` for card grids. `md:grid-cols-2` and `md:grid-cols-3` are the two staples.
- **Fixed elements:** header is fixed top with backdrop-blur; sticky CTA bar slides up from bottom after 800px of scroll and hides 300px before the footer.

### Corner radii
- Inputs / small chips: `0.5rem` (`r-sm`)
- Buttons: `0.75rem`–`1rem` (`r-md` / `r-lg`)
- Cards: `1.25rem`–`1.5rem` (`r-xl` / `r-2xl`) — this is the brand's "shoulder" — distinctive, slightly soft
- Tool surfaces (operator app panels): `1.75rem` (`r-3xl`)
- **No fully rounded corners except on `.pill` chips and the `StatusPulse` dot.**

### Card recipes (use these — they're real CSS classes from `globals.css`)
- **`.section-shell`** — outer container for marketing sections. `border 1px solid neon/12`, layered linear+radial gradient bg, `shadow 0 18px 60px black/22`.
- **`.surface-card`** — generic content card. Same border, but a simpler vertical gradient bg.
- **`.surface-feature`** — hero-feature card with a top-left neon radial glow + a 120° highlight pseudo-element.
- **`.surface-tool`** — operator-tool surface. Darker, with inset top highlight and the largest outer shadow.

---

## ICONOGRAPHY

YardFlow ships a **proprietary 50+ icon SVG library** at `flow-state-site/components/icons/FlowIcons.tsx` — **NOT** Lucide, Heroicons, or any open set. Imports of the library look like:

```tsx
import { Velocity, Shield, Crosshair, Agent, Nexus, Confirm } from '@/components/icons/FlowIcons';
```

### System characteristics
- **24×24 viewBox** (a few variants ship at 32×32 for the logo marks).
- **Stroke-based.** `strokeWidth="1.5"` is the default; `2` for emphasis paths, `1` for de-emphasized scaffolding.
- **`stroke="currentColor"` + `fill="none"`** is the dominant pattern, so icons inherit color. Solid accents are filled with `currentColor` at 100% or `opacity="0.4–0.6"` for fades.
- **Geometric, minimal, logistics-tech aesthetic.** No rounded-cute icons. No emoji derivatives. Custom-drawn paths.
- **Categories** in the library:
  - Directional: `FlowArrow`, `Pulse`, `Confirm`, `Dismiss`, `Chevron*`
  - Energy: `Velocity`, `Ignite`
  - Data: `Metrics`, `Timeline`, `Scope`, `Config`, `Trending`
  - Location/Network: `Nexus`, `Beacon`, `Orbital`, `Territory`
  - Security: `Lock`, `Shield`, `Caution`
  - Intelligence: `Cortex`, `Agent`, `Crosshair`
  - People/Org: `Team`, `Portfolio`, `Currency`, `Facility`, `Server`, `External`, `Export`, `DataFile`
  - Logistics: `Haul`, `Cargo`, `Plant`, `Cart`, `Anchor`, `Cycle`, `Genesis`, `Construct`
  - Communication: `Signal`, `Comm`, `Manifest`, `Waypoint`, `Device`, `Prism`
  - Archetypes (trailer types): `DryVan`, `Reefer`, `Intermodal`, `Flatbed`, `Tanker`

### Logos & marks
- **Logo mark:** `assets/logo-network.svg` is the canonical **Network Hub** mark (central node + 3 facility nodes + connecting paths + outer-circle context ring), in `#00B4FF`. There's an alternate **Flow** variant (the "industrial fluidity" flowing-arrow path) at `assets/logo-flow.svg` — used as the favicon and as the "micro" mark for ≤20px contexts.
- **Wordmark:** type-set in Inter, `Yard` in white + `Flow` in neon. No fixed SVG wordmark — it's HTML/CSS in production so the split-color works.
- **Origin line:** `by FreightRoll` in tiny tracked steel, sits directly below the wordmark.
- 4 historical logo variants existed in `lib/branding.ts` (network, flow, flow_v2, nexus, signal, flow_micro). The current production default is **`flow_v2`** — the Industrial Fluidity mark.

### Emoji & unicode
- **No emoji.** See content fundamentals above.
- **Unicode characters used as inline markers:**
  - `→` after CTAs ("Apply for Membership →", "See flowSPOTTER →")
  - `✓` in benefit lists (neon)
  - `×` in "typical reality" lists (ember)
  - `✦` for callouts / founding-member-program eyebrow (cyan)

### When you need an icon and one isn't in `FlowIcons`
Substitute **Lucide React** (`lucide-react@latest`, CDN: `https://unpkg.com/lucide-static@latest/icons/...`) — same stroke weight (1.5), same minimal-geometric vocabulary. **Flag every substitution to the user** with a code comment so they know it's not a real YardFlow icon.

---

## ⚠️ Caveats — flag to user

- **No webfonts shipped locally.** Inter + JetBrains Mono are loaded from Google Fonts (matching production, which uses `next/font/google`). If you need offline-safe fonts, drop TTFs into `fonts/` and update `colors_and_type.css` `@font-face` rules.
- **No slide deck template was provided.** The `slides/` directory is intentionally absent. Re-run if you ship a template.
- **The "Flow State by FreightRoll" prototype repo** uses the old name. The current production product is **YardFlow by FreightRoll**. Treat "Flow State" as a historical codename only.
- **Operator app UI was not fully built in either repo** — `flowTWIN` / `flowNETWORK` exist as marketing concepts and a few component scaffolds. The operator UI kit is a best-effort reconstruction from the homepage's mini-mockups + the `Singularity` Genesis map.