# Keysmith

Version 1.0.0 · Published via Claudesign.

---

# Keysmith Design System

**Keysmith** offers non-custodial wallets to AI agents. Users sign in with Face ID / Touch ID, create any number of wallets, set spending policies, and drop the generated agent key into an agent harness (OpenClaw, Hermes, Claude Code, or any x402-capable client) so the agent can pay for APIs, compute, data, and services autonomously — within the rules the user sets.

The product is a dense, dark, data-rich dashboard. The mood is **command-center meets fintech**: serious about money, clear about state, zero decorative noise. Every pixel earns its place by communicating state or enabling action.

## Products represented

| Product | What it is |
|---|---|
| **Keysmith App** (`app.keysmith.ai`) | The wallet management dashboard. Create MPC-secured wallets on Base, fund with USDC, issue agent keys, set policies, view transactions. |
| **Skills Marketplace** | Public catalog of agent skills (pre-built x402-compatible tools). Browsable without auth. |
| **Why / Security / FAQ** | Marketing surfaces within the same app — explain the product to new visitors. |

## Source materials

| Source | Location | Notes |
|---|---|---|
| Production codebase | `oviato-ai-app/` (mounted, read-only) | Astro 5 + React 19 + Tailwind 4. Currently branded "Oviato"; this design system **renames the brand to Keysmith** per the uploaded logo. See §Rebrand below. |
| Design spec | `oviato-ai-app/.design/design.md` | 598-line spec documenting colors, type, components, animations. Used as the source of truth for token values. |
| Logo mark | `uploads/ks-logo.png` → `assets/keysmith-logo.png` | Coral wordmark, transparent background |
| Logo symbol | `uploads/ks-icon.png` → `assets/keysmith-icon.png` | The stylized "K" monogram |
| Brand palette | `uploads/colors.png` → `assets/palette-reference.png` | 4-swatch reference: coral, blue-grey, pale cyan, deep navy |
| Display font | `uploads/Unbounded-VariableFont_wght.ttf` → `fonts/` | Used for display/hero type |

## Rebrand note — Oviato → Keysmith

The attached codebase (`oviato-ai-app`) ships under the "Oviato" brand with a blue `#1899E7` accent. The user has provided a new wordmark and icon under the name **Keysmith**, plus a new palette centered on coral `#ee6055`. This design system uses **Keysmith** as the canonical brand:

- Primary accent: **coral `#ee6055`** (was Oviato blue)
- Display font: **Unbounded** (new — for hero/display type)
- Body font: **Outfit** (retained from codebase)
- All product structure, component inventory, and copy tone are lifted from the Oviato codebase — only the name, logomark, and primary accent change.

Where the original codebase says "Oviato" in product copy (e.g. "Oviato Agent Wallet"), treat that as "Keysmith Agent Wallet" in new output.

---

## Index — what's in this folder

```
Keysmith Design System/
├── README.md                    ← you are here
├── SKILL.md                     ← Agent Skill manifest (cross-compat with Claude Code)
├── colors_and_type.css          ← all tokens as CSS vars (import once at root)
│
├── fonts/
│   └── Unbounded-VariableFont_wght.ttf
│
├── assets/
│   ├── keysmith-logo.png        ← coral wordmark
│   ├── keysmith-icon.png        ← K monogram
│   ├── palette-reference.png    ← 4-swatch palette
│   ├── agent-dollar.png         ← hero illustration (marketing)
│   ├── empty-state-no-wallet.png
│   ├── base-symbol.svg          ← Base chain logo (for "on Base" chips)
│   └── icons/
│       ├── anthropic.svg / openai.svg / google.svg / meta.svg /
│       ├── xai.svg / mistral.svg / perplexity.svg / deepseek.svg /
│       ├── cohere.svg / qwen.svg
│       └── — LLM provider logos used in marketing & Skills
│
├── preview/                     ← cards that populate the Design System tab
│   ├── colors-brand.html
│   ├── colors-neutral.html
│   ├── colors-status.html
│   ├── type-display.html
│   ├── type-body.html
│   ├── type-mono.html
│   ├── spacing.html
│   ├── radii.html
│   ├── shadows.html
│   ├── buttons.html
│   ├── inputs.html
│   ├── cards.html
│   ├── badges.html
│   ├── status-dot.html
│   ├── logo.html
│   └── iconography.html
│
└── ui_kits/
    └── keysmith-app/
        ├── README.md
        ├── index.html           ← live prototype of dashboard
        ├── TopBar.jsx
        ├── Sidebar.jsx
        ├── WalletCard.jsx
        ├── StatCard.jsx
        ├── Button.jsx
        └── — other JSX modules
```

