jmrp.io / kleidos
[READ-ONLY] Mirror of https://github.com/jmrplens/kleidos. Kleidos — Hardware BLE password manager for ESP32-S3 (M5StickC Plus2, StickS3, M5Stack Gray, T-Deck, Cardputer) jmrplens.github.io/kleidos/
0
Fork 0

Configure Feed

Select the types of activity you want to include in your feed.

kleidos / docs / design / handoff /
at main 2 folders 3 files
José M. Requena Plens Adopt the sheet status-container anatomy for filled status surfaces
9bf3bd66
assets
reference
README.md
tokens.css
tokens.json
README.md

Handoff: Kleidos UI — Brand Identity + StickS3#

Overview#

Next-generation UI for Kleidos, an open-source hardware password manager on ESP32. This bundle covers the approved brand identity, the complete StickS3 screen catalog (135×240, 2-button), the complete CoreInk catalog (200×200, 1-bit e-paper) and the complete CoreS3 / Core2 catalog (320×240, capacitive touch). Gray, T-Deck and Cardputer follow in later drops.

About the design files#

The .dc.html files in reference/ are design references authored in HTML — prototypes of the intended look and behavior, not production code to ship. Recreate them in the firmware's real rendering environment (ESP32 display driver / LVGL or the project's existing UI layer), using its established patterns. tokens.json / tokens.css and the SVGs in assets/ are the directly reusable artifacts; sync those and rebuild the screens natively.

Fidelity#

High-fidelity. Final colors, RGB565-quantized values, typography, spacing and interactions. Every screen is drawn at 1 design px = 1 panel px — measure directly off the mock.

Design tokens#

Canonical values in tokens.json (with RGB565 hex + WCAG contrast) and tokens.css (CSS custom properties + theme selectors). Highlights:

  • Brand: #00D2FF cyan (RGB565 0x069F, 11.7:1 on black).
  • Dark TFT theme (default, 8 of 9 variants): base #000, surface #111, selection #0F3460, text #E0E0E0 / #8899AA / #444, divider #222; status success #51CF66, warning #FF6B6B, caution #FFD43B, info #FFA500, admin #C48500. All RGB565-safe; ratios in the JSON.
  • E-ink theme (CoreInk only): white + 4 grays + black. Grays are ordered dither, not solid; no anti-aliasing. Paper is default, dark is a full invert.
  • Type: Inter (labels/titles) + JetBrains Mono (PIN/TOTP/fingerprints, tabular). Per-device legibility floors in font.floors — StickS3 body = 12px (just-legible band), PIN digit ≥20 arcmin.
  • Spacing: 8-pt grid. Radius: 2/6/10/999. Motion: 200ms fade (e-paper snaps).
  • assets/logo-full.svg — full mark (ring + keyhole). Use ≥24px and for branding.
  • assets/logo-glyph.svg — solid keyhole, no ring. Use ≤24px and on 1-bit e-paper.
  • assets/logo-glyph-currentcolor.svg — glyph inheriting currentColor for headers.
  • Construction, clear-space (= ring radius) and min sizes in logo of tokens.json.
  • Header brand mark across devices = the glyph (no ring) so it fits the title bar.

Icons#

