[all hosts] (iPad) Refresh iPad design article (#5305)

* Merge iPad design article

* Fix redirection link

* Add the iPad article back

* Add property links

* Update docs/concepts/add-in-development-best-practices.md

Co-authored-by: Sam Ramon <[email protected]>

---------

Co-authored-by: Sam Ramon <[email protected]>

Author: AlexJerabek

docs/concepts/add-in-development-best-practices.md

@@ -2,108 +2,115 @@
 title: Best practices for developing Office Add-ins
 description: Apply the best practices when developing Office Add-ins.
 ms.topic: best-practice
-ms.date: 10/10/2024
+ms.date: 07/28/2025
 ms.localizationpriority: medium
 ---
 
 # Best practices for developing Office Add-ins
 
-Effective add-ins offer unique and compelling functionality that extends Office applications in a visually appealing way. To create a great add-in, provide an engaging first-time experience for your users, design a first-class UI experience, and optimize your add-in's performance. Apply the best practices described in this article to create add-ins that help your users complete their tasks quickly and efficiently.
+Great add-ins provide unique, compelling functionality that extend Office apps in visually appealing ways. To build a successful add-in, you'll need to create an engaging first-time user experience, design a polished UI, and optimize performance. Follow the best practices in this article to help your users complete tasks quickly and efficiently.
 
 [!INCLUDE [publish policies note](../includes/note-publish-policies.md)]
 
 ## Provide clear value
 
-- Create add-ins that help users complete tasks quickly and efficiently. Focus on scenarios that make sense for Office applications. For example:
-  - Make core authoring tasks faster and easier, with fewer interruptions.
-  - Enable new scenarios within Office.
-  - Embed complementary services within Office applications.
-  - Improve the Office experience to enhance productivity.
-- Make sure that the value of your add-in is clear to users right away by [creating an engaging first-run experience](#create-an-engaging-first-run-experience).
-- Learn how to create an [effective AppSource listing](/partner-center/marketplace-offers/create-effective-office-store-listings) to promote your add-in.
-  - Make the benefits of your add-in clear in your title and description. Don't rely on your brand to communicate what your add-in does.
-  - Your add-in must provide sufficient value to justify users' investment. Your add-in shouldn't be a simple utility or of limited scope.
-  - [!INCLUDE [AppSource enterprise info](../includes/appsource-enterprise.md)]
+Build add-ins that help users complete tasks quickly and efficiently. Focus on scenarios that make sense for Office apps, such as:
+
+- Make core authoring tasks faster and easier with fewer interruptions.
+- Enable new scenarios within Office.
+- Embed complementary services within Office apps.
+- Improve the Office experience to enhance productivity.
+
+Make sure users understand your add-in's value immediately by [creating an engaging first-run experience](#create-an-engaging-first-run-experience).
+
+When you're ready to promote your add-in, learn how to create an [effective AppSource listing](/partner-center/marketplace-offers/create-effective-office-store-listings).
+
+- Make your add-in's benefits clear in the title and description. Don't rely only on your brand to communicate what your add-in does.
+- Ensure your add-in provides sufficient value to justify users' investment. It shouldn't be just a simple utility or have limited scope.
+- [!INCLUDE [AppSource enterprise info](../includes/appsource-enterprise.md)]
 
 ## Create an engaging first-run experience
 
-- Engage new users with a highly usable and intuitive first experience. Note that users are still deciding whether to use or abandon an add-in after they download it from the store.
+New users are still deciding whether to use or abandon your add-in after downloading it from the store. Here's how to win them over.
 
-- Make the steps that the user needs to take to engage with your add-in clear. Use videos, placemats, paging panels, or other resources to entice users.
+- **Make the next steps clear.** Use videos, placemats, paging panels, or other resources to guide users through your add-in.
 
-- Reinforce the value proposition of your add-in on launch, rather than just asking users to sign in.
+- **Lead with value, not registration.** Reinforce your add-in's value proposition when it launches rather than immediately asking users to sign in.
 
-- Provide teaching UI to guide users and make your UI personal.
+- **Provide helpful guidance.** Include teaching UI to guide users and make the experience feel personal.
 
   ![A "Do" versus "Don't" comparison on how to guide your users to use the UI. The "Do" example shows an add-in that includes a button users can click to get started. The "Don't" example shows an add-in with no introductory steps or buttons.](../images/contoso-part-catalog-do-dont.png)
 
-- If your content add-in binds to data in the user's document, include sample data or a template to show users the data format to use.
+- **Show users what to expect.** If your content add-in binds to data in the user's document, include sample data or a template to show users the expected data format.
 
   ![A "Do" versus "Don't" comparison on including an option to insert sample data in your add-in. The "Do" example shows an add-in that includes a button users can click to insert sample data. The "Don't" example shows an add-in without sample data or buttons.](../images/add-in-title.png)
 
-- Offer [free trials](/partner-center/marketplace-offers/monetize-addins-through-microsoft-commercial-marketplace). If your add-in requires a subscription, make some functionality available without a subscription.
+- **Offer free trials.** If your add-in requires a subscription, make some functionality available without one.
 
-- Make the sign-up experience simple. Prefill information, such as email and display name, and skip email verifications.
+- **Simplify sign-up.** Prefill information like email and display name, and skip email verifications when possible.
 
-- Avoid pop-up windows. If you have to use them, guide the user to enable your pop-up window.
+- **Avoid pop-ups.** If you must use them, guide users on how to enable your pop-up window.
 
-For patterns that you can apply as you develop your first-run experience, see [UX design patterns for Office Add-ins](../design/first-run-experience-patterns.md).
+For patterns you can apply when developing your first-run experience, see [UX design patterns for Office Add-ins](../design/first-run-experience-patterns.md).
 
 ## Use add-in commands
 
-- Provide relevant UI entry points for your add-in by using add-in commands. For details, including design best practices, see [add-in commands](../design/add-in-commands.md).
+Provide relevant UI entry points for your add-in by using add-in commands. These commands help users discover and access your add-in's functionality directly from the Office ribbon. For details and design best practices, see [add-in commands](../design/add-in-commands.md).
 
 ## Apply UX design principles
 
-- Ensure that the look and feel and functionality of your add-in complements the Office experience. See [Design the UI of Office Add-ins](../design/add-in-design.md).
+Follow these key principles to create add-ins that feel native to Office:
+
+- **Match the Office experience.** Ensure your add-in's look, feel, and functionality complement the Office experience. See [Design the UI of Office Add-ins](../design/add-in-design.md).
 
-- Favor content over chrome. Avoid superfluous UI elements that don't add value to the user experience.
+- **Prioritize content over chrome.** Avoid unnecessary UI elements that don't add value to the user experience.
 
-- Keep users in control. Ensure that users understand important decisions, and can easily reverse actions the add-in performs.
+- **Keep users in control.** Make sure users understand important decisions and can easily reverse actions your add-in performs.
 
-- Use branding to inspire trust and orient users. Don't use branding to overwhelm or advertise to users.
+- **Use branding thoughtfully.** Inspire trust and help orient users, but don't overwhelm or advertise to them.
 
-- Avoid scrolling. Optimize for 1366 x 768 resolution.
+- **Minimize scrolling.** Optimize for 1366 x 768 resolution.
 
-- Don't include unlicensed images.
+- **Use licensed images only.** Avoid legal and branding issues that come from unlicensed images.
 
-- Use [clear and simple language](../design/voice-guidelines.md) in your add-in.
+- **Write clearly.** Use [clear and simple language](../design/voice-guidelines.md) in your add-in.
 
-- Account for [accessibility](../design/accessibility-guidelines.md) - make your add-in easy for all users to interact with, and accommodate assistive technologies such as screen readers.
+- **Design for accessibility.** Make your add-in easy for all users to interact with and accommodate assistive technologies like screen readers. See our [accessibility guidelines](../design/accessibility-guidelines.md).
 
-- Design for all platforms and input methods, including mouse/keyboard and [touch](#optimize-for-touch). Ensure that your UI is responsive to different form factors.
+- **Support all platforms and input methods.** Design for mouse/keyboard and [touch](#optimize-for-touch). Ensure your UI responds well to different form factors.
 
 ### Optimize for touch
 
-- Use the [Context.touchEnabled](/javascript/api/office/office.context#office-office-context-touchenabled-member) property to detect whether the Office application that your add-in runs on is touch enabled.
+Touch support is essential for modern Office add-ins.
+
+- **Detect touch support.** Use the [Context.touchEnabled](/javascript/api/office/office.context#office-office-context-touchenabled-member) property to detect whether the Office app your add-in runs on is touch-enabled.
 
   > [!NOTE]
   > This property isn't supported in Outlook.
 
-- Ensure that all controls are appropriately sized for touch interaction. For example, buttons have adequate touch targets, and input boxes are large enough for users to enter input.
-
-- Don't rely on non-touch input methods like hover or right-click.
+- **Size controls appropriately.** Make sure all controls work well with touch interaction. For example, buttons need adequate touch targets, and input boxes should be large enough for users to enter text easily.
 
-- Ensure that your add-in works in both portrait and landscape modes. Be aware that on touch devices, part of your add-in might be hidden by the soft keyboard.
+- **Don't rely on hover or right-click.** These input methods aren't available on touch devices.
 
-- Test your add-in on a real device by using [sideloading](../testing/sideload-an-office-add-in-on-ipad.md).
+- **Support both orientations.** Ensure your add-in works in both portrait and landscape modes. Remember that on touch devices, the soft keyboard might hide part of your add-in.
 
-> [!NOTE]
-> If you're using [Fluent UI React](../quickstarts/fluent-react-quickstart.md) for your design elements, many of these elements are built into the design system.
+- **Test on real devices.** Use [sideloading](../testing/sideload-an-office-add-in-on-ipad.md) to test your add-in on actual touch devices.
 
 ## Optimize and monitor add-in performance
 
-- Create the perception of fast UI responses. Your add-in should load in 500 ms or less.
+Performance directly impacts user satisfaction. Follow these guidelines to keep your add-in fast and responsive:
 
-- Ensure that all user interactions respond in under one second.
+- **Aim for quick loading.** Your add-in should load in 500 ms or less to create the perception of fast UI responses.
 
-- Provide loading indicators for long-running operations.
+- **Respond quickly to interactions.** All user interactions should respond in under one second.
 
-- Use a content delivery network (CDN) to host images, resources, and common libraries. Load as much as you can from one place.
+- **Show progress for long operations.** Provide loading indicators for operations that take time.
 
-- Follow standard web practices to optimize your web page. In production, use only minified versions of libraries. Only load resources that you need, and optimize how resources are loaded.
+- **Use a CDN.** Host images, resources, and common libraries on a content delivery network (CDN). Load as much as possible from one place.
 
-- If operations take time to execute, provide feedback to users. Note the thresholds listed in the following table. For additional information, see [Resource limits and performance optimization for Office Add-ins](../concepts/resource-limits-and-performance-optimization.md).
+- **Follow web optimization best practices.** In production, use only minified versions of libraries. Load only the resources you need and optimize how they're loaded.
+
+- **Provide feedback for longer operations.** When operations take time to execute, give users feedback based on the thresholds in the following table. For more information, see [Resource limits and performance optimization for Office Add-ins](../concepts/resource-limits-and-performance-optimization.md).
 
   |Interaction class|Target|Upper bound|Human perception|
   |:-----|:-----|:-----|:-----|
@@ -116,31 +123,32 @@ For patterns that you can apply as you develop your first-run experience, see [U
   |Extended|>500 ms|>10 seconds|Long enough to do something else while waiting. Might need feedback.|
   |Long running|>5 seconds|>1 minute|Users will certainly do something else.|
 
-- Monitor your service health, and use telemetry to monitor user success.
+- **Monitor your service.** Use telemetry to monitor service health and user success.
 
-- Minimize data exchanges between the add-in and the Office document. For more information, see [Avoid using the context.sync method in loops](correlated-objects-pattern.md).
+- **Minimize data exchanges.** Reduce data exchanges between your add-in and the Office document. For more information, see [Avoid using the context.sync method in loops](correlated-objects-pattern.md).
 
 ## Publish and market your add-in
 
-- Create a [Partner Center account](/partner-center/marketplace-offers/open-a-developer-account). This could take some time. If you plan to publish your add-in to AppSource, get this process going as soon as possible.
-
-- Create an [effective AppSource listing](/partner-center/marketplace-offers/create-effective-office-store-listings).
+Ready to share your add-in with the world? Here's how to get started.
 
-  - Use succinct and descriptive add-in titles. Include no more than 128 characters.
+- **Create a Partner Center account.** This process can take time, so if you plan to publish to AppSource, start early. See [Partner Center account](/partner-center/marketplace-offers/open-a-developer-account).
 
-  - Write short, compelling, and accurate descriptions of your add-in. Answer the question "What problem does this add-in solve?".
+- **Create an effective AppSource listing.** Follow these tips:
 
-  - Convey the value proposition of your add-in in your title and description. Don't rely on your brand.
+  - Use succinct, descriptive titles (128 characters or fewer).
+  - Write short, compelling descriptions that answer "What problem does this add-in solve?"
+  - Convey your add-in's value proposition clearly in the title and description. Don't rely only on your brand.
 
-- Create a website to help users find and use your add-in.
+  Learn more about [creating effective AppSource listings](/partner-center/marketplace-offers/create-effective-office-store-listings).
 
-- Publish your add-in to [AppSource](/partner-center/marketplace-offers/submit-to-appsource-via-partner-center). Be sure to follow the AppSource [prepublish checklist](/partner-center/marketplace-offers/checklist) and [submission guide](/partner-center/marketplace-offers/add-in-submission-guide).
+- **Publish to AppSource.** Follow the AppSource [prepublish checklist](/partner-center/marketplace-offers/checklist) and [submission guide](/partner-center/marketplace-offers/add-in-submission-guide). Make sure to:
 
-  - Ensure that your add-in works error-free in all operating systems, browsers, and devices supported by the minimum set of APIs declared in your add-in manifest.
+  - Test your add-in thoroughly on all supported operating systems, browsers, and devices.
+  - Provide detailed testing instructions and resources for certification reviewers.
 
-  - Provide detailed testing instructions and resources for certification reviewers to verify the functionality of your add-in.
+- **Create a website.** Help users discover your add-in outside of AppSource.
 
-- [Promote your add-in](/partner-center/marketplace-offers/promote-your-office-store-solution) from your website.
+- **Promote your add-in** from your website. See [how to promote your add-in](/partner-center/marketplace-offers/promote-your-office-store-solution).
 
 > [!IMPORTANT]
 > [!INCLUDE [AppSource enterprise info](../includes/appsource-enterprise.md)]