From 2bbd97ac793a70c0c91bf25f6a2c41bb247c03e2 Mon Sep 17 00:00:00 2001 From: vincentadamnemessis Date: Thu, 13 Aug 2026 10:05:19 +0800 Subject: [PATCH 01/15] docs(windows): freeze UIOS research and design contract --- .ui-os/design/DIRECTIONS.md | 85 + .ui-os/design/DISCOVERY.md | 78 + .ui-os/design/FROZEN_CONTRACT.md | 109 + .ui-os/design/WIREFRAMES.md | 79 + .../baseline/windows-runtime-boundary.json | 24 + .ui-os/evidence/manifest.json | 20 + .ui-os/flows.json | 148 + .ui-os/project.json | 32 + .ui-os/research-task-windows.json | 85 + ...ndows-winui3-standard-20260813-review.json | 13 + .../manifest.json | 804 +++++ .../objects/balena-etcher-fcc7a0c1e178.html | 986 ++++++ .../objects/fluent-motion-42ab4dc9afb2.html | 379 ++ ...ithub-desktop-onboarding-7567553258da.html | 944 +++++ ...s-accessibility-overview-16e36128ea2b.html | 1673 +++++++++ .../objects/ms-file-picker-e528f24783d9.html | 1865 ++++++++++ .../ms-navigationview-6d9beff44ebb.html | 3051 +++++++++++++++++ .../ms-progress-controls-46c7ddeaae35.html | 1704 +++++++++ .../ms-ui-settings-motion-5b2413221dc1.html | 1521 ++++++++ .../pattern-intelligence-brief.md | 108 + .../task-context.json | 89 + .ui-os/tokens.json | 55 + 22 files changed, 13852 insertions(+) create mode 100644 .ui-os/design/DIRECTIONS.md create mode 100644 .ui-os/design/DISCOVERY.md create mode 100644 .ui-os/design/FROZEN_CONTRACT.md create mode 100644 .ui-os/design/WIREFRAMES.md create mode 100644 .ui-os/evidence/baseline/windows-runtime-boundary.json create mode 100644 .ui-os/evidence/manifest.json create mode 100644 .ui-os/flows.json create mode 100644 .ui-os/project.json create mode 100644 .ui-os/research-task-windows.json create mode 100644 .ui-os/research/reviews/windows-winui3-standard-20260813-review.json create mode 100644 .ui-os/research/runs/windows-winui3-standard-20260813/manifest.json create mode 100644 .ui-os/research/runs/windows-winui3-standard-20260813/objects/balena-etcher-fcc7a0c1e178.html create mode 100644 .ui-os/research/runs/windows-winui3-standard-20260813/objects/fluent-motion-42ab4dc9afb2.html create mode 100644 .ui-os/research/runs/windows-winui3-standard-20260813/objects/github-desktop-onboarding-7567553258da.html create mode 100644 .ui-os/research/runs/windows-winui3-standard-20260813/objects/ms-accessibility-overview-16e36128ea2b.html create mode 100644 .ui-os/research/runs/windows-winui3-standard-20260813/objects/ms-file-picker-e528f24783d9.html create mode 100644 .ui-os/research/runs/windows-winui3-standard-20260813/objects/ms-navigationview-6d9beff44ebb.html create mode 100644 .ui-os/research/runs/windows-winui3-standard-20260813/objects/ms-progress-controls-46c7ddeaae35.html create mode 100644 .ui-os/research/runs/windows-winui3-standard-20260813/objects/ms-ui-settings-motion-5b2413221dc1.html create mode 100644 .ui-os/research/runs/windows-winui3-standard-20260813/pattern-intelligence-brief.md create mode 100644 .ui-os/research/runs/windows-winui3-standard-20260813/task-context.json create mode 100644 .ui-os/tokens.json diff --git a/.ui-os/design/DIRECTIONS.md b/.ui-os/design/DIRECTIONS.md new file mode 100644 index 0000000..768f837 --- /dev/null +++ b/.ui-os/design/DIRECTIONS.md @@ -0,0 +1,85 @@ +# Windows Standard design directions + +Both directions consume the independently reviewed task-time research run `windows-winui3-standard-20260813` and preserve the same shared product kernel, action identities, state scopes, confirmation, fingerprints, backup, manifest, and rollback behavior. They differ in structure, not palette. + +## Direction A — Guided Fluent workspace (selected) + +**Shape:** one WinUI `NavigationView` owns application destinations. Convert owns a bounded four-step task whose current step is rendered in one work surface with a persistent command footer. + +```text +NavigationView Convert content +Conversion Step 1 of 4 — Input + Convert save [mode] [slot] +Records [3DS source selected-path row] + History [current reference in Repair] +Advanced [output selected-path row] + Experimental CEC [technical details disclosure] +Application -------------------------------- + Settings status/reason + Fix [Inspect] +``` + +### Full flow + +1. **Input** — choose source, optional read-only current reference, and output; Inspect is the sole primary action. +2. **Optional Data** — all domains are off by default. Enabling a domain reveals only its required paths and independent actions. **Skip optional data** removes only optional intent; **Continue to Dry Run** never requires optional configuration. +3. **Dry Run** — a Ready/Needs action list explains the exact core transaction. The sole primary action is **Run Dry Run**. A blocker sits in the footer with one local Fix. +4. **Write / Result** — authorized fingerprints lead to native `ContentDialog` confirmation. Running feedback stays local with stable CTA geometry. Success/failure shows report and rollback without false success. +5. **History** — current-session history only; empty state offers **Start conversion** and never hosts conversion blockers. +6. **Experimental CEC** — isolated advanced route with its own acknowledgement and transaction sequence. +7. **Settings** — language, CLI fallback, update checking and accessibility/motion diagnostics; no conversion blocker. + +### Expert path + +- Windows standard Tab/Shift+Tab order follows task order. +- `Alt` access keys are attached to frequent route/primary commands where WinUI supports them. +- Enter/Space activates focused commands; Escape cancels confirmation and returns focus to the invoker. +- No keyboard shortcut bypasses Inspect, Dry Run, expected-hash binding, confirmation, or rollback evidence. + +### Why selected + +- Most legible at the 920×600 minimum and at increased text scale. +- Separates application navigation from ordered transaction progress. +- Makes the disabled reason, Fix, and current primary action one stable local unit. +- Keeps first-time guidance while progressive disclosure protects expert density. +- Maps directly to native `NavigationView`, `InfoBar`, `Expander`, picker, progress and dialog primitives. + +## Direction B — Compact operation canvas (rejected) + +**Shape:** the same app `NavigationView`, but Convert presents a persistent source/current/output comparison canvas with a right-side transaction inspector and collapsible task sections. + +```text +NavigationView Source / current / output Transaction inspector +Convert [path summary rows] status + next action +History [Inspect details] Dry Run evidence +CEC [Optional details] Write / rollback +Settings +``` + +### Full flow + +- Users can inspect or replace any selected input without moving between steps. +- Optional System/ExtData attach beneath their related source/target row. +- Dry Run, write confirmation, result and recovery stay in the transaction inspector. +- History may reopen a previous session result into the inspector without mutating inputs. + +### Why rejected + +- At minimum width or 150–200% text scale the comparison and inspector compete, forcing either horizontal compression or a long stacked canvas. +- First-time users must understand the source/current/output topology before seeing a single next action. +- Persistent transaction inspector risks duplicating state already present at the affected input or result surface. +- It is faster for expert repeated repair, but that efficiency does not outweigh weaker first-run clarity for this Pilot. + +## Decision matrix + +| Criterion | A Guided Fluent workspace | B Compact operation canvas | +| --- | ---: | ---: | +| Five-second task clarity | 5 | 3 | +| Information hierarchy | 5 | 4 | +| Minimum-window behavior | 5 | 3 | +| Windows native fit | 5 | 4 | +| Keyboard/focus predictability | 5 | 4 | +| Text scaling / zh-Hans | 5 | 3 | +| Scoped recovery | 5 | 4 | +| Expert repeat efficiency | 4 | 5 | +| Cross-screen consistency | 5 | 4 | + diff --git a/.ui-os/design/DISCOVERY.md b/.ui-os/design/DISCOVERY.md new file mode 100644 index 0000000..d0d8f3f --- /dev/null +++ b/.ui-os/design/DISCOVERY.md @@ -0,0 +1,78 @@ +# Windows UI Quality OS discovery + +## Verified repository baseline + +- Repository: `MHToolkit/mh-save-sync`. +- Isolated worktree: `/Volumes/GameHub/Development/Games/mh-save-sync-windows-ui-quality-os`. +- Feature branch: `feat/mh3g-windows-ui-quality-os`. +- Baseline: `origin/main` at `b3d58f70aa713b5e7f0ba7397d745b7166925547` (`v0.0.18`). +- Target stack: unpackaged **WinUI 3**, .NET 8, Windows App SDK `1.8.260710003`, Windows 10 1809 minimum, x64 self-contained packaging. +- Backend boundary: the existing C# presentation invokes the bundled Rust CLI as independent argv elements. Rust remains authoritative for inspection, dry-run authorization, expected hashes, transactional write, manifest, backup, and rollback. + +## Runtime baseline status + +A downloaded portable executable exists at `/Users/vincentadamnemessis/Downloads/MH3GSaveConverter-Portable-x64.exe`, but it is an older, provenance-uncertain artifact (timestamp 2026-08-01; embedded assembly version `1.0.0.0`) and is not tied to the current `v0.0.18` source hash. This macOS host has no active Windows VM or native Windows runner. Previous GameHub execution was already reported unusable and is not repeated. + +Therefore **current Windows runtime baseline screenshots, UI Automation tree, focus traversal, High Contrast, text scaling, and animation evidence are BLOCKED/UNVERIFIED**. The Pilot may improve source, fixtures, source-level gates and Windows CI capture support here, but must not label cross-compilation or static XAML inspection as Windows runtime proof. + +## Existing surface inventory + +The current app is one 1,240×900 `ScrollViewer` containing the entire product: + +- fixed top brand/status/language strip; +- a large illustrated hero and a four-item visual stage strip; +- five post-operation `InfoBar` continuations; +- source/current/output/CLI controls; +- Inspect, progress inspection, event inspection, Dry Run, Write, rollback; +- shared `system`, ExtData, CEC, latest report, and operation history; +- 43 buttons, 16 text boxes, 8 InfoBars, 104 text blocks, 28 hard-coded ARGB colors; +- no `NavigationView`, no `Expander`, no stable `AutomationId`, and no deterministic UI fixture launch contract. + +The `StageArtwork` control swaps among five raster images and overlays a second stage presentation. Hard-coded light surfaces and text colors bypass theme and High Contrast resources. A single long surface means task scope, utility scope, history, status, and recovery compete vertically. + +## Baseline problems to solve + +1. **No primary navigation:** core conversion, optional transactions, CEC, history, report, update, and rollback are stacked into one document. +2. **Repeated state/navigation:** top status, hero stage labels, stage artwork, InfoBars, section copy, and action availability all describe the same progression. +3. **Primary action distance:** Inspect, Dry Run, Write, rollback, and their explanations live in different columns or far-apart vertical regions; the correct next action is not stable at the first screen. +4. **Optional-data contradiction:** `SelectedOptionalDataIsConfigured` currently disables core Dry Run and Write whenever an enabled optional domain is incomplete. This makes “optional” a global core blocker. +5. **Scope leakage risk:** all global InfoBars and optional controls share one root surface, so unrelated history/report/settings content has no structural boundary from optional warnings. +6. **Repair path cognitive load:** source, read-only current reference, output, version detection, and CLI path appear as one uninterrupted technical form. +7. **Technical detail dominance:** CLI path, hashes/reports/manifests, file topology and transaction implementation remain in primary reading order. +8. **Theme/accessibility debt:** hard-coded colors, missing stable AutomationIds, no explicit minimum-size contract, no deterministic keyboard/High Contrast/text-scale fixture coverage. +9. **Decorative displacement:** the hero and stage artwork consume the highest-value area but do not select a step, fix a blocker, or authorize a transaction. +10. **No causal motion contract:** stage artwork transitions exist, but async action acknowledgement, local dependency reveal, selected-path confirmation, and reduced-motion equivalents are undefined. + +## Shared product kernel + +The Windows profile must preserve the already established cross-client task semantics: + +`Select source / read-only current reference / output → Inspect → configure or skip Optional Data → Dry Run → Confirm Write → Result / Rollback` + +- New conversion omits the current-reference input. +- Repair keeps source, current reference, and output as three independent roles. +- Optional transactions are opt-in and independently authorized; skipping them never weakens or blocks core conversion. +- Experimental CEC remains an advanced, independently acknowledged transaction. +- No fixture may execute the CLI, touch a real save, or report a synthetic write as real success. + +## Delete / merge before adding + +| Delete or merge | Windows destination / reason | +| --- | --- | +| Large hero and `StageArtwork` | Remove from operational flow. Keep only a compact product mark and, if useful, one small non-interactive empty-state vector. | +| Four visual stage labels | Replace with one bounded step indicator inside Convert; it communicates location but is not a second app navigator. | +| Top status badge and five global continuation InfoBars | Render state once at the narrowest affected surface; put the next action in a persistent task footer. | +| One giant ScrollViewer | Use a native grouped `NavigationView`: Convert, History, Experimental CEC, Settings. | +| Dry Run/Write side card plus remote reasons | One current-step surface; disabled CTA has one adjacent reason and executable Fix. | +| Always-visible CLI path | Move to Settings/technical disclosure; bundled sidecar remains the default. | +| Raw report/hash/manifest in primary order | Move to `Expander`/dialog technical details except confirmation and recovery-critical evidence. | +| Global optional readiness gate | Scope incomplete optional paths to that component only; core Inspect/Dry Run/Write stay independent. | +| Raster control-like artwork | Use licensed WinUI `SymbolIcon`/font glyphs for interaction and theme-aware vectors for any retained empty-state illustration. | + +## Baseline machine evidence + +- `scripts/verify-mh3g-save-converter-windows-source.py`: PASS on baseline. +- `cargo test -p mh3g-save-convert`: 220 passed on baseline. +- `cargo clippy -p mh3g-save-convert --all-targets -- -D warnings`: PASS on baseline. +- macOS `dotnet build --no-restore`: expectedly failed because the isolated worktree had no restored Windows-target assets; this is environment evidence, not a product regression. + diff --git a/.ui-os/design/FROZEN_CONTRACT.md b/.ui-os/design/FROZEN_CONTRACT.md new file mode 100644 index 0000000..a4c6b01 --- /dev/null +++ b/.ui-os/design/FROZEN_CONTRACT.md @@ -0,0 +1,109 @@ +# Frozen Windows UI contract v0.1 — Guided Fluent workspace + +Status: **frozen for candidate implementation**. Research receipt: `../research/reviews/windows-winui3-standard-20260813-review.json` (`pass`). Material IA, visual-language, state-meaning, or motion-intent changes require a new contract revision and fresh review; implementation must not silently accept a new baseline. + +## Shared kernel invariants + +1. The product task remains `source / read-only current reference / output → Inspect → optional configure or skip → Dry Run → Confirm Write → Result / Rollback`. +2. New conversion uses source and output. Repair uses three independent roles: original 3DS source, current Wii U/Cemu reference (read-only), and separate output. +3. App navigation has exactly four grouped destinations: Convert, History, Experimental CEC, Settings. +4. Convert is one bounded four-step task: Input, Optional Data, Dry Run, Write/Result. Progress is not a second app navigator. +5. Each current task surface has one page title, one scoped state presentation, and one primary action. +6. The primary action remains in the first viewport at 1,120×760 and 920×600. If disabled, one adjacent plain-language reason and one executable Fix appear in the same footer host. +7. Optional data is opt-in and independently authorized. An incomplete optional domain blocks only its own Dry Run/write. It never blocks core Inspect, core Dry Run, or core write. +8. History and Settings never render `optional.missing-path` or another conversion blocker. +9. Experimental CEC remains independent, experimental, acknowledged, dry-run authorized, hash-bound, confirmed, backed up, manifested and reversible. +10. Rust CLI argv, JSON status, fingerprints, expected hashes, output-absence intent, transaction manifests, backups, confirmations and rollback are authoritative and fail closed. +11. Fixtures cannot invoke the CLI, read real saves, create targets, or claim a real write. Synthetic success is clearly marked as preview-only evidence. + +## Windows profile mapping + +- `NavigationView` owns application routes. Its native back/navigation semantics are not used to skip transaction gates. +- Use WinUI Button, ToggleSwitch, CheckBox, ComboBox, TextBox, InfoBar, Expander, ProgressBar, ContentDialog, FileOpenPicker and FolderPicker. +- Controls use WinUI `SymbolIcon`/licensed vector glyphs plus localized labels; interaction icons are never rasterized text. +- Work surfaces use theme resources and an explicit High Contrast resource dictionary. Hard-coded light-only foreground/background colors are forbidden. +- Default width is 1,120 and minimum is 920×600. The active content reflows to one column before clipping. +- XAML/task order defines logical Tab order. Primary and local Fix controls expose stable AutomationId and Name; scoped state uses one polite live region. +- Paths may visually ellipsize only while UI Automation retains the complete value and role. + +## Information hierarchy and plain copy + +1. Page title and one-sentence task purpose. +2. Current-step progress and scoped readiness. +3. Required controls and selected-path summaries. +4. Current primary command plus adjacent reason/Fix. +5. Technical details disclosure for CLI path, hashes, reports, version detection and manifests. + +Preferred role labels: + +- `3DS source` +- `Current Wii U reference (read-only)` +- `Output` +- `Optional data` +- `Skip optional data` +- `Dry Run checks these exact files without writing.` + +## Stable semantic IDs + +- Routes: `mh3g.converter.windows.navigation.{convert,history,experimentalCEC,settings}`. +- Titles: `mh3g.converter.windows.page.{input,optionals,dryRun,writeResult,history,experimentalCEC,settings}.title`. +- Primary actions: `mh3g.converter.windows.action.{inspect,continueOptionals,runDryRun,confirmWrite,startConversion}`. +- Local actions: `mh3g.converter.windows.action.{fixOptional,skipOptional,chooseSource,chooseCurrent,chooseOutput,rollback}`. +- State: `mh3g.converter.windows.state.{inputMissing,optionalMissing,optionalSkipped,dryRunReady,dryRunBlocked,writeAuthorized,running,success,failure,historyEmpty}`. +- Path rows: `mh3g.converter.windows.path.{source,current,output,systemSource,systemTarget,extdataSource,extdataTarget,cecSource,cecTarget}`. + +## Deterministic fixture contract + +Launch fixtures are opt-in through explicit `--ui-fixture ` / `MH3G_UI_FIXTURE` parsing before the window is created: + +- `first-run` +- `input.empty` +- `components.optional-missing` +- `components.optional-skipped` +- `dry-run.ready` +- `dry-run.blocked` +- `write.authorized` +- `write.confirmation` +- `conversion.success` +- `conversion.failure` +- `history.empty` +- `history.result` + +Every fixture uses a fixed seed and synthetic `C:\UIFixture\...` presentation paths. No fixture may call `ConverterCliClient` or `FileFingerprintService`, and no destructive dialog fixture may accept its primary action. + +## Motion contract + +| Seam | Purpose / frequency | Windows behavior | Reduced motion | Evidence | +| --- | --- | --- | --- | --- | +| Inspect/Dry Run/Write starts | Immediate receipt; occasional | CTA frame remains fixed; local text/state changes immediately and native indeterminate `ProgressBar` appears | Same text and progress semantics; no custom motion | state trace + normal/reduced terminal frames | +| Optional enabled | Relate toggle to dependent fields; occasional | Short interruptible local opacity/content transition, no whole-page movement | Immediate reveal/collapse | state trace + focus order | +| Picker returns | Confirm cause/effect; frequent | Path row updates in place and retains/reclaims focus; no toast | Immediate update | interaction trace + UIA value | +| Blocked → ready → authorized/result | Clarify state progression; occasional | Fixed footer host changes icon/text/surface over one short native transition | Immediate static replacement | transition trace + final screenshots | +| Success | Rare completion | One bounded check/status transition; never loops | Immediate check/status | bounded trace + terminal frame | + +Custom motion is permitted only when `Windows.UI.ViewManagement.UISettings.AnimationsEnabled` is true. No page slide, navigation delay, form stagger, hover lift/scale, shimmer, confetti, failure shake, flash, or looping empty-state motion. + +## Required responsive/state matrix + +Critical coverage on a native Windows runner: + +- 1,120×760 default and 920×600 minimum; +- Light, Dark, High Contrast; +- English and zh-Hans; +- 100%, 150%, and critical 200% text scaling cells; +- pointer and full keyboard path; +- normal and disabled animation preference; +- input empty, optional missing/skipped, Dry Run ready/blocked/running, write authorized/confirmation/running, success/failure, history empty/result, recovery. + +## Acceptance gates + +- 0 duplicate primary navigation. +- 0 optional blocker instances on History or Settings. +- 0 critical clipping, overlap, inaccessible action, or focus trap in required native Windows cells. +- One primary action per current task surface. +- Disabled primary action has one adjacent reason and executable Fix. +- UI Automation identifiers are unique and stable. +- Accessibility critical findings: 0. +- Motion normal/reduced traces preserve identical state meaning and stable primary-action geometry. +- Machine, independent AI, Windows runtime, and human/task verdicts remain separate. Human stays pending until a real target user completes the task. + diff --git a/.ui-os/design/WIREFRAMES.md b/.ui-os/design/WIREFRAMES.md new file mode 100644 index 0000000..e987442 --- /dev/null +++ b/.ui-os/design/WIREFRAMES.md @@ -0,0 +1,79 @@ +# Frozen direction wireframes + +These text wireframes define structure and hierarchy, not pixels. Runtime WinUI remains authoritative. + +## Input + +```text +┌ Navigation ┐ Input & inspection Step 1 of 4 +│ Convert │ Choose the exact files for this conversion. +│ History │ +│ CEC │ Mode [New conversion ▼] Slot [user2 ▼] +│ Settings │ +└────────────┘ 3DS source + [No source selected ] [File] [Folder] + + Output + [No output selected ] [File] [Folder] + + Technical details ▸ + ───────────────────────────────────────────────── + Choose a source and output to continue. [Inspect] +``` + +## Optional missing + +```text +Optional data Step 2 of 4 +Core conversion does not require optional data. + +[on] Shared system + Source [not selected] [Choose] + Target [not selected] [Choose] + ⚠ Shared system needs both paths. [Choose paths] + +[off] Guild cards / quests + +────────────────────────────────────────────────────────────── +Optional paths affect only this component. [Skip optional data] [Continue] +``` + +## Dry Run blocked / ready + +```text +Dry Run Step 3 of 4 +Checks the exact core files without writing. + +✓ 3DS source inspected +✓ Output intent inspected +! Original converter version has multiple candidates + +────────────────────────────────────────────────────────────── +Choose one detected version, then try again. [Choose version] [Run Dry Run] +``` + +## Write confirmation / result + +```text +Write & result Step 4 of 4 +✓ Dry Run authorized these exact files + +Source / current / output summary +Technical hash details ▸ + +────────────────────────────────────────────────────────────── +Authorization is current. [Confirm write] + +ContentDialog: target + fingerprint + backup + manifest + Cancel / Write + +Result: ✓ completed | ✕ failed, report ▸, manifest, Roll back +``` + +## History empty + +```text +History +No transactions in this app session. +Start with an explicit source and output; nothing is scanned automatically. +[Start conversion] +``` diff --git a/.ui-os/evidence/baseline/windows-runtime-boundary.json b/.ui-os/evidence/baseline/windows-runtime-boundary.json new file mode 100644 index 0000000..87066e3 --- /dev/null +++ b/.ui-os/evidence/baseline/windows-runtime-boundary.json @@ -0,0 +1,24 @@ +{ + "schema": "mh3g.windows-ui-baseline-boundary/v1", + "source_revision": "b3d58f70aa713b5e7f0ba7397d745b7166925547", + "target": "windows-winui3-x64", + "host": "macos-arm64", + "runtime_status": "blocked-unverified", + "reason": "No active native Windows runner or VM is available. A local portable executable is older and not provenance-bound to the current source, and previously reported GameHub execution is not repeated.", + "source_hashes": { + "MainWindow.xaml": "f1960aa4ff0011aa800aace184056cd9ae6b078458753688384484001a75535a", + "MainWindow.xaml.cs": "20abbbfa32310779623df5ef3c5134d519db912b97962490dbf12657d64948c7", + "MainViewModel.cs": "7d0f2fa7bd5e9492f1abc9b8af2dd01235cbdbb414da92f652b4856ca297fa96" + }, + "unverified": [ + "current default-window screenshot", + "minimum-window screenshot", + "UI Automation tree", + "keyboard focus traversal", + "screen reader", + "text scaling", + "High Contrast", + "normal and reduced motion", + "artifact startup" + ] +} diff --git a/.ui-os/evidence/manifest.json b/.ui-os/evidence/manifest.json new file mode 100644 index 0000000..4511f1f --- /dev/null +++ b/.ui-os/evidence/manifest.json @@ -0,0 +1,20 @@ +{ + "schema_version": "uios.evidence/v0.1", + "project": { + "id": "mh3g-save-converter", + "revision": "b3d58f70aa713b5e7f0ba7397d745b7166925547", + "dirty": true + }, + "inputs": { + "contract_sha256": "09638a4326d67ff8d8fc1340ba11d2b8390c3a78710eb60c816de9b91a8d6567", + "flows_sha256": "549013ee5054b5725604503c23e71fae48196f4d552d862f3f83a59db438f2dc", + "tokens_sha256": "37e36f1a4757ffa9b8a6861759fcce18baded0a54ef5dc6e4209182793a166c3" + }, + "cells": [], + "verdicts": { + "machine": "pending", + "independent_ai": "pending", + "human": "pending", + "release": "blocked" + } +} diff --git a/.ui-os/flows.json b/.ui-os/flows.json new file mode 100644 index 0000000..a900cd1 --- /dev/null +++ b/.ui-os/flows.json @@ -0,0 +1,148 @@ +{ + "schema_version": "uios.flows/v0.1", + "flows": [ + { + "id": "conversion.new", + "entry": "User starts a new conversion with no local save modified", + "success": "The selected output slot is transactionally written and a backup plus manifest is available", + "actions": [ + "conversion.select-source", + "conversion.select-output", + "conversion.inspect", + "conversion.configure-optionals", + "conversion.skip-optionals", + "conversion.run-dry-run", + "conversion.confirm-write", + "conversion.review-result", + "conversion.rollback" + ] + }, + { + "id": "conversion.repair", + "entry": "User has an original 3DS slot, a read-only current Wii U reference, and an explicit separate output", + "success": "Eligible historical conversion fields are repaired while later Wii U progress is retained and transaction evidence is produced", + "actions": [ + "conversion.select-source", + "conversion.select-current-reference", + "conversion.select-output", + "conversion.inspect", + "conversion.configure-optionals", + "conversion.skip-optionals", + "conversion.run-dry-run", + "conversion.choose-history-version", + "conversion.confirm-write", + "conversion.review-result", + "conversion.rollback" + ] + }, + { + "id": "optional.standard", + "entry": "User explicitly enables system, guild-card, or quest migration", + "success": "Each selected optional transaction is independently previewed, authorized, written, and recoverable", + "actions": [ + "conversion.configure-optionals", + "optional.fix-paths", + "conversion.skip-optionals", + "optional.run-dry-run", + "optional.confirm-write", + "conversion.review-result", + "conversion.rollback" + ] + }, + { + "id": "utility.cec", + "entry": "Advanced user opens Experimental CEC and explicitly acknowledges its risk", + "success": "The exact CEC mailbox and cache are independently dry-run, written, and recoverable", + "actions": [ + "cec.select-mailbox", + "cec.select-cache", + "cec.acknowledge", + "cec.run-dry-run", + "cec.confirm-write", + "conversion.rollback" + ] + } + ], + "states": [ + { + "id": "input.missing", + "scope": "control", + "severity": "warning", + "blocks": ["conversion.inspect"], + "recovery": ["conversion.select-source", "conversion.select-output"], + "presentation": {"allowed_hosts": ["conversion.input"], "max_primary_instances": 1, "global_banner": "forbidden"} + }, + { + "id": "optional.missing-path", + "scope": "section", + "severity": "warning", + "blocks": ["optional.run-dry-run", "optional.confirm-write"], + "recovery": ["optional.fix-paths", "conversion.skip-optionals"], + "presentation": {"allowed_hosts": ["conversion.optionals", "conversion.write.optionals"], "max_primary_instances": 1, "global_banner": "forbidden"} + }, + { + "id": "optional.skipped", + "scope": "section", + "severity": "info", + "blocks": [], + "recovery": ["conversion.configure-optionals"], + "presentation": {"allowed_hosts": ["conversion.optionals", "conversion.review"], "max_primary_instances": 1, "global_banner": "forbidden"} + }, + { + "id": "dry-run.blocked", + "scope": "surface", + "severity": "warning", + "blocks": ["conversion.run-dry-run", "conversion.confirm-write"], + "recovery": ["conversion.inspect", "conversion.choose-history-version"], + "presentation": {"allowed_hosts": ["conversion.review"], "max_primary_instances": 1, "global_banner": "forbidden"} + }, + { + "id": "dry-run.ready", + "scope": "surface", + "severity": "success", + "blocks": [], + "recovery": ["conversion.run-dry-run"], + "presentation": {"allowed_hosts": ["conversion.review"], "max_primary_instances": 1, "global_banner": "forbidden"} + }, + { + "id": "write.authorized", + "scope": "surface", + "severity": "success", + "blocks": [], + "recovery": ["conversion.confirm-write"], + "presentation": {"allowed_hosts": ["conversion.write"], "max_primary_instances": 1, "global_banner": "forbidden"} + }, + { + "id": "conversion.running", + "scope": "surface", + "severity": "info", + "blocks": ["conversion.confirm-write"], + "recovery": [], + "presentation": {"allowed_hosts": ["conversion.input", "conversion.review", "conversion.write"], "max_primary_instances": 1, "global_banner": "forbidden"} + }, + { + "id": "conversion.failed", + "scope": "surface", + "severity": "error", + "blocks": ["conversion.confirm-write"], + "recovery": ["conversion.inspect", "conversion.run-dry-run", "conversion.rollback"], + "presentation": {"allowed_hosts": ["conversion.write", "conversion.result"], "max_primary_instances": 1, "global_banner": "forbidden"} + }, + { + "id": "conversion.success", + "scope": "surface", + "severity": "success", + "blocks": [], + "recovery": ["conversion.review-result", "conversion.rollback"], + "presentation": {"allowed_hosts": ["conversion.result", "history.session"], "max_primary_instances": 1, "global_banner": "forbidden"} + }, + { + "id": "history.empty", + "scope": "surface", + "severity": "info", + "blocks": [], + "recovery": ["conversion.select-source"], + "presentation": {"allowed_hosts": ["history.session"], "max_primary_instances": 1, "global_banner": "forbidden"} + } + ] +} diff --git a/.ui-os/project.json b/.ui-os/project.json new file mode 100644 index 0000000..a87a0e9 --- /dev/null +++ b/.ui-os/project.json @@ -0,0 +1,32 @@ +{ + "schema_version": "uios.project/v0.1", + "product": { + "id": "mh3g-save-converter", + "name": "MH3G Save Converter", + "primary_users": [ + "First-time MH3G players converting one local Japanese 3DS character slot to Wii U or Cemu", + "Returning players repairing an older converted slot while preserving later Wii U progress", + "Advanced users deliberately migrating optional system, ExtData, or experimental CEC data" + ], + "critical_jobs": [ + "Choose explicit source and output paths, inspect read-only, configure or skip optional data, run Dry Run, confirm a guarded write, then review or roll back", + "Repair from original 3DS source plus a read-only current Wii U reference into a separate output without weakening fingerprint or transaction checks", + "Keep every optional domain independently configured, authorized, written, and recoverable" + ] + }, + "targets": [ + "windows" + ], + "status": { + "agent_proposed_status": "draft", + "verifier_status": "pending_pilot" + }, + "gates": { + "required_lanes": [ + "machine", + "independent_ai", + "human" + ], + "human_task_evidence": "required_for_material_flow_change" + } +} diff --git a/.ui-os/research-task-windows.json b/.ui-os/research-task-windows.json new file mode 100644 index 0000000..ccb2048 --- /dev/null +++ b/.ui-os/research-task-windows.json @@ -0,0 +1,85 @@ +{ + "schema_version": "uios.research-task/v0.2", + "task_id": "mh3g-save-converter-windows-ui-quality-os-20260813", + "summary": "Redesign the existing MH3G Save Converter WinUI 3 desktop workflow so first-time and returning users can inspect, optionally extend, dry-run, safely write, review, and roll back without duplicated navigation, remote recovery, or optional-data scope confusion.", + "product": { + "id": "mh3g-save-converter", + "class": "windows-desktop-save-conversion-utility", + "primary_users": [ + "first-time MH3G player converting one 3DS slot", + "returning player repairing a previously converted Wii U or Cemu slot", + "advanced user adding optional system, ExtData, or experimental CEC data" + ], + "critical_job": "complete a local conversion or repair with explicit inputs, a read-only inspection, optional data that may be skipped, a fingerprint-bound dry run, guarded write, and recoverable result" + }, + "research_kinds": [ + "layout", + "interaction-pattern", + "component", + "motion", + "style", + "iconography", + "onboarding" + ], + "targets": [ + { + "id": "windows-winui3-desktop", + "platform": "windows", + "framework": "winui3", + "form_factor": "desktop", + "input_modes": ["pointer", "keyboard", "screen-reader"] + } + ], + "states": [ + "first-run", + "input-empty", + "input-inspecting", + "optional-missing", + "optional-skipped", + "dry-run-ready", + "dry-run-blocked", + "dry-run-running", + "write-authorized", + "write-confirmation", + "write-running", + "conversion-success", + "conversion-failure", + "history-empty", + "history-result", + "recovery" + ], + "accessibility_requirements": [ + "keyboard-and-ui-automation", + "logical-focus-order", + "text-scaling-and-locale-expansion", + "high-contrast", + "reduced-motion-and-animation-preferences", + "non-color-cues", + "stable-accessibility-identifiers" + ], + "constraints": { + "brand": [ + "MH Toolkit product identity", + "restrained utility-first brand layer", + "licensed WinUI SymbolIcon or project vector assets only for controls" + ], + "existing_system": [ + "WinUI 3 with Windows App SDK 1.8", + "existing C# MainViewModel and Rust CLI sidecar", + "shared conversion kernel: input, inspect, optional, dry run, confirm write, result or rollback", + "source, current reference, and output remain separate paths", + "hash, backup, manifest, confirmation, and fail-closed semantics remain unchanged" + ], + "forbidden": [ + "real save data", + "Cemu or emulator launch", + "macOS visual translation", + "Apple material or web dashboard styling", + "global optional-data blockers", + "decorative hero, glow, texture, confetti, looping empty-state motion", + "navigation animation or delayed primary actions", + "animation as the only state signal" + ] + }, + "freshness_claim": "current" +} diff --git a/.ui-os/research/reviews/windows-winui3-standard-20260813-review.json b/.ui-os/research/reviews/windows-winui3-standard-20260813-review.json new file mode 100644 index 0000000..17ac531 --- /dev/null +++ b/.ui-os/research/reviews/windows-winui3-standard-20260813-review.json @@ -0,0 +1,13 @@ +{ + "schema_version": "uios.research-review/v0.2", + "manifest_path": "/Volumes/GameHub/Development/Games/mh-save-sync-windows-ui-quality-os/.ui-os/research/runs/windows-winui3-standard-20260813/manifest.json", + "manifest_sha256": "c33b8c80328a16b7c6c5734d5c642599f9fb3a94fcb1097eb206ca7a1835e6ee", + "context_sha256": "4d999977163c19026d470038147c4568a3628985c2d4669eeaa8a6437ecc1766", + "protected_snapshot_sha256": "bb5a74dd2747e7a3aa14944422228ccba54dc62f9828df8ddaf47bf831c93144", + "reviewed_at": "2026-08-13T02:01:26Z", + "verdict": "pass", + "reviewer": "isolated-uios-research-review", + "notes": [ + "Grounded Standard proposal: all eight hashed artifacts match and all canonical URLs independently reopened with publisher and claimed substance intact; candidates adapt rather than copy and cover Windows native, keyboard/UIA, High Contrast, text scaling, non-color and AnimationsEnabled fallbacks. Shipped-flow evidence remains public and incomplete, so runtime usability, visual fidelity, motion, and accessibility are not verified." + ] +} diff --git a/.ui-os/research/runs/windows-winui3-standard-20260813/manifest.json b/.ui-os/research/runs/windows-winui3-standard-20260813/manifest.json new file mode 100644 index 0000000..d55b8e8 --- /dev/null +++ b/.ui-os/research/runs/windows-winui3-standard-20260813/manifest.json @@ -0,0 +1,804 @@ +{ + "schema_version": "uios.research/v0.2", + "run_id": "windows-winui3-standard-20260813", + "task": { + "id": "mh3g-save-converter-windows-ui-quality-os-20260813", + "context_path": "task-context.json", + "context_sha256": "4d999977163c19026d470038147c4568a3628985c2d4669eeaa8a6437ecc1766", + "product_id": "mh3g-save-converter", + "product_revision": "b3d58f70aa713b5e7f0ba7397d745b7166925547", + "git_status_sha256": "9bfd1aae9a960e67e70e2382d9f28be367d3bcea58743e5203e9523463acba29", + "protected_snapshot_sha256": "bb5a74dd2747e7a3aa14944422228ccba54dc62f9828df8ddaf47bf831c93144" + }, + "research_mode": "standard", + "research_kinds": [ + "layout", + "interaction-pattern", + "component", + "motion", + "style", + "iconography", + "onboarding" + ], + "started_at": "2026-08-13T01:42:50Z", + "completed_at": "2026-08-13T01:54:02Z", + "network_mode": "live", + "freshness_claim": "current", + "targets": [ + { + "id": "windows-winui3-desktop", + "platform": "windows", + "framework": "winui3", + "form_factor": "desktop", + "input_modes": [ + "pointer", + "keyboard", + "screen-reader" + ] + } + ], + "states": [ + "first-run", + "input-empty", + "input-inspecting", + "optional-missing", + "optional-skipped", + "dry-run-ready", + "dry-run-blocked", + "dry-run-running", + "write-authorized", + "write-confirmation", + "write-running", + "conversion-success", + "conversion-failure", + "history-empty", + "history-result", + "recovery" + ], + "accessibility_requirements": [ + "keyboard-and-ui-automation", + "logical-focus-order", + "text-scaling-and-locale-expansion", + "high-contrast", + "reduced-motion-and-animation-preferences", + "non-color-cues", + "stable-accessibility-identifiers" + ], + "queries": [ + { + "id": "q-winui-navigation-layout", + "text": "current official WinUI 3 desktop NavigationView hierarchy keyboard high contrast guidance", + "research_kind": "layout", + "target_ids": [ + "windows-winui3-desktop" + ], + "executed_at": "2026-08-13T01:46:00Z" + }, + { + "id": "q-winui-file-picker", + "text": "current Windows App SDK 1.8 WinUI 3 file and folder picker implementation", + "research_kind": "component", + "target_ids": [ + "windows-winui3-desktop" + ], + "executed_at": "2026-08-13T01:46:00Z" + }, + { + "id": "q-winui-progress-feedback", + "text": "current WinUI ProgressBar ProgressRing async operation local feedback guidance", + "research_kind": "interaction-pattern", + "target_ids": [ + "windows-winui3-desktop" + ], + "executed_at": "2026-08-13T01:46:00Z" + }, + { + "id": "q-windows-accessibility", + "text": "current Windows app accessibility UI Automation keyboard text scale high contrast motion preference", + "research_kind": "interaction-pattern", + "target_ids": [ + "windows-winui3-desktop" + ], + "executed_at": "2026-08-13T01:46:00Z" + }, + { + "id": "q-fluent-motion", + "text": "current Fluent Windows task state transition motion reduced motion guidance", + "research_kind": "motion", + "target_ids": [ + "windows-winui3-desktop" + ], + "executed_at": "2026-08-13T01:46:00Z" + }, + { + "id": "q-shipped-onboarding-recovery", + "text": "shipped Windows desktop utility onboarding next step empty state and recovery flow", + "research_kind": "onboarding", + "target_ids": [ + "windows-winui3-desktop" + ], + "executed_at": "2026-08-13T01:46:00Z" + }, + { + "id": "q-shipped-guarded-conversion", + "text": "shipped desktop image conversion utility source target guarded write progress result flow", + "research_kind": "interaction-pattern", + "target_ids": [ + "windows-winui3-desktop" + ], + "executed_at": "2026-08-13T01:46:00Z" + } + ], + "sources": [ + { + "id": "ms-navigationview", + "query_id": "q-winui-navigation-layout", + "title": "NavigationView - Windows apps", + "canonical_url": "https://learn.microsoft.com/en-us/windows/apps/develop/ui/controls/navigationview", + "publisher_id": "microsoft", + "tier": "primary-authority", + "classification": "platform-convention", + "retrieval_mode": "live", + "retrieved_at": "2026-08-13T01:47:12Z", + "opened_full_page": true, + "content_sha256": "6d9beff44ebb1dd8e28a44a3cf4584f0b7cd325040cb140806268408c2777822", + "artifact_path": "objects/ms-navigationview-6d9beff44ebb.html", + "artifact_sha256": "6d9beff44ebb1dd8e28a44a3cf4584f0b7cd325040cb140806268408c2777822", + "artifact_bytes": 131063, + "retriever": { + "mode": "bundled-http", + "tool": "pattern-intelligence-http", + "final_url": "https://learn.microsoft.com/en-us/windows/apps/develop/ui/controls/navigationview" + }, + "live_receipt": { + "status": 200, + "checked_at": "2026-08-13T01:47:12Z", + "etag": "\"wzjThNK/VdaQS/B92I6ZQNeggUY=\"", + "last_modified": "Wed, 05 Aug 2026 08:00:08 GMT" + }, + "source_revision_date": null, + "license_status": "linked-reference-only", + "affected_targets": [ + "windows-winui3-desktop" + ], + "claims": [ + "NavigationView is the native top-level container; keyboarding and high-contrast theme resources must remain supported." + ] + }, + { + "id": "ms-file-picker", + "query_id": "q-winui-file-picker", + "title": "Open files and folders with Windows App SDK pickers", + "canonical_url": "https://learn.microsoft.com/en-us/windows/apps/develop/files/using-file-folder-pickers", + "publisher_id": "microsoft", + "tier": "implementation", + "classification": "recommendation", + "retrieval_mode": "live", + "retrieved_at": "2026-08-13T01:47:12Z", + "opened_full_page": true, + "content_sha256": "e528f24783d9367bf8c4aa4c4946fdf0f19f7a5ab754656d6b3bb27256599db4", + "artifact_path": "objects/ms-file-picker-e528f24783d9.html", + "artifact_sha256": "e528f24783d9367bf8c4aa4c4946fdf0f19f7a5ab754656d6b3bb27256599db4", + "artifact_bytes": 69280, + "retriever": { + "mode": "bundled-http", + "tool": "pattern-intelligence-http", + "final_url": "https://learn.microsoft.com/en-us/windows/apps/develop/files/using-file-folder-pickers" + }, + "live_receipt": { + "status": 200, + "checked_at": "2026-08-13T01:47:12Z", + "etag": "\"Wl4vsxOQUaCXN1XcWUpZYYoQotg=\"", + "last_modified": "Wed, 05 Aug 2026 07:59:59 GMT" + }, + "source_revision_date": null, + "license_status": "linked-reference-only", + "affected_targets": [ + "windows-winui3-desktop" + ], + "claims": [ + "Windows App SDK 1.8 pickers provide native file and folder selection with a WindowId and return paths suitable for local confirmation." + ] + }, + { + "id": "ms-progress-controls", + "query_id": "q-winui-progress-feedback", + "title": "Progress controls - Windows apps", + "canonical_url": "https://learn.microsoft.com/en-us/windows/apps/develop/ui/controls/progress-controls", + "publisher_id": "microsoft", + "tier": "implementation", + "classification": "recommendation", + "retrieval_mode": "live", + "retrieved_at": "2026-08-13T01:47:13Z", + "opened_full_page": true, + "content_sha256": "46c7ddeaae3526fed92ba375219de33baeceb3bd6d77ac505a882130accfb311", + "artifact_path": "objects/ms-progress-controls-46c7ddeaae35.html", + "artifact_sha256": "46c7ddeaae3526fed92ba375219de33baeceb3bd6d77ac505a882130accfb311", + "artifact_bytes": 62185, + "retriever": { + "mode": "bundled-http", + "tool": "pattern-intelligence-http", + "final_url": "https://learn.microsoft.com/en-us/windows/apps/develop/ui/controls/progress-controls" + }, + "live_receipt": { + "status": 200, + "checked_at": "2026-08-13T01:47:13Z", + "etag": "\"1u3eKpyYUBJWTO84BNAG85048zE=\"", + "last_modified": "Wed, 05 Aug 2026 08:00:01 GMT" + }, + "source_revision_date": "2026-07-08", + "license_status": "linked-reference-only", + "affected_targets": [ + "windows-winui3-desktop" + ], + "claims": [ + "Choose determinate or indeterminate progress by whether duration is known and interaction is blocked; pair progress with explanatory text when needed." + ] + }, + { + "id": "ms-accessibility-overview", + "query_id": "q-windows-accessibility", + "title": "Accessibility overview - Windows apps", + "canonical_url": "https://learn.microsoft.com/en-us/windows/apps/design/accessibility/accessibility-overview", + "publisher_id": "microsoft", + "tier": "accessibility-authority", + "classification": "normative", + "retrieval_mode": "live", + "retrieved_at": "2026-08-13T01:47:14Z", + "opened_full_page": true, + "content_sha256": "16e36128ea2b0c2f0f488597ebd70bb37de3a2f07146e25b6fda934a0643424a", + "artifact_path": "objects/ms-accessibility-overview-16e36128ea2b.html", + "artifact_sha256": "16e36128ea2b0c2f0f488597ebd70bb37de3a2f07146e25b6fda934a0643424a", + "artifact_bytes": 66977, + "retriever": { + "mode": "bundled-http", + "tool": "pattern-intelligence-http", + "final_url": "https://learn.microsoft.com/en-us/windows/apps/design/accessibility/accessibility-overview" + }, + "live_receipt": { + "status": 200, + "checked_at": "2026-08-13T01:47:14Z", + "etag": "\"2Ma9MiHehZcgEO2HcxyvzVBVpRA=\"", + "last_modified": "Wed, 05 Aug 2026 08:00:03 GMT" + }, + "source_revision_date": null, + "license_status": "linked-reference-only", + "affected_targets": [ + "windows-winui3-desktop" + ], + "claims": [ + "WinUI controls inherit keyboard and UI Automation support, while text, scaling, color, and high contrast require explicit verification." + ] + }, + { + "id": "fluent-motion", + "query_id": "q-fluent-motion", + "title": "Fluent 2 motion", + "canonical_url": "https://fluent2.microsoft.design/motion", + "publisher_id": "microsoft", + "tier": "primary-authority", + "classification": "platform-convention", + "retrieval_mode": "live", + "retrieved_at": "2026-08-13T01:47:30Z", + "opened_full_page": true, + "content_sha256": "42ab4dc9afb22832d658eb80442f1efbc39df821b0be6b782b6149c1746e46a7", + "artifact_path": "objects/fluent-motion-42ab4dc9afb2.html", + "artifact_sha256": "42ab4dc9afb22832d658eb80442f1efbc39df821b0be6b782b6149c1746e46a7", + "artifact_bytes": 123126, + "retriever": { + "mode": "bundled-http", + "tool": "pattern-intelligence-http", + "final_url": "https://fluent2.microsoft.design/motion" + }, + "live_receipt": { + "status": 200, + "checked_at": "2026-08-13T01:47:30Z", + "etag": null, + "last_modified": null + }, + "source_revision_date": null, + "license_status": "linked-reference-only", + "affected_targets": [ + "windows-winui3-desktop" + ], + "claims": [ + "Motion should communicate hierarchy, feedback, and spatial relation with platform-native timing rather than decorative choreography." + ] + }, + { + "id": "github-desktop-onboarding", + "query_id": "q-shipped-onboarding-recovery", + "title": "GitHub Desktop onboarding and suggested next steps", + "canonical_url": "https://github.blog/news-insights/product-news/github-desktop-update/", + "publisher_id": "github.blog", + "tier": "shipped-product", + "classification": "recommendation", + "retrieval_mode": "live", + "retrieved_at": "2026-08-13T01:47:32Z", + "opened_full_page": true, + "content_sha256": "7567553258da3e158e0cea1d384ea5ce368c237993c047bf014fb340c4a119c6", + "artifact_path": "objects/github-desktop-onboarding-7567553258da.html", + "artifact_sha256": "7567553258da3e158e0cea1d384ea5ce368c237993c047bf014fb340c4a119c6", + "artifact_bytes": 167844, + "retriever": { + "mode": "bundled-http", + "tool": "pattern-intelligence-http", + "final_url": "https://github.blog/news-insights/product-news/github-desktop-update/" + }, + "live_receipt": { + "status": 200, + "checked_at": "2026-08-13T01:47:32Z", + "etag": null, + "last_modified": null + }, + "source_revision_date": "2021-12-19", + "license_status": "linked-reference-only", + "affected_targets": [ + "windows-winui3-desktop" + ], + "claims": [ + "A shipped desktop utility uses contextual next-step guidance in initial and empty states rather than leaving users to infer the workflow." + ] + }, + { + "id": "balena-etcher", + "query_id": "q-shipped-guarded-conversion", + "title": "balenaEtcher shipped image-writing utility", + "canonical_url": "https://github.com/balena-io/etcher", + "publisher_id": "github.com", + "tier": "shipped-product", + "classification": "recommendation", + "retrieval_mode": "live", + "retrieved_at": "2026-08-13T01:47:34Z", + "opened_full_page": true, + "content_sha256": "fcc7a0c1e17860b9cd6bd5e49bf171b92d2dbf0db169b2a85101e4e5c0edd20a", + "artifact_path": "objects/balena-etcher-fcc7a0c1e178.html", + "artifact_sha256": "fcc7a0c1e17860b9cd6bd5e49bf171b92d2dbf0db169b2a85101e4e5c0edd20a", + "artifact_bytes": 346562, + "retriever": { + "mode": "bundled-http", + "tool": "pattern-intelligence-http", + "final_url": "https://github.com/balena-io/etcher" + }, + "live_receipt": { + "status": 200, + "checked_at": "2026-08-13T01:47:34Z", + "etag": "W/\"9aa8383cbaf23024ad5f2c7618e914d8\"", + "last_modified": null + }, + "source_revision_date": null, + "license_status": "permitted-with-attribution", + "affected_targets": [ + "windows-winui3-desktop" + ], + "claims": [ + "A shipped destructive desktop utility makes source selection, target selection, guarded write, verification, and failure recovery explicit while protecting system drives." + ] + }, + { + "id": "ms-ui-settings-motion", + "query_id": "q-fluent-motion", + "title": "UISettings AnimationsEnabled", + "canonical_url": "https://learn.microsoft.com/en-us/uwp/api/windows.ui.viewmanagement.uisettings.animationsenabled?view=winrt-26100", + "publisher_id": "microsoft", + "tier": "implementation", + "classification": "recommendation", + "retrieval_mode": "live", + "retrieved_at": "2026-08-13T01:48:39Z", + "opened_full_page": true, + "content_sha256": "5b2413221dc15d5cedf92a61c2d41f343b3e227300ee978f10287cb8668657fc", + "artifact_path": "objects/ms-ui-settings-motion-5b2413221dc1.html", + "artifact_sha256": "5b2413221dc15d5cedf92a61c2d41f343b3e227300ee978f10287cb8668657fc", + "artifact_bytes": 50434, + "retriever": { + "mode": "bundled-http", + "tool": "pattern-intelligence-http", + "final_url": "https://learn.microsoft.com/en-us/uwp/api/windows.ui.viewmanagement.uisettings.animationsenabled?view=winrt-26100" + }, + "live_receipt": { + "status": 200, + "checked_at": "2026-08-13T01:48:39Z", + "etag": "\"p8uYS3UqVynwNjrVZAZQHo2G7w4=\"", + "last_modified": "Wed, 05 Aug 2026 07:38:14 GMT" + }, + "source_revision_date": null, + "license_status": "linked-reference-only", + "affected_targets": [ + "windows-winui3-desktop" + ], + "claims": [ + "Windows exposes the user animation preference through UISettings.AnimationsEnabled; custom motion must preserve semantics when disabled." + ] + } + ], + "candidates": [ + { + "id": "guided-native-workflow", + "title": "Guided native workflow", + "user_problem": "A first-time player must understand the next safe action without reading every path, hash, optional transaction, and recovery detail at once.", + "reusable_principle": "Use one native application navigator, then reveal one bounded task stage with one local primary action and contextual recovery.", + "source_ids": [ + "ms-navigationview", + "ms-file-picker", + "ms-accessibility-overview", + "fluent-motion", + "github-desktop-onboarding" + ], + "decision": "adapt", + "source_expression": "Windows guidance supplies adaptive top-level navigation and familiar pickers, while a shipped desktop onboarding flow presents contextual next steps after an empty or completed state.", + "product_expression": "The converter can separate Convert, History, Advanced, and Settings in a single Fluent shell, then keep source selection, optional data, Dry Run, guarded write, and recovery inside one ordered conversion workspace.", + "target_adaptations": [ + { + "target_id": "windows-winui3-desktop", + "native_components": "Use WinUI 3 NavigationView only for application destinations; use Windows App SDK FileOpenPicker and FolderPicker, native Button, ToggleSwitch, InfoBar, ContentDialog, and text controls inside the conversion task.", + "navigation": "Keep application navigation persistent and distinct from a compact conversion progress indicator; do not create a second sidebar or animate page navigation.", + "density": "Use Windows desktop spacing with one readable working column at the minimum window and wider summary support only when space permits; collapse technical details rather than shrinking controls.", + "icons": "Use licensed WinUI SymbolIcon or project vector glyphs paired with plain labels for commands; never use a symbol without an accessible name.", + "motion": "Use native control feedback and a short local opacity or visual-state change only when optional fields appear or the footer state changes.", + "input_behavior": "Preserve logical XAML order for Tab traversal, Enter or Space activation, Escape cancellation, visible focus, pointer hover supplied by native controls, and stable focus after asynchronous state changes." + } + ], + "accessibility": { + "reduced_motion": "Read UISettings.AnimationsEnabled; when false, swap optional and footer states immediately without translation or scale.", + "non_motion_equivalence": "Every transition ends in persistent title, status text, enabled state, reason, and recovery command that remain understandable without animation.", + "contrast": "Resolve foregrounds, surfaces, borders, and focus visuals from theme resources with an explicit HighContrast dictionary rather than hard-coded light colors.", + "non_color": "Pair warning, success, failure, selection, and readiness colors with text, state icon, and control enabled state.", + "text_scaling": "Let labels and path summaries wrap, keep buttons auto-sized, and reflow to one column before text clips in English, Simplified Chinese, or increased text scale.", + "focus_input": "Use the semantic task order as the XAML order and move focus only after explicit navigation, not after background status updates.", + "assistive_tech": "Assign stable AutomationId, accessible Name, role, value, and LiveSetting only to scoped status changes; avoid repeating the same status in several live regions." + }, + "motion": { + "purpose": "spatial-continuity", + "frequency": "occasional", + "trigger": "The user enables optional data or a task state changes between blocked, ready, running, and result.", + "timing_intent": "Immediate semantic state update with one short platform-native local content transition; the primary command frame never moves.", + "interruptible": true, + "looping": "none", + "stop_condition": "", + "reduced_motion_variant": "Instant layout update plus persistent text, icon, and focus semantics.", + "performance_risk": "Avoid animating ScrollViewer layout, page containers, blur, shadow, or long path text; prefer one compositor-friendly opacity state if used." + }, + "contraindications": [ + "Do not expose optional System, ExtData, or CEC fields until the user enables that transaction.", + "Do not duplicate NavigationView with a second persistent stage rail.", + "Do not move the task primary action away from its local reason or recovery action." + ], + "copied_assets": [], + "confidence": 0.9 + }, + { + "id": "compact-operation-canvas", + "title": "Compact operation canvas", + "user_problem": "A returning player needs to compare selected source, current reference, output, readiness, and recovery quickly without walking through a decorative wizard.", + "reusable_principle": "Keep the operation summary and its guarded command stable, then disclose the affected inputs and technical report at the narrowest truthful scope.", + "source_ids": [ + "ms-navigationview", + "ms-progress-controls", + "ms-accessibility-overview", + "ms-ui-settings-motion", + "balena-etcher" + ], + "decision": "adapt", + "source_expression": "A shipped destructive utility foregrounds source, target, guarded execution, verification, and recovery; Windows controls distinguish local nonblocking progress from interaction-blocking wait states.", + "product_expression": "The converter can present a compact source-current-output summary above a stable command footer, with read-only inspection and recovery details expanding beside the exact field or operation they explain.", + "target_adaptations": [ + { + "target_id": "windows-winui3-desktop", + "native_components": "Use WinUI path rows backed by native pickers, an InfoBar at the affected operation, ProgressBar for nonmodal unknown work, ProgressRing only when the local surface truly cannot continue, and ContentDialog for the write confirmation.", + "navigation": "Retain one NavigationView for application destinations; inside Convert use an operation canvas and compact state summary rather than another navigational list.", + "density": "Favor concise selected-path summaries, aligned labels, and a two-column review layout only above the responsive breakpoint; stack inputs and footer at the minimum width.", + "icons": "Use Windows symbols for file, folder, inspect, shield, write, undo, warning, and completion, always accompanied by localized text for primary and destructive commands.", + "motion": "Keep the footer rectangle fixed and crossfade only its status content; use native progress behavior during Inspect, Dry Run, and Write.", + "input_behavior": "Allow expert keyboard traversal through the three core paths and primary command before progressive technical disclosures; preserve focus when a picker returns and announce the selected path locally." + } + ], + "accessibility": { + "reduced_motion": "Disable custom transitions when AnimationsEnabled is false and leave only native static state changes and progress text.", + "non_motion_equivalence": "Running, blocked, authorized, success, and failure always have plain text, an icon, and an automation state independent of progress animation.", + "contrast": "Use Windows theme resources and test all semantic surfaces in Light, Dark, and High Contrast without relying on translucent fills.", + "non_color": "Show the exact blocked reason and a labeled Fix action; never use accent color alone to distinguish selected, ready, or failed.", + "text_scaling": "Selected paths may truncate visually only when their accessible name retains the full path; labels, reasons, and commands must wrap or reflow.", + "focus_input": "Keep a deterministic Tab path from source to current reference to output to primary action, with Escape closing confirmation and focus returning to the invoking control.", + "assistive_tech": "Expose progress state, blocked reason, selected path, manifest location, and rollback availability through native UI Automation patterns and scoped polite announcements." + }, + "motion": { + "purpose": "feedback", + "frequency": "occasional", + "trigger": "Inspect, Dry Run, or Write starts or resolves, or a native picker returns a selected path.", + "timing_intent": "Acknowledge input immediately; keep the CTA geometry fixed while a nearby label and native progress indicator communicate work, then show one bounded completion transition.", + "interruptible": true, + "looping": "bounded", + "stop_condition": "Stop progress motion when the asynchronous command resolves, cancels, or fails.", + "reduced_motion_variant": "Replace custom crossfade or spatial transition with an immediate text and icon update; retain only essential native progress behavior if the operation is still running.", + "performance_risk": "Do not animate height, width, large surfaces, or progress position manually; use native progress controls and compositor-safe opacity only." + }, + "contraindications": [ + "Do not imitate balenaEtcher branding, wording, exact three-panel composition, or assets.", + "Do not turn History or Settings into operation-summary panels with conversion blockers.", + "Do not render hashes, fingerprints, or manifest JSON permanently at the primary level." + ], + "copied_assets": [], + "confidence": 0.86 + } + ], + "rejections": [ + { + "id": "reject-decorative-hero-dashboard", + "idea": "Retain the large artwork hero, four stage labels, global status badge, repeated InfoBars, and card-heavy single scrolling dashboard.", + "reason": "The current product already repeats navigation and status while pushing the active task and recovery apart; Windows platform guidance supports a native top-level navigator and scoped controls instead of compensating with decorative hierarchy.", + "source_ids": [ + "ms-navigationview", + "github-desktop-onboarding" + ] + }, + { + "id": "reject-global-blocking-spinner", + "idea": "Use a full-window indeterminate ring and disable all navigation for every Inspect, Dry Run, picker, or optional transaction.", + "reason": "Windows guidance distinguishes nonmodal and blocking progress; most converter operations should keep unrelated application destinations responsive and scope waiting feedback to the command that started it.", + "source_ids": [ + "ms-progress-controls", + "ms-accessibility-overview" + ] + }, + { + "id": "reject-ornamental-motion", + "idea": "Add page slides, staggered form entrance, hover lift, looping empty-state art, failure shake, or success confetti.", + "reason": "These effects add no operational meaning, compete with frequent keyboard and pointer tasks, and create unnecessary reduced-motion and performance obligations.", + "source_ids": [ + "fluent-motion", + "ms-ui-settings-motion" + ] + }, + { + "id": "reject-optional-as-required", + "idea": "Keep System, ExtData, or CEC paths visible as missing requirements before core Inspect or Dry Run.", + "reason": "Optional transactions must remain independently skippable; contextual next-step evidence supports showing the next relevant action rather than unrelated global blockers.", + "source_ids": [ + "github-desktop-onboarding", + "ms-accessibility-overview" + ] + } + ], + "contradictions": [ + { + "source_ids": [ + "ms-navigationview", + "github-desktop-onboarding" + ], + "conflict": "NavigationView is appropriate for top-level destinations, while onboarding evidence favors contextual sequential guidance; using both as navigation would duplicate hierarchy.", + "resolution": "Use NavigationView only for Convert, History, Advanced, and Settings. Represent conversion progress as a non-navigational, bounded in-page state sequence with one local command." + }, + { + "source_ids": [ + "ms-progress-controls", + "balena-etcher" + ], + "conflict": "A guarded write may deserve blocking feedback, but Inspect and Dry Run do not justify freezing the whole application.", + "resolution": "Keep command geometry stable, disable only conflicting controls, use scoped text plus ProgressBar for nonmodal work, and reserve modal confirmation or blocking ProgressRing for the actual write boundary." + } + ], + "protected_files": [ + { + "scope": "plugin", + "path": ".codex-plugin/plugin.json", + "sha256": "6dab1143cf01d70c754f35a5b1e8e8d69a472ed1d5f795ce870b42f573117f24" + }, + { + "scope": "plugin", + "path": "assets/project-template/flows.json", + "sha256": "d3304e6b6ac380c80d1eaa01bf2196aedeed42430cb02fad80813633a926c47d" + }, + { + "scope": "plugin", + "path": "assets/project-template/project.json", + "sha256": "c0e5932228e44cfefaf8ca786f91cae21dd2dcfe3d6ccb06cfd23689faecfbbc" + }, + { + "scope": "plugin", + "path": "assets/project-template/tokens.json", + "sha256": "f88a8f78819020dffd779494710042eac7f3eb5da21f29b533ba10b25d739236" + }, + { + "scope": "plugin", + "path": "assets/research-task-template.json", + "sha256": "408d6acb8631d64cab6b63ecccd973d76f587c5a6d825c08bf6744c5a178525f" + }, + { + "scope": "plugin", + "path": "references/evidence-contract.md", + "sha256": "cca00e244fe0befbf7d761d0b5c731834cffd9d4b75be2915c6e27174d4b0bcd" + }, + { + "scope": "plugin", + "path": "references/kernel.md", + "sha256": "c7704f2bce4f05ec5a51e41a6a6c78fff892848a552b1580415ba920afea6e3d" + }, + { + "scope": "plugin", + "path": "references/motion-intelligence.md", + "sha256": "0d5cd07a56f0da7dfd2c55739578b226a9854a664bc4441b289d0f6eb379590f" + }, + { + "scope": "plugin", + "path": "references/pattern-intelligence.md", + "sha256": "44329e4a72ac11389891e46f25ff196cdda2adba3b92e782b9545b9fc6a433d1" + }, + { + "scope": "plugin", + "path": "references/profiles.md", + "sha256": "0d8a4d23e26462ef388ebcc9b49fde1268637ef1d89e717d1abbd5bfc3b67e71" + }, + { + "scope": "plugin", + "path": "references/role-prompts.md", + "sha256": "47013cb05ea96e26ed62b36ca0987952f5af7ba5592b31e1bd4ce9081cb0631f" + }, + { + "scope": "plugin", + "path": "references/source-registry.md", + "sha256": "c90d72ed88ebf82f995b856595eb7ab67cbc5424961e97aa2d082b2ff479b81e" + }, + { + "scope": "plugin", + "path": "references/standards-sources.md", + "sha256": "d38dab3e6a2c27ed0368ef601950dd77b4ea509eea1df9921ce40819ddb0f4c1" + }, + { + "scope": "plugin", + "path": "references/style-intelligence.md", + "sha256": "b1c6ccb79a2fcfd4152134afca27306d75452293788196154b326f7dd0751087" + }, + { + "scope": "plugin", + "path": "references/workflow.md", + "sha256": "0f27704d443efac53685027aa04b429fae8c2ce6e4ccf8e116ef59ec701d2535" + }, + { + "scope": "plugin", + "path": "schemas/evidence.schema.json", + "sha256": "dc7414d061fdaf4b6852ea721ab2308395fb3f6551431f8b2d4e8cf4701c4277" + }, + { + "scope": "plugin", + "path": "schemas/flows.schema.json", + "sha256": "fc84e0d732ad86c51b256e06e7b5a41468aba0cdf887b02ff4eb7d84fa9b129e" + }, + { + "scope": "plugin", + "path": "schemas/project.schema.json", + "sha256": "5683e56d98d5d0875975210d899b915f9f1ae1f5a12213e2067006a8440ef9eb" + }, + { + "scope": "plugin", + "path": "schemas/research.schema.json", + "sha256": "6be02ad673eb814c46f85d2835a3a81865c99d8a3fa8c63f741726d5031774c1" + }, + { + "scope": "plugin", + "path": "schemas/tokens.schema.json", + "sha256": "6ae4e1719ea73f078d6f56b5eab782cd9dcacbef258cd6baf36aa3029303d9d5" + }, + { + "scope": "plugin", + "path": "scripts/pattern_intelligence.py", + "sha256": "491439a339eaf5e96d737a8125a263d746c7db878020e15466f6ecec38c3b2d4" + }, + { + "scope": "plugin", + "path": "scripts/ui_os.py", + "sha256": "677b64a60c686bc84bdabb3316b85e8813fd79864a489d6f33fb99b861d91d86" + }, + { + "scope": "plugin", + "path": "skills/uios-design/SKILL.md", + "sha256": "0025a9f59dd9b9ebd7dd8ca13ff0fa0bdd9ef9cd2e084a2fa53517b339277f0a" + }, + { + "scope": "plugin", + "path": "skills/uios-design/agents/openai.yaml", + "sha256": "cca06cada07909a075be3431596ed9138d99225e1d0ed3c93d691984ff0a0660" + }, + { + "scope": "plugin", + "path": "skills/uios-implement/SKILL.md", + "sha256": "d2e2f32c0968ecc0be27e58344c245db9b020890d38357b2c0a86ddaf68073c3" + }, + { + "scope": "plugin", + "path": "skills/uios-implement/agents/openai.yaml", + "sha256": "5e84077fac23036aa6bdcd64a4a8ee26e7dc727b1011f5ce379f0f97d26709b3" + }, + { + "scope": "plugin", + "path": "skills/uios-orchestrate/SKILL.md", + "sha256": "991f493535dd75f490f1ed6d751e899c5488ee7935fe11295e0988632de4d544" + }, + { + "scope": "plugin", + "path": "skills/uios-orchestrate/agents/openai.yaml", + "sha256": "4d1a4f158ad8e8d6253d1210307fe76fd4d4261646c4899bcdb396b17ab95921" + }, + { + "scope": "plugin", + "path": "skills/uios-refresh/SKILL.md", + "sha256": "49980791aa415129d981dc13166746c343eda0f7d730a98c3dea73c2a49185af" + }, + { + "scope": "plugin", + "path": "skills/uios-refresh/agents/openai.yaml", + "sha256": "88ecfa0854787f4f290b8c3d404c19bacbda648515dad6e22ad4aae258b6a36b" + }, + { + "scope": "plugin", + "path": "skills/uios-research-review/SKILL.md", + "sha256": "617adf85ec9a707bcbf700ec2c248dee575985d1e50b78b357e5bd53b49b0764" + }, + { + "scope": "plugin", + "path": "skills/uios-research-review/agents/openai.yaml", + "sha256": "5e97fa9976131dd89404a197dfe05ff6cff547faf225aa43a1dcef6a7280666d" + }, + { + "scope": "plugin", + "path": "skills/uios-research/SKILL.md", + "sha256": "06a919fcf7aa727934e6ec21ba2f05b347dc7399df9b2dc5b81dc3f58a94fa6b" + }, + { + "scope": "plugin", + "path": "skills/uios-research/agents/openai.yaml", + "sha256": "d29fdf4fb538140777bcce36644ac2d491182b1160e23bb515daeabb3d0c46c2" + }, + { + "scope": "plugin", + "path": "skills/uios-verify/SKILL.md", + "sha256": "f9c7a6572a375e5f3806d85464d5f72345a2fa8ca794e052f40d2860df0ebe48" + }, + { + "scope": "plugin", + "path": "skills/uios-verify/agents/openai.yaml", + "sha256": "dbde1eb673d550a8129093c33af45b2528bd0f84e6181fea746efff20a960553" + }, + { + "scope": "plugin", + "path": "tests/test_pattern_intelligence.py", + "sha256": "226d4bb8bd6e8d6eb4f6b77c892dbb6aca89da914db3dcce5fd63d413e6345ba" + }, + { + "scope": "plugin", + "path": "tests/test_ui_os.py", + "sha256": "7a3f68dc3622e5e17a6ee6c3af1908c15782d0983ab49a4d3272ff127aa229c3" + }, + { + "scope": "product", + "path": ".ui-os/evidence/manifest.json", + "sha256": "d5686268cdc01966504b443b0f32ff3d6f65bcb471eaeb10f883bf9e821814f3" + }, + { + "scope": "product", + "path": ".ui-os/flows.json", + "sha256": "d3304e6b6ac380c80d1eaa01bf2196aedeed42430cb02fad80813633a926c47d" + }, + { + "scope": "product", + "path": ".ui-os/project.json", + "sha256": "959ee08c40874cac4ec42c143e9a15481cfabae31a5df7134f9701f4b9ab47d0" + }, + { + "scope": "product", + "path": ".ui-os/tokens.json", + "sha256": "f88a8f78819020dffd779494710042eac7f3eb5da21f29b533ba10b25d739236" + } + ], + "limitations": [ + "The shipped-product lane uses public release and repository evidence, not a newly recorded interactive Windows session or a paid flow database.", + "The GitHub Desktop onboarding source is historical and supports only the contextual-next-step principle; it is not current visual-style authority.", + "The balenaEtcher source establishes a shipped safety-oriented utility and recovery posture but does not provide a complete adjacent-state screenshot set in the fetched artifact.", + "This isolated research role did not run or modify the WinUI application; runtime fidelity, animation behavior, accessibility tree, and minimum-window behavior remain implementation and verification work." + ], + "brief": { + "path": "pattern-intelligence-brief.md", + "sha256": "7a621c6cea4b1a23605badf468ab53b3a6eab999ff9e37c2c54d674505f023f5", + "bytes": 8823 + }, + "verdict": "grounded_proposal" +} diff --git a/.ui-os/research/runs/windows-winui3-standard-20260813/objects/balena-etcher-fcc7a0c1e178.html b/.ui-os/research/runs/windows-winui3-standard-20260813/objects/balena-etcher-fcc7a0c1e178.html new file mode 100644 index 0000000..7f3cdc9 --- /dev/null +++ b/.ui-os/research/runs/windows-winui3-standard-20260813/objects/balena-etcher-fcc7a0c1e178.html @@ -0,0 +1,986 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + GitHub - balena-io/etcher: Flash OS images to SD cards & USB drives, safely and easily. · GitHub + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +
+ Skip to content + + + + + + + + + + + + +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + + + +
+ +
+ + + + + + + + +
+ + + + + + +
+ + + + + + + + + +
+
+
+ + + + + + + + + + + + + + + + + + + + +
+ +
+ +
+ +
+ + + + / + + etcher + + + Public +
+ + +
+ +
+ + +
+
+ +
+
+ + + + +
+ + + + + +
+ + + + + + + + + + + + + + + + + + +

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

