Design System — Marketing (kyomi.ai)

Inherits from: kyomi/DESIGN.md ("Refined Warmth") Scope: Everything under apps/marketing/ (marketing site at kyomi.ai) Last Updated: 2026-04-21

Why this file exists

The app at app.kyomi.ai and the marketing site at kyomi.ai are two surfaces of the same product. They must feel like one thing. The root kyomi/DESIGN.md owns the tokens, typography, and aesthetic direction. This file narrows that system to the marketing context and records the places where marketing deviates — always with a stated reason.

Inherited without change

• Aesthetic direction: Refined Warmth. Editorial precision with organic energy.
• Typography stack: Instrument Serif (display) / DM Sans (body) / Geist Mono (data).
• Warm palette: #FAFAF8 / #1C1917 / #6B6660 / #E8E5DE with #D97706 as the one accent.
• Decoration level: Intentional. Typography does most of the work.
• Semantic colors, weight guidelines, typographic marks (⁂ § †).

Marketing-specific calls

Layout

• Approach: Creative-editorial, not grid-disciplined. The app follows a strict grid; marketing is where Kyomi earns permission to break it.
• Max content width: 1280px for the main layout, 720px for body prose, 860px for pricing/feature grids.
• Hero: Centered, serif headline, understated CTA. No background image overlays. The headline alone does the work.

Hero headline treatment

• Instrument Serif, 400 weight, letter-spacing: -0.02em, line-height: 1.05.
• Fluid sizing: clamp(2.5rem, 6vw, 4.5rem).
• One key phrase per hero can be italic (<em>) to carry the editorial voice.
• No gradients on hero text. Ever.

Prices

• Price numbers use Geist Mono with font-variant-numeric: tabular-nums.
• This is the signature typographic move on the pricing page — no BI tool does this; every SaaS uses the same neutral sans. Geist Mono + tabular makes $5 read like a ledger, not a pricing card.
• Price color is --color-foreground, not --color-primary. The amber accent is reserved for CTAs and active states. The mono type gives the price its weight, not color.
• The per-period suffix (/month, /user) switches back to DM Sans at a smaller size.

CTAs

• Primary: solid #D97706 background, white text, no gradient, no shadow. border-radius: 0.5rem. Hover darkens to #B45309.
• Secondary: ghost button — transparent background, #D4D0C8 border, foreground text. Hover border darkens and background becomes surface-alt.
• Never two primary CTAs adjacent. If the hero has "Start free trial" as primary, the secondary must be ghost ("See pricing").

Section dividers

• Use the asterism (⁂) via <hr> inside blog content or <hr class="asterism"> on marketing pages. It replaces default horizontal rules with a centered editorial mark on the page background.
• Never use decorative gradient bars or emoji rules.

Footnotes and annotations

• Use the dagger (†) as a footnote marker in tooltips and card footers (e.g. "Data stays in your warehouse†").
• The footnote body sits below the section in --color-muted-foreground at text-sm, preceded by a matching †.

Journey steps and feature cards

• White-surface cards with a 1px warm border. No amber left border. The amber left-border bar that used to live on JourneyStep was a startup aesthetic that fought the editorial tone.
• Card titles are Instrument Serif (1.375–1.5rem, weight 400).
• Icons are amber at 1.75rem, top-left of the card.

What marketing must NOT do

• No gradient CTA blocks. The amber-to-darker-amber "Ready to transform" CTA block on the old pricing/home pages is the single loudest thing on the site. It goes. Replaced by a warm surface card with one primary CTA.
• No colored pill boxes for feature highlights. Use the card pattern.
• No "Save 25%" green ribbons. Pricing is flat, no toggle, no comparison.
• No stock-photo hero overlays. The existing hero-screenshot.png background on index.md goes — the headline stands alone.
• No stacked-logo marquees. Datasource names sit in a single line of DM Sans body text, muted color, bullets between them. (Current: correct — keep it.)
• No @heroicons/vue icons inside pill boxes with colored backgrounds. Inline icons are muted, small, and match their surrounding text weight.

Icons — open gap

The app uses Phosphor Icons for brand consistency with the amber starburst logo. Marketing still uses @heroicons/vue. The existing components (InlineIcon.vue, JourneyStep.vue, FeatureCard.vue) hard-code Heroicons imports. Migrating to Phosphor (via @phosphor-icons/vue or SVG spritesheet) is scoped as a follow-up — it touches every marketing page.

Until then: keep icons muted (--color-muted-foreground by default, --color-primary only when the icon is the focal point of a card).

Homepage content architecture

Principle: Show the product in the first 3 seconds. Cut abstract benefits. Say one thing well instead of saying everything poorly.

Target audience: Data-savvy founders/CTOs and data team leads who already know what BI tools are. They want to see what Kyomi does, fast.

Memorable thing: "It just works." Type a question, get a chart.

Homepage structure (4 sections, not 7+)

1. Hero — "Ask your data anything." + product screenshot (chat interface with dashboard). The product visual takes 60%+ of the hero viewport. Subtitle: concrete ("Connect BigQuery, Snowflake, or Postgres. Type a question. Get a chart."), not categorical ("The Data Intelligence Platform").

2. How it works — 3 visual steps: connect, ask, save. Each has a real screenshot. No journey step cards, no abstract benefit text.

3. One differentiator — "It gets smarter every time you use it." Shown as a concrete before/after (week 1: Kyomi asks which table. Week 2: it knows). One paragraph, one visual. Not four abstract journey steps.

4. Integrations — Slack, Claude Code, proactive watches. Each with a screenshot. Replaces three separate integration sections.

5. Trust + CTA — Security callout (data stays in warehouse), pricing, one CTA. The warm surface card.

What was cut (moved to /features or removed)

• "Intelligence That Compounds" (4 abstract journey steps)
• "From Question to Insight in Seconds" (redundant with hero)
• "Built-in Website Analytics" (moved to /features)
• "MCP: Your Data Intelligence, Everywhere" (folded into integrations)
• "Why Teams Choose Kyomi" (4 abstract feature cards)
• "One Platform, Four Capabilities" (abstract bullet list)

Screenshots needed

These placeholder images should be captured from the real app:

• Datasource connection dialog (step 1 of "How it works")
• Chat input with a real question being typed (step 2)
• Watch creation UI or alert notification (integrations card 3)

Decisions log

Date	Decision	Rationale
2026-05-12	Homepage content restructure: 7 sections → 4, product-first	Site was "wishy washy" — abstract benefits with no product visibility. Competitive research showed every successful product in the category leads with product screenshots. Chat-first hero differentiates from BI tools that show dashboards.
2026-05-12	Headline changed to "Ask your data anything."	"The Data Intelligence Platform" said nothing. New headline is a concrete action the user can picture. Targets technical buyers who want to see what the product does, not read about categories.
2026-05-12	Cut 6 sections of abstract text	Each section described capabilities without showing them. Replaced with 4 sections that all have visuals. Total content went from ~230 lines to ~80.
2026-04-21	Created this file	Marketing site was visually divergent from the app. Cool slate palette, system-ui type, gradient CTAs, Heroicons in pills. Aligning to kyomi/DESIGN.md "Refined Warmth" with marketing-specific rules for hero, prices, and CTAs.
2026-04-21	Price numbers in Geist Mono tabular	Editorial move — no competitor does this. Signals "serious about data."
2026-04-21	Retired amber-to-darker-amber gradient CTA blocks	Loudest element on every page, fought the refined tone. Replaced with warm surface cards.
2026-04-21	Retired amber left-border on JourneyStep	Startup aesthetic. Card + warm border reads more editorial.