ake/akefin-design-system
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
akefin-design-system/README.md
Alkim Ake Gozen 8b790b7601 first commit
2026-05-23 11:59:45 +09:00

12 KiB
Raw Permalink Blame History

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.