rto intelligence — Design System

A design system for rto intelligence — a free, open-source platform that answers questions about RTO governing documents in plain language. Every answer is cited, every source is verifiable, and the entire methodology is published.

• Live: https://www.rtointelligence.ai
• Repo: https://github.com/rdarrah7-code/rto-intelligence (Next.js 15 + Tailwind + Supabase)
• Built by: Ryan Darrah

What this repository is

This is a communication artifact, not a dependency. Its purpose is to make the visual and editorial rules of rto intelligence legible to anyone who needs to represent or extend the brand — designers drafting a pitch deck, a partner writing a co-marketing page, a journalist picking a screenshot, an LLM answering a question about the product, or a future contributor adding a new surface to the app.

It is a reference, not the source of truth for production code. The live rules live in rdarrah7-code/rto-intelligence (the Next.js app). This repository observes those rules, names them, and explains why they are the way they are so they can be reproduced faithfully off-platform.

Relationship to the product repository

	rto-intelligence (product)	this repository (design system)
Purpose	Ship the working platform	Document how the platform looks and sounds
Audience	Engineers running the app	Anyone communicating about rto intelligence
Contents	Next.js app, Supabase schema, retrieval pipeline	Tokens, UI kits, voice rules, preview cards
Source of truth for	Colors, components, copy	Rationale, patterns, cross-surface guidance
Update cadence	Continuous	Periodic — tracks the product

If the two drift, the product repository wins. When a color or component changes there, this repo should be updated to match. The one consistency check already run during this system's creation is documented in "Known issues" below — use it as a template for future audits.

Product context

rto intelligence is a research tool, not a chat product. It is aimed at energy professionals (firm transmission customers, financial traders, regulators, academics, consultants) who need fast, cited answers from governing documents published by three RTOs — MISO, PJM, and SPP — totaling 584 documents and 6,882 indexed excerpts. Every answer is grounded in retrieved source passages, every claim is cited, and a second model pass verifies groundedness before the answer is displayed with a confidence score.

Because the domain is regulatory, the brand leans serious, utilitarian, and trustworthy — close in spirit to an academic search interface or a government data portal. It is deliberately not a consumer AI product. No gradients, no glassmorphism, no illustrated mascots, no emoji. The voice is plain and explanatory; the layout is dense with text and citations; the colors are restrained (navy, off-white, one electric blue for the wordmark).

Sources used to build this system

All of the following live in the repo rdarrah7-code/rto-intelligence:

File	What it gave us
app/app/globals.css	HSL color tokens, authority-tier colors, radius, scrollbar
app/tailwind.config.ts	Token wiring, --font-sans / --font-mono mapping
app/app/layout.tsx	Inter font import, page metadata, voice samples
app/app/page.tsx	Homepage — hero, logo mark, nav, CTAs, stats, bottom-CTA, footer
app/app/about/page.tsx	"About" long-form copy — voice calibration
app/app/how-it-works/page.tsx	14 explainer cards — voice calibration
app/app/faq/page.tsx	FAQ voice, content patterns
app/app/login/page.tsx	Auth card, tabs, form fields
app/app/library/page.tsx	Primary app UI (ask/search, citations, confidence)
app/components/ui/badge.tsx	Badge variants incl. tier & RTO colors
app/public/og-image.png	Brand mark in use → assets/og-image.png

Identity at a glance

• Wordmark: black circle with serif-ish rto inside, next to the word intelligence in electric blue Courier New (monospace). The circle is always outlined, never filled. Used at multiple sizes from 16px (footer) to 90px (hero).
• Primary color: #1e3a6e — deep navy used for CTAs, headings, numeric stats, and the dark bottom-CTA band.
• Accent color: #0066FF — electric blue, reserved for the intelligence wordmark and inline links.
• Typography: Inter for UI and long-form prose; Courier New for the wordmark and inline numeric citations ([1], [2]).
• Authority tiers: amber (Tier 1 — tariff), sky (Tier 2 — manual/protocol), slate (Tier 3 — BPM).
• RTOs: violet (MISO), blue (PJM), emerald (SPP).

---

Content fundamentals

Voice

• Plain-language but technically exact. The product is for people who use words like "Loss of Load Expectation" and "FTR Obligation" in daily work. Copy never waters those terms down, but it does explain them.
• Explanatory, not promotional. Marketing copy reads like documentation — the site earns trust by showing its work. Example (homepage):

  "This is not a general search tool that also knows about energy markets. It is a retrieval system built specifically for RTO governing documents, with answer generation that is constrained to what the documents actually say."

• Never hedges when it shouldn't; always hedges when it should. The system says "the tariff governs" but also "historical 'as-of' queries are on the roadmap — the current version is explicit about what it covers and what it doesn't." 'I don't know' is a first-class outcome, not a failure mode.
• Third-person about the product, second-person to the reader. "rto intelligence retrieves governing document excerpts…" / "When you ask a question…"

Casing & punctuation