3,481 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Etcher

+
+

Flash OS images to SD cards & USB drives, safely and easily.

+
+

Etcher is a powerful OS image flasher built with web technologies to ensure +flashing an SDCard or USB drive is a pleasant and safe experience. It protects +you from accidentally writing to your hard-drives, ensures every byte of data +was written correctly, and much more. It can also directly flash Raspberry Pi devices that support USB device boot mode.

+

Current Release +License +Balena.io Forums

+
+

Download | Support | Documentation | Contributing | Roadmap

+

Supported Operating Systems

+
    +
  • Linux; most distros; Intel 64-bit.
  • +
  • Windows 10 and later; Intel 64-bit.
  • +
  • macOS 10.13 (High Sierra) and later; both Intel and Apple Silicon.
  • +
+

Installers

+

Refer to the downloads page for the latest pre-made +installers for all supported operating systems.

+

Packages

+

Debian and Ubuntu based Package Repository (GNU/Linux x86/x64)

+

Package for Debian and Ubuntu can be downloaded from the Github release page

+
Install .deb file using apt
+
   sudo apt install ./balena-etcher_******_amd64.deb
+
Uninstall
+
   sudo apt remove balena-etcher
+

Redhat (RHEL) and Fedora-based Package Repository (GNU/Linux x86/x64)