---

## Content Fundamentals

**Voice.** Direct, technical, confident. Reads like good developer tooling: explain what's happening, then show the action. No marketing fluff, no emoji in copy (though emoji **are** used as wallet avatars — see below). The product takes money seriously.

**Person.** Mostly second-person for instructions ("Create your first wallet", "Fund your wallet to get started"). Third-person for the agent ("Your agent gets its own wallet", "Your agent checks the price every hour"). Never first-person plural ("we") in UI — only in long-form security explanations where trust needs a human voice.

**Casing.** Sentence case everywhere — buttons, headings, menu items, modal titles. **Uppercase + letter-spacing 0.5px** for micro-labels only (section headers inside cards, field labels, status pills). Example: `DEPOSITED`, `ACTIVE`, `YOUR WALLETS`.

**Tone examples** (verbatim from the codebase):
- Hero: *"Your agent is smart. Give it spending power."*
- Problem framing: *"Agents wait on you. Every API call, every purchase, every deployment — your agent stops and asks for permission. You become the bottleneck."*
- Empty state: *"Create your first Agent Wallet to get started and give your agent the power to pay for goods and services and receive payments non-custodially."*
- Destructive action: *"Kill it anytime with one click."*
- FAQ answer: *"No. Keysmith uses 2-of-3 Shamir Secret Sharing… we physically cannot move your funds without your participation."*

**Numbers.** Always monospace. Always with locale formatting (`$2,450.00`, not `$2450`). Currency suffix (`USDC`) is a separate, smaller span in muted text.

**Addresses & keys.** Always truncated inline: `0x742d...bD08`. Full value only in modals with an explicit copy button. Keys are masked with `●` until an explicit passkey-gated reveal.

**Emoji.** **Yes**, but only as wallet avatars (🦅 Swift Falcon, 🧭 Bright Compass, 🔥 Silent Ember). Rendered in the `Noto Emoji` family for cross-platform consistency. Never decorative, never in headings or body copy.

**Punctuation.** Em-dashes (`—`) to break thoughts. Bullet points via `·` in inline status lines (`Active · 28d left · wallet-a7x3`). No exclamation marks except for successful completion states ("Created!").

---

## Visual Foundations

### Color philosophy

**Coral is the hero.** The `#ee6055` coral is Keysmith's signature — it's the logo color, the primary CTA color, and the focus ring. Use it for **one** prominent action per view (the "Create Wallet" button on the dashboard, the "Sign" button in modals, the active nav tab). Do not use it for decorative backgrounds, gradients behind text, or anywhere the user is not meant to tap.

**Status colors are semantic, not moods.**
- **Green `#4ade80`** → money (balance, deposits), active state, success.
- **Red `#f87171`** → withdrawals, rejections, limits exceeded, destructive actions on hover.
- **Yellow `#facc15`** → limits, max-per-tx, paused state.
- **Purple `#a78bfa`** → skills, agent identity (the "A" in the MPC ceremony), special/external.
- **Mist `#98c1d9`** → informational chips, the "U" (user) share in MPC ceremony.

**Neutrals are the canvas.** 95% of the UI is built from `--ks-ink` (page), `--ks-surface` (card), `--ks-border`. Color should feel *rationed*, not sprinkled.

### Typography

Three families. Each has a job and never swaps:

- **Unbounded** (display) — hero text, marketing headlines. Geometric, character-forward. 700/800 weight.
- **Outfit** (body) — everything else in UI. Clean geometric sans. 400–700.
- **JetBrains Mono** (data) — **all** addresses, keys, hashes, amounts, code. No exceptions. 400–700.

Uppercase micro-labels (`DEPOSITED`, `ACTIVE`) use Outfit 9–10px / 600 / `letter-spacing: 0.5px`.

### Spacing

4px base grid. Common increments: 4, 8, 12, 16, 20, 24, 32, 40, 56. Page padding is `24px 28px`. Card padding is `16px`. Compact rows (sidebar items, transaction rows) use `10px 12px`.

