# Japanese Light Theme UI Policy

Date: 2026-06-20

The default GUI is a Japanese light-theme support utility. It should feel like
a calm manufacturer or support-desk tool for diagnosing an audio device, not an
open-source developer demo.

## Design Intent

- Prioritize clarity, trust, and operational safety over technical density.
- Show the current step, target device, capability matrix state, selected test
  condition, and next required action before exposing expert controls.
- Keep risky lifecycle actions visibly gated and explain why disabled actions
  are unavailable.
- Keep raw backend details available for troubleshooting, but do not make them
  the first visual impression.

## Default Language And Tone

- Japanese is the default UI language.
- Primary workflow labels use plain support-utility wording:
  - `出力経路`
  - `対象デバイス`
  - `対応状況確認`
  - `対応状況マトリックス`
  - `テスト条件`
  - `実行 / 書き出し`
  - `記録・安全`
  - `自動診断`
- Avoid playback-app wording that starts with "choose the format you want to
  play." Standard wording should instead say:
  - `このデバイスの対応状況を確認します`
  - `対応しているフォーマットからテスト条件を選択してください`
- Safety messages should be direct and calm. Avoid dramatic wording.
- Backend identifiers, HRESULT values, JSON keys, and raw driver/API names may
  remain English because they are diagnostic evidence.
- When English is selected, application-owned visible UI text must not show
  Japanese. The only intended visible exception is device names or raw
  externally supplied driver strings as reported by Windows or the driver.
  The language selector itself must show `Japanese` / `English` while English
  mode is active.

## Theme

- The app uses a light theme by default.
- Backgrounds should be quiet neutral grays and whites, with restrained blue
  accents for selected state and actions.
- Warning and fault colors should be visible but not visually alarming unless
  a device lifecycle operation is blocked.
- Explanatory copy should use muted text, while fields, selectors, tables, and
  actionable cells should have clearly visible borders, darker header bands, and
  stronger selected/available/error states so inputs do not blend into
  descriptions.
- Cards are not nested. The main layout is a top ribbon, three functional tabs,
  and a single-row bottom action bar. The tabs are Output Path / `出力経路`,
  Test Conditions / `テスト条件`, and Logs / `ログ`.
- Dense diagnostic tables should separate selection from detail: device tables
  stay compact for choosing a device, while API and full device IDs live in the
  selected-device detail area. Format compatibility is split into PCM and DSD
  matrices with short cell labels and full details available on hover/selection.

## Single Workflow

The GUI no longer has separate standard/detail/expert display modes. All users
follow the same strict flow, distributed across three functional tabs:

1. Choose the target API.
2. Refresh only that target API.
3. Select a device from the refreshed API list.
4. Let the app automatically check compatibility for that selected API/device.
5. Select an available matrix cell as the test condition.
6. Adjust signal, API-specific scheduling, lifecycle, logging, and safety
   settings.
7. Run/export the selected condition.

Low-level fields remain available inside this flow. They should not create a
format-first bypass, a different start path, or a second interpretation of the
selected device.

The Output Path tab owns API/device/format selection. Device selection is a
compact table; PCM and DSD format results are separate matrices. The Test
Conditions tab owns signal, buffer/scheduling, lifecycle, automation, and
execution settings. The Logs tab owns diagnostic evidence, realtime state,
errors, and recent logs. This keeps the strict workflow visible without putting
every technical control on screen at once.

## Font Policy

- No font files are bundled.
- At runtime, the app tries Windows-installed Japanese fonts from
  `C:\Windows\Fonts`, currently Yu Gothic/Yu Gothic UI family files first and
  then Meiryo family files.
- The ImGui Japanese glyph range is loaded when a Japanese font is available.
- If no Japanese system font can be loaded, the app falls back to the default
  ImGui font and shows an ASCII/English warning in the top area so the warning
  remains readable even without Japanese glyph coverage.

## Safety-State UI Rules

- While any backend is active, the GUI blocks backend/device/format changes,
  refresh, automation planning/running, and new start commands.
- Changing the requested backend clears the selected device, accepted format,
  and selected matrix condition. Switching between WASAPI shared and WASAPI
  exclusive also requires a fresh API refresh, device selection, automatic
  compatibility check, and matrix-cell selection.
- Capability matrix/test-condition state is separate from run settings.
  Changing the target device, backend/API path, or matrix format invalidates
  the old matrix condition. Changing signal level or duration does not require
  a capability rescan.
- Format revision and run-configuration revision are separate. Backend, device,
  signal mode, sample rate, sample type, valid/container bits, channel count,
  channel mask, and DSD rate stale an accepted format. Frequency, amplitude,
  duration, channel enable/polarity/phase, buffer, lifecycle, logging, and
  automation settings are logged for the next run without forcing a reprobe.
- WASAPI `IAudioClient::GetMixFormat` evidence may be represented as
  reference-only matrix cells and cannot be selected for playback.
- Format selection is matrix-only. Unsupported, unchecked, reference-only, and
  not-applicable cells cannot become startable test conditions.
- Recent on-screen logs are bounded for responsiveness. The full event history
  remains available in the diagnostic bundle.
