crank/__REVIEW_UX.md

UX and Copy Remediation Plan

Purpose

This document defines the UX, copywriting, and localization cleanup track for the current UI. It is separate from __REVIEW_FRONT.md:

• __REVIEW_FRONT.md focuses on frontend architecture, safety, module structure, and delivery mechanics;
• __REVIEW_UX.md focuses on user-facing clarity, consistency, language quality, and product honesty.

The goal is to remove developer-facing language, broken localization patterns, misleading placeholders, and half-functional UI signals from the product surface.

Core Principle

The UI must speak to operators, not to developers.

That means:

• no implementation jargon such as "slice", "wired", "resolved at runtime" unless the user truly needs it;
• no debug-style booleans in user-visible success messages;
• no fake functionality presented as nearly available unless the user can act on it;
• no mixed EN/RU phrasing where the product can speak normally in one language.

Scope

This plan covers:

1. English copy cleanup;
2. Russian copy cleanup;
3. pluralization support;
4. login UX cleanup;
5. settings honesty cleanup;
6. command palette decision and follow-through;
7. wizard message polish;
8. terminology consistency rules.

Track A: English Copy Quality

Problem Types

A1. Literal formatting markers leaking into UI

Examples:

• apikeys.callout.body
• wizard.step2.auth_profile_hint

Current issue:

• backticks are rendered literally as characters;
• they do not become semantic formatting in HTML;
• the user sees developer-style markdown notation.

Decision

Do not use markdown-style backticks in translation strings rendered through normal text nodes.

Allowed alternatives:

• plain text without emphasis;
• explicit <code> only when rendered through a trusted HTML path that is intended for markup;
• a dedicated visual class if code-like styling is actually needed.

Required fixes

• apikeys.callout.body
  • replace `Last used` with plain text or a proper code-like span in a trusted template
• wizard.step2.auth_profile_hint
  • remove `execution_config.auth_profile_ref` from user-facing copy

Preferred rewrites

Instead of:

• Last used updates after successful MCP authentication.

Use:

• Last used updates after a successful MCP call.

Instead of:

• Selected profile will be resolved at runtime and attached through execution_config.auth_profile_ref.

Use:

• The selected auth profile is applied automatically when this tool runs.

A2. Internal planning jargon visible to users

Examples:

• secrets.profiles.empty_body

Current issue:

• next slice is a delivery-planning term, not a product term.

Decision

All planning jargon must be removed from UI strings.

Forbidden user-facing phrases:

• next slice
• this build does not pretend
• wired yet
• not wired
• backed by
• resolved at runtime unless the user truly configures runtime behavior

Preferred rewrite

Instead of:

• Create auth profiles in the next slice to bind secrets to upstream authentication.

Use:

• Create auth profiles in the Wizard when configuring an operation.

A3. Unsafe or awkward symbols in plain text

Examples:

• agents.drawer.recommendation

Current issue:

• <15 appears directly in text and should not rely on plain text rendering safety.

Decision

Prefer natural language over symbolic shorthand in user guidance.

Preferred rewrite:

• LLMs usually work best when an agent has fewer than 15 tools.

A4. Debug-style status messages

Examples:

• wizard.test.window_completed_body
• wizard.test.session_started_body

Current issue:

• booleans like true/false are shown directly to users;
• milliseconds are exposed when approximate guidance is enough.

Decision

User-visible status text must describe outcome, not internal flags.

Required rewrites

wizard.test.window_completed_body

Current:

• Window complete: {window_complete}. Truncated: {truncated}. Has more: {has_more}.

Target behavior:

• message should describe:
  • how many items were collected;
  • whether data was truncated;
  • whether more data is available.

Preferred shape:

• Collected {count} items.
• Collected {count} items. Results were truncated.
• Collected {count} items. More data is available if you extend the window or continue polling.

wizard.test.session_started_body

Current:

• Poll after {poll_after_ms} ms from the stream sessions view.

Preferred:

• Session started. Check Stream sessions in a few seconds.

A5. Awkward English phrasing

Examples:

• logs.range.1h: Last 1 hour

Preferred:

• Last hour

Acceptance Criteria

• no markdown backticks in plain-text translations;
• no delivery jargon in user-facing EN strings;
• no debug booleans in wizard result messaging;
• obvious awkward phrases are normalized to natural English.

Track B: Russian Copy Quality

Problem Types

B1. Missing keys

Known example:

• wizard.step2.auth_basic exists in EN and must exist in RU with product-quality copy.
• secrets.profiles.subtitle_count in the RU section is effectively still English and must be treated as a translation-parity defect, not just as weak wording.

Decision

Translation parity is mandatory for both locales.

Every newly added EN key must either:

