SAGIO Design & Styling Guidelines¶

Canonical visual system for SAGIO marketing surfaces, the x402 Payment Facilitator landing page, and developer documentation. Derived from the live implementation in apps/landing.

Use this document when building new pages in other repos or apps so they feel like part of the same product family.

Reference implementation: apps/landing
Key files: tailwind.config.js, src/styles/globals.css, src/components/ui/kit.tsx, src/pages/Home.tsx

1. Design vibe¶

SAGIO should feel like premium fintech with editorial confidence — not crypto-bro neon, not corporate SaaS gray.

Quality	How it shows up
Dark & warm	Soft slate canvas (`ink-`), ivory text (`paper-`), never pure `#000` / `#fff` body pairs
Technical but human	Mono labels and code; serif italics for emphasis; plain-language body copy
Restrained motion	Scroll reveals, subtle hover lifts, orchestrated hero sequences — respect `prefers-reduced-motion`
Developer-trustworthy	Clean docs layout, readable code blocks, precise endpoint specs
NZ-grown, global	Understated, direct tone; no hype gradients on every surface

One-line brief for AI / contractors:

Dark warm slate canvas, ivory type, balance-blue accent, IBM Plex body, JetBrains Mono for labels/code, Instrument Serif for editorial emphasis, hairline borders, dot-grid texture, pill CTAs.

2. Color system¶

Primary ramps (use these)¶

Token	Hex	Role
`ink-950`	`#0f141b`	Page background, deepest surfaces
`ink-900`	`#161d26`	Elevated sections, modals, nav dropdowns
`ink-800`	`#1f2937`	Cards on hover, secondary surfaces
`paper-50`	`#faf8f1`	Primary text, primary CTA fill
`paper-100`	`#f5f2ea`	Body default (via `text-paper-50/80` on layout)
`paper-50/70`	—	Secondary body copy
`paper-50/45`	—	Section labels, meta text
`paper-50/40`	—	Footer copyright, timestamps
`accent`	`#4b65bf`	Links, icons, focus rings, caret in wordmark
`accent-400`	`#6a80cc`	Lighter accent hover (optional)
`accent-600`	`#4057a6`	Pressed / darker accent states

Brand gradient (text & accents only)¶