• Product name is always lowercase: rto intelligence. Never RTO Intelligence or Rto Intelligence. Even at the start of sentences it stays lowercase.
• RTOs are uppercase: MISO, PJM, SPP.
• Sentence case for all UI — buttons, headings, links. Never Title Case.
• Em-dashes are used liberally for clauses, not hyphens: "the tariff controls — and in any conflict between a tariff provision and a BPM, the tariff wins."
• Numbers with thousands separators: 584 documents, 6,882 indexed excerpts. Not "584" as bare digits if it reads awkwardly.

⚠️ Known copy inconsistency in the source repo: the homepage stats strip hard-codes 566 governing documents, while the about, how-it-works, and FAQ pages all say 584. This design system uses 584 everywhere since it's the majority and appears on the pages that talk about the corpus in depth. Keep an eye out when the homepage is re-generated.

Tone examples

Situation	Copy
Headline	"Accurate RTO research, grounded in source documents."
Subhead	"Accurate RTO research with answers grounded in source documents and citations you can verify."
CTA button	"Try a search →"
Secondary CTA	"How it works"
Trust strip	"Source-grounded answers · Extensive citations · Structured RTO coverage"
Bottom CTA	"Start searching the governing documents. · Access is open during beta."
Footer legal	"rto intelligence is an educational tool. Answers are not legal or regulatory advice."
Error state	"Low confidence — answer may be incomplete or partially unsupported"

What the voice avoids

• Exclamation marks. There are zero in the marketing pages. Don't add any.
• Emoji. Zero in the product. Don't add any.
• Marketing hype ("powerful," "revolutionary," "AI-powered"). The site says "generic AI tools … may generate plausible-sounding but incorrect regulatory text" — it critiques hype, it doesn't perform it.
• Second-person imperatives that sound like onboarding ("Let's get started!"). Copy respects the reader's time.

---

Visual foundations

Colors

The system is built on shadcn-style HSL CSS variables (--primary, --muted, etc.) but the hand-written hex values on the homepage are the source of truth for the marketing surface. They match the HSL tokens almost exactly.

Core palette

Role	Hex	HSL	Usage
Ink (foreground)	#1a1f2e	222 25% 14%	Body text, headlines
Primary navy	#1e3a6e	218 65% 32%	CTAs, stats, step bullets, bottom-CTA band
Electric blue	#0066FF	—	intelligence wordmark, inline links
Muted text	#6b7280	218 10% 44%	Subheads, metadata, footer links
Body text	#374151	—	Paragraph prose
Border	#e2e5ea / #d1d5db	216 16% 88%	Hairlines, card borders, inputs
Off-white	#f8f9fb	216 20% 97%	Section backgrounds, cards
White	#ffffff	—	Page background

Authority-tier colors (from globals.css)

Tier	Name	HSL
1	Tariff — highest authority	35 85% 45% (amber)
2	Manual / protocol	200 70% 40% (sky blue)
3	BPM / stakeholder	215 10% 52% (slate)

RTO badge colors (from badge.tsx)

RTO	Tailwind family
MISO	violet-500
PJM	blue-500
SPP	emerald-500

Semantic colors (inline in page.tsx)

Role	Bg	Border	Text
Warning (generic AI callout)	#fef9f0	#fde8b4	#b45309 / #d97706
Positive (rto intelligence callout)	#f0f6ff	#bfdbfe	#1e3a6e
Error banner	#fef2f2	#fecaca	#b91c1c

Typography

• Sans-serif body: Inter (loaded via next/font/google with variable --font-sans). Used for everything except the wordmark.
• Monospace display: Courier New / Courier. Used only for the wordmark (rto + intelligence), inline citation superscripts, and the tiny monospaced bits inside the citation chip.
• Weights used: 400 (body), 500 (buttons, small labels), 600 (card titles, section headings), 700 (page H1 / H2, big stat numbers).
• Letter-spacing: -0.01em on the two large headings (h1, h2), 0.1em uppercase on small eyebrow labels ("How it works", "Why this is different"), 0.08em uppercase on 11px column headers inside contrast cards.

Typographic scale actually in use (marketing pages):

Role	Size	Weight	Notes
Hero H1	38px	700	-0.01em, line-height: 1.2
Section H2	28–30px	700	-0.01em, line-height: 1.3
Intro paragraph	18px	400	line-height: 1.55
Body paragraph	16px	400	line-height: 1.75
Card title	16px	600	—
Card body	14px	400	line-height: 1.6
Card detail	13px	400	line-height: 1.65, muted
Button / CTA	15px	500	—
Nav link	14px	400	—
Small metadata	13px	400	muted
Eyebrow	12px	600	uppercase, 0.1em
Contrast header	11px	600	uppercase, 0.08em

Spacing & layout

• Content widths: 680px for long-form, 720px for narrative sections, 760px for "how it works", 900px for stats strip, 640px for hero query chips. The hero is capped at 560px for the headline and 480px for the subhead. No surface ever goes full-bleed-fluid-wide.
• Section padding: 96px 24px vertical on marketing sections, 72px 24px on the stats band, 28px 32px on nav and footer.
• Gaps: 32px between grid cells; 28px between horizontal nav links; 24px between cards; 12px between CTA buttons; 8px between query chips.
• Radii: 6px (small buttons, nav button), 8px (CTA buttons, contrast cards, warning cards), 10px (search bar, cards), 20px (query chips pill), 50% (logo circle, step bullets). The shadcn token --radius is 0.5rem (8px) by default.