+
Yum
+

Package for Fedora-based and Redhat can be downloaded from the Github release page

+
    +
  1. Install using yum
  2. +
+
   sudo yum localinstall balena-etcher-***.x86_64.rpm
+

Arch/Manjaro Linux (GNU/Linux x64)

+

Etcher is offered through the Arch User Repository and can be installed on both Manjaro and Arch systems. You can compile it from the source code in this repository using balena-etcher. The following example uses a common AUR helper to install the latest release:

+
yay -S balena-etcher
+
Uninstall
+
yay -R balena-etcher
+

WinGet (Windows)

+

This package is updated by gh-action, and is kept up to date automatically.

+
winget install balenaEtcher #or Balena.Etcher
+
Uninstall
+
winget uninstall balenaEtcher
+

Chocolatey (Windows)

+

This package is maintained by @majkinetor, and +is kept up to date automatically.

+
choco install etcher
+
Uninstall
+
choco uninstall etcher
+

Support

+

If you're having any problem, please raise an issue on GitHub, and +the balena.io team will be happy to help.

+

License

+

Etcher is free software and may be redistributed under the terms specified in +the license.

+

About

Flash OS images to SD cards & USB drives, safely and easily.

Topics

Resources

Contributing

Stars

34.1k stars

Watchers

442 watching

