Skip to content

0009-adopt-full-mhui-in-main-app.md

Latest commit

 

History

History
139 lines (124 loc) · 8.21 KB

0009-adopt-full-mhui-in-main-app.md

File metadata and controls

139 lines (124 loc) · 8.21 KB
Raw

ADR 0009: Adopt Full MHUI in the Main App

  • Status: Accepted
  • Date: 2026-09-14
  • Supersedes: Only the Cookle app presentation bullets of ADR 0008

The companion exclusion below describes this original rollout only. ADR 0010 evaluates those surfaces independently for later adoption.

Context

Cookle 3.9 has shipped. The post-release presentation review compared the existing Recipe Detail, a native List treatment, and a broader MHUI composition with identical content, ordering, navigation, and actions. The expanded composition was selected for Recipe Detail and establishes the direction for broader adoption in the main app.

MHUI supports both native List/Form containers and composed reading screens. Stally demonstrates the native-container route; Cookle's Recipe Detail comparison supplies the evidence for the composed route. Neither route requires changing the product's information architecture.

Decision

  • Cookle links the full MHUI product with the remote version requirement 2.3.0..<3.0.0, applies the neutral standard theme once at its application root, and configures the same theme's native appearance at startup. It accesses existing MHDesign metrics through MHUI's re-export, without a separate direct MHDesign product dependency or app-local metric overrides.
  • Recipe Detail uses mhScreen with the recipe name as its native navigation title, a leading photo, and compact recipe facts, followed by cooking and diary actions. Ingredients, categories, and diaries use grouped rows and steps and notes use reading sections, all on the open canvas. Dates and secondary actions form the quieter closing area. Cooking is primary and deletion is destructive. Existing facts, conditions, handlers, navigation, and confirmations remain; Edit stays in the native toolbar.
  • Adopt MHUI broadly at app-owned screen boundaries. Product collections and editors use MHUI content presentation inside native List and Form containers. Freely arranged reading and task screens use stack composition. Settings and utilities retain native grouping and row geometry on MHUI's themed canvas and row surfaces. Choose the route by screen purpose while preserving selection, editing, focus, keyboard, and navigation behavior.
  • Cookle owns screen composition, wording, accent assets, routes, state, and behavior. MHUI owns its theme and selected presentation primitives. Do not move domain behavior, generic helpers, or screen models into MHUI.
  • Full-screen media, system pickers, camera, share sheets, alerts, and package-owned presentations may retain their native or owning presentation. Glass belongs to appropriate controls, not recipe text surfaces.
  • CookleLibrary, Watch, and Widgets remain outside this adoption and gain no MHUI/MHDesign dependencies. App Intent implementations remain behavior adapters without presentation-package imports. Reused recipe sections default to native presentation for Intent snippets.
  • This decision does not change MHPlatform boundaries, Operations contracts, deployment support, persistence, or release policy. New features and diary-list information architecture are separate work.

Rollout and Verification

The dependency baseline advanced to MHUI 1.19 on 2026-09-15. Cookle inherits its revised semantic palette, typography, surface borders, and heading decoration removal through the standard components and theme. The app does not use removed heading-cue APIs or override package-owned theme values. The baseline advanced again to MHUI 1.20 on 2026-09-17. The update preserves the established source contract while adding app-wide palette selection, native-container ownership guidance, and explicit Liquid Glass opt-in for floating actions. Cookle selects Linen to pair MHUI's warm neutral surfaces with the app-owned orange accent, keeps native List/Form rows and sections platform-owned, and relies on the non-glass content-action default instead of disabling Glass across complete recipe and cooking screens. The baseline advanced to MHUI 2.0 on 2026-09-26. The Linen palette is removed upstream, so Cookle applies the neutral standard theme and keeps its accent. Because 2.0 no-argument container chrome selects MHUI content presentation, every List and Form now chooses its route explicitly: product collections, details, and editors use content presentation, and settings, subscription, and diagnostics use native presentation. Screen names move to native navigation titles, sections and grouped rows sit on the open canvas, and empty and search states drop their surface frames. The baseline advanced to MHUI 2.1 on 2026-09-26. Native container chrome now applies MHUI's canvas and text colors, so each app-owned native settings or diagnostics List wraps its complete rows once in MHContainerContent for the themed row surface. The subscription host keeps its MHPlatform-owned StoreKit section without an added row surface. Action roles share padding, dimensions follow the eight-point grid, and the recipe collection keeps content presentation at every width; Cookle copies no previous metrics or palette values. The baseline advanced to MHUI 2.2 on 2026-09-26. The startup call becomes configureNativeAppearance(), and the root theme supplies the orange accent as native control tint, including toolbars. Default content buttons used MHUI's primary text or destructive role, while explicit MHUI action styles keep their treatments. Composed sections use the package's 40-point section and 8-point heading rhythm without app compensation. The baseline advanced to MHUI 2.3 on 2026-09-26. Composed screens fill the available navigation column within MHUI's responsive margins, without the earlier 640-point maximum or an app width override. Native split-view column allocation is unchanged. Default content buttons return to the accent, and detached editors rely on mhInputChrome for primary input text and the hidden editor background. The earlier composition refinement applied the SDK's visual hierarchy: reading content gains emphasis through alignment and spacing, while surfaces group related rows and action styles identify the next useful operation.

The application root and expanded Recipe Detail established the first slice. Recipe browsing, the Diary landing screen, and Search results subsequently adopted the same composed screen, grouped-row, and surface vocabulary. The 2.0 update moves Recipe browsing and Search results to content List presentation; Search keeps the native searchable field and activation behavior. The main-app rollout records subsequent screen choices, semantic commits, before/after evidence, and verification gaps. Cooking, Recipe Detail, Diary landing, and the photo collection retain composed layout; detached editors use input chrome. Root linkage alone does not complete adoption, and implementation does not replace the screen-level verification recorded there.

Repository checks require the actual Cookle MHUI product and Frameworks edges, validate the remote minimum, and reject separate MHDesign links and excluded surface imports or links. Negative checks use disposable copies.

Each affected screen needs an app build and targeted runtime evidence for content, routes, actions, size classes, appearance, and accessibility. Existing comparison captures establish the selected phone direction; they do not prove production navigation, photo behavior, VoiceOver, or distribution readiness. Package behavior changes require package verification and affected-consumer checks. The original adoption left the approved MHUI 1.18 package unchanged.

Consequences

Recipe Detail delegates shared spacing, typography, and action styling to MHUI while Cookle chooses the reading order and where grouped surfaces help. Unframed prose and compact facts reduce repeated card boundaries. Adaptive layout can still increase wrapping and scroll length while preserving recipe data and available operations. Main browsing surfaces now approach Recipe Detail through the same visual language instead of weakening the detail screen. Native-container adoption remains a complete route when a screen has specific system interaction needs.

ADR 0008 remains authoritative for all unaffected package, library, adapter, Operations, and test-posture boundaries.