### Backgrounds

- **No gradients behind text.** The main page is flat `--ks-ink`.
- **No repeating patterns or textures.**
- **No hand-drawn illustrations** (the one illustration is `agent-dollar.png` on the marketing page — treat as the exception).
- Marketing pages *may* use a subtle grid-line background (`GridBackground.tsx` in the codebase) at low opacity.
- Cards use subtle diagonal gradients between two very close neutral shades (`#151a24 → #121620`) for faint depth. See `.ovi-card` / `.ks-card`.
- The "accent card" (`.ks-card-accent`) has a faint coral radial bloom bottom-right — only used once per view, on the primary balance card.

### Corner radii

- **Pills (`9999px`)** for all interactive pill elements: buttons, inputs, chips, badges, status dots.
- **12px** for cards and panels.
- **16px** for modals and marketing hero cards.
- **8px** for sidebar items, icon tiles, avatar squares.
- **4px** for tiny inline status pills (`ACTIVE`).

Never mix radii within the same component class.

### Borders

- Default: `1px solid var(--ks-border)` (`#1e2438`).
- Hover on interactive surfaces: border brightens to `--ks-border-strong` (`#283048`).
- Focus rings use coral: `0 0 0 2px var(--ks-coral-glow)` + coral border.
- Input fields inherit `--ks-border` with a coral focus ring.

### Shadows

Shadows are **earned**, not default. Static elements have none.

- Cards at rest: no shadow. Elevation comes from background contrast + border.
- Cards on hover: `0 8px 24px rgba(0,0,0,0.30)` + `-1px` translate-Y.
- Primary CTA on hover: `0 3px 14px rgba(238,96,85,0.22)` (coral-tinted glow).
- Modals: `0 16px 48px rgba(0,0,0,0.55)`.
- Focus ring on inputs: `0 0 0 2px rgba(238,96,85,0.15)`.
- Status dot (green, active): `0 0 8px rgba(74,222,128,0.3)` + 2s pulse.
- Sign modal shield: animated glow between `0 0 12px` and `0 0 28px` in coral.

### Cards

Three card variants:

1. **`.ks-card`** — default. Subtle gradient background, 1px neutral border, 16px radius. Hover brightens border and lifts by 1px.
2. **`.ks-card-glow`** — stat cards on the dashboard. Slightly stronger border, subtle coral glow shadow.
3. **`.ks-card-accent`** — the balance card. Coral-tinted border, radial coral bloom in bottom-right corner. Use **once per view** on the primary object.

### Animation

Fast and purposeful. Nothing longer than 500ms except ambient effects (pulse, orbit, glow).

- **Fade-in + 8px slide** for entering content (lists, cards). Staggered 40ms per item.
- **Scale-in** from `0.94 → 1.0` for modals and success states.
- **Pulse** (1 → 0.5 → 1 opacity, 2s) for "active" status dots.
- **Animated counter** — balances and stat values tween from old → new value over 800–1200ms with ease-out-cubic.
- **Typing effect** during wallet creation — 35–40ms per character, blinking coral cursor at end.
- **MPC ceremony** — 3 orbiting share tokens (U/S/A) around a central shield, 3s linear loop, collapsing to center on completion.
- **Hex scramble** — 28 random hex chars updating every 60ms at 50% opacity during key generation.
- **Confetti burst** on wallet created.
- All animations respect `prefers-reduced-motion: reduce` and shrink to `0.01ms`.

### Hover & press states

- **Hover on links** → brightens from `--ks-fg-2` to `--ks-fg-1`.
- **Hover on nav tab** → inactive tabs brighten; active tab keeps its glow.
- **Hover on cards** → `-1px` translate-Y + border brightens + shadow appears.
- **Hover on icon buttons** → border brightens to `--ks-fg-3`.
- **Press** → `transform: scale(0.97)` for ~80ms. Not a color shift — a size shift. Applies to buttons, pills, and tap targets.
- **Disabled** → 50% opacity + `cursor: not-allowed`.

### Transparency & blur

- Modal overlay: `rgba(0,0,0,0.55)` + `backdrop-filter: blur(4px)`.
- Nothing else uses blur. No glassmorphism, no frosted panels.
- "Glow" backgrounds (e.g. `--ks-coral-glow: rgba(238,96,85,0.12)`) are solid colors at low alpha, applied as a flat `background`, never as a blurred overlay.