Forks

Releases

Packages

Used by

Contributors

Languages

+
+ + + + +
+ +
+ +
+
+ +
+ +
+

Footer

+ + + + +
+
+ + + + + © 2026 GitHub, Inc. + +
+ + +
+
+ + + + + + + + + + + + + + + + + + + + +
+
+
+ + + diff --git a/.ui-os/research/runs/windows-winui3-standard-20260813/objects/fluent-motion-42ab4dc9afb2.html b/.ui-os/research/runs/windows-winui3-standard-20260813/objects/fluent-motion-42ab4dc9afb2.html new file mode 100644 index 0000000..165cdfd --- /dev/null +++ b/.ui-os/research/runs/windows-winui3-standard-20260813/objects/fluent-motion-42ab4dc9afb2.html @@ -0,0 +1,379 @@ + Motion - Fluent 2 Design System + Skip to main content

Motion

+

Motion defines relationships and transitions to help people recognize changes and move toward their goals. Good motion design can also bring a sense of humanity and delight to an experience while making it more sophisticated and satisfying.

+
+
+

Motion principles

0% played
Play

Functional

Motion is applied with purpose and intent to serve the functionality of an experience. Use motion to identify the next step, inform people of changes in the UI, and celebrate what they’ve accomplished.

0% played
Play

