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).

Decisions log

Date	Decision	Rationale
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.