jmrp.io / kleidos

0

[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

kleidos / docs / design / claude-design-bundle /

at main 6 folders 6 files

José M. Requena Plens Raise the per-variant capacities, and stop shipping unusable vault UI 6w ago

brand-logos-color

Add the Claude Design context bundle Self-contained design-brief package for the next-gen UI pass: README brief with the phased workflow (identity, components, screens per device, pixel-exact handoff), verified device inventory, the mined interaction model (per-screen StickS3 button maps plus input-scaling guidance), the implemented component catalog, design-system tokens and constraint references, photo-verified true-scale device fronts, 29 live StickS3 captures, three real-cadence UI videos (PIN timing arc, vault navigation, letter carousel), brand identity, and the multicolor/gray logo contact sheets. Claude-Session: https://claude.ai/code/session_01SV58JXhfxhhc9DC6vdjBo4

2 months ago

brand-logos-gray

Add the Claude Design context bundle Self-contained design-brief package for the next-gen UI pass: README brief with the phased workflow (identity, components, screens per device, pixel-exact handoff), verified device inventory, the mined interaction model (per-screen StickS3 button maps plus input-scaling guidance), the implemented component catalog, design-system tokens and constraint references, photo-verified true-scale device fronts, 29 live StickS3 captures, three real-cadence UI videos (PIN timing arc, vault navigation, letter carousel), brand identity, and the multicolor/gray logo contact sheets. Claude-Session: https://claude.ai/code/session_01SV58JXhfxhhc9DC6vdjBo4

2 months ago

Close the fleet-UI remainder: severity shape, e-paper grammar, sub-bar contrast The eight-device review left a tail of findings that needed no owner ruling. They are landed here, each with the adversarial pass that followed them — which caught three regressions the first attempt would have shipped. Severity stops being carried by color alone (design principle 9, WCAG 1.4.1). A card's mark is now inked in that card's OWN tone rather than a hardcoded destructive red, so a caution card wears a yellow triangle instead of a red one whose shape and tint disagree about how bad the situation is. Transitions deliberately carry no mark at all: the only shape the dialog component owns means "something is wrong", and the pending-admin route raises a CAUTION progress card ("Opening admin / starting WiFi") where a hazard triangle would be a lie. A test pins the tone on Caution — Danger cannot catch that regression, because the correct and the hardcoded expression agree there. CoreInk speaks its own chassis grammar. The credential detail drops to 1-bit because a 6-tone settle blocks the loop ~1.8 s and drops the button presses a navigable screen depends on; the tab-switch gesture is advertised; the lock face stops naming a letter that chassis does not print; the toast body clears the ink floor. The selected tab label lifts a rung only when it measures inside its cell — the fit reserves headroom because the canvas measures the regular face while the label draws bold (1.02-1.05x wider), and where no rung fits at all the string was the problem: fr "Mot de passe" needed 72px in a 66px cell, so it is now "MdP", which also fixes a silent overrun on Cardputer. Indicators that carry information clear the 3:1 non-text bar: empty PIN slots, page dots and char-wheel positions were on kMuted at 2.16:1 — information encoded below the floor its own pattern doc prescribed, so the doc moved too, with the carve-out WCAG grants genuinely inactive components. The list stops drawing a scroll rail when nothing scrolls. Documentation that lied is corrected, most consequentially the serial harness: TAP and HOLD were documented as accepting the same ids as PRESS, but resolveDefer maps only A/B/C, so TAP P and HOLD K silently did nothing — a trap for anyone scripting the CoreInk side keys. Native 2558/2558, seven variants clean. Claude-Session: https://claude.ai/code/session_01XBVa8G5jrkprye4gVAkQSU

1 month ago

Add the Claude Design context bundle Self-contained design-brief package for the next-gen UI pass: README brief with the phased workflow (identity, components, screens per device, pixel-exact handoff), verified device inventory, the mined interaction model (per-screen StickS3 button maps plus input-scaling guidance), the implemented component catalog, design-system tokens and constraint references, photo-verified true-scale device fronts, 29 live StickS3 captures, three real-cadence UI videos (PIN timing arc, vault navigation, letter carousel), brand identity, and the multicolor/gray logo contact sheets. Claude-Session: https://claude.ai/code/session_01SV58JXhfxhhc9DC6vdjBo4

2 months ago

screenshots-sticks3

Add the Claude Design context bundle Self-contained design-brief package for the next-gen UI pass: README brief with the phased workflow (identity, components, screens per device, pixel-exact handoff), verified device inventory, the mined interaction model (per-screen StickS3 button maps plus input-scaling guidance), the implemented component catalog, design-system tokens and constraint references, photo-verified true-scale device fronts, 29 live StickS3 captures, three real-cadence UI videos (PIN timing arc, vault navigation, letter carousel), brand identity, and the multicolor/gray logo contact sheets. Claude-Session: https://claude.ai/code/session_01SV58JXhfxhhc9DC6vdjBo4

2 months ago

Add the Claude Design context bundle Self-contained design-brief package for the next-gen UI pass: README brief with the phased workflow (identity, components, screens per device, pixel-exact handoff), verified device inventory, the mined interaction model (per-screen StickS3 button maps plus input-scaling guidance), the implemented component catalog, design-system tokens and constraint references, photo-verified true-scale device fronts, 29 live StickS3 captures, three real-cadence UI videos (PIN timing arc, vault navigation, letter carousel), brand identity, and the multicolor/gray logo contact sheets. Claude-Session: https://claude.ai/code/session_01SV58JXhfxhhc9DC6vdjBo4

2 months ago

Add the Claude Design context bundle Self-contained design-brief package for the next-gen UI pass: README brief with the phased workflow (identity, components, screens per device, pixel-exact handoff), verified device inventory, the mined interaction model (per-screen StickS3 button maps plus input-scaling guidance), the implemented component catalog, design-system tokens and constraint references, photo-verified true-scale device fronts, 29 live StickS3 captures, three real-cadence UI videos (PIN timing arc, vault navigation, letter carousel), brand identity, and the multicolor/gray logo contact sheets. Claude-Session: https://claude.ai/code/session_01SV58JXhfxhhc9DC6vdjBo4

2 months ago

brand-identity.png

Add the Claude Design context bundle Self-contained design-brief package for the next-gen UI pass: README brief with the phased workflow (identity, components, screens per device, pixel-exact handoff), verified device inventory, the mined interaction model (per-screen StickS3 button maps plus input-scaling guidance), the implemented component catalog, design-system tokens and constraint references, photo-verified true-scale device fronts, 29 live StickS3 captures, three real-cadence UI videos (PIN timing arc, vault navigation, letter carousel), brand identity, and the multicolor/gray logo contact sheets. Claude-Session: https://claude.ai/code/session_01SV58JXhfxhhc9DC6vdjBo4

2 months ago

brand-identity.svg

Add the Claude Design context bundle Self-contained design-brief package for the next-gen UI pass: README brief with the phased workflow (identity, components, screens per device, pixel-exact handoff), verified device inventory, the mined interaction model (per-screen StickS3 button maps plus input-scaling guidance), the implemented component catalog, design-system tokens and constraint references, photo-verified true-scale device fronts, 29 live StickS3 captures, three real-cadence UI videos (PIN timing arc, vault navigation, letter carousel), brand identity, and the multicolor/gray logo contact sheets. Claude-Session: https://claude.ai/code/session_01SV58JXhfxhhc9DC6vdjBo4

2 months ago

component-inventory.md

Add the Claude Design context bundle Self-contained design-brief package for the next-gen UI pass: README brief with the phased workflow (identity, components, screens per device, pixel-exact handoff), verified device inventory, the mined interaction model (per-screen StickS3 button maps plus input-scaling guidance), the implemented component catalog, design-system tokens and constraint references, photo-verified true-scale device fronts, 29 live StickS3 captures, three real-cadence UI videos (PIN timing arc, vault navigation, letter carousel), brand identity, and the multicolor/gray logo contact sheets. Claude-Session: https://claude.ai/code/session_01SV58JXhfxhhc9DC6vdjBo4

2 months ago

device-inventory.md

Remove the M5Stack Gray variant from the fleet The M5Stack Gray is retired (owner-approved): the fleet drops from 9 to 8 device variants. This removes the Gray as a build target / device while keeping every reusable driver and HAL layer intact. Removed (Gray-exclusive wiring only): - variants/m5stack_gray/ (variant.h, ini, sdkconfig, the four envs) - src/boards/board_gray.cpp (the DEVICE_ID==5 board-registry factory) - the web installer mockup (gray.svg + screen png) and app.js entry - docs/hardware/devices/m5stack-gray.md and every fleet-list / inventory / identifier / secure-availability row across docs, CI, and instructions Kept (per owner: preserve tested drivers/HAL even with no current consumer): - the IP5306 PMIC driver family (src/drivers/power/ip5306*) — Gray was its only board; still native-validated by test_small_pmic_regmaps - the classic-ESP32 RTC_CNTL MMIO regmap (rtc_cntl_esp32_regmap.h) — Gray was the only classic internal-RTC board; still native-validated - board_gray_log_wrap.cpp renamed to board_log_printf_wrap.cpp: the __wrap_log_printf stub is fleet-wide (esp32_base defines the gate), not Gray-specific DEVICE_ID 5 is retired and left unused so the remaining ids stay stable. CI covering set rebalanced (Gray was the classic-ESP32 representative): sticks3, tdeck, cores3_se, m5core_ink, m5stickc_plus2. m5stickc_plus2 (classic ESP32 + ST7789 full-frame polling + 8 MB OTA) replaces the Gray's classic-ESP32 + OTA + polling coverage. core2_v13 is intentionally not added to CI: it is an "Initial" WIP board that currently overflows DRAM at link (pre-existing), so it cannot be a green gate member. Native tests 2306/2306. Base envs build green for the new CI set (sticks3, m5stickc_plus2, tdeck, cores3_se, m5core_ink). Claude-Session: https://claude.ai/code/session_01P6BNTpbgrvnZXSJnNuj8ZJ

2 months ago

interaction-model.md

Raise the per-variant capacities, and stop shipping unusable vault UI Every board now pins the capacity its flash and RAM actually support: tdeck and cores3_se 700, core2_v13 500, sticks3 and cardputer 250, m5stickc_plus2 180. The two 4 MB boards stay at 100 — their rekey-safe ceiling is 139, and staging a second vault for a change-PIN on a fuller one would run the filesystem out of space. m5stickc_plus2 could not honestly hold 180: it had 3,132 B of internal DRAM left against the 4,096 B bar. The slack came from a real absurdity. Every button board compiled BOTH vault-menu layouts and picked one at runtime from whether a third button existed, though a board's buttons are fixed at manufacture. Each unused layout carries a row array sized by capacity, so plus2 was paying 5 KB for a screen it can never draw. Boards now declare which layout they use and only that one is compiled: plus2 goes to 9,196 B, sticks3 to 143,141, cores3_se to 78,985. core2_v13 recovers only the view object because its row arrays already live in PSRAM, which is the placement working as intended. The declaration is deliberate rather than inferred. Button count looked like the discriminator only because today's fleet correlates: cardputer and tdeck are wide-screen boards with no third button, and the old rule would have handed them the narrow layout if their keyboards ever went away. What actually decides the layout is width — a sliding pill indicator is what fits 135 px, while a top tab bar plus an action bar need room, and a past CoreInk header garble came from that view hardcoding 320x240. Input decides only how you move between tabs. So the variant states its choice, with no default, and a build-time tie rejects a board declaring a layout its hardware cannot drive. The names were lying too. Both layouts draw tabs, so "Tabbed" distinguished nothing: they are now NarrowVaultView and WideVaultView, after the constraint that actually separates them. KeyboardVaultView keeps its name on purpose — cardputer is 240x135 and tdeck is 320x240, one narrow and one wide, and both use it, so there the discriminator really is the input device. Review of the change caught a T-Deck pin that had never been raised while five other artifacts already advertised 700, a NAV TOTP macro that regressed on the wide boards so the screenshot suite filed a vault-list capture as the TOTP screen, a selector whose "no silent default" promise had a hole (an unknown token preprocesses to zero, which was the one value exempted, so a typo compiled no view at all), and a variant guard whose regex rejected correct declarations that carried a trailing comment. Verified: native 2861/2861, all three repo guards, and all eight boards build with their declared layout confirmed present and its siblings absent in each map. Claude-Session: https://claude.ai/code/session_01Q2J5gQSFMTDLVzPUYog51r

1 month ago

README.md

Kleidos — Claude Design context bundle#

Kleidos is an open-source hardware password manager (a YubiKey-class personal security device): an encrypted credential vault on an ESP32-S3 that types the owner's passwords into their own computers over BLE, unlocked by a PIN entered on the physical device. The firmware ships on 9 device variants with radically different screens (1.14" 135×240 portrait TFT up to 2.8" 320×240 touch TFT, plus a 200×200 1-bit e-paper) and input hardware (2 buttons, 3 buttons/touch zones, full touchscreens, QWERTY keyboards, a trackball, a jog wheel).

The design brief#

Design the next-generation Kleidos UI from scratch, following the brand identity (brand-identity.svg) and the design-system tokens/constraints (design-system/), for every device variant.

Work in this order:

Brand identity first — confirm or evolve the identity (brand-identity.svg, design-system/brand-tokens.md): logo usage, palette (must quantize to RGB565), type ladder, the dark-TFT vs paper-e-ink theme duality, and a coherent icon set (line weight, radii, 12/16/24 px sizes — today's iconography is ad-hoc).
Component mockups second — one spec/mockup per implemented component in component-inventory.md (header, action bar, tab bar, menu list, popup family, PIN dial, letter carousel, editors, …), in every state (default, selected, disabled, error, empty) and at each density preset. Components are the contract: every screen is composed from them.
Screens per device third — compose the components into every screen of each variant, driven by that device's real inputs and ergonomics (device-inventory.md §2, interaction-model.md §4: 2 buttons vs 3 buttons/touch zones vs full touch vs keyboard+trackball vs jog wheel) and its true screen geometry (device-fronts/).
Handoff last — for each component and screen, final mockups at exact panel resolution (1 px = 1 panel px) so they can be verified pixel-for-pixel against on-device captures (the repo has a screenshot/video harness for this).

Also account for i18n: all UI strings are localized (device ships with a language picker at onboarding); layouts must tolerate translated strings (~+35% width vs English) without truncation.

Per-variant notes:

The StickS3 (135×240, 2 buttons) is the reference only because it is the smallest, most constrained target and the UI we can document best. Its current screens (screenshots-sticks3/, videos-sticks3/) show what exists today — they are context, not a spec. The redesign is explicitly free to redesign or improve the StickS3 itself, screen by screen, as long as the result stays operable with its 2 buttons and respects its legibility floors.
The interaction grammar in interaction-model.md describes how navigation works today on 2 buttons and how the owner wants it scaled to richer devices: exploit extra inputs (direct touch, typed search, trackball, wheel) rather than emulating the 2-button flow.
Every metric decision (font sizes, touch targets, spacing) must respect the per-device legibility floors and density presets in design-system/ — these panels run from 141 to 241 PPI and are viewed at ~30 cm.
The CoreInk e-paper gets its own design language within the brand: 1-bit live rendering, 6-tone static grayscale, ~5 fps bounded animation, zero-power image retention (see device-inventory.md §6).

What each resource is#

Path	What it is
`device-inventory.md`	Verified hardware truth: screens (panel, resolution, active area mm, PPI, orientation), input modalities, case identity, per-device capability notes. Start here.
`interaction-model.md`	The interaction grammar: per-screen button maps on StickS3 (short/long/multi press), timeouts, popup rules, and input-scaling guidance for the other 8 variants.
`component-inventory.md`	The component catalog as factored in the implementation (chrome, content, editors, popup family, foundations) — the checklist for phase 2, with known gaps.
`design-system/`	`tokens.json` (colors, type ladder, spacing, per-device density presets) + constraint references (legibility floors, motion envelopes, contrast/accessibility rules, small-display typography, touch targets, UI patterns).
`device-fronts/`	Photo-verified true-scale front renders of all 9 devices (1 SVG mm = 1 real mm) — the canonical frames for mockups. Contact sheet included.
`screenshots-sticks3/`	29 live captures of the current StickS3 UI at 2× (onboarding, PIN arc, vault, TOTP, settings, admin, popups).
`videos-sticks3/`	Real-cadence screen recordings: PIN timing-arc entry, vault navigation, letter-carousel text editor. Motion/feel reference.
`brand-identity.svg/.png`	The Kleidos brand identity sheet — logo, wordmark, color story. Single source of truth for brand.
`brand-logos-color/`	Multicolor third-party brand-logo atlases (RGB565) rendered per credential row/detail on TFT devices.
`brand-logos-gray/`	The same logos as 4- and 6-tone grayscale (Bayer-dithered) for the e-paper.

Hard constraints (non-negotiable)#

1 design px = 1 panel px (no @2x rendering on device).
Colors must quantize cleanly to RGB565; the UI background is near-black.
Touch targets ≥ the sizes in design-system/spacing-and-targets.md — but only tdeck / cores3_se / core2_v13 have touch at all.
E-paper: no anti-aliasing on live 1-bit content; ordered dithering only; animation in bounded regions.
Every screen must be operable with the device's actual inputs (see interaction-model.md §4) — on 2-button devices everything must be reachable through tap/hold/double-tap of A and B.
Credentials/security: no design may put secret material on screen without an explicit reveal action; destructive actions use hold-to-confirm.