| name | controller-ui |
| description | Use when building or reviewing Air Jam controller surfaces so touch controls stay simple, readable, and game-appropriate instead of drifting into dense web-app UI patterns. |
Controller UI
Use this skill for controller gameplay and lobby surfaces.
Read First
docs/generated/controller-ui.mddocs/visual-system.mddocs/iconography.mddocs/composition-shell-contract.md when the controller needs lobby/status/lifecycle shell work
Gameplay Rules
- gameplay controller UI should live inside an absolute
inset-0 root
- avoid scroll during active gameplay
- use large touch targets
- disable accidental text selection
- keep actions obvious and single-purpose
Lobby Rules
- keep the flow simple
- allow scroll only when it helps
- keep the hierarchy sparse
- prefer the shared shell contract for top status and lifecycle action placement unless the game has a strong reason to go fully custom
Shell Contract Rule
For controller shell work:
- prefer
RuntimeShellHeader, LifecycleActionGroup, useControllerShellStatus, useControllerLifecyclePermissions, and useControllerLifecycleIntents for the default composition path
- if you need custom markup, keep the same lifecycle behavior and action ordering
- do not keep duplicate lifecycle controls in both a top shell and a legacy local panel
Design Direction
- build controller UI like a game control surface
- avoid card-heavy dashboards
- avoid tiny controls and dense text
- avoid emoji-as-icon UI
- if the template already defines semantic panel, shell, or touch-surface utilities, use those before inventing new visual patterns
Icon Rule
Prefer:
@tabler/icons-react for general UI and system actionsreact-icons Gi* exports for gameplay-specific concepts such as abilities, status effects, pickups, and damage types
Do not mix icon packs casually throughout the tree.
Prefer local wrapper modules so icon usage stays curated and replaceable.
Attribution Note
If the project uses react-icons Gi* icons, remember that the underlying Game Icons set has its own attribution requirements.
Downstream teams remain responsible for how they satisfy those requirements.
Anti-Patterns
- generic SaaS UI for active gameplay
- hard-coded desktop-like layouts on mobile
- nested control groups that hide or shrink the main action