Natural

Motion in Fluent 2 experiences feels fluid and real by following physical laws such as inertia, gravity, weight and velocity. This makes animations more believable and predictable.

0% played
Play

Consistent

Consistency in motion design helps unify Microsoft experiences and improves the flow between products. Consistent motion provides a sense of familiarity and strengthens Fluent’s Unmistakably Microsoft principle.

0% played
Play

Appealing

Delightful animation draws people in. Designing engaging moments using motion helps people relate to your product and creates a more memorable experience.


+

Duration and easing

Duration and easing describe how long an object moves and how its speed changes along the way. Getting duration and easing right guarantees that people have enough time to notice the motion and interpret what it communicates.

Duration

Animations need to strike a balance between feeling too sluggish and too abrupt. Make it feel natural and quick by considering the size of the element and the distance it travels. Give larger elements more time to animate than smaller elements. Aim for a fast and smooth motion without making people wait.

0% played
Play
0% played
Play

Use quick, natural durations

0% played
Play

Unnatural durations can be jarring and abrupt

Easing

Easing is what gives an animation a natural and organic feel, as opposed to a uniform and rigid motion. There are different types of easing that can be applied to animations, such as linear easing, ease-in, ease-out, and ease-in-out. By choosing the right easing function, makers can create animations that are natural and engaging, improving the user experience.

