# Best Practices 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./pages/i16RUpMIJ1hqIym73t8h
Common PatternsRecipes for the most common page types./pages/nuIC9dFKJRLG7aUU3PNh
PIN OverrideHow PIN-protection works for sensitive actions./pages/ZB1p1C3xoZi8Tr9w4b1S
--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.in8sync.com/client-admin-guide/active-workflows/getting-started/best-practices.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.