---
name: tuturuuu-satellite-app-ux
description: Tuturuuu satellite app UX guidance. Use when building or revamping standalone apps such as Mail or CMS that use @tuturuuu/satellite auth, providers, i18n, workspace routes, navigation, and focused app shells.
---

# Tuturuuu Satellite App UX

## Core Workflow

Use this skill for standalone app surfaces under `apps/*` that behave like
satellite apps rather than sections inside `apps/web`.

Start with `AGENTS.md`, `git status --short`, and active coordination notes.
Then inspect the target app's existing `proxy.ts`, `i18n/routing.ts`,
providers, workspace layout, navigation, and app-session routes before designing
new UI.

## App Shell Checklist

- Use `@tuturuuu/satellite` providers, i18n helpers, constants, and app-session
  helpers where the app already follows that pattern.
- Keep auth target names consistent across proxy, verify-token, refresh, logout,
  and server session reads.
- Preserve workspace route shapes and locale handling. New dashboard routes need
  navigation aliases, icons, permissions or access gates, and empty states.
- Build the actual app workspace as the first screen. Avoid marketing-style
  landing pages for operational apps.
- Prefer a focused app shell with clear primary navigation, search/filter tools,
  and compact repeated actions over a generic dashboard card wall.
- Add strings to the owning app's English and Vietnamese bundles. If shared UI
  strings are added, update every app bundle that ships that shared surface.

## Data And Mutation Rules

- Use TanStack Query for client fetching/mutation.
- Put shared app API clients behind `packages/internal-api/src/*` when code is
  reused outside one route.
- Do not add raw client-side app API fetches.
- Keep protected data reads and writes behind server-owned APIs. Do not expose
  privileged Supabase access to satellite clients.

## Cross-App Parity

For Calendar or Finance, assume the standalone app and the `apps/web`
counterpart move together unless the user explicitly scopes an exception.

For other satellite apps, inspect whether a shared package or `apps/web`
counterpart already owns the behavior before duplicating logic in the app.

## Verification

Run focused tests for the target app first, then required repo checks:

```bash
bun type-check:<app>
bun i18n:sort
bun i18n:check
```

Finish with `bun check` for TypeScript, JavaScript, messages, or repo config
changes unless an unrelated pre-existing blocker prevents it. Do not run
long-running dev/build commands unless the user explicitly asks.