### Layout rules

- **Top bar**: 64px, `--ks-ink` background, bottom border. Logo left, nav middle, balance chip + user menu right.
- **Sidebar**: 240px fixed, `--ks-surface` background, right border (gradient: neutral top → faint coral bottom). Scrollable if the wallet list is long.
- **Main content**: flex-1, scrollable, padded `24px 28px`, max content width `800px` on wide screens.
- **Mobile (<768px)**: sidebar collapses, stat grids go 1-column, padding shrinks to `16px 14px`. Balance chip moves into the mobile menu dropdown.

---

## Iconography

**Primary icon set: [Lucide](https://lucide.dev)** — stroke-based, 1.5–2px stroke weight, consistent metaphors. Used throughout the React app via `lucide-react` (v0.475+). Default size 14×14 in the UI, 16–20px for featured/hero icons, 12×12 for tiny inline icons. Color inherits from the parent text color.

**Common Lucide icons in use:**
`Vault`, `Plus`, `Copy`, `Check`, `ArrowUpRight`, `ArrowDownLeft`, `Key`, `Shield`, `Eye`, `EyeOff`, `LogOut`, `Clock`, `Settings`, `Wallet`, `Menu`, `X`, `ChevronDown`, `Pause`, `Play`, `Zap`, `AlertCircle`, `ExternalLink`, `RefreshCw`, `ArrowRight`, `Terminal`, `Globe`, `CreditCard`, `Server`, `TrendingUp`, `Bot`, `Lock`.

**Load Lucide from CDN in HTML artifacts:**

```html
<script type="module">
  import { createIcons, Vault, Plus, Copy /* ... */ } from "https://esm.sh/lucide@0.475.0";
  createIcons({ icons: { Vault, Plus, Copy } });
</script>
```

Or use the sprite approach from `https://unpkg.com/lucide-static@0.475.0/icons/<name>.svg` for plain HTML.

**Brand & partner logos (SVG):** Stored in `assets/icons/` — `anthropic`, `openai`, `google`, `meta`, `xai`, `mistral`, `perplexity`, `deepseek`, `cohere`, `qwen`. Used on marketing pages ("supported agents") and in the Skills marketplace. **Always render at their native color.**

**Base chain logo:** `assets/base-symbol.svg` — used as a tiny 12×12 link icon next to `tx_hash` values that link out to BaseScan.

**Wallet avatars are emoji.** Rendered in the `Noto Emoji` font for platform consistency. Each wallet picks one emoji at creation time (🦅 🧭 🔥 etc.).

**Unicode chars as icons** — used sparingly for inline dividers only: `·` between status fragments, `→` in copy. Not used as icons.

**No hand-drawn SVG icons.** If a needed icon isn't in Lucide, pick the nearest Lucide match rather than drawing a new one.

---

## Tokens quick reference

Import `colors_and_type.css` once at the root; then use:

| Need | Token |
|---|---|
| Page background | `var(--ks-ink)` |
| Card background | `var(--ks-surface)` |
| Body text | `var(--ks-fg-1)` |
| Muted text | `var(--ks-fg-2)` / `var(--ks-fg-3)` |
| Primary CTA | `background: var(--ks-coral-gradient); color: var(--ks-on-coral);` |
| Coral focus ring | `box-shadow: var(--sh-focus-ring);` |
| Balance / money | `color: var(--ks-success); font-family: var(--font-mono);` |
| Display heading | `font-family: var(--font-display); font-weight: 800;` |
| Section label | `class="ks-label"` |
| Pill radius | `border-radius: var(--r-pill)` |
| Card radius | `border-radius: var(--r-card)` |

---

## Font substitution flag

The uploaded **Unbounded** variable font is bundled in `fonts/` and used for display type. If rendering in an environment without access to local font files (e.g. a sandboxed preview), we fall back to Outfit 700 for display. **Outfit** and **JetBrains Mono** are loaded from Google Fonts. If the user wants a different display font, swap the `@font-face` src and the `--font-display` value — no other token changes required.

---

## See also

- **`SKILL.md`** — manifest for using this as a Claude Code / Agent Skill
- **`ui_kits/keysmith-app/`** — live prototype recreating the dashboard
- **`preview/`** — individual design-system preview cards