Borders

Almost everything is separated by 1px hairlines, not shadows:

• #e2e5ea for section dividers and nav/footer borders
• #d1d5db for input borders and chip borders
• #bfdbfe / #fde8b4 / #fecaca for semantic card borders
• 4px solid #1e3a6e left-rule on the emphasis blockquote (the only colored left-border card pattern used — do not extend this to other cards)

Shadows

Essentially no shadow elevation in the marketing pages. The login card uses shadow-sm (Tailwind's smallest); hover on query chips produces a faint blue halo (0 0 0 3px rgba(0,102,255,0.08)). That's it. Depth is communicated with background color (#f8f9fb vs #ffffff) and hairlines.

Hover & press states

• Query chips: border shifts to #0066FF, adds a 3px rgba(0,102,255,0.08) ring. No transform.
• Primary CTAs: opacity: 0.9 on hover via Tailwind hover:opacity-90.
• Text links: electric blue (#0066FF), no underline at rest, underline on hover.
• Thumbs feedback: background swap from transparent to primary/10 or destructive/10.
• No transforms, no bounces, no scale effects anywhere.

Animation

• Streaming tokens fade in with an 80ms opacity + 2px translateY ease-out. That is the only motion in the entire product.
• Transitions on color / border / opacity use the default Tailwind 150ms ease. Never spring animations, never staggered entrances.

Backgrounds

• Page background alternates between white (#ffffff) and off-white (#f8f9fb) section by section to create rhythm.
• One dark section — the bottom CTA — uses #1e3a6e navy with white text. No gradients anywhere on the site.
• No imagery, no illustration, no texture. The OG image is typographic (the wordmark + three big numbers).

Iconography

See the dedicated section below, but in short: Lucide icons (lucide-react in package.json) used sparingly, stroke-only, usually at w-3.5 h-3.5, w-4 h-4, or w-5 h-5. SVG checkmarks and search glyphs are hand-rolled inline on the homepage with stroke-width: 1.5–1.8. No filled icons, no duotone icons, no emoji.

Cards

Three patterns in use:

1. Plain card — #ffffff background, 1px solid #e2e5ea, radius 10px, padding 28px 24px. Used for "How it works" explainer cards.
2. Off-white card — #f8f9fb background, 1px solid #e2e5ea, radius 8px, padding 20px 24px. Used for the emphasis blockquote.
3. Semantic callout card — light tinted bg + matching tinted border, radius 8px, small uppercase eyebrow at top. Used for the amber/blue contrast pair comparing "Generic AI search" vs "rto intelligence".

Layout rules

• Nav is fixed at top: 0, full width, 56px tall, 1px bottom border, no shadow.
• Marketing content sits on a center column; headers sit in a narrower column than body prose would.
• Stats strip uses auto-fit minmax(180px, 1fr) grid — responsive without a media query.
• Footer links live in a single flex row with 16px gaps, wrapping on small screens.

---

Iconography

Primary system: Lucide (lucide-react@^0.475.0, already in package.json). Used only in app-shell surfaces (the library/search UI) — never in marketing. Examples actually used: Search, ChevronDown, Loader2, AlertCircle, Shield / ShieldCheck / ShieldAlert / ShieldX, ThumbsUp/ThumbsDown, AlertTriangle, Eye/EyeOff, BookOpen, X, Flag, Clock, MessageSquare.

Sizes seen in code: w-3 h-3 (12px, tiny in-button), w-3.5 h-3.5 (14px, most common), w-4 h-4 (16px, banner icons), w-5 h-5 (20px, confidence banner). Always stroke, never fill.

For marketing pages, icons are hand-rolled inline SVGs (a magnifier and a checkmark) with stroke-width: 1.5 and stroke-width: 1.8 respectively. Match Lucide's weight if extending.

Emoji: never. Zero occurrences in the codebase.

Unicode glyphs in use: → (right arrow in CTAs), ← (back link in subpage headers), · (middot in metadata separators), — (em-dash in prose). No other decorative characters.

The wordmark is also the favicon — an inline SVG rendering the ring

• rto lockup in black on white. No separate logo PNG.

Logo assets are rebuilt from CSS (not an SVG file) so they scale cleanly. See assets/ for the OG image (the one bitmap asset the site ships).

---

Files in this design system

Root-level:

• README.md — this file
• SKILL.md — packaging for Agent Skills / Claude Code
• colors_and_type.css — CSS custom properties for color, type, radius

Folders:

• assets/ — logo components (reusable JSX), OG image, favicon data URI
• preview/ — small HTML cards surfaced in the Design System tab
• ui_kits/site/ — marketing site recreation (home, how-it-works, login)
• ui_kits/app/ — library search/ask app recreation
• app/ — the raw imported source files from rdarrah7-code/rto-intelligence (kept for reference; don't ship these)

Quick start for designers

Open ui_kits/site/index.html to explore the marketing side, or ui_kits/app/index.html for the search/ask product. Both reference colors_and_type.css and the logo component, so you can pull them apart and recombine.