# Semi UI shell vNext — Design QA

- Source visual truth: `/Users/lingniu/.codex/attachments/e33960ff-ed87-40f8-9da6-8e6615a653c5/image-1.png`
- Desktop implementation: `/tmp/lingniu-ui-audit-20260720/14-after-desktop-pass2.png`
- Mobile implementation: `/tmp/lingniu-ui-audit-20260720/05-after-mobile-pass2.png`
- Mobile secondary navigation: `/tmp/lingniu-ui-audit-20260720/06-mobile-more.png`
- Mobile cross-page state: `/tmp/lingniu-ui-audit-20260720/07-mobile-statistics.png`
- 2K implementation: `/tmp/lingniu-ui-audit-20260720/15-after-2k.png`
- Full-view comparison: `/tmp/lingniu-ui-audit-20260720/16-reference-comparison-final.png`
- Focused navigation comparison: `/tmp/lingniu-ui-audit-20260720/17-sidebar-comparison.png`
- Viewports: 1440 × 900, 2560 × 1440, 390 × 844
- State: authenticated mock administrator; Monitor list mode with four vehicles

## Comparison scope

The supplied Semi image is a different product and data state, so it is not a
pixel-for-pixel content specification. The comparison treats its application
shell, navigation rhythm, whitespace, typography, surface treatment and
interaction hierarchy as the visual truth. The vehicle table keeps the width
required by the operational task instead of copying the reference's team rail.

## Findings and iteration history

### Pass 1

- **[P1] Layered navigation chrome made the shell feel heavy.**
  - Evidence: the baseline used a soft square behind every icon, gradient
    selection fills and several shadow layers; the reference uses quiet icons,
    one selected row and neutral white space.
  - Fix: removed icon plates and gradients, simplified hover/selected states,
    aligned group labels and introduced one restrained active indicator.
  - Post-fix evidence: focused navigation comparison.
- **[P1] Mobile hierarchy was too compressed.**
  - Evidence: `/tmp/lingniu-ui-audit-20260720/02-before-mobile.png` used an
    unbranded title bar, 9px navigation labels and truncated vehicle facts.
  - Fix: added the supplied brand mark, rebuilt the bottom navigation rhythm,
    increased the essential text scale and redistributed the four vehicle
    metrics evenly without reducing the visible vehicle count.
  - Post-fix evidence: mobile implementation and mobile cross-page state.
- **[P2] Page transitions rebuilt the content container.**
  - Evidence: the shell keyed the entire content container by pathname.
  - Fix: kept the content container stable and animated only the newly mounted
    route surface; reduced-motion users receive no transition.
  - Post-fix evidence: Monitor → Mileage route change retained the shell and
    updated the title, active navigation and page content.

### Pass 2

- **[P2] Collapsed sidebar hid its reopen affordance.**
  - Evidence: `/tmp/lingniu-ui-audit-20260720/08-desktop-collapsed.png` showed
    an empty collapse footer because a legacy selector hid every nested span,
    including Semi's icon wrapper.
  - Fix: restored only the icon wrapper, rotated the chevron and preserved the
    text-hidden compact state.
  - Post-fix evidence:
    `/tmp/lingniu-ui-audit-20260720/11-desktop-collapsed-final.png`; browser
    state changed from `收起侧栏` to `展开侧栏` and back.
- **[P2] Desktop data type remained optically smaller than the reference.**
  - Evidence: first full-view comparison showed the header, filter controls,
    table headings and primary row values losing hierarchy at 1440px.
  - Fix: increased the desktop shell header to 76px, raised navigation and
    table type sizes, and increased control and row heights while retaining
    the operational density.
  - Post-fix evidence: final full-view comparison and 2K implementation.

## Required fidelity surfaces

- **Fonts and typography:** system/PingFang stack is appropriate for Chinese;
  page titles, navigation, controls and primary values now form a clear scale.
  Tabular figures are enabled for telemetry. No actionable P0–P2 issue remains.
- **Spacing and layout rhythm:** the shell uses a 220px desktop rail, 76px
  desktop header, 56px mobile header and 64px safe-area-aware mobile
  navigation. Cards use quieter 9–10px radii and one-pixel boundaries.
- **Colors and tokens:** white surfaces, `#f5f6f7` canvas, `#e6e8eb` borders
  and Semi blue `#0064fa` now match the reference's foreground/background
  balance. Operational green/red tones remain semantic.
- **Image quality and assets:** supplied brand SVG assets are used directly.
  No placeholder illustration, custom SVG or CSS-drawn brand asset was added.
- **Icons:** all shell actions use the existing Semi icon family. Selected,
  hover, pressed and collapsed states remain optically aligned.
- **Copy and content:** each page title now has a short task description on
  desktop. Mobile keeps only the title to protect first-screen task density.
- **Responsiveness:** 390px mobile, 1440px desktop and 2560px 2K states were
  rendered without overlap, hidden persistent controls or shell overflow.
- **Accessibility:** semantic navigation names and page headings remain intact;
  mobile targets are at least 42px in the shell, focus styles are preserved,
  and `prefers-reduced-motion` disables the new transitions. Screenshot review
  cannot prove full assistive-technology compatibility.

## Interaction and console checks

- Mobile More opens a Semi SideSheet with grouped analysis and governance
  destinations, then closes without changing page state.
- Mobile Mileage navigation changes URL, heading and active tab and renders the
  fixed-column mileage matrix.
- Desktop sidebar collapses and expands with a visible affordance in both
  states.
- No framework error overlay or application runtime error was observed.
  Semi UI's known React `findDOMNode` development deprecation warning remains.

## Follow-up polish

- P3: continue raising secondary explanatory text on legacy page-specific
  surfaces as each page enters the Semi migration.
- P3: consolidate older workspace CSS overrides after the visual migration is
  complete; removing them now would expand regression scope without changing
  this shell's rendered result.

final result: passed