0% played
Play

Linear easing

Linear easing means that the animation moves at a constant speed from start to finish. This type of easing can feel unnatural; use it only in cases that need a consistent rate, like rotations.

0% played
Play

Ease-in

Ease-in animations start slow and then speed up.

0% played
Play

Ease-out

Ease-out animations start fast and then slow down.

0% played
Play

Ease-in-out

Ease-in-out animations start slow, speed up in the middle, and then slow down again before ending.


+

Transitions, or motion in practice

Transitions introduce, dismiss, or change content via an animation. and are at the heart of effective UI motion design. They help people understand how the UI works and give it a high-quality look and feel. When speaking about motion, the term transition describes most animations in the UI.

Four of the most common transitions we use are:

  1. Enter and Exit
  2. Elevation
  3. Top level
  4. Container transform

Enter and exit

Enter and exit introduces or dismisses elements in the UI. These elements can enter and exit from off-screen or from within the bounds of the screen. This pattern is commonly used for menus, dialogs, and other interactive elements that appear and disappear on the screen.

0% played
Play

Elevation

The elevation pattern is used to visually indicate changes in elevation or depth on the user interface. This pattern is commonly used for button states, drag and drop interactions, windows, and creating a hierarchy of elements. By using elevation to indicate changes in depth, it helps to create a clear and intuitive experience by providing visual cues to the user about the relationships between elements on the screen.

