harb/docs/UX-DECISIONS.md

UX-DECISIONS.md — Design & Messaging Decisions

Living record of UX/messaging decisions. Agents must follow these. Updated after each review session.

Last updated: 2026-02-22

---

Audience

• Primary: Crypto natives who understand DeFi but don't know KrAIken
• Not targeting: Beginners, "new to DeFi" users
• No ELI5 content on the landing page
• Beginners can find their way through the docs if curious

Landing Page Variants

Variant	File	Target	Tone
Default	HomeView.vue	General crypto users	Clean, professional
Offensive	HomeViewOffensive.vue	Degens, technical users	Aggressive, direct
Mixed	HomeViewMixed.vue	Blend	Balanced

Offensive is strongest for crypto natives. Default wins for broader appeal.

Messaging Rules

Do Say

• "Stake & Grow" (not "Start Earning")
• "Floor guaranteed" (the mechanism exists, even if floor can decrease)
• "Token-owned liquidity" (metaphor, acceptable in marketing)
• "No admin keys" ONLY when staker governance is implemented
• "How It Works →" as equal-weight CTA alongside "Get $KRK"

Staking Visibility

• Staking is NOT mentioned on the landing page. The staking app is password-protected for a reason — it's for insiders, not casual visitors.
• Landing page sells the token and protocol. The CTA is "Get $KRK", not "Stake".
• No staking mechanics, staking CTAs, or staking explainers on any HomeView variant.
• Visitors discover staking through the community, not through the landing page.

Don't Say

• "Start Earning" / "Earn yield" / "APY" — staking isn't yield
• "Stake" / "Stake & Grow" / "Staking" on the landing page — see above
• "You just hold and win" — too promissory (changed to "You just hold.")
• "Open source" — repo is private
• "Three strategies" — three positions, one strategy
• Raw holder count when it's low (show growth % instead)

Staking Value Prop

The one-liner: "Stake → invite friends → supply grows → you profit with leverage."

Staking is leveraged directional exposure that pays off when the community grows. It is NOT passive income. It is NOT yield farming.

Display Rules

Numbers

• Show USD as primary for all ETH amounts (people can't relate to 0.0000029 ETH)
• Keep ETH as secondary/tooltip for crypto natives
• Use CoinGecko API for ETH/USD, cache 5 min
• Format: ≥$1000 → "$25.4k", ≥$1 → "$2.50", <$1 → "$0.007"
• Never use toFixed(4) on tiny ETH values — use dynamic precision

Stats

• Show growth trends (sparklines, ↑X%) not raw counts
• Multiple mini-sparklines per stat card, not a single health graph
• 7 days or since launch (whichever shorter) for historical data
• Ring buffer only — no unbounded snapshot tables (disk growth concern)
• Live indicator (green dot + "Updated Xs ago") for freshness

Contract Addresses

• Show in footer with copy buttons
• Link to Basescan for verification

Docs

• "How It Works" should be equal-weight navigation item, not buried
• Recenter explainer: keep it to 3 bullets (atomic, sentiment-driven, bull/bear)
• No Baseline comparison table — borrow their language, don't name-drop them
• Code page (/docs/code) for contract source viewing instead of Codeberg link

Tone

• Sharp, direct, no fluff
• Technical confidence without overclaiming
• "We" when referring to the protocol community
• Never condescending
• Dark theme, minimal decoration