TopoloCommerce Design Appendix

What It Is

This page is the design appendix for TopoloCommerce. It records how Commerce is allowed to feel distinct while still staying inside the canonical Topolo design system.

Architecture

TopoloCommerce must use the canonical Topolo design docs as the source of truth:

• /internal/platform/design-language
• /internal/platform/mobile-experience-rollout
• /internal/platform/topolo-ui-kit

The allowed variation is product-layer simplicity, not platform-level divergence.

That means:

• apps/ops-web keeps the Topolo shell, shared launcher, shared auth/loading/callback surfaces, first-party icon system, and Topolo spacing and border hierarchy
• apps/guest-web and apps/guest-mobile can feel calmer and more direct, but they still inherit Topolo rhythm, typography discipline, mobile acceptance rules, and restrained accent behavior
• Apple-style simplicity is an interaction influence only; it cannot replace the Topolo shell, token contract, or suite identity model

Runtime Surfaces

The design contract differs slightly by surface:

apps/ops-web

• Topolo first-party suite app
• 64px top bar
• 256px desktop sidebar
• shared launcher and bug reporter
• module-aware route visibility inside a stable shell

apps/guest-web

• public venue runtime
• no Topolo launcher
• touch-first presentation
• image or video-led catalog emphasis
• explicit confirmation before sending a request or order

apps/guest-mobile

• managed kiosk surface
• same venue-aware module contract as guest web
• Cupertino-style interaction polish is allowed where it reinforces clarity

API Reference

The main implementation touchpoints are:

• PlatformApplications/TopoloCommerce/apps/ops-web/src/App.jsx
• PlatformApplications/TopoloCommerce/apps/ops-web/src/styles/app.css
• PlatformApplications/TopoloCommerce/apps/guest-web/src/App.jsx
• PlatformApplications/TopoloCommerce/apps/guest-web/src/styles/app.css
• PlatformApplications/TopoloCommerce/apps/guest-mobile/lib/screens/commerce_guest_app.dart

Auth and Permissions

Design must reinforce auth boundaries rather than hide them.

• shared Topolo auth surfaces belong only to apps/ops-web
• guest surfaces should not imply that a customer is using a human-authenticated Topolo suite app
• topolo_auth_flutter stays reserved for operator setup, diagnostics, or recovery mode in the mobile runtime

Data Ownership

TopoloCommerce does not own a separate design-token system.

The canonical design authority remains in TopoloDocs and the shared browser package. App-local styling may refine layout and interaction, but it must not redefine the platform contract independently.

Deployments

Because apps/ops-web is a first-party signed-in app, its browser identity must stay aligned with:

• Auth launcher metadata
• the shared first-party icon registry in @topolo/ui-kit
• shared Topolo launcher and callback surfaces

Guest surfaces can deploy independently without suite-launcher chrome, but they still need to pass the Topolo mobile viewport gates.

Failure Modes

• an Apple-inspired preset is treated as a replacement for Topolo shell geometry or token rules
• guest surfaces inherit suite-launcher affordances and start looking like operator tools
• staff surfaces drift back into generic card-grid dashboards that ignore the Topolo shell and hierarchy rules
• phone and tablet states collapse from desktop instead of being designed intentionally
• voice becomes a mandatory UX path instead of an optional assistive layer

Debugging

• compare any proposed Commerce UI with /internal/platform/design-language before treating it as final
• validate phone and tablet states against the documented Topolo mobile rollout viewports
• inspect the signed-in ops shell first if launcher, icon, or callback states drift
• inspect the guest surfaces if launcher or login behavior appears in ordinary customer flow

Change Log / Verification

• Added the canonical TopoloCommerce design appendix on 2026-04-10 and locked the design direction to Topolo foundations plus restrained Apple-style simplicity