akefin-design-system/README.md

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