0% played
Play

Top level

The top level transition is used to navigate between different pages and destinations. Since the elements at the top level are large and take up a significant amount of screen real estate, use a quick fade transition instead of moving or sliding UI elements around on and off the screen. This approach helps keep the UI consistent and clear, avoiding unintentional hierarchy and disorientation.

0% played
Play

Container transform

A container transform refers to the process of changing the layout or position of a container element on the UI. This is done through a resize and/or reposition. Container transforms are commonly used in responsive design, to adjust the layout of a website or application to different screen sizes or orientations.

0% played
Play

+

Choreography

Choreography refers to the arrangement and order of movements in an animation. Poor choreography can result in an animation that appears cheap or takes an excessive amount of time to conclude.

Staggering

Staggering is the process of delaying the start of one or more animations. This can be used to soften the entry of large sets of items or to shift people’s gaze in a specified direction.

Pay attention to when it’s appropriate to stagger an animation and when they may need to end at the same time. Keep in mind the overall duration of the animations and use short offsets between them. When loading the same content multiple times, consider using different animation offsets. It may be appropriate to programmatically vary the offsets, starting with larger gaps and gradually shortening them. When using a list of items that is bound to an animated parent, consider the timing of the parent animation as well.

For most scenarios, a staggered animation is preferred. Non-staggered animation should only be used for very large groups of elements, when staggering makes the animation take too long to complete.

Hierarchy

Hierarchy refers to the order in which elements are animated. Animation hierarchy allows you to direct people’s attention to UX elements in a preferred order, and helps to ease the flow of navigation to critical areas.

Give important elements more emphasis through more prominent movements and longer durations. Conversely, less significant elements should be grouped together with synchronized timing to create a cohesive visual experience.

0% played
Play

Use choreography help build focus

0% played
Play

Moving elements together can create ambiguity


+

Accessible motion design

Fluent’s principle one for all, all for one means that we consider the needs of everyone in every aspect of designing and developing UI. Incorporating thoughtful motion design aligns our products to the Microsoft goal of helping everyone achieve more.

Groups who may be unable to perceive motion or may be adversely impacted by motion include people with vestibular disorders, people with low vision, people who use screen readers, or people who are sensitive to visual stimuli. Here are some general rules to make sure that these groups can also benefit fully from your apps.

Design for and include a “no motion” setting for your app or website as recommended by the WCAG.

Keep durations short and the movement natural.

Avoid flashes, jarring movements, or any other sudden movements that could trigger an epileptic seizure.

Keep the motion constrained to the element in focus. Adding motion in other areas of the screen may distract from the task at hand.

Consider other ways of communicating information that conveyed via animations, like using ARIA live regions to expose and announce dynamic content.

\ No newline at end of file diff --git a/.ui-os/research/runs/windows-winui3-standard-20260813/objects/github-desktop-onboarding-7567553258da.html b/.ui-os/research/runs/windows-winui3-standard-20260813/objects/github-desktop-onboarding-7567553258da.html new file mode 100644 index 0000000..545b8be --- /dev/null +++ b/.ui-os/research/runs/windows-winui3-standard-20260813/objects/github-desktop-onboarding-7567553258da.html @@ -0,0 +1,944 @@ + + + + + + + + + + + GitHub Desktop 1.6 now available - The GitHub Blog + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+
+
+
+
+
+

GitHub Desktop 1.6 now available

+

We are excited to release GitHub Desktop 1.6, bringing new features and improvements around onboarding, suggested next steps, and large file restrictions.

+
+
+
+
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+ + + ·@nerdneha + +
+
+
+ + + | + +
+ | + + + + 2 minutes
+
+
+ +
+
+
+
+
+
+
+
+

We are excited to release GitHub Desktop 1.6, bringing new features and improvements around onboarding, suggested next steps, and large file restrictions.

+

