Akefin Design System

A precision finance design system for Akefin — a multi-entity personal & business accounting platform for a solo consultant operating across South Korea (KRW), Turkey (TRY), and Japan (JPY).

This system is tuned for a domain where density, trust, and bilingual (Latin + Hangul) text rendering all matter. It draws aesthetic inspiration from pi.dev (the user's stated favourite): a calm, paper-light surface, a grid background, generously-italic serif display type, and crisp monospace data.

---

Source materials

Source	Notes
alkimake/akefin-design-system (private GitHub)	Empty at time of writing — this project IS that design system. Re-pull when populated. https://github.com/alkimake/akefin-design-system
uploads/picode_screenshot.png	The pi.dev landing page, attached as the aesthetic target
uploads/screenshot-2026-05-22_22-25-21.png	pi.dev code-edit interaction view
Akefin brief (in chat)	Three legal entities (Personal / 9TFox / Finacode), 3-tier AI categorization, double-entry plain-text ledger output

For future readers / agents: if you have access to the GitHub repo above, pull it before designing — there may be updated components, brand marks, or screenshots not reflected here.

---

Product context

Akefin automates the import of Korean Toss bank exports, categorizes transactions through a 3-tier AI pipeline (Rules → LLM → Agent), and routes anything unmatched to a human review queue. Final output: plain-text double-entry ledger files, git-versioned for audit.

Primary surfaces:

• Web dashboard — the daily-driver. Review queue, rule management, ledger overview, import status.
• Mobile (iOS/Android) — same data, optimised for the review-on-the-go case.

Three independently-tracked entities, always visible as scope:

Badge	Entity	Scope
Personal	Personal finances	KR (KRW), TR (TRY), JP (JPY)
9TFox	Korean sole trader	Consulting income/expenses (KRW)
Finacode	Turkish partnership	Partner-share only, Wise transfers

Core UI primitives:

• Confidence chip — green (rules / 100%) → blue (LLM ≥0.85) → amber (0.70–0.85) → red (<0.70 or unmatched)
• Tier badge — Rules · LLM · Agent · Unmatched
• Entity badge — three distinct accent hues, used as scope, never as page tint
• Account picker — hierarchical, fuzzy-searchable, MRU-aware
• Ledger preview — monospace two-leg posting confirmation

---

CONTENT FUNDAMENTALS

Akefin is professional financial-operations software. Copy reflects that.

Voice & tone

• Authoritative, calm, technical. Never marketing-y, never cute. Closer to a Unix man page than a SaaS dashboard.
• Specific over generic. "23 transactions staged for review" — not "You have new items".
• No filler verbs. "Review", "Categorize", "Post" — not "Let's review", "Time to categorize".
• Domain language is welcome. Use ledger, posting, leg, account, entity, tier, match, unmatched, staged. Don't over-translate accounting terms for a user who lives in them.

Person & address

• Predominantly imperative ("Approve", "Override", "Promote rule").
• Where a subject is needed, you (sparingly). Never we. Never your money — say the ledger or this entity.

Casing

• Sentence case for body, descriptions, table headers, menu items, button labels longer than two words.
• UPPERCASE small-tracked for tab labels, eyebrow labels, section dividers, status strips — the pi.dev [ READ THE DOCS ]-style chrome.
• Title Case only for proper nouns (entity names, currency codes, Toss).

Numbers, currency, dates

• Amounts: always monospace, right-aligned, signed. + 1,240,000 KRW for income, − 38,500 KRW for expense. Decimal separator follows locale, but the column aligns on the decimal.
• Currency code follows the amount, separated by a thin space. Never use the currency symbol alone (₩, ₺, ¥ are ambiguous at a glance across these three).
• Dates: ISO YYYY-MM-DD in dense data views, 2 Mar 2026 in headers, never 03/02/26.
• Confidence: two-decimal fixed-point, 0.92, never 92%.

Korean (한국어) handling

• Hangul appears natively in payee memos (적요) and bank institution names. Don't romanise. Don't translate inline.
• When showing a translated/AI-inferred name, render it secondary: 이마트 트레이더스 · E-Mart Traders (inferred).

Emoji & decoration

• No emoji. Anywhere. This is an accounting tool.
• Decorative iconography is sparse — keep glyphs functional (status, direction, expand/collapse).

Sample copy

Review queue · 23 staged · 4 high-confidence · 19 need attention

2026-03-02 −38,500 KRW 스타벅스 강남역점 Personal ★ 0.94 LLM

[ APPROVE ] [ OVERRIDE ] [ SKIP ]

Promote 17 suggested rules · Last import 4 min ago · 9TFox ledger clean

---

VISUAL FOUNDATIONS

The system is paper-quiet, grid-anchored, type-led. It should feel like a precision instrument from a well-lit study, not a SaaS app.

Surface & background

• Primary surface: warm cream paper (--bg, #ECE7DC). The default page background.
• Secondary surface: cool pale ink-grey (--surface, #EBEEF1) for code/data blocks, terminal-style frames, ledger previews. The two-surface contrast is the system's signature.
• Background grid texture (1px × 1px, ~6% opacity grey lines, 24px spacing) is applied to the page body. This is a load-bearing motif — do not omit.

Type

• Display serif (italic-leaning): Spectral — substitutes for Plantin MT Pro which pi.dev uses. Headings prefer italic at light weight. (Substitution flagged — please supply Plantin MT Pro woff2 to replace.)
• Body / UI sans: IBM Plex Sans — used for tab labels, body text, button chrome.
• Mono / data: JetBrains Mono — all amounts, account paths, dates in dense views, code blocks, ledger postings. Tabular figures are mandatory.
• Korean (Hangul): IBM Plex Sans KR for chrome, Pretendard for body when Hangul is the primary content. Hangul lines up at slightly larger optical size than Latin.
• Type ramp lives in colors_and_type.css.

Color

• Background neutrals first; saturation is reserved for semantic meaning (confidence tiers, entity badges).
• Three entity hues — Personal (slate teal), 9TFox (rust), Finacode (indigo) — only as badge accent / 4px scope strip, never as a full UI tint.
• Confidence spectrum: green → blue → amber → red. These are the only "decorative" colors in the chrome.
• Full palette in colors_and_type.css.

Spacing & density

• Base unit 4px. Compact density: row height 32px for review-queue lines, 40px for primary list rows, 48px for table headers / page tabs.
• Inner padding ramp 4 · 8 · 12 · 16 · 24 · 40.
• Type at 14px / 1.45 line-height for chrome, 13px / 1.4 mono for data tables.

Borders

• Hairline borders are the primary divider — 1px solid var(--rule) (#D5CFC2 on cream, #D7DCE2 on ink-grey). No shadow-as-divider.
• Card borders are 1px, never thicker. Border-radius is 2px. Rounded-everything is explicitly not the look.
• Terminal-style code frames have a 1px border + an inset 1px hairline on the inner edge, mimicking a window chrome.

Shadows

• Reserved. Use only for popovers, account-picker dropdowns, focus-mode dialogs. Never on cards or inline rows.
• Single elevation: 0 1px 0 rgba(20,18,12,.04), 0 8px 24px -8px rgba(20,18,12,.16). Soft, paper-shadow, not material.

Corner radii

• --r-sm: 2px, --r-md: 3px, --r-lg: 4px. Maximum 4px. Pills (--r-pill: 999px) only on confidence chips and tier badges.

Borders, hover, press

• Hover: cream surfaces darken by ~3% (use color-mix); ink-grey surfaces lighten by ~2%. Text links underline on hover; underline thickness 1px, offset 2px.
• Press: scale 0.99, never a color flash. Buttons get a 1px inset shadow.
• Focus: 2px outline in --focus (#3A6FB0), offset 2px. No focus ring removal.

Transparency & blur

• Used only for modals/popovers' backdrop (rgba(20,18,12,0.32)) and the global command-K palette. No frosted-glass elsewhere.

Animation

• Minimal and short. Cubic-bezier (0.2, 0, 0.2, 1), durations 80ms (chrome hover), 140ms (popovers), 220ms (modal/tab transitions).
• No bounces, no springs. A calm, instrument-like motion language. Confidence chips do not pulse, entity badges do not animate in.

Layout rules

• Fixed top chrome: a 56px header strip (entity scope + global search + status).
• Optional 240px left navigation rail with collapse to 56px icon strip.
• Content max-width 1440px; tables and review queue may extend full-bleed inside the rail.

Imagery vibe

• Almost no photography. If product imagery is needed: cool, sober, well-lit, slight grain, no people, mostly objects. Default to no image and let type do the work.

Iconography vibe

• Light-weight (~1.25px stroke), monoline, geometric. Lucide is the substitute (see ICONOGRAPHY below).

Dark theme (secondary)

• A direct inversion: ink black background (#13120F), warm paper foreground. Same hues, same hierarchy. Not the default for the user, but supported.

---

ICONOGRAPHY

Akefin has no proprietary icon set at time of writing. The system uses Lucide (https://lucide.dev) as the substitute — its 1.25px monoline geometric style matches the calm-instrument aesthetic.

• Loaded via CDN: https://unpkg.com/lucide@latest
• Used at three sizes only: 14px (inline chrome), 16px (default UI), 20px (page headers)
• No filled variants. Stroked only.
• No emoji. Anywhere.
• No unicode glyph icons except: ↑ ↓ → (sort + direction), · (separator), ✓ (matched), — (em-dash, range).
• The Akefin wordmark is the only branded glyph — it lives at assets/akefin-wordmark.svg and is a small monospaced lockup, see Brand cards in preview/.
• Three entity marks (Personal, 9TFox, Finacode) are 2-3 letter monograms in mono type with a 4px coloured stripe — see assets/entity-marks.svg.

Flagged substitution: Lucide stands in until an Akefin-native icon set is produced. The closest mono-line set was chosen specifically to match the pi.dev stroke weight.

---

Index

/
├── README.md                  ← you are here
├── SKILL.md                   ← Claude/Agent Skill entrypoint
├── colors_and_type.css        ← all color + type CSS variables + semantic classes
├── fonts/                     ← webfonts (Spectral, IBM Plex Sans, IBM Plex Sans KR, JetBrains Mono, Pretendard)
├── assets/                    ← logos, entity marks, sample iconography
├── preview/                   ← design-system cards (registered in the Design System tab)
└── ui_kits/
    ├── web/                   ← Akefin web dashboard recreation
    │   ├── README.md
    │   ├── index.html
    │   └── *.jsx
    └── mobile/                ← Akefin mobile (iOS frame) recreation
        ├── README.md
        ├── index.html
        └── *.jsx

---

Known caveats

1. Plantin MT Pro (pi.dev's display face) is proprietary — substituted with Spectral from Google Fonts. Please supply the original .woff2 to replace.
2. The akefin-design-system GitHub repo was empty when this was generated — components here are synthesised from the brief + pi.dev aesthetic, not lifted from existing code.
3. No real Akefin screenshots were provided. The UI kits are an interpretation of the brief's component inventory, not a recreation of an existing UI. Iterate.
4. Dark theme is sketched but light is the priority per user preference.