Technical reference. For task-based help, see the corresponding user guide.

Documentation status: reviewed against implementation · Reviewed: 2026-07-21 · Editor rollout: pilot-gated · Primary users: eligible practice owners/administrators and linked families · Surfaces: coach portal, mobile web and platform API

Organization branding lets a practice add a logo, a short welcome message and a coherent application palette. Mobile family and coach contexts inherit the active organization's branding while preserving a safe Littles default when no eligible brand is available.

• The Branding navigation item is a controlled pilot.
• In development, coach actors may access it. In production, the coach must match the configured branding-sandbox email allowlist (with a maintained pilot fallback list).
• This client rollout gate does not grant write authority. The platform independently requires an active owner or organizationAdmin membership in an organization that is neither suspended nor archived.
• The preview can run in simulator-only mode. Simulator changes are intentionally not a claim that the organization has been saved.

1. The editor loads GET /coach/organization/branding.
2. The coach can apply a curated preset and then adjust individual tokens.
3. Day/night controls change the preview context. Mobile web derives a coordinated night palette from the day tokens rather than persisting a second independent theme.

1. JPEG, PNG and WebP images are compressed to a maximum side of 1,024 px at approximately 0.8 quality; GIF remains uncompressed so animation is not destroyed.
2. The portal requests a signed upload in organization-branding using an organizations/<organizationId>/… path, uploads the image, then saves its object path as logoAssetId.
3. The welcome message can be previewed in the mobile welcome treatment before save.

1. The coach portal embeds the mobile build and sends preview changes with postMessage.
2. The preview URL carries only the initial route/simulator flag; logo paths and palette data are not serialized into the URL.
3. Mobile web applies preview CSS variables without converting the simulation into trusted persisted organization data.

1. Apply branding sends the normalized model to PUT /coach/organization/branding.
2. Mobile web resolves the organization associated with the current coach or authorized family context and maps the theme into CSS custom properties.
3. Branding is reused on invitation/access views, family home and activity/analysis areas, allergy ladders, session preparation, questionnaires, sleep plans and subscription/access treatments.
4. An invite-acceptance flow can present the configured welcome message for the newly linked organization.

• The production allowlist decides whether the experimental editor is visible; owner/admin membership decides whether data can be written.
• A family receives branding only through an authorized active organization relationship. Client-provided organization IDs are not trusted.
• Object paths are stored; media is delivered through short-lived authorization described in Feature 30.
• Preview messages validate their hosting context. Branding data is deliberately excluded from shareable URLs.
• A brand cannot weaken route authorization or tenant isolation; it changes presentation only.

Branding is still a pilot editor. Do not promise general availability from the existence of the API or simulator, and do not bypass the allowlist by linking directly to the route.

1. [ ] Production editor visibility follows the configured pilot gate.
2. [ ] Server writes require an active owner/admin membership and reject suspended/archived organizations.
3. [ ] Every optional color validates as #RRGGBB and null values fall back coherently.
4. [ ] Logo preparation preserves supported formats and uses an organization-scoped signed path.
5. [ ] Preview updates day/night presentation without putting brand data in the URL.
6. [ ] Save propagates to authorized coach/family contexts and no unrelated tenant.
7. [ ] Missing or failed branding resolution leaves an accessible default theme.
8. [ ] Welcome text respects the 180-character limit.

• Coach portal: admin-web/src/routes/BrandingPanel.tsx, admin-web/src/branding-sandbox.ts, admin-web/src/mobile-web-build-url.ts
• Mobile web: mobile-web/src/hooks/useOrganizationBrandTheme.ts, mobile-web/src/api/organizationBranding.ts, mobile-web/src/brandingPreview/simulator.ts, branding components and mobile-web/src/App.tsx
• Platform: platform/packages/shared/src/access.ts, platform/apps/api/src/routes/coach-routes.ts, platform/apps/api/src/services/coach-organization-branding-service.ts

• 03 — Coach invitations and family linking
• 12 — Family questionnaires
• 13 — Published sleep plans
• 23 — Practice settings and team labels
• 30 — Signed files and profile media