Component Patterns

For @prepared911/ui in apps and remotes, load the find-pattern, compose-ui, and choose-control agent skills before implementing (see root AGENTS.md). Layout uses Box / FlexBox enum props, not native layout tags (div, section, span, article, header, footer, main, aside or nav) anywhere in consumer trees. File size limits: Component organization: File structure: Use sub-components (e.g., <Icon />) instead of render functions (e.g., getIcon()). Benefits: For GraphQL data, pass the fragment reference (FragmentType), not an id and not the raw object. An id makes the child fetch for itself, a second query for data its parent already has (a child can still own a query when justified). A raw result object ties the child to the parent's query. The child declares a Message_message fragment, takes message: FragmentType<typeof MessageMessageFragmentDoc>, and reads it with useFragment. See GraphQL Fragments, and Testing a Fragment-Owning Component on Its Own for how to test such a component. React component files must not exceed 500 lines. Extract logic to hooks, sub-components, or utilities when approaching this limit. File size guidance: GraphQL files MUST be co-located with the component/hook that uses them (GraphQL near operation pattern). A component that renders its parent's data declares a fragment in its own fragments.graphql and reads it with useFragment. When a component may call useQuery itself: the Fragments guide. For larger features: Key principles: One component/hook = one concern. The UserDashboard query selects id on user and spreads ...UserProfileSection_user and ...PostsSection_user. A section reads its data from its fragment, so it never calls useQuery itself. Favor small, composable components over "god" components. Use Error Boundaries to protect pages from crashes. Always log errors to Datadog. A hook returns an Apollo error for the component to show. It doesn't report it: the shell's Apollo client reports a network or transport failure once, and the backend has already reported an error it returned in the response (Who reports an error). 🚨 ALL HOOKS MUST BE UNIT TESTED 🚨 See Unit Testing for comprehensive testing patterns. For more detailed technical guidance, see these reference files: