edison/chanora
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add baseline references and workspace tasks

Browse Source
This commit is contained in:
Edison Jwa
2026-05-23 06:52:24 +09:00
parent 7d5d8c2c90
commit 3200312b0d
5 changed files with 8017 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/additional_docs/material3-guideline.md
+93
View File
@@ -0,0 +1,93 @@
# Chanora UI/UX Guideline — Material 3 Baseline
**Version:** 0.9.2
**Status:** Baseline Candidate
**Language:** English
**Lifecycle support:** Supports SysDes, SRS, SAD, SDD, and Verification
**Design baseline:** Material 3 + Chanora Design System
**Repo path:** `docs/ui-ux/material3-guideline.md` ---
## 1. Purpose
This guideline defines the UI and UX baseline for the Chanora Flutter application. Chanora shall use Material 3 as the foundation, but product-specific voice, channel, connection, latency, diagnostics, platform, and accessibility semantics shall be expressed through Chanora Design System components and tokens.
## 2. Core UI Principles
| Principle | Requirement |
|---|---|
| Voice-first control | Mute, deaf, push-to-talk, current channel, and input status must be visible or directly reachable. |
| Connection awareness | Connected, connecting, reconnecting, disconnected, and error states must be visible. |
| Adaptive layout | Layout must adapt by window class rather than hardcoding behavior by platform name. |
| Accessibility baseline | Critical controls must have semantics, focus behavior, text scaling support, and non-color-only status expression. |
| Platform respect | Permission, safe area, keyboard, back, haptic, and audio-route behavior must follow platform expectations. |
| Localization-ready | Product-owned strings must be localized; server-provided content must be displayed as content. |
## 3. Primary Screens
| Screen | Stage | Purpose |
|---|---|---|
| Home | P0 | Recent servers, bookmarks, manual connect entry |
| Connect | P0 | Host, port, nickname, password, identity selection |
| Server | P0 | Channel tree, clients, connection status, current channel |
| Voice | P0 | Voice controls, input level, device summary |
| Chat | P1 | Channel text messages |
| Settings | P0 | Audio, UI, localization, platform behavior, shortcuts |
| Diagnostics | P0 | Status, redacted export, troubleshooting information |
## 4. Interaction Rules
| Area | Rule |
|---|---|
| Channel tree | Select, expand/collapse, join, context menu, keyboard traversal |
| Client tile | Show speaking, mute/deaf, volume, latency when available |
| Voice controls | Must be reachable with touch, mouse, and keyboard |
| Diagnostics | Export must require explicit user action and show redaction notice |
| Settings | Destructive or permission-changing actions require clear confirmation or explanation |
| Text entry | Chat input must respect IME and keyboard safe areas |
## 5. Motion Rules
| Scenario | Allowed behavior |
|---|---|
| Page transition | Minimal fade or shared-axis style transition |
| Speaking indicator | Subtle pulse, disabled or simplified under reduced motion |
| Reconnect banner | Clear state transition without disruptive animation |
| Layout change | Resize/reflow smoothly where possible |
| Error state | Immediate, clear, non-color-only feedback |
## 6. Accessibility Rules
| Rule | Baseline |
|---|---|
| Minimum target | Critical controls should meet a 48dp target where practical. |
| Semantics | Icon-only controls require labels. |
| Focus | Desktop and tablet keyboard use require visible focus. |
| State expression | Critical states require more than color. |
| Text scale | Critical controls remain reachable under increased text size. |
| Reduced motion | Non-essential animation is reduced or disabled. |
## 7. Internationalization UX
Product strings are localized. Server-provided server names, channel names, nicknames, and messages are not translated. Mixed-language and bidirectional text must be rendered as text content and preserved through diagnostics unless redacted.
## 8. Change History
| Version | Date | Description |
|---|---|---|
| 0.1.0 | 2026-05-14 | Initial UI/UX guideline for Material 3, adaptive layout, accessibility, platform behavior, and i18n. |
## Baseline Candidate 0.9.1 Update
| Version | Date | Description |
|---|---|---|
| 0.9.1 | 2026-05-14 | Updated baseline after product decision closure: Apple App Store SDK gate uses Xcode 26+ and iOS 26 / iPadOS 26 SDK+ since 2026-04-28, platform baselines and decision traceability propagated across the document set. |
## Baseline Candidate 0.9.2 Update
| Version | Date | Description |
|---|---|---|
| 0.9.2 | 2026-05-14 | Corrected Apple App Store Connect upload gate to 2026-04-28 and checked full-package naming, references, and coverage. |
docs/additional_docs/srs.md
+2850
View File
File diff suppressed because it is too large Load Diff
docs/additional_docs/sysdes.md
+3047
View File
File diff suppressed because it is too large Load Diff
docs/additional_docs/sysrs.md
+2007
View File
File diff suppressed because it is too large Load Diff
justfile
+20 -36
View File
@@ -2,9 +2,7 @@
#
# Conforms to docs/governance/repository-bootstrap-plan.md v0.1.0 §3,
# which requires a `justfile` with stubs for format / lint / test /
# verify-docs / security-scan. The repository is documentation- and
# PoC-first; until the product Flutter/Rust workspace exists, most
# targets are placeholders.
# verify-docs / security-scan.
#
# Install just: https://github.com/casey/just
@@ -25,16 +23,10 @@ verify-docs:
# Format every codebase in the repo that has a formatter wired up.
format:
@echo "[format] Rust PoCs"
@for d in poc/*/; do \
if [ -f "$$d/Cargo.toml" ]; then \
(cd "$$d" && cargo fmt --all) || exit 1; \
fi; \
done
@if [ -d poc/flutter_rust_bridge_hello ]; then \
echo "[format] Flutter PoC"; \
(cd poc/flutter_rust_bridge_hello && dart format lib test integration_test rust/src) || exit 1; \
fi
@echo "[format] Rust workspace"
cargo fmt --package chanora_audio --package chanora_bridge --package chanora_core --package chanora_diagnostics --package chanora_protocol --package chanora_state --package chanora_storage
@echo "[format] Flutter app"
cd apps/chanora_flutter && dart format lib test
# ---------------------------------------------------------------------------
# Lint
@@ -42,38 +34,30 @@ format:
# Run linters on every codebase that has them wired up.
lint:
@echo "[lint] Rust PoCs"
@for d in poc/*/; do \
if [ -f "$$d/Cargo.toml" ]; then \
(cd "$$d" && cargo clippy --all-targets -- -D warnings) || exit 1; \
fi; \
done
@if [ -d poc/flutter_rust_bridge_hello ]; then \
echo "[lint] Flutter PoC"; \
(cd poc/flutter_rust_bridge_hello && flutter analyze) || exit 1; \
fi
@echo "[lint] Rust workspace"
cargo clippy --workspace --all-targets --all-features -- -W clippy::all
@echo "[lint] Flutter app"
cd apps/chanora_flutter && flutter analyze
# ---------------------------------------------------------------------------
# Test
# ---------------------------------------------------------------------------
# Run all PoC test suites that have one.
# Run local test suites. Live/network tests remain explicitly ignored.
test:
@echo "[test] tsclientlib-connect-spike: build only (live-server smoke must be run manually)"
@(cd poc/tsclientlib-connect-spike && cargo build --release)
@echo "[test] flutter_rust_bridge_hello: headless verification"
@(cd poc/flutter_rust_bridge_hello && \
flutter build linux --debug && \
LD_LIBRARY_PATH="$$PWD/build/linux/x64/debug/bundle/lib:$$LD_LIBRARY_PATH" \
flutter test test/poc_verification_test.dart)
@echo "[test] Rust workspace"
cargo test --workspace --all-targets --all-features
@echo "[test] Flutter app"
cd apps/chanora_flutter && flutter test
# ---------------------------------------------------------------------------
# Security scan
# ---------------------------------------------------------------------------
# Placeholder — real security scanning will be wired up when the product
# workspace exists. See docs/security/dependency-and-supply-chain-report.md
# and docs/governance/repository-bootstrap-plan.md §5.
# Run the local dependency audit when cargo-audit is installed.
security-scan:
@echo "[security-scan] placeholder — no product workspace yet."
@echo "[security-scan] documentation gates live under docs/security/"
@if command -v cargo-audit >/dev/null 2>&1; then \
cargo audit; \
else \
echo "[security-scan] cargo-audit not installed; run: cargo install cargo-audit"; \
fi