assets/icons/*.svg — 8 system icons on a 24-unit grid, 2px stroke, 2px radius, round caps, currentColor stroke: lock, key, credential, totp, settings, ble, battery, warning. Below 16px step stroke to 1.5px; at 12px / on e-paper render solid.

Input grammar (StickS3, 2-button)#

  • A short = ↓ / next · B short = ↑ / prev
  • A hold = open / confirm · B hold = back
  • A×2 / B×2 = switch home tab · power = lock
  • Secrets never render without an explicit reveal (hold); destructive actions use hold-to-confirm.
  • A persistent action bar always maps the buttons (hardware buttons are unlabeled).

Screens (StickS3) — see reference/Kleidos Phase 4 - Verification.dc.html#

Organized into sections, all 1:1:

  • A · Onboarding: welcome, button tour, gesture grammar, language, secret-type (PIN 4–8 / passphrase), create PIN, confirm PIN, passphrase, pair, done. Progress bar after welcome.
  • B · Home: lock (idle clock) + unlock (PIN entry, logo lockup + marker dial, no header), then the three-tab pager: Vault · TOTP · Settings (sliding indicator).
  • C · Vault: list navigation + credential action carousel — stops mix actions (Type, Delete) and data fields (username, URL, related TOTP, notes). Type/reveal only on hold A.
  • D · TOTP: list (live arcs), navigation, open one (full code + countdown).
  • E · Settings: Device (brightness, auto-lock, shake-to-lock, UI language, HID keyboard layout), Wi-Fi client (saved/scanned networks, password entry, clock sync then disconnect), Wi-Fi admin AP (QR + SSID/password/URL), Bluetooth (paired hosts, actions, rename), change PIN (marker dial), OTA, factory reset (hold-to-confirm).
  • F · Popups: toast, banner, notice, alert, confirm, choice, hold-to-confirm, spinner, transition.

Text entry — horizontal carousel#

All on-device text entry (passphrase, Wi-Fi password, host rename) uses a horizontal letter carousel: active glyph centered in a box, dimmed neighbors left/right, using the panel width. Dial/buttons scroll the letter; hold to accept. (Applies to StickS3 and CoreInk.)

PIN timing arc (canonical component)#

Logo + "Kleidos"/kleidos wordmark at top, a dial disc with digits 0–9 around the rim and markers, the chosen digit large in the center, progress dots, then the footer. Reused for create / confirm / unlock / change-PIN. Do not substitute a plain progress arc.

Screens (CoreInk) — see reference/Kleidos Phase 4 - CoreInk.dc.html#

200×200 1-bit e-paper, paper theme default (white base, black ink), optional dark invert. Grays are ordered dither, never solid; no anti-aliasing; motion ≤5 fps; no cyan on panel. Inputs: dial ▲▼ scroll · dial press OK/open · ‹ side button back · top button home/wake (both side/top are push buttons). Sections mirror StickS3:

  • A · Onboarding: welcome, control tour (animated halo cycles each button ~5fps), gesture, language, secret type (PIN 4–8 / passphrase), create/confirm PIN, passphrase, done.
  • B · Home: lock (zero-power retained clock), unlock (dial disc), three tabs with K0 inverse bar.
  • C · Vault: two candidate detail layouts to trial — Option A · menu (scrolling action list, best for static e-paper) and Option B · carousel (Stick-style stepped, uses the 5fps motion). Implementation picks one. Reveal only on OK-hold.
  • D · TOTP: list (dither arcs), open one.
  • E · Settings: refresh mode (full/partial — replaces brightness, no backlight), auto-lock, UI language, HID layout, Wi-Fi (networks, password, clock sync then disconnect), admin AP (QR + SSID/password/URL), Bluetooth (hosts, actions), change PIN, OTA, factory reset.
  • F · Popups: toast, notice, alert, confirm, choice, spinner, transition — status = icon + tone + dither, never color; modals are K0-outlined cards.

Files#

  • tokens.json, tokens.css — design tokens (sync these).
  • assets/logo-*.svg, assets/icons/*.svg — brand + icon assets.
  • reference/Kleidos Brand Identity.dc.html — identity sheet (palette, type ladder, icon language).
  • reference/Kleidos Phase 4 - Verification.dc.html — the full StickS3 1:1 catalog.
  • reference/Kleidos Phase 4 - CoreInk.dc.html — the full CoreInk 1:1 catalog (paper e-ink).

Screens (CoreS3 / Core2) — see reference/Kleidos Phase 4 - Touch CoreS3 Core2.dc.html#

One UI for both shells. 320×240 · 199 PPI · RGB565 · dark · capacitive touch with 3 under-screen buttons (A/B/C) as fallback; power left edge (13mm from top), reset bottom edge (13mm from right); targets ≥ 44px. Gestures: tap select · swipe ↕ scroll · swipe ↔ change tab · long-press reveal secret. Text entry uses the on-screen QWERTY keyboard; PIN uses the on-screen numeric keypad (not the dial/carousel of button devices). Sections:

  • A · Onboarding: welcome, touch tour (tap ripple + swipe), language, secret type, create PIN (keypad), passphrase (QWERTY), pair, done.
  • B · Home: lock (tap-to-wake), unlock (keypad), three-tab pager (tap / swipe ↔).
  • C · Vault: detail = big tappable action buttons + scrollable fields; reveal on long-press; delete hold-to-confirm.
  • D · TOTP: list (live arcs), open one.
  • E · Settings: brightness (drag slider), auto-lock, shake-to-lock (toggle, IMU), UI language, HID layout, Wi-Fi (networks, clock sync then off), admin AP (QR), Bluetooth, change PIN (keypad), OTA, factory reset.
  • F · Popups: toast, confirm, choice, alert, spinner.

Screens (Cardputer) — see reference/Kleidos Phase 4 - Cardputer.dc.html#

240×135 · 241 PPI · RGB565 · dark · 56-key QWERTY, no touch. type to filter/enter · ⏎ open · esc back · fn+←→ switch tab · fn+↑↓ move. Key positions: fn (orange)

  • Aa (cyan) row 3 left; ctrl · opt (green) · alt row 4 left; arrows bottom-right; fn+arrows navigates. PIN & passphrase are typed (no keypad/carousel). Token delta: at 241 PPI read at phone distance, promote body copy up a size (11px is dense-data only). Sections:
  • A · Onboarding: welcome, key tour (fn/opt/arrows), language, secret type, typed PIN, typed passphrase, pair, done.
  • B · Home: lock (key-to-wake), unlock (typed PIN), three-tab pager (fn+←→ / type-to-filter).
  • C · Vault: type-ahead search; detail with single-key shortcuts (⏎ type, r reveal-hold, t TOTP); delete hold-⏎.
  • D · TOTP: list, open one.
  • E · Settings: brightness/auto-lock (←→ steppers, hold ramp), HID layout, Wi-Fi, admin AP (QR), Bluetooth, change PIN (typed), OTA, factory reset.
  • F · Popups: toast, confirm (⏎/esc), choice, alert, spinner.

Screens (T-Deck) — see reference/Kleidos Phase 4 - T-Deck.dc.html#

320×240 · 141 PPI · RGB565 · dark · QWERTY + capacitive touch + trackball + GPS; power right edge, reset left. Richest input mix: type filter/enter · tap/swipe like CoreS3 · ⏎ open · esc back · trackball = optional mouse pointer (off by default) · GPS used only to sync the RTC then powered off. Sections:

  • A · Onboarding: welcome, input tour (type/tap/trackball), language, GPS clock-sync prompt (T-Deck only), secret type, done.
  • B · Home: lock (key/tap-to-wake), unlock (type or keypad), three-tab pager, optional trackball cursor.
  • C · Vault: type-ahead search; detail = big tappable buttons that are also key shortcuts (⏎ type, r reveal-hold, t TOTP); reveal on hold only.
  • D · TOTP: list (live arcs), open one.
  • E · Settings + GPS: the Sync clock flow (entry → GPS on, acquiring fix → RTC set, GPS off); brightness, HID layout, Wi-Fi (alt clock sync), admin AP (QR), Bluetooth, change PIN, OTA, factory reset.
  • F · Popups: toast, confirm, choice, alert, spinner.

Screens (M5Stack Gray) — see reference/Kleidos Phase 4 - Gray.dc.html#

320×240 · ~199 PPI · RGB565 · dark · 3 membrane buttons (A/B/C), no touch; reset/power left edge. A up/prev · B select (hold = back) · C down/next · hold A/C switch tab. Persistent action bar always maps the three buttons. Body 16px sits on the floor at 199 PPI — re-verify on Gray. Sections:

  • A · Onboarding: welcome, button tour (A/B/C glow in turn), gesture, language, secret type, create/confirm PIN (3-button spinner), passphrase (horizontal carousel), pair, done.
  • B · Home: lock (button-to-wake), unlock (spinner), three-tab pager (A/C move, hold A/C tab).
  • C · Vault: scrolling action menu (A/C move, B activate, hold B back); reveal on Reveal item (hold B); delete hold-B.
  • D · TOTP: list (live arcs), open one.
  • E · Settings: brightness/auto-lock (A + / C − spinner, hold ramp, B save), HID layout, Wi-Fi, admin AP (QR), Bluetooth, change PIN (spinner), OTA, factory reset (hold B).
  • F · Popups: toast, confirm, choice, alert, spinner.

Notes#

  • Verify body 12px and the PIN arc on real StickS3 glass at ~30cm before locking sizes.
  • Open token deltas to check on hardware: Cardputer body promotion, Gray 16px-on-floor.