• be translated in RU in the same change;
• or fail verification.

Required future safeguard

Add a translation parity checker to detect:

• missing RU keys;
• missing EN keys;
• exact duplicate placeholder keys if unintended.

B2. Russian pluralization is currently structurally incomplete

Known examples:

• workspace_setup.member_count
• workspace_setup.members.days_ago
• secrets.used_by_count

Current problem:

• templates like {count} участников fail for 1;
• templates like {count} дня назад fail for 5.

Decision

Introduce plural helpers based on Intl.PluralRules.

Target API

In i18n.js, add a helper such as:

function tPlural(count, forms) {
  // locale-aware choice
}

Where:

• English uses one / other
• Russian uses one / few / many

Target translation style

Instead of one flat string:

• workspace_setup.member_count: '{count} участников'

Use grouped forms, for example:

• workspace_setup.member_count.one
• workspace_setup.member_count.few
• workspace_setup.member_count.many

Or an equivalent plural storage format, as long as the API is stable.

First keys to migrate

• workspace_setup.member_count
• workspace_setup.members.days_ago
• secrets.used_by_count
• secrets.profiles.subtitle_count
• wizard.step3.grpc.streaming_hidden
• wizard.grpc.services_found

B3. Developer calques and transliterated jargon

Examples:

• резолвиться
• в следующем срезе
• notification settings
• lifecycle
• usage references
• advanced future integrations

Decision

Russian copy should be plain product Russian, while keeping real technical terms intact.

Keep in English only true technical terms such as:

• gRPC
• WSDL
• JSON
• Bearer
• Query
• Mutation
• WebSocket

Rewrite non-terms into Russian.

Required rewrites

wizard.step2.auth_profile_hint

Instead of:

• Выбранный профиль будет резолвиться в runtime...

Use:

• Выбранный профиль применяется автоматически при каждом вызове инструмента.

secrets.callout.body

Remove mixed language and rewrite as:

• После создания или ротации API возвращает только метаданные, поэтому на этой странице доступны управление секретами и просмотр их использования.

secrets.hint.generic

Avoid:

• advanced future integrations

Use:

• Подходит для произвольного JSON, если секрет нужно использовать в нестандартной интеграции.

workspace_setup.create.footer

Replace:

• Owner

With:

• Владелец

secrets.profiles.subtitle_count

Current RU text is still English-like and must be translated fully.

Acceptance Criteria

• no missing translation keys between EN/RU;
• Russian plural forms are grammatically correct;
• no developer calques remain in user-facing RU strings;
• role names are translated consistently.

Track C: Login Experience Cleanup

Problem

The login screen currently highlights unavailable functionality:

• Forgot password
• Google SSO
• Request access

all with Planned badges.

This creates the impression of unfinished product state on the very first screen.

There is also a developer-style note explaining what is not wired.

Decision

The login page must present only working entry points.

Recommended product behavior

Production/default mode

Show:

• email
• password
• sign-in button

Optionally show a single unobtrusive note:

• Password reset and SSO will be added later.

But only if product really needs that promise visible.

Preferred option:

• hide non-working actions completely.

Development-only mode

If the team wants visibility for future auth work, gate it behind a development flag.

Example:

• window.CrankFeatures.showPlannedAuth

Required changes

Remove or gate:

• disabled Forgot password?
• disabled Google SSO
• disabled Request access
• login.password_only developer note from production HTML

Acceptance Criteria

• login page does not lead with unavailable features;
• no developer-facing implementation note is shown in normal product mode.

Track D: Settings Honesty Pass

Problem

The settings page still contains a full Notifications section and other planned capability language that reads like UI cargo cult:

• detailed controls that do nothing;
• developer-style subtitle text;
• explanation written from the implementation perspective.

Decision

If a settings area is not functional, it should not be represented as a near-complete interactive configuration panel.

Product rule

There are only two acceptable states:

1. fully functional configuration;
2. compact informational placeholder.

Avoid:

• large fake forms;
• multiple toggles with Planned badges;
• controls that imply persistence when none exists.

Required changes

settings.page.subtitle

Current EN subtitle speaks about capabilities being visible but not wired.

Replace with a user-centered subtitle such as:

• Manage your profile, password, and workspace settings.

Notifications section

Replace the current detailed pseudo-settings with one compact informational card:

• title
• short explanation
• possibly one sentence: Notification routing and per-user preferences will be added later.

No fake toggles.

Planned security capabilities

Keep only if:

• they are clearly informational;
• they do not look like interactive controls.

If they look interactive, collapse them into one planned card as well.

Acceptance Criteria

• settings page describes what users can do now;
• non-functional areas are compact and clearly informational;
• no fake detailed settings remain.

Track E: Command Palette Decision

Problem

