# Native Shell Design — Functional and Visual Spec

**Status:** Approved and implemented · 2026-07-16  
**Scope:** The shared Angular renderer when packaged for Windows, Linux, macOS, and Android. The hosted web app remains behaviorally unchanged.  
**Out of scope:** Search/result-card redesign, purchase-plan information architecture, custom window-control glyphs, iOS, and general rebranding.

## 1. Problem

The packaged applications currently reuse the hosted app's full brand header without adapting it to their native containers.

- Desktop shows an operating-system title bar and then a second, web-style brand header. The duplicated chrome makes the renderer feel like a site inside a window.
- The current header is tall and promotional: large icon, full product title, tagline, and generous vertical padding. That works as a web masthead but consumes disproportionate space in desktop and especially mobile applications.
- Android's system status bar and the app header form two adjacent surfaces with slightly different colors. The seam is visible, particularly in dark mode and on devices that enforce edge-to-edge rendering.

The design should make the top of each packaged app read as one intentional shell while preserving native window and system behavior.

## 2. Design principles

1. **One top surface.** A user should see one app bar, not a native bar followed by a web masthead.
2. **Native controls, owned composition.** The app owns the surface around system controls but does not redraw or imitate those controls.
3. **Content first.** The shell identifies the app and exposes `Pirkumu plāns`; it does not repeat a marketing tagline on every screen.
4. **Platform-adaptive, not platform-themed.** Typography, colors, and actions stay shared. Insets, density, dragging, and native controls adapt to the host.
5. **Safe by construction.** Window controls, display cutouts, status bars, gesture areas, keyboard navigation, and touch targets must not overlap content.

## 3. Chosen direction

### 3.1 Desktop: integrated title bar with native controls

Use Electron's hidden title-bar mode and Window Controls Overlay rather than a fully frameless window:

- **Windows and Linux:** `titleBarStyle: 'hidden'` with `titleBarOverlay` enabled. Electron keeps native minimize, maximize/restore, and close controls in the system-defined order.
- **macOS:** `titleBarStyle: 'hiddenInset'`. The native traffic lights remain visible and receive macOS-specific leading clearance.
- The renderer's app bar becomes the draggable title-bar surface. Interactive descendants, including `Pirkumu plāns`, are explicitly non-draggable.
- The draggable surface supports native move, double-click maximize/restore, snapping, full-screen transitions, and system accessibility through Electron/OS behavior.
- Do not use `frame: false` and do not implement custom minimize/maximize/close buttons in HTML.

This produces a single coherent surface while preserving the conventions and behavior of all three desktop operating systems.

### 3.2 Android: edge-to-edge app bar

Treat the status bar as part of the app composition instead of a separately colored strip:

- Draw the header surface behind a transparent system status bar.
- Pad header content by the actual top/left/right safe-area insets so icons, cutouts, and rounded corners never cover controls.
- Use Capacitor 8's bundled `SystemBars` API and injected `--safe-area-inset-*` variables. Do not add the legacy Status Bar plugin.
- Set system icon appearance to dark icons in the light theme and light icons in the dark theme, including live OS theme changes.
- Keep the gesture navigation bar transparent. Continue applying the bottom safe-area inset to the purchase-plan sheet and any bottom-aligned interactive content.

The result is one uninterrupted header color behind both the Android notification indicators and app controls.

## 4. Shell anatomy

The packaged-app header contains only:

1. compact engine mark;
2. product title;
3. flexible draggable/empty space on desktop;
4. `Pirkumu plāns` action and count badge.

The tagline `Ievadi detaļas numuru — salīdzini cenas Latvijas veikalos` is removed from packaged shells. It may remain in the hosted web masthead.

Use the shorter shell title **`Auto detaļu salīdzinātājs`**, matching the existing Electron window title. The longer page/document title remains available to the hosted page and assistive technology.

### Desktop metrics

- App-bar height: **48 px**.
- Horizontal padding: **12 px**, plus native-control exclusion zones.
- Mark: **28 × 28 px**, 8 px corner radius; engine glyph 18 px.
- Title: 14 px, semibold, single line.
- `Pirkumu plāns`: compact outline/ghost action, 32 px high. Keep its text at normal desktop widths; collapse to icon + badge only when space is constrained.
- Bottom separator: one subtle border using the shared `border` token.
- The content column begins 20 px below the shell rather than inheriting masthead spacing.

Native-control clearance must come from Window Controls Overlay geometry/CSS environment values where available. macOS receives an explicit traffic-light leading region. No clickable or readable content may sit beneath window controls.

### Android metrics

- Header surface height: **56 px plus the top safe-area inset**.
- Content row: 56 px, 12–16 px horizontal padding after left/right safe-area insets.
- Mark: **32 × 32 px**, engine glyph 20 px.
- Title: 16 px, semibold, single line with ellipsis.
- `Pirkumu plāns`: 48 × 48 px icon action with count badge; no visible text label. It retains the full accessible label.
- The current header tagline is omitted.
- The search form begins 16 px below the app bar.

The header remains visually fixed at the top while results scroll. It should not collapse in this iteration; collapsing adds motion and state without solving a current usability problem.

### Hosted web

