> For the complete documentation index, see [llms.txt](https://docs.in8sync.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.in8sync.com/client-admin-guide/getting-started/best-practices.md). # Best Practices Production-readiness checklist, performance and accessibility tips, and common mistakes to avoid when building pages. A practical checklist plus the patterns to avoid. Use this as a pre-publish review for any production page. ## Production Checklist Before publishing a page to production, verify: ### Functionality * [ ] All components display correctly without errors * [ ] Forms submit successfully with valid data * [ ] Forms show clear errors for invalid data * [ ] Navigation between pages works correctly * [ ] Data loads and displays as expected * [ ] Buttons and actions perform their intended functions * [ ] Required fields are marked and enforced ### Visual * [ ] Page looks correct on desktop * [ ] Page looks correct on tablet * [ ] Page looks correct on mobile * [ ] Theme colours are applied consistently * [ ] Text is readable (good contrast, appropriate sizes) * [ ] Spacing is consistent and content is not cramped ### Data * [ ] Data sources are configured and returning results * [ ] Empty states are handled (what does the page show with no data?) * [ ] Large data sets are paginated * [ ] Error states show helpful messages ### Security * [ ] PIN override is configured where required (discounts, voids, sensitive actions) * [ ] No passwords or credentials in HTML or JavaScript components * [ ] Data shown is appropriate for the target user role ## Performance Tips ### Page Load Speed 1. **Limit components per page.** A page with 50+ components will load slower than one with 20. Split complex pages into multiple modules. 2. **Limit data-fetching components.** Each Chart Widget, Report Widget, or data-connected component makes a request when the page loads. A page with 10 charts makes 10 separate requests. 3. **Use pagination.** Report Widget and similar components should paginate data rather than loading everything at once. 4. **Optimize images.** Large product images slow down catalog pages. Ensure images are compressed and appropriately sized before uploading. 5. **Set reasonable refresh intervals.** A 5-second refresh creates constant load. Use 30-60 seconds for near-real-time needs, or manual refresh for reports. ### Layout Performance 1. **Keep nesting shallow.** 3 levels of layout nesting is typical. 5+ levels add unnecessary complexity. 2. **Prefer Grid over nested Rows.** A Grid with 3 columns is more efficient than 3 nested Rows inside a Column. 3. **Avoid empty wrappers.** A Column containing a single component is unnecessary — place the component directly. ## Accessibility Making your pages accessible ensures all users can interact with them effectively. ### Text and Readability * **Use sufficient colour contrast.** Text should be clearly readable against its background. Dark text on light backgrounds (or vice versa) is safest. * **Use readable font sizes.** Body text should be at least 14px. Avoid going below 12px for any user-facing text. * **Use heading levels correctly.** H1 for page title, H2 for sections, H3 for subsections. Do not skip levels. ### Navigation * **Provide clear labels.** Button labels should describe the action ("Place Order" not "Submit"). Navigation items should describe the destination. * **Make buttons big enough to click.** Use at least "medium" size buttons, especially for mobile users. * **Do not rely on colour alone.** If a status is shown in red, also include a text label or icon. ### Forms * **Label all fields.** Every input should have a visible label. * **Provide error messages.** When validation fails, tell the user what went wrong and how to fix it. * **Mark required fields.** Use the "required" setting on essential fields. ## Common Mistakes ### Layout Mistakes | Mistake | Why It Is a Problem | Better Approach | | ------------------------ | ------------------------------------- | ------------------------------------- | | Deep nesting (5+ levels) | Slower rendering, hard to maintain | Flatten with Grid components | | Fixed-width components | Break on smaller screens | Use relative widths and grow settings | | No mobile testing | Poor experience on phones and tablets | Always preview at all screen sizes | | Inconsistent spacing | Page looks unprofessional | Use consistent gap and padding values | ### Data Mistakes | Mistake | Why It Is a Problem | Better Approach | | ------------------------ | ----------------------------------------- | ---------------------------------------- | | No pagination | Slow loading with large data sets | Enable pagination on all data components | | No empty state | Confusing blank areas when no data exists | Configure empty state messages | | Too many data components | Many simultaneous requests on page load | Reduce data components or use tabs | ### Configuration Mistakes | Mistake | Why It Is a Problem | Better Approach | | ------------------------------------ | ------------------------------------- | ----------------------------------------------- | | Wrong module type | Components missing or not working | Choose the correct module type from the start | | Forgetting to publish | Users see outdated version | Publish after every round of changes | | No PIN override on sensitive actions | Security risk for discounts and voids | Configure PIN override per your security policy | | Unclear button labels | Users do not know what actions do | Use descriptive, action-oriented labels | ## Design Principles ### Keep It Simple * A clean, focused page is better than a feature-packed one. * Each page should have a clear primary purpose. * If you need to explain how a page works, it is probably too complex. ### Be Consistent * Use the same layout patterns across pages. * Keep button styles consistent (primary for main actions, secondary for alternatives). * Use the same spacing values throughout. ### Guide the User * Place the most important content at the top. * Use visual hierarchy (size, weight, colour) to draw attention to key elements. * Provide clear next steps — what should the user do after viewing this page? ### Test Like a User * Do not test with your admin knowledge. Test as if you have never seen the system before. * Test the complete flow, not just individual pages. * Test error scenarios, not just the happy path. ## Maintenance ### Regular Review * **Monthly:** Review page performance. Are there slow-loading pages? * **Quarterly:** Review page designs. Are there unused components or outdated content? * **After major changes:** Test affected pages when catalogs, user roles, or workflows change. ### Before risky edits The Page Builder doesn't keep an automatic publish history — once you publish, the previous version is gone. For risky edits: * **Copy the workflow first** and edit the copy. The original stays as your known-good baseline. * **Take a screenshot** of the current canvas before bigger restructures, so you have a visual reference if you need to rebuild. * **Publish in stages.** Make one section's worth of changes, publish, verify, then start the next. ### Documentation * Keep a list of your custom pages and their purposes. * Add comments to any JavaScript or CSS components explaining what they do. * Note which saved searches are used by which report components. ## Related
Layout & ResponsiveHow layouts collapse on smaller screens.Layout & Responsive Design
Common PatternsRecipes for the most common page types.Common Page Patterns
PIN OverrideHow PIN-protection works for sensitive actions.PIN Override