linear-gradient(120deg, #5bc0f6, #94d8fa, #4b65bf, #5bc0f6);

Use on headline words or hero highlights via .text-gradient-ocean (animated).
Do not flood full sections with gradient backgrounds.

Legacy `ocean-*` ramp¶

Still in Tailwind for compatibility. Prefer ink + paper for new work. ocean-* neutrals map closely to older charcoal grays if you need them.

Semantic / status colors¶

Use	Tailwind
Success / live	`emerald-300`, `emerald-400/10` bg
Warning / preparing	`amber-300`, `amber-400/10` bg
Error	`red-400` (sparingly)
HTTP GET (docs)	`accent` or `sky-400`
HTTP POST (docs)	`emerald-400`
HTTP 402 (x402)	`amber-400` — literal protocol nod

Borders & overlays¶

border-white/[0.08]   — section dividers
ring-1 ring-white/10  — cards, inputs, panels
bg-white/5            — ghost buttons, nav hover
bg-white/10           — active nav, hairline grid gutters
bg-black/70           — modal scrim
selection:bg-accent/30 selection:text-paper-50

3. Typography¶

Font stack¶

Role	Family	Weight	Usage
Sans	IBM Plex Sans	400–800	All UI, headings, body
Mono	JetBrains Mono	200 (wordmark), bold (labels)	Eyebrows, tags, status, `x402`, code
Serif	Instrument Serif	normal italic	Editorial pull quotes, hero emphasis
Wordmark	JetBrains Mono	200	`[S^GIO]` animated mark

Host fonts locally (see apps/landing/public/fonts/) or load equivalent webfonts.

Type scale¶

Element	Classes / specs
Hero H1	`text-[2.65rem] sm:text-6xl md:text-7xl font-medium leading-[0.98] tracking-[-0.03em]`
Section H2	`text-4xl md:text-5xl font-medium tracking-[-0.02em]`
Section H3	`text-xl md:text-2xl font-medium` or `text-2xl lg:text-3xl` on cards
Editorial quote	`.instrument text-3xl sm:text-4xl md:text-[2.7rem] leading-[1.24]`
Body	`text-base md:text-lg leading-relaxed text-paper-50/70`
Small body	`text-sm leading-relaxed text-paper-50/70`
Eyebrow / section label	`font-mono text-[11px] uppercase tracking-[0.18em]` to `tracking-[0.26em] text-paper-50/45`
Card tag	`font-mono text-[10px] uppercase tracking-[0.2em] text-paper-50/45`

Voice in type¶

Headlines: medium weight (not extrabold everywhere). Reserve font-bold for CTAs and form labels.
Serif italic spans: one phrase per headline max — e.g. "like a message", "we wished existed".
Mono uppercase: short labels only (PRINCIPLES, SETTLEMENT, POST /api/payment-intents).

Base scale¶

html { font-size: 16px; }
@media (min-width: 1024px) { html { font-size: 17px; } }
@media (min-width: 1536px) { html { font-size: 18px; } }

4. Layout & spacing¶

Page shell¶

<div className="min-h-screen bg-ink-950 font-sans text-paper-50/80 overflow-x-hidden selection:bg-accent/30 selection:text-paper-50">
  <Header />
  <main>{/* page */}</main>
  <Footer />
</div>

Content width¶

Context	Max width	Horizontal padding
Marketing sections	`max-w-7xl mx-auto`	`px-4 sm:px-6 lg:px-8`
Editorial / legal / docs article	`max-w-3xl` or `max-w-4xl`	same
Docs with sidebar	`max-w-7xl` grid: sidebar `w-64` + content `min-w-0`	same

Section rhythm¶

Hero:     pt-32 pb-16 md:pt-36 md:pb-24  (or md:pt-44 for inner pages)
Section:  py-24 md:py-32
Closing:  py-28 md:py-40

Separate sections with border-t border-white/[0.08].

Grid patterns¶

Hairline panel grid (suite cards, principles):

<div className="grid gap-px overflow-hidden rounded-2xl bg-white/10 ring-1 ring-white/10 md:grid-cols-3">
  <div className="bg-ink-950 p-8 md:p-9">...</div>
</div>

Value / feature cards:

<div className="rounded-3xl p-7 bg-white/[0.03] ring-1 ring-white/10">...</div>

5. Surface treatments¶

Dot grid¶

.bg-dotgrid {
  background-image: radial-gradient(circle, rgba(245, 242, 234, 0.09) 1.5px, transparent 1.5px);
  background-size: 32px 32px;
}

Use behind hero wordmark or on card hover with a radial mask:

[mask-image:radial-gradient(ellipse_at_top,black,transparent_65%)]

Grain overlay¶

Apply .grain on a relative container. Subtle film texture at ~5% opacity.

Ambient glow¶

<div className="pointer-events-none absolute -top-32 left-1/2 -translate-x-1/2 w-[45rem] h-[28rem] rounded-full blur-3xl bg-accent/[0.06]" />

Card hover glow:

<div className="absolute ... bg-accent/[0.08] opacity-0 blur-3xl group-hover:opacity-100 transition-opacity duration-700" />

6. Components¶

Fixed: top-3 md:top-6, centered, max-w-4xl
Bar: bg-ink-950/60 backdrop-blur-2xl ring-1 ring-white/10 rounded-full
Links: px-4 py-2 text-sm font-medium rounded-full
Active: text-paper-50 bg-white/10
Idle: text-paper-50/60 hover:text-paper-50 hover:bg-white/5
Primary nav CTA: compact pill — bg-paper-50 text-ink-950 font-bold rounded-full

Primary CTA¶

// kit.tsx — PrimaryCTA
"px-7 py-3.5 rounded-full bg-paper-50 text-ink-950 font-bold text-sm md:text-base
 shadow-md hover:shadow-lg hover:bg-white hover:-translate-y-0.5 active:scale-95
 ring-1 ring-black/5"

Optional shimmer on hover (absolute gradient sweep). Pair with ArrowUpRight icon.

Ghost CTA¶

"px-7 py-3.5 rounded-full bg-white/5 ring-1 ring-white/15 text-paper-50 font-semibold
 backdrop-blur-sm hover:bg-white/10 active:scale-95"

Eyebrow pill¶

"inline-flex items-center gap-2 px-3.5 py-1.5 rounded-full
 bg-white/5 ring-1 ring-white/10 font-mono text-[11px] uppercase tracking-[0.18em] text-paper-50/60"
// + pulsing dot: w-1.5 h-1.5 rounded-full bg-accent animate-pulse

Icons¶

Library: Lucide React
Section icons: h-6 w-6 text-accent strokeWidth={1.75}
Icon containers: w-12 h-12 rounded-2xl bg-accent/10 ring-1 ring-accent/20

Forms (contact, waitlist)¶

// Input
"rounded-xl bg-ink-950/60 ring-1 ring-white/10 px-4 py-3 text-paper-50
 placeholder:text-paper-50/40 focus:ring-2 focus:ring-accent/60"

// Label
"text-xs font-semibold uppercase tracking-wider text-paper-50/60"

// Submit (accent variant in modals)
"px-6 py-3 bg-accent text-white text-sm font-bold rounded-full"

Scrim: bg-black/70 backdrop-blur-md
Panel: bg-ink-900 ring-1 ring-white/10 rounded-3xl shadow-2xl
Mobile: rounded-t-3xl bottom sheet style

Accordion (FAQ)¶

Border: border-b border-white/10
Question: text-base md:text-lg font-medium text-paper-50
Chevron rotates + text-accent when open

7. Motion¶

Easing curve (standard)¶

const EASE: [number, number, number, number] = [0.16, 1, 0.3, 1];

Reveal on scroll¶

// Framer Motion — viewport once, 0.6s duration
initial={{ opacity: 0, y: 24 }}
whileInView={{ opacity: 1, y: 0 }}
viewport={{ once: true, amount: 0.2 }}
transition={{ duration: 0.6, ease: [0.16, 1, 0.3, 1], delay }}

Stagger siblings with delay: i * 0.06.

Hero sequence¶

Wordmark animation completes first (SagioWordmark)
Headline: blur + slide from left
Subtext + CTAs: fade up with ~0.35s stagger

Always provide a static fallback when useReducedMotion() is true.

Tailwind animations (available)¶

Class	Use
`animate-gradient-x`	Gradient text
`animate-float`	Decorative elements
`animate-pulse`	Eyebrow dot, live indicators
`animate-spin-slow`	Orbit / loading decor

8. x402 Facilitator & documentation patterns¶

These extend the marketing system for facilitator landing and API docs without breaking the vibe.

Product positioning (SAGIO Pay / x402)¶

Name: SAGIO Pay (settlement product) · x402 Payment Facilitator (technical)
One-liner: Stablecoin payments cleared in seconds via our x402 facilitator.
Technical hook: Gasless stablecoin payments on Base using EIP-2612 permit and one-click settlement.

Facilitator landing page structure¶

Hero — Eyebrow: x402 · Payment Facilitator · Headline with serif emphasis · Primary CTA: Read the docs · Ghost: View on Base
Flow diagram — Merchant → Facilitator → Wallet → On-chain settlement (hairline grid or horizontal steps)
Capabilities — 3–4 cards: Gasless permits, 402 challenges, One-confirm settlement, Base L2
Integration — Code snippet (create intent → checkout → confirm)
Status / network — Mono badges: base-sepolia, USDC, Live
CTA — Get API access or team@sagio.io

Documentation layout¶

┌─────────────────────────────────────────────────┐
│  [Floating pill nav — same as marketing]        │
├──────────┬──────────────────────────────────────┤
│ Sidebar  │  Article                             │
│ (mono    │  H1 + last updated                   │
│  nav)    │  Prose body                          │
│          │  Endpoint cards                      │
│          │  Code blocks                         │
└──────────┴──────────────────────────────────────┘

Sidebar: bg-ink-950, links text-sm text-paper-50/60 hover:text-paper-50, active text-accent
Article background: same bg-ink-950 — docs are not a light mode fork

Endpoint card (docs)¶

<article className="rounded-2xl bg-white/[0.03] ring-1 ring-white/10 overflow-hidden">
  <div className="flex items-center gap-3 px-5 py-4 border-b border-white/10">
    <span className="font-mono text-xs font-bold uppercase tracking-wider text-emerald-400">POST</span>
    <code className="font-mono text-sm text-paper-50">/api/payment-intents</code>
  </div>
  <div className="px-5 py-4 text-sm text-paper-50/70">...</div>
</article>

For x402 challenge responses, badge HTTP status 402 in text-amber-400.

Code blocks¶

<pre className="overflow-x-auto rounded-xl bg-ink-900 ring-1 ring-white/10 p-4
  font-mono text-sm leading-relaxed text-paper-50/90">
  <code>{json}</code>
</pre>

JSON keys: default paper-50/90
Strings: optional text-sky-300/90
Numbers / booleans: optional text-accent-400

Inline code¶

`font-mono text-sm text-accent bg-accent/10 px-1.5 py-0.5 rounded`

Protocol terms (always mono)¶

x402, EIP-2612, permit, intentId, payment-intents, checkout, 402 Payment Required

9. Brand assets¶

Asset	Path (landing)
Wordmark (ivory)	`/logos/sagio-wordmark-ivory.png`
Wordmark (charcoal)	`/logos/sagio-wordmark-charcoal.png`
Animated mark	`SagioWordmark` component — `[S^GIO]` with `^` in `text-accent`
IBM Plex Sans	`/fonts/IBM-Plex-Sans/`
JetBrains Mono	`/fonts/JetBrainsMono-ExtraLight.ttf`

Copy these assets into other repos or serve from a shared CDN path.

10. Portable Tailwind config¶

Minimal theme.extend to drop into any Vite + Tailwind project:

// tailwind.config.js excerpt
export default {
  theme: {
    extend: {
      fontFamily: {
        sans: ['"IBM Plex Sans"', 'system-ui', 'sans-serif'],
        mono: ['"JetBrains Mono"', 'ui-monospace', 'monospace'],
        serif: ['Instrument Serif', 'Georgia', 'serif'],
      },
      colors: {
        paper: {
          50: '#faf8f1',
          100: '#f5f2ea',
          200: '#ece7db',
          300: '#ddd6c6',
          400: '#c9c0ab',
        },
        ink: {
          DEFAULT: '#1f2937',
          800: '#1f2937',
          900: '#161d26',
          950: '#0f141b',
        },
        accent: {
          DEFAULT: '#4b65bf',
          400: '#6a80cc',
          500: '#4b65bf',
          600: '#4057a6',
          700: '#36498c',
        },
      },
      keyframes: {
        'gradient-x': {
          '0%, 100%': { backgroundPosition: '0% 50%' },
          '50%': { backgroundPosition: '100% 50%' },
        },
      },
      animation: {
        'gradient-x': 'gradient-x 6s ease infinite',
      },
    },
  },
};

11. Portable CSS utilities¶

@layer base {
  body {
    font-family: 'IBM Plex Sans', system-ui, sans-serif;
    background-color: #0f141b;
    color: #f5f2ea;
    -webkit-font-smoothing: antialiased;
  }
}

.instrument {
  font-family: 'Instrument Serif', Georgia, serif;
}

.font-wordmark {
  font-family: 'JetBrains Mono', ui-monospace, monospace;
  font-weight: 200;
}

@layer utilities {
  .text-gradient-ocean {
    background-image: linear-gradient(120deg, #5bc0f6, #94d8fa, #4b65bf, #5bc0f6);
    background-size: 250% 250%;
    -webkit-background-clip: text;
    background-clip: text;
    color: transparent;
  }

  .bg-dotgrid {
    background-image: radial-gradient(circle, rgba(245, 242, 234, 0.09) 1.5px, transparent 1.5px);
    background-size: 32px 32px;
  }
}

12. Do / Don't¶

Do¶

Use ink-950 + paper-50 as the default dark theme pair
Keep generous whitespace and clear section hierarchy
Use mono sparingly for labels, protocol terms, and code
Use hairline gap-px grids for grouped content
Animate on scroll once (viewport: { once: true })
Match CTA styles exactly across marketing and docs

Don't¶

Switch docs to light mode unless there's a strong accessibility reason
Use pure black #000 or sterile cold gray backgrounds
Stack multiple gradients, glows, and grain on the same section
Use extrabold on every heading
Use crypto clichés (rocket emojis, laser gradients, "WAGMI")
Invent product copy — pull from apps/landing/src/lib/products.ts and API specs in docs/api/

13. Dependencies (reference stack)¶

Package	Use
`tailwindcss`	Utility styling
`framer-motion`	Reveals, hero, modals
`lucide-react`	Icons
`react-router-dom`	Client routing (or equivalent)
`class-variance-authority` + `cn()`	Conditional classes (optional)

14. Changelog¶

Version	Date	Notes
1.0	2026-07-07	Initial canonical doc from `apps/landing` implementation; adds x402/docs patterns

Maintainers: update this file when landing tokens change. The YAML frontmatter block is machine-readable for AI tooling and design-token pipelines.