The hosted web app keeps the current non-draggable masthead in this change. Shared colors and component behavior remain identical, but desktop-only control clearance and Android safe-area padding must never leak into the hosted layout.

## 5. Color and theme behavior

- The shell uses the shared `card` surface and `card-foreground` text tokens in both themes.
- Electron's title-bar overlay color and symbol color are synchronized with those same theme surfaces. Theme changes update the overlay without recreating the window.
- Android's transparent status bar reveals the exact header surface; no separately approximated native color is used.
- System icons must meet contrast requirements in both light and dark OS themes.
- Startup background uses the active shell/background color closely enough to avoid a white flash before Angular paints. Exact splash-screen artwork is unchanged.

## 6. Platform identification

Platform-specific layout must use explicit host capabilities/build configuration, not user-agent parsing:

- Electron is identified by `window.comparatorDesktop`.
- The Android build supplies an Android host marker through its dedicated Angular configuration/runtime.
- The app root exposes a stable `data-host="web|desktop|android"` attribute (or equivalent classes) for CSS and testing.

Only shell presentation branches by host. Search, filters, results, purchase-plan behavior, strings, and persistence remain shared.

## 7. Interaction and accessibility requirements

- Desktop users can drag the window from all unused app-bar space.
- Buttons, links, inputs, and badges inside the app bar never initiate dragging.
- Native controls remain operable by pointer, keyboard, accessibility APIs, window-manager shortcuts, and touch where supported.
- The plan action retains a descriptive accessible name on every platform; the count badge is included in or adjacent to that name without being announced ambiguously.
- Touch targets on Android are at least 48 × 48 px.
- At 200% desktop zoom and at Android's largest supported font setting, the title truncates before actions overlap. The plan action remains reachable.
- Focus indication and current light/dark contrast behavior are preserved.

## 8. Responsive and window-state behavior

- Desktop shell must work at the existing 780 px minimum width and at maximized/full-screen sizes.
- Maximized Windows/Linux windows must not show accidental outer gaps or draggable regions over the system controls.
- macOS full-screen mode keeps native traffic-light/full-screen behavior.
- Linux behavior is verified on at least one common desktop environment; visual differences in native controls are accepted, overlap or missing controls are not.
- Android is verified in portrait and landscape, with a display cutout if available, gesture navigation, three-button navigation, keyboard open, and light/dark themes.
- The purchase-plan sheet continues to extend to the visual edges while keeping its header and bottom controls inside safe areas.

## 9. Acceptance criteria

### Desktop

- Only one top bar is visible beneath/around native window controls.
- No tagline appears in the packaged desktop shell.
- Drag, double-click maximize/restore, minimize, maximize, restore, close, snap, and full-screen behaviors work normally.
- No app content overlaps native controls on Windows, Linux, or macOS.
- The title-bar surface, symbols, renderer header, and startup background are coherent in light and dark themes.
- The hosted web header does not acquire draggable regions or desktop control padding.

### Android

- The status bar is transparent and the app header's exact surface continues behind it; there is no differently shaded strip.
- Status-bar icons have correct contrast in light and dark themes and update when the OS theme changes.
- Header content is not hidden by status icons, camera cutouts, rounded corners, or landscape insets.
- Gesture and three-button navigation do not cover plan-sheet or page controls.
- The compact header fits a narrow phone without hiding the `Pirkumu plāns` action.

### Regression

- Search, store progress, filters, solve flows, external links, and purchase-plan operations behave exactly as before.
- Web unit tests, root TypeScript/tests, desktop smoke/package smoke, Android lint, and Android debug assembly pass.

## 10. Verification artifacts

Implementation review should include paired screenshots, not only automated checks:

- Windows: normal and maximized, light and dark.
- Linux: normal and maximized.
- macOS: normal and full-screen, or an owner-run checklist if no Mac runner is available.
- Android: portrait and landscape, light and dark, including one screenshot with the plan sheet open.
- Hosted web: desktop-width regression screenshot.

## 11. Rejected alternatives

### Keep the native desktop frame and only shrink the web header

This reduces height but preserves the fundamental two-bar composition. It is the lowest-risk fallback if a specific Linux window manager exposes an Electron overlay defect, not the primary design.

### Fully custom desktop frame and HTML window controls

This can look identical across platforms, but identical is not the goal. It would make the app responsible for control order, hover/pressed states, maximize/restore state, high contrast, scaling, snapping affordances, accessibility, and macOS traffic-light conventions. The maintenance and regression surface is not justified here.

### Give Android's status bar a matching opaque color

On modern Android targets the status bar is edge-to-edge and transparent by design; direct status-bar colors are deprecated or ineffective on Android 15+. Drawing the real app surface behind the system bar avoids approximate color conversion and follows the platform direction.

## 12. Implementation boundary after approval

After this spec is approved, implementation should be delivered as one shell-focused change:

1. add explicit host identification and responsive app-bar markup;
2. integrate the Electron title-bar overlay and theme synchronization;
3. configure Android `SystemBars`, safe-area consumption, and live icon style;
4. add focused platform/layout tests;
5. run automated gates and capture the verification screenshots above.

Any broader redesign of search controls, result cards, navigation, branding, or plan content requires a separate follow-up spec.