With the release of GitHub Desktop 1.6, we’re addressing the question we constantly ask ourselves after we finish a task: “What’s next?”. This is the first iteration intended to keep you in your groove so that you can share your code with your team as quickly as possible. We’ve provided guidance for onboarding and suggestions for what actions to take depending on where you are in your workflow.

+

Get started faster

+

For past versions, once you’ve downloaded Desktop and completed the setup, you were left without additional guidance. Because the next steps weren’t clear, our users weren’t sure how to get started. With the new onboarding workflow, you’ll find steps to help you add your first repository and get started building software more quickly.

+

Guidance to help you get started faster

+

Suggested next steps to keep you moving forward

+

Often, we’ve seen users struggle with how they should use the app when there are no changes. What state is my repository in? What should I do next? Should I publish my branch or pull new changes from GitHub? How do I view my files?

+

In 1.6, when there are no changes, GitHub Desktop will offer a few different options for useful next steps based on your last action in the application. If you’ve just committed, it’s likely you’ll want to push your branch to GitHub. Or maybe you’re just picking up a project, and you want to pull down the latest changes to view them in your editor. Depending on where you are in the process, this new feature will help you keep your momentum and continue shipping.

+

Suggested next steps in action

+

Support around large file restrictions

+

We’re also excited to highlight a feature that addresses a pain point for many users around large file restrictions. Our support team has been fielding questions about how to address GitHub’s restriction on files greater than 100MB. Starting today, if you try to commit a large file into your repository in Desktop, we’ll alert you and provide the option to back out of your commit or get set up on Git LFS.

+

This feature wouldn’t have been possible without one of our open source community members, @Daniel-McCarthy. He recognized the level of impact this would have, worked with our team to determine the best way to solve the problem, and then submitted a pull request. Thanks for making GitHub Desktop awesome @Daniel-McCarthy! We love our open source contributors <3.

+

Stay tuned

+

As with all of our features, we’ll continue to iterate on these based on feedback from you. We’re excited to continue our work making developers happier and more productive in 2019!

+

Try out the latest improvements in Desktop 1.6

+ +
+ + +
+
+

+ Written by

+
+ +
+
+ + +
+
+
+

+ Related posts

+
+ + + +
+
+ +
+
+ +
+
+
+
+ +
+ +
+ + + + + + + + + + + + + + diff --git a/.ui-os/research/runs/windows-winui3-standard-20260813/objects/ms-accessibility-overview-16e36128ea2b.html b/.ui-os/research/runs/windows-winui3-standard-20260813/objects/ms-accessibility-overview-16e36128ea2b.html new file mode 100644 index 0000000..10d968c --- /dev/null +++ b/.ui-os/research/runs/windows-winui3-standard-20260813/objects/ms-accessibility-overview-16e36128ea2b.html @@ -0,0 +1,1673 @@ + + + + + Accessibility overview - Windows apps | Microsoft Learn + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + + Skip to main content + + + + + + + + + +
+ + + +
+ + +
+
+ +
+ + +
+
+
+ + + +
+ +
+ +
+
+ + +
+
+
+
+ +
+
+ +
+ + + +
+
+ + + +
+ + + + + + +
+ + + +
+ + + + + + + + + + + + + + + + Edit + + +
+ + + + + + +
+
+
+ +
+
+ + + + +

Accessibility overview

+ + + +
+
+ + +
+ +
+
+ + + +

This topic introduces concepts and technologies related to building accessible Windows apps.

+

Accessible Windows applications support not only people with disabilities (both temporary and permanent) but also those with personal preferences, specific work styles, or situational and environmental constraints (such as shared work spaces, low bandwidth, bright sunlight, noisy or quiet surroundings, while cooking, and so on).

+

The guidance is written for development teams that treat accessibility as a core quality requirement and use automated accessibility checks as part of regular engineering workflows. Use these topics to define accessibility expectations early, validate them continuously, and prevent regressions as features evolve.

+

Many disabilities, including impaired mobility, vision, color perception, hearing, speech, cognition, and literacy, can be addressed by providing:

+
    +
  • Support for keyboard interactions and screen readers.
  • +
  • Support for user customization, such as font, zoom setting (magnification), color, and high-contrast settings.
  • +
  • Alternative or supplemental UI.
  • +
+

XAML controls provide built-in support for keyboard access and assistive technologies such as screen readers. This built-in support enables a basic level of accessibility that you can customize through various properties. If you are creating your own custom XAML components and controls, you can also add similar support to those controls by using an *automation peer- (for more info, see Custom automation peers).

+

In addition, data binding, style, and template features let you dynamically support alternative UI and changes to display settings.

+

UI Automation

+

Accessibility support comes primarily from the integration of the Microsoft UI Automation framework. That support is provided through base classes and the built-in behavior of the class implementation for control types, as well as an interface representation of the UI Automation provider API. Each control class uses the UI Automation concepts of automation peers and automation patterns that report the control's role and content to UI Automation clients. The app is treated as a top-level window by UI Automation, and through the UI Automation framework all the accessibility-relevant content within that app window is available to a UI Automation client. For more info about UI Automation, see UI Automation Overview.

+

Assistive technology

+

Many accessibility needs are met by assistive technology products installed by the user or by tools and settings provided by the operating system. This includes screen readers, screen magnifiers, and high-contrast settings.

+

Assistive technology products include a wide variety of software and hardware. These products work through the standard keyboard interface and accessibility frameworks that report information about the content and structure of the UI to screen readers and other assistive technologies. Examples of assistive technology products include:

+
    +
  • The On-Screen Keyboard (OSK), or software keyboard, which lets people use a pointer instead of a hardware keyboard to type text.
  • +
  • Voice-recognition software, which converts spoken words into typed text.
  • +
  • Screen readers, which convert text into spoken words or formats like Braille.
  • +
  • The Narrator screen reader, built into Windows, has a touch mode that can perform screen reading tasks through touch gestures.
  • +
  • Programs or settings that adjust the display, for example high contrast themes, dots per inch (dpi), or the Magnifier tool.
  • +
+

Apps that have good keyboard and screen reader support usually work well with various assistive technology products. In many cases, a Windows app works with these products without additional modification of information or structure. However, you may want to modify some settings for optimal accessibility experience or to implement additional support.

+

See Accessibility testing for how to test basic accessibility scenarios with assistive technologies.

+

Screen reader support and basic accessibility information

+

Screen readers provide access to text within an app by rendering it in another format, such as spoken language or Braille output. The exact behavior of a screen reader depends on the software and how the user configured it.

+

For example, some screen readers read the entire UI when the user starts or switches to an app, which enables the user to receive all informational content before attempting to navigate it. Some screen readers also read the text associated with an individual control when it receives focus during tab navigation. This enables users to orient themselves as they navigate among the input controls of an application. Narrator is an example of a screen reader that supports both behaviors.

+

The most important information that a screen reader or any other assistive technology needs in order to help users understand or navigate an app is an accessible name for each element in an app. In many cases, a control or element already has an accessible name derived from other property values, such as an element that supports and displays inner text. For other elements, you might need to provide an accessible name through the element structure. And sometimes you need to explicitly provide the accessible name. For more details on how these derived values work in common UI elements, and for more info about accessible names in general, see Expose basic accessibility information.

+

There are several other automation properties available (including the keyboard properties described in the next section). However, not all screen readers support all automation properties, so you should test all appropriate automation properties with a variety of screen readers.

+

Keyboard support

+

Building keyboard accessibility (for traditional, modified, or keyboard emulation hardware) into your app, helps users who are blind, have low vision, or have motor control issues, to navigate through and use the full functionality of your app. It also lets users without disabilities choose the keyboard for navigation due to preference or efficiency.

+

The basic XAML control model provides built-in keyboard support including tab navigation, text input, and control-specific support. The elements that serve as layout containers (such as panels) use the layout order to establish a default tab order and provide an accessible representation of the UI. ListView and GridView controls provide built-in arrow-key navigation. Button controls handle the Spacebar or Enter keys for button activation.

+

For more info about all the aspects of keyboard support, including tab order and key-based activation or navigation, see Keyboard accessibility.

+

Media and captioning

+

You typically display audio-visual media through a MediaPlayerElement object. For accessibility purposes, provide controls that enable users to play, pause, and stop the media, and also include captions or alternative audio tracks.

+

Accessible text

+

When you design and implement text in your app, focus on these three core accessibility requirements.

+
    +
  • Assistive technologies must be able to determine whether text should be read during tab-sequence navigation or as part of the overall document content. You can influence this behavior by choosing the correct text element and setting its properties appropriately. Because each text element maps to a specific purpose and often to a corresponding UI Automation role, using the wrong element can expose the wrong role and create a confusing experience for assistive technology users.
  • +
  • Many users have low vision or color-vision deficiencies and cannot read text reliably unless there is sufficient contrast between text and background. This impact can be easy to underestimate during design. Following established contrast guidance helps prevent unreadable text for these users. For more info, see Accessible text requirements.
  • +
  • Text that is too small is difficult for many users to read. Start with a reasonable default text size, and ensure your app works correctly with system text and display scaling. This is especially important in UIs that contain large amounts of text or dense visual layouts.
  • +
+

Supporting high-contrast themes

+

XAML controls get their visual appearance from theme resource dictionaries, including high-contrast theme resources. When a user enables a high-contrast mode, controls automatically resolve to the appropriate high-contrast resources. To preserve this behavior, avoid styling approaches that block theme resource lookup, such as hard-coded colors or explicit styles that prevent high-contrast theme values from overriding your custom values. For more info, see High-contrast themes.

+

Design for alternative UI

+

In many cases, you can communicate essential information more effectively by using multiple cues. For example, combine icons with color to support users with color-vision deficiencies, and pair visual alerts with sound to support users who are deaf or hard of hearing.

+

When needed, provide an alternative accessible UI that removes nonessential visuals and animation and simplifies interaction flows. The following code example shows how to switch one UserControl for another based on a user setting.

+
<StackPanel x:Name="LayoutRoot" Background="White">
+
+  <CheckBox x:Name="ShowAccessibleUICheckBox" Click="ShowAccessibleUICheckBox_Click">
+    Show Accessible UI
+  </CheckBox>
+
+  <ContentControl x:Name="ContentBlock">
+    <local:ContentPage/>
+  </ContentControl>
+
+</StackPanel>
+
+
private void ShowAccessibleUICheckBox_Click(object sender, RoutedEventArgs e)
+{
+    if (sender is CheckBox checkBox)
+    {
+        ContentBlock.Content = checkBox.IsChecked == true
+            ? new AccessibleContentPage()
+            : new ContentPage();
+    }
+}
+
+

Assistive technology support in custom controls

+

When you create a custom control, implement or extend one or more AutomationPeer subclasses to provide accessibility support. In some cases, reusing the same peer class as the base control can provide acceptable baseline automation behavior for your derived control. However, you should validate this through testing, and in most cases you should still implement a dedicated peer so it can report the correct class name and behavior for your custom control. For implementation guidance, see Custom automation peers.

+

Assistive technology support in apps that support XAML / Microsoft DirectX interop

+

By default, Microsoft DirectX content that's hosted in a XAML UI (using SwapChainPanel or SurfaceImageSource) is not accessible. The XAML SwapChainPanel DirectX interop sample (archived legacy sample) shows how to make hosted content accessible through UI Automation by creating an AutomationPeer for the DirectX content. This technique makes the hosted content accessible through UI Automation.

+

Verification and publishing

+

Treat accessibility verification as an ongoing engineering activity, not a final QA pass. Run automated checks for every build where possible, and pair them with targeted manual assistive technology validation for critical user journeys.

+

For more info about accessibility declarations and publishing your app, see Accessibility in the Store.

+

Examples

+
+

Open the WinUI 3 Gallery app and see the following Accessibility principles in action:

+ +
+
+ + + + + +
WinUI 3 Gallery iconThe WinUI 3 Gallery app includes interactive examples of WinUI controls and features. Get the app from the Microsoft Store or browse the source code on GitHub.
+
+ + +
+ +
+ + +
+ + + + + + + + + + + + + +
+ +
+ + + + + + + + + +
+ + + +
+ +
+ + +
+
+
+