Update Text component docs: Add warning about nesting Icon/Badge

- Add best practice: Use Stack for icons and badges instead of nesting
- Add limitation: Explain React Native alignment issue with nested Icon/Badge
- Provide Stack with direction='inline' as recommended alternative

Addresses #21094

Author: armaan-ghosh

packages/ui-extensions/src/surfaces/point-of-sale/components/Text/Text.doc.ts

@@ -42,6 +42,7 @@ const data: ReferenceEntityTemplateSchema = {
 - **Apply appropriate tones:** Use \`success\` for positive outcomes, \`warning\` or \`critical\` for alerts, \`info\` for helpful context, \`auto\` for neutral content.
 - **Balance color intensity:** Use \`strong\` for emphasis, \`base\` for readability, \`subdued\` for secondary info.
 - **Nest for mixed formatting:** Nest \`Text\` components when you need multiple styles within one text block.
+- **Use Stack for icons and badges:** When combining text with icons or badges, use Stack with direction="inline" instead of nesting components inside Text.
 `,
     },
     {
@@ -50,6 +51,8 @@ const data: ReferenceEntityTemplateSchema = {
       title: 'Limitations',
       sectionContent: `
 Complex rich text formatting isn't supported—use multiple \`Text\` components or nested text elements for varied formatting needs.
+
+Nesting Icon or Badge components inside Text isn't supported due to React Native alignment limitations—use Stack with direction="inline" and alignItems="center" instead to properly align icons and badges with text.
 `,
     },
   ],