[POS UI extensions]: Improved target, API, and component descriptions for 2025-01

[mcvinci]

This PR:

• Improves all target, API, and component descriptions in the POS UI extensions docs for version 2025-01
• Improves all target, API, and component example titles and example descriptions in the POS UI extensions docs for version 2025-01
• Adds "Best practices" and "Limitations" sections to API and component pages
• Reorganizes the sub-categories in the IA to match the prototype
• Partially fixes https://github.com/Shopify/shopify-dev/issues/64745
• Partially fixes https://github.com/Shopify/shopify-dev/issues/64910
• Partially fixes https://github.com/Shopify/shopify-dev/issues/65232
• Partially fixes https://github.com/Shopify/shopify-dev/issues/65233
• Closes https://github.com/Shopify/shopify-dev-feedback/issues/7190
• Closes https://github.com/Shopify/shopify-dev-feedback/issues/7321
• Closes https://github.com/Shopify/shopify-dev-feedback/issues/7313
• Closes https://github.com/Shopify/shopify-dev-feedback/issues/7372
• Closes https://github.com/Shopify/shopify-dev-feedback/issues/7447
• Closes https://github.com/Shopify/shopify-dev-feedback/issues/7592
• Closes https://github.com/Shopify/shopify-dev-feedback/issues/7718
• Closes https://github.com/Shopify/shopify-dev-feedback/issues/7900
• Closes https://github.com/Shopify/shopify-dev-feedback/issues/7937
• Closes https://github.com/Shopify/shopify-dev-feedback/issues/7333
• Closes https://github.com/Shopify/shopify-dev-feedback/issues/7389
• Closes https://github.com/Shopify/shopify-dev-feedback/issues/7431
• Closes https://github.com/Shopify/shopify-dev-feedback/issues/7429
• Closes https://github.com/Shopify/shopify-dev-feedback/issues/7522
• Closes https://github.com/Shopify/shopify-dev-feedback/issues/7662
• Closes https://github.com/Shopify/shopify-dev-feedback/issues/7675
• Closes https://github.com/Shopify/shopify-dev-feedback/issues/8306

Tophatting

1. In the ui-extensions repo, run yarn docs:point-of-sale 2025-01.
2. In shopify-dev, run a server (dev server) and review the 2025-01 docs (descriptions for targets, APIs, and components) at https://shopify-dev.shop.dev/docs/api/pos-ui-extensions/2025-01

Known issues

• Unable to create different descriptions on API and component index pages versus detailed API and component pages. For the time being, I've just added the long description that is intended for the details pages.
• Some nested descriptions get duplicated, given the existing generated docs infrastructure. Hoping that we can resolve this as we continue the templated refs project work.

Focus for reviewers

I'm mainly looking for a gut-check on the following:

• Do the descriptions convey the necessary context?
• Are the descriptions positioned in the right place? (Typically, above interfaces and fields)
• Are the changes scoped to descriptions only? Or have we accidentally updated / added types?

[github-actions]

We detected some changes in packages/*/package.json or packages/*/src, and there are no updates in the .changeset directory. If the changes are user-facing and should cause a version bump, run yarn changeset to track your changes and include them in the next release CHANGELOG. If you are making simple updates to repo configuration, examples, or documentation, you do not need to add a changeset.

[johndcollett]

structure looks good.