From 6ee80834eefdc3223576e33f960e44354efb68e0 Mon Sep 17 00:00:00 2001 From: pNexus Date: Wed, 10 Jun 2026 18:06:55 +0800 Subject: [PATCH] =?UTF-8?q?docs(design):=20=E8=A1=A5=E5=85=85=E6=8E=A7?= =?UTF-8?q?=E5=88=B6=E9=9D=A2=E6=9D=BF=E8=AE=BE=E8=AE=A1=E7=A8=BF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 补充控制面板设计说明，并细化 RuntimeHost 状态与主界面线框图，便于后续实现对齐交互范围。 --- DESIGN.md | 148 +++++++++ docs/runtime_host_status_detail.svg | 168 ++++++++++ .../control-panel-main-wireframe.svg | 307 +++++++++--------- 3 files changed, 467 insertions(+), 156 deletions(-) create mode 100644 DESIGN.md create mode 100644 docs/runtime_host_status_detail.svg diff --git a/DESIGN.md b/DESIGN.md new file mode 100644 index 0000000..0be99e8 --- /dev/null +++ b/DESIGN.md @@ -0,0 +1,148 @@ +# Control Panel Design Language + +## Overall Structure + +The control panel uses a clear engineering-dashboard layout. Screens are divided into large functional regions, not decorative sections. A detail screen should usually split into: + +- a left information column +- a right controls column +- stacked status/log panels when more than one information region is needed + +Panels should align their titles with their primary content. If a title describes a card grid, align the title with the grid's left edge. If a title describes a log window, align it with the log window's left edge. + +Do not use decorative icons beside section titles. Titles should read as labels for the content region, not as illustrated headers. + +## Color System + +Use a restrained white-and-gray base with small semantic accents. + +- Page background: `#F4F6F8` +- Main panel background: `#FFFFFF` +- Normal card background: `#FFFFFF` +- Main panel border: `#C9D1D9` +- Inner card border: `#D5DDE5` +- Primary text: `#17202A` +- Secondary text: `#52616F` +- Muted text: `#7B8794` + +Semantic colors: + +- Primary blue: `#2F80ED` +- Primary blue fill: `#F3F8FF` +- Soft blue control fill: `#E8F1FF` +- Success green: `#31A66A` +- Success green fill: `#D9F5E5` +- Warning yellow: `#D99000` +- Warning yellow fill: `#FFFBED` +- Scrollbar track: `#E5E9EE` +- Scrollbar thumb: `#A4AFBA` + +Avoid large colored surfaces. Blue, green, and yellow are reserved for semantic accents: primary operations, connected/success states, warnings, and log categories. + +## Radius + +Except scrollbars, all rectangular UI surfaces use one radius: + +- Standard radius: `10px` + +This applies to main panels, status cards, operation cards, chips, log windows, and reserved areas. + +Scrollbars are auxiliary controls and may keep smaller radii: + +- Scrollbar track radius: `6px` +- Scrollbar thumb radius: `4.5px` + +## Typography + +Use straightforward system-safe typography. + +- Primary UI font: `Arial, sans-serif` +- Log/monospace font: `Courier, monospace` + +Text hierarchy: + +- Main section title: `22px`, `700`, `#17202A` +- Section description: `14px`, `#52616F` +- Operation card title: `22px`, `700`, `#17202A` +- Operation card description: `14px`, `#52616F` +- Status card label: `14px`, `600`, `#52616F` +- Status card value: `38px`, `700`, `#17202A` +- Log line: `15px`, monospace + +## RuntimeHost Detail Layout + +The RuntimeHost detail view is a two-column detail page. + +Left column: + +- top panel: runtime status summary +- bottom panel: session log + +Right column: + +- full-height controls panel + +### Runtime Status Panel + +The status panel contains: + +- a title and one-line description +- a bound-state chip aligned to the title row +- three horizontal status cards + +Status cards use white backgrounds, gray borders, and the standard 10px radius. Each status card has three levels: + +- small label +- large core value +- small semantic detail + +Use semantic detail colors sparingly: + +- connected/ready detail: `#31A66A` +- warning/detail requiring attention: `#D99000` +- informational detail: `#2F80ED` + +### Session Log Panel + +The log panel contains: + +- a title and one-line description +- a compact `Start / Stop` control on the title row +- a large log window +- a slim scrollbar + +The log window is white with a gray border. Log text is monospace. + +Log color mapping: + +- TX: `#2F80ED` +- RX: `#31A66A` +- SYS: `#7B8794` + +### Controls Panel + +The controls panel contains: + +- a title and one-line description +- a regular operation-card grid +- a reserved area at the bottom for future actions + +Operation cards should have consistent size, spacing, title alignment, and radius. + +Operation card color mapping: + +- primary operations: fill `#F3F8FF`, border `#2F80ED` +- normal query operations: fill `#FFFFFF`, border `#D5DDE5` +- attention operations: fill `#FFFBED`, border `#D99000` +- reserved/future area: fill `#FFFFFF`, border `#C9D1D9`, text `#52616F` + +## Visual Rules + +- Keep large surfaces white. +- Use gray borders to define structure. +- Use color only for semantics. +- Avoid gradients, decorative textures, and illustrated title icons. +- Avoid mixed corner radii in the same screen. +- Align section titles to the primary content edge. +- Keep controls in a predictable grid. +- Keep logs dense and scannable. diff --git a/docs/runtime_host_status_detail.svg b/docs/runtime_host_status_detail.svg new file mode 100644 index 0000000..3d8c188 --- /dev/null +++ b/docs/runtime_host_status_detail.svg @@ -0,0 +1,168 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + RuntimeHost Status + Service lifecycle, bind state, runtime snapshot + + + + BOUND + + + + Connection + Active + USB Ready + + + + Runtime State + Warm + Last ping 00:01.2 + + + + Health + 98% + No crash signal + + Updated 14:32:08 [SDK] + + + + + + + Session Log + Tx blue, Rx green, system purple + + + + + Start / Stop + + + + + 14:32:06.212 [TX] bind request sent + 14:32:06.438 [RX] ping => "pong" + 14:32:07.042 [SYS] state poll updated + 14:32:08.115 [RX] getHealthStateJson => {"ok":true} + 14:32:08.640 [TX] request warm start + 14:32:09.021 [SYS] log stream running + 14:32:09.302 [RX] runtime lifecycle => WARM + 14:32:09.618 [TX] getDebugSnapshotJson + 14:32:09.774 [RX] debug snapshot => 1.4 KB + 14:32:10.001 [SYS] snapshot cached + + + + + + + + + + + + + + Controls + Rounded grid buttons fill control card + + + + + Bind + Start bridge + session + + + + + Unbind + Close service + link + + + + + Ping + Check round + trip + + + + + + Runtime State + getRuntime + StateJson + + + + + Health + getHealth + StateJson + + + + + Debug + getDebug + SnapshotJson + + + + + + Lifecycle + getRuntimeLifecycle + StateJson + + + + + Warm Start + requestRuntime + WarmStart + + + + + + Room for future actions + without shrinking button grid + + + diff --git a/docs/wireframes/control-panel-main-wireframe.svg b/docs/wireframes/control-panel-main-wireframe.svg index c2a6794..514eb58 100644 --- a/docs/wireframes/control-panel-main-wireframe.svg +++ b/docs/wireframes/control-panel-main-wireframe.svg @@ -1,175 +1,170 @@ - + - + - kiwii-sdk-control-panel - AAR SDK validation control panel. Device components stay visible; unavailable components stay gray until capability detected. + kiwii-sdk-control-panel + AAR SDK validation control panel. Components stay visible; unavailable surfaces stay gray until detected. - - Global RuntimeHost Status - - Bound: false - - Ping: NOT_BOUND - Last API: none - Last error: waiting for RuntimeHost bind - - Bind - - Unbind - - Ping - RuntimeHost bound enables component detection; component availability is still per-device. + + Global RuntimeHost Status + RuntimeHost binding controls SDK access. Component availability remains detected per device. - - RuntimeHostStatusComponent - - Active - Always interactive; owns bind state refresh. - - Bind Host - - Runtime - - Health - - Lifecycle + + Bound: false + + Ping: NOT_BOUND + Last API: none + Last error: waiting for RuntimeHost bind - - CameraComponent - - Gray: not detected - Needs RuntimeHost bound + camera state available. - - Detect - - State - - Open Full Camera View + + Bind + + Unbind + + Ping - - LeftHandleComponent - - Gray: not detected - Needs left handle data. - - Detect - - IMU - - HE Static - - HE Stream + + RuntimeHostStatus + + Active + Always interactive. Owns bind, runtime, health, and lifecycle checks. + + Bind Host + + Runtime + + Health + + Lifecycle - - RightHandleComponent - - Gray: not detected - Needs right handle data. - - Detect - - IMU - - HE Static - - HE Stream + + Camera + + Gray: not detected + Requires RuntimeHost binding and camera state availability. + + Detect + + State + + Full Camera View - - BalanceBoardComponent - - Gray: not detected - Needs balance board data. - - Detect - - State - - Balance - - Telemetry + + Left Handle + + Gray: not detected + Requires left handle data before IMU and haptics are enabled. + + Detect + + IMU + + Haptics - - MotorComponent - - Gray: not detected - Needs motor state/control state. - - Detect - - Set Kg - - Set Mode - - State + + Right Handle + + Gray: not detected + Requires right handle data before IMU and haptics are enabled. + + Detect + + IMU + + Haptics - - TelemetrySafetyComponent - - Gray: bound - Available after RuntimeHost bound. - - Telemetry - - Safety - - Device Cmd - - Trace + + Balance Board + + Gray: not detected + Requires balance board data before telemetry views are enabled. + + Detect + + State + + Balance - - SessionLogComponent - - Active - Records all SDK calls. - - 16:27:00 bind() -> false - 16:27:05 camera.detect -> skipped + + Motor + + Gray: not detected + Requires motor state and motor control state. + + Detect + + Set Kg + + Mode - - CameraComponent Detail View - When CameraComponent is selected, user can open full camera preview without hiding device cards. - - Full Camera Preview - 16:9 frame, full visible image - - Camera State - - Refresh Frame - - Open Fullscreen - status: unavailable - reason: Host not bound + + Telemetry Safety + + Gray: bound + Available after RuntimeHost is bound. + + Telemetry + + Safety + + Device Cmd - - Selected Component Result - Latest call, params, status, return summary, error summary. - - selected=CameraComponent - call=detect - status=idle - result=waiting for RuntimeHost bind + + Session Log + + Active + Records SDK calls and skipped actions. + + 16:27:05 camera.detect -> skipped + + + CameraComponent Detail View + Selected camera detail keeps the component grid visible while showing a full preview and camera actions. + + Full Camera Preview + 16:9 frame, full visible image + + Camera State + + Refresh Frame + + Open Fullscreen + status: unavailable + reason: Host not bound + + + Selected Component Result + Latest call, params, status, result, and error summary. + + selected=CameraComponent + call=detect + status=idle + result=waiting for RuntimeHost bind + + 16:27:00 bind() -> false + 16:27:05 camera.detect -> skipped + 16:27:08 motor.detect -> skipped