Help docs updates from Intercom ticket review (Sept 2025)

general/kaleidoscope-map-troubleshooting.md

@@ -0,0 +1,19 @@
+# Kaleidoscope Map Integration Troubleshooting
+
+## Troubleshooting Steps
+1. **Check Kaleidoscope App Installation**
+   Make sure the Kaleidoscope App is installed and authorized in your Shopify store.
+2. **Verify API Keys**
+   Double-check your API keys and ensure they are pasted into the theme settings under Integrations > Maps.
+3. **Theme Version**
+   If you updated your theme, ensure the Kaleidoscope snippets are correctly included. Reinstall if necessary.
+4. **Published Theme**
+   Confirm that the correct theme (with map integration) is published in your store.
+5. **Clear Cache**
+   Clear your browser and Shopify cache after making changes.
+
+## Visual Example
+
+![Example of successful Kaleidoscope map integration](../.assets/kaleidoscope-map-example.png)
+
+If the map does not appear, check your browser's console for errors and contact support.

general/license-transfer-faq.md

@@ -0,0 +1,11 @@
+# Theme License Transfer FAQ
+
+**Q: Can I transfer my theme license to a different store?**
+- Yes, you can transfer a purchased theme license to a new Shopify store you own. Remove the theme from your old store, then install and publish it on your new store from the Shopify Theme Store or your theme file.
+- If you get a license or activation error, contact [support](https://brickspacelab.com/pages/contact) for help.
+
+**Q: What happens to customizations during a license transfer?**
+- Custom code and settings do not automatically transfer. Download your theme files and make note of customizations before transferring.
+
+**Q: Are there limits on the number of transfers?**
+- Each theme license is valid for a single Shopify store at a time. Multiple transfers are allowed but only one live store per license.

general/onboarding-color-guide.md

@@ -0,0 +1,18 @@
+# Onboarding & Color Setup
+
+## Theme Onboarding
+1. Select your theme in Shopify admin > Online Store > Themes.
+2. Preview before publishing to check demo content and design.
+3. Open 'Customize' to access the theme editor.
+4. Click 'App embeds' if using integrations like chat or maps.
+
+## Color Setup
+1. In 'Customize', select 'Colors'.
+2. Every color setting has an example preview—adjust and preview before saving.
+3. Refer to [Shopify docs: color setup](https://help.shopify.com/manual/online-store/themes/theme-structure/settings/colors) for in-depth info.
+
+### Visual Guide
+
+![Screenshot of color settings panel](../.assets/theme-onboarding-color-setup.png)
+
+If your colors don’t display as expected, double check you’re editing the active theme and that there are no third-party code overrides.

keystone/migration-compatibility-checklist.md

@@ -0,0 +1,13 @@
+# Keystone Migration & Compatibility Checklist
+
+1. **Backup your store** before making any theme or app updates.
+2. **Check version requirements** for both Shopify and the Keystone theme—run the latest stable versions.
+3. **Review installed apps** to ensure they're compatible with new theme features.
+4. **Disable conflicting code** from old themes or custom apps.
+5. **Test in a duplicate theme** before publishing live changes.
+6. **Check visuals and layout** on mobile and desktop.
+7. **Contact support** if you run into unexpected issues or errors.
+
+> **Pro tip:** Always stage changes on a non-live theme to avoid impacting your live store.
+
+![Keystone compatibility checklist](../.assets/keystone-compatibility-checklist.png)

paper/collection-sorting-faq.md

@@ -0,0 +1,10 @@
+# Collection Sorting in the Paper Theme
+
+In Paper, collections are sorted based on the rules set in your Shopify admin. You can control the default sort order (Best selling, Alphabetical, Price, etc) for each collection in Shopify > Products > Collections > [Your Collection] > Sort.
+
+If you want to show a custom sort (e.g. by metafield, vendor, tag, or manual arrangement), use Shopify's built-in sort tools. The Paper theme respects the order set in the Shopify admin.
+
+> **Tip:** Refresh your storefront after updating sorting in admin to see changes reflected in Paper.
+
+![Screenshot of collection sorting settings](../.assets/paper-collection-sort-settings.png)
+

space/h1-accessibility-guide.md

@@ -0,0 +1,11 @@
+# H1 Headings & Accessibility in Space Theme
+
+- The Space theme uses a single H1 tag on each page, reserved for the primary heading.
+- For best accessibility and SEO, do not add additional H1 elements in custom sections, banners or app blocks.
+- Use H2, H3, and other heading levels for secondary titles.
+- Alt text is available for all images in sections and banners—ensure these fields are filled out for screen readers.
+- All Space theme templates are tested with keyboard navigation and screen readers.
+
+> **Accessibility Tip:** To check heading order, use Chrome DevTools or a browser accessibility extension.
+
+![Screenshot of accessibility settings](../.assets/space-theme-accessibility-example.png)