tuturuuu-satellite-app-ux

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:

bun i18n:add --app chat --key common.save --value en="Save" --value vi="Lưu"
bun type-check:chat
bun i18n:sort
bun i18n:check

Use bun i18n:add for satellite translation key add/remove/replace work when possible; use --entries or --entries-file for bulk updates so every detected locale file is updated and sorted together. Reserve manual message JSON edits for broad prose rewrites or value-only updates. 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.