⌘K is visible in the navigation, but there is no working command palette attached to it.

This is worse than not showing it at all.

Decision Matrix

Option 1: Remove it

Choose this if:

• there is no actual command palette implementation;
• there is no near-term product need for it;
• keeping the hint only creates false expectation.

Option 2: Implement it

Choose this only if the product has a real command list worth exposing.

Minimum useful scope:

• go to Operations
• go to Agents
• go to API Keys
• go to Secrets
• go to Logs
• go to Usage
• go to Settings
• switch workspace
• create new operation
• create new agent

Current recommendation

Based on current code surface, remove it first.

Reason:

• there is visible affordance;
• there is no working interaction;
• product already has enough active work without adding a new shell feature mid-stream.

If later implemented, it should land as its own feature:

• feat/frontend-command-palette

Acceptance Criteria

• either ⌘K is removed everywhere;
• or a real command palette exists and is keyboard-accessible.

No middle state.

Track F: Wizard Messaging and Step Clarity

Problem

Wizard copy still includes:

• technical internal language;
• poor plural handling;
• insufficiently clear streaming result messages;
• protocol-step context that changes without enough explicit signaling.

Required changes

F1. Auth selector copy

Remove implementation references such as:

• execution_config.auth_profile_ref

Replace with operator language:

• The selected auth profile is applied automatically when the tool runs.

F2. Streaming result messages

Replace technical booleans and milliseconds with outcome-focused language.

For:

• window
• session
• async_job

F3. gRPC plural and summary strings

Fix:

• streaming method(s)
• 1 services

Use locale-aware pluralization helpers.

F4. Step-3 protocol clarity

The sidebar label changing per protocol is useful, but not always obvious enough after protocol switching.

Recommended UI change:

• add a small protocol badge near the step title on step 3:
  • REST config
  • GraphQL operation
  • gRPC method
  • WebSocket stream
  • SOAP binding

This should exist both:

• in the main pane heading;
• optionally in the sidebar if compact enough.

Acceptance Criteria

• wizard status/result text reads like product UX, not runtime telemetry;
• plural forms are correct;
• step 3 protocol-specific context is explicit.

Track G: Terminology Rules

Problem

The UI currently mixes three categories without a clear rule:

1. real technical terms;
2. product concepts;
3. implementation jargon.

Terminology Policy

Keep as technical terms

• Query
• Mutation
• gRPC
• REST
• WebSocket
• SOAP
• WSDL
• JSON
• Bearer token

Translate to product language

• workflow
• settings
• usage
• notifications
• workspace
• owner

Never expose as user-facing jargon

• slice
• wired
• resolved at runtime
• metadata only if better phrasing exists
• future integrations
• usage references
• backed by

Acceptance Criteria

• technical terms remain technical;
• implementation jargon disappears from UI.

Track H: Verification and Guardrails

Problem

Without guardrails, translation and UX regressions will return.

Required safeguards

H1. Translation parity check

Add a script/test that verifies:

• EN and RU contain the same key set;
• missing keys fail CI.

H2. Dangerous copy lint

Add a lightweight scan for forbidden phrases in user-facing translations:

• next slice
• wired
• resolved at runtime
• backticks in plain text translations
• (s) plural suffix

This can be a simple repo script at first.

H3. UX regression checklist

Extend manual regression docs with:

• login first impression check;
• no dead nav affordances;
• no fake settings sections;
• pluralization smoke in RU.

Acceptance Criteria

• parity regressions are caught automatically;
• obvious UX copy anti-patterns are detectable before release.

Delivery Order

Recommended order:

1. feat/frontend-ux-review-plan
2. feat/frontend-i18n-remediation
3. feat/frontend-login-simplification
4. feat/frontend-settings-honesty-pass
5. feat/frontend-command-palette-decision
6. feat/frontend-wizard-copy-polish
7. feat/frontend-plural-rules
8. feat/frontend-ux-guardrails

Per-Slice Verification

Each slice should include:

• targeted node --check for touched JS
• targeted Playwright smoke if the affected page already has coverage
• manual locale switch smoke for EN and RU

Additional rules:

• login cleanup must be visually checked on first load;
• plural-rule slice must include sample assertions for RU forms;
• command-palette decision slice must verify no dead ⌘K affordance remains.

Success Definition

This UX cleanup track is complete when:

• the product no longer exposes developer planning language;
• EN and RU feel intentional rather than partially translated;
• plural forms are correct in both locales;
• login shows only meaningful actions;
• settings no longer presents fake detailed controls;
• the command palette affordance is either real or removed;
• wizard status and streaming messages are understandable without internal knowledge.

At that point, the UI stops feeling like a well-built internal tool and starts reading like a finished product surface.