Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

Improve HoverCard docs page and block examples (#1584)

rubyycheungffbcef82e471
diff --git a/packages/cli/templates/blocks/components/HoverCard/HoverCardHookBasedHoverCard.doc.mjs b/packages/cli/templates/blocks/components/HoverCard/HoverCardHookBasedHoverCard.doc.mjs
deleted file mode 100644
index b173ca11ef..0000000000
--- a/packages/cli/templates/blocks/components/HoverCard/HoverCardHookBasedHoverCard.doc.mjs
+++ /dev/null
@@ -1,10 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'HoverCard — Hook API',
- description:
- 'Uses the useXDSHoverCard hook for direct control over hover card behavior and placement.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['HoverCard', 'Button', 'VStack'],
-};
diff --git a/packages/cli/templates/blocks/components/HoverCard/HoverCardHookBasedHoverCard.tsx b/packages/cli/templates/blocks/components/HoverCard/HoverCardHookBasedHoverCard.tsx
deleted file mode 100644
index 68c0d52f3c..0000000000
--- a/packages/cli/templates/blocks/components/HoverCard/HoverCardHookBasedHoverCard.tsx
+++ /dev/null
@@ -1,34 +0,0 @@
-'use client';
-
-import {useXDSHoverCard} from '@xds/core/HoverCard';
-import {XDSButton} from '@xds/core/Button';
-import {XDSVStack} from '@xds/core/Layout';
-
-export default function HoverCardHookBasedHoverCard() {
- const hoverCard = useXDSHoverCard({
- placement: 'above',
- delay: 200,
- });
-
- return (
- <div style={{padding: 80}}>
- <XDSButton
- label="Using hook directly"
- ref={hoverCard.ref}
- aria-describedby={hoverCard.describedBy}>
- Using hook directly
- </XDSButton>
- {hoverCard.renderHoverCard(
- <div style={{width: 200}}>
- <XDSVStack gap={2}>
- <div style={{fontWeight: 600}}>Jane Doe</div>
- <div style={{fontSize: 14, opacity: 0.7}}>Software Engineer</div>
- <div style={{fontSize: 13}}>
- Building great products with great people.
- </div>
- </XDSVStack>
- </div>,
- )}
- </div>
- );
-}
diff --git a/packages/cli/templates/blocks/components/HoverCard/HoverCardInlineTextHoverCard.doc.mjs b/packages/cli/templates/blocks/components/HoverCard/HoverCardInlineTextHoverCard.doc.mjs
index ffaed62b45..5e64b00210 100644
--- a/packages/cli/templates/blocks/components/HoverCard/HoverCardInlineTextHoverCard.doc.mjs
+++ b/packages/cli/templates/blocks/components/HoverCard/HoverCardInlineTextHoverCard.doc.mjs
@@ -1,10 +1,10 @@
/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
export const doc = {
type: 'block',
- name: 'HoverCard — Inline Text',
+ name: 'HoverCard — Definition',
description:
- 'Hover cards wrapping inline text nodes within a paragraph, useful for user mentions or link previews.',
+ 'Shows a term definition on hover within a paragraph. Use for technical terms, jargon, or concepts that some readers may not know — like a glossary built into the text.',
isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['HoverCard', 'VStack'],
+ aspectRatio: 16 / 9,
+ componentsUsed: ['HoverCard', 'Layout', 'Text'],
};
diff --git a/packages/cli/templates/blocks/components/HoverCard/HoverCardInlineTextHoverCard.tsx b/packages/cli/templates/blocks/components/HoverCard/HoverCardInlineTextHoverCard.tsx
index 914e88ded4..514d3250d7 100644
--- a/packages/cli/templates/blocks/components/HoverCard/HoverCardInlineTextHoverCard.tsx
+++ b/packages/cli/templates/blocks/components/HoverCard/HoverCardInlineTextHoverCard.tsx
@@ -1,45 +1,48 @@
'use client';
+import * as stylex from '@stylexjs/stylex';
import {XDSHoverCard} from '@xds/core/HoverCard';
import {XDSVStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+
+const styles = stylex.create({
+ content: {maxWidth: 200},
+});
export default function HoverCardInlineTextHoverCard() {
return (
- <div style={{padding: 80}}>
- <p>
- The project is maintained by{' '}
- <XDSHoverCard
- content={
- <div style={{width: 200}}>
- <XDSVStack gap={2}>
- <div style={{fontWeight: 600}}>Jane Doe</div>
- <div style={{fontSize: 14, opacity: 0.7}}>
- Software Engineer
- </div>
- <div style={{fontSize: 13}}>
- Building great products with great people.
- </div>
- </XDSVStack>
- </div>
- }
- placement="above">
- Jane Doe
- </XDSHoverCard>
- ,{' '}
- <XDSHoverCard
- content={
- <div style={{width: 200}}>
- <XDSVStack gap={2}>
- <div style={{fontWeight: 600}}>John Smith</div>
- <div style={{fontSize: 14, opacity: 0.7}}>Product Manager</div>
- </XDSVStack>
- </div>
- }
- placement="above">
- John Smith
- </XDSHoverCard>
- , and others.
- </p>
- </div>
+ <XDSText type="body">
+ The component uses a{' '}
+ <XDSHoverCard
+ content={
+ <XDSVStack gap={1} xstyle={styles.content}>
+ <XDSText type="label">Focus trap</XDSText>
+ <XDSText type="body" color="secondary">
+ A pattern that keeps keyboard focus inside a container, preventing
+ it from moving to elements outside. Used in dialogs and modals to
+ ensure accessibility.
+ </XDSText>
+ </XDSVStack>
+ }
+ placement="above">
+ focus trap
+ </XDSHoverCard>{' '}
+ to keep keyboard navigation inside the{' '}
+ <XDSHoverCard
+ content={
+ <XDSVStack gap={1} xstyle={styles.content}>
+ <XDSText type="label">Modal dialog</XDSText>
+ <XDSText type="body" color="secondary">
+ An overlay that blocks interaction with the rest of the page until
+ the user responds. Uses the native HTML dialog element for
+ built-in accessibility and backdrop support.
+ </XDSText>
+ </XDSVStack>
+ }
+ placement="above">
+ modal dialog
+ </XDSHoverCard>
+ .
+ </XDSText>
);
}
diff --git a/packages/cli/templates/blocks/components/HoverCard/HoverCardInteractiveContent.doc.mjs b/packages/cli/templates/blocks/components/HoverCard/HoverCardInteractiveContent.doc.mjs
index ecca483c9c..b66bf69a65 100644
--- a/packages/cli/templates/blocks/components/HoverCard/HoverCardInteractiveContent.doc.mjs
+++ b/packages/cli/templates/blocks/components/HoverCard/HoverCardInteractiveContent.doc.mjs
@@ -1,10 +1,10 @@
/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
export const doc = {
type: 'block',
- name: 'HoverCard — Interactive Content',
+ name: 'HoverCard — Link Preview',
description:
- 'A hover card with interactive buttons inside, allowing users to take actions without navigating away.',
+ 'Shows a page summary when hovering a link — title, description, and URL. Use for documentation links, article references, or any URL where a preview helps the user decide whether to click.',
isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['HoverCard', 'Button', 'VStack', 'HStack'],
+ aspectRatio: 16 / 9,
+ componentsUsed: ['HoverCard', 'Icon', 'Layout', 'Text'],
};
diff --git a/packages/cli/templates/blocks/components/HoverCard/HoverCardInteractiveContent.tsx b/packages/cli/templates/blocks/components/HoverCard/HoverCardInteractiveContent.tsx
index 6db699bda5..e382abe4d7 100644
--- a/packages/cli/templates/blocks/components/HoverCard/HoverCardInteractiveContent.tsx
+++ b/packages/cli/templates/blocks/components/HoverCard/HoverCardInteractiveContent.tsx
@@ -1,29 +1,42 @@
'use client';
+import * as stylex from '@stylexjs/stylex';
import {XDSHoverCard} from '@xds/core/HoverCard';
-import {XDSButton} from '@xds/core/Button';
+import {XDSIcon} from '@xds/core/Icon';
import {XDSVStack, XDSHStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+import {LinkIcon} from '@heroicons/react/24/outline';
+
+const styles = stylex.create({
+ content: {maxWidth: 280},
+});
export default function HoverCardInteractiveContent() {
return (
- <div style={{padding: 80}}>
+ <XDSText type="body">
+ Read more in the{' '}
<XDSHoverCard
placement="below"
content={
- <XDSVStack gap={2}>
- <div>Interactive hover card content</div>
- <XDSHStack gap={2}>
- <XDSButton label="Follow" variant="primary">
- Follow
- </XDSButton>
- <XDSButton label="Message">Message</XDSButton>
+ <XDSVStack gap={2} xstyle={styles.content}>
+ <XDSHStack gap={2} vAlign="start">
+ <XDSIcon icon={LinkIcon} size="sm" color="secondary" />
+ <XDSVStack gap={1}>
+ <XDSText type="label">Getting Started Guide</XDSText>
+ <XDSText type="body" color="secondary">
+ Learn how to set up your first project, invite team members,
+ and configure your workspace.
+ </XDSText>
+ <XDSText type="supporting" color="secondary">
+ docs.example.com/getting-started
+ </XDSText>
+ </XDSVStack>
</XDSHStack>
</XDSVStack>
}>
- <XDSButton label="Hover for interactive content">
- Hover for interactive content
- </XDSButton>
+ Getting Started Guide
</XDSHoverCard>
- </div>
+ .
+ </XDSText>
);
}
diff --git a/packages/cli/templates/blocks/components/HoverCard/HoverCardProfileHoverCard.doc.mjs b/packages/cli/templates/blocks/components/HoverCard/HoverCardProfileHoverCard.doc.mjs
index 7a3978b697..b39346da72 100644
--- a/packages/cli/templates/blocks/components/HoverCard/HoverCardProfileHoverCard.doc.mjs
+++ b/packages/cli/templates/blocks/components/HoverCard/HoverCardProfileHoverCard.doc.mjs
@@ -3,8 +3,8 @@ export const doc = {
type: 'block',
name: 'HoverCard — Profile Preview',
description:
- 'A hover card that shows a user profile summary on hover, the most common hover card pattern.',
+ 'Shows a user profile summary on hover with name, role, and bio. Use on usernames, avatars, or mentions to let users preview a profile without navigating away.',
isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['HoverCard', 'Button', 'VStack'],
+ aspectRatio: 16 / 9,
+ componentsUsed: ['HoverCard', 'Button', 'Layout', 'Text'],
};
diff --git a/packages/cli/templates/blocks/components/HoverCard/HoverCardProfileHoverCard.tsx b/packages/cli/templates/blocks/components/HoverCard/HoverCardProfileHoverCard.tsx
index ce2ba135d6..e654c97733 100644
--- a/packages/cli/templates/blocks/components/HoverCard/HoverCardProfileHoverCard.tsx
+++ b/packages/cli/templates/blocks/components/HoverCard/HoverCardProfileHoverCard.tsx
@@ -1,27 +1,41 @@
'use client';
+import * as stylex from '@stylexjs/stylex';
import {XDSHoverCard} from '@xds/core/HoverCard';
+import {XDSAvatar} from '@xds/core/Avatar';
import {XDSButton} from '@xds/core/Button';
-import {XDSVStack} from '@xds/core/Layout';
+import {XDSIcon} from '@xds/core/Icon';
+import {XDSVStack, XDSHStack} from '@xds/core/Layout';
+import {XDSText, XDSHeading} from '@xds/core/Text';
+import {CalendarIcon} from '@heroicons/react/24/outline';
+
+const styles = stylex.create({
+ avatar: {flexShrink: 0},
+ content: {maxWidth: 280},
+});
export default function HoverCardProfileHoverCard() {
return (
- <div style={{padding: 80}}>
- <XDSHoverCard
- placement="above"
- content={
- <div style={{width: 200}}>
- <XDSVStack gap={2}>
- <div style={{fontWeight: 600}}>Jane Doe</div>
- <div style={{fontSize: 14, opacity: 0.7}}>Software Engineer</div>
- <div style={{fontSize: 13}}>
- Building great products with great people.
- </div>
- </XDSVStack>
- </div>
- }>
- <XDSButton label="Hover me">Hover me</XDSButton>
- </XDSHoverCard>
- </div>
+ <XDSHoverCard
+ placement="below"
+ content={
+ <XDSHStack gap={3} vAlign="start" xstyle={styles.content}>
+ <XDSAvatar name="Jane Doe" size={48} xstyle={styles.avatar} />
+ <XDSVStack gap={1}>
+ <XDSHeading level={3}>@janedoe</XDSHeading>
+ <XDSText type="body" color="secondary">
+ Crafting accessible, scalable design systems for modern teams.
+ </XDSText>
+ <XDSHStack gap={1} vAlign="center">
+ <XDSIcon icon={CalendarIcon} size="xsm" color="secondary" />
+ <XDSText type="supporting" color="secondary">
+ March 2024
+ </XDSText>
+ </XDSHStack>
+ </XDSVStack>
+ </XDSHStack>
+ }>
+ <XDSButton label="@janedoe" variant="ghost" />
+ </XDSHoverCard>
);
}
diff --git a/packages/core/src/HoverCard/HoverCard.doc.mjs b/packages/core/src/HoverCard/HoverCard.doc.mjs
index 50cd9cf3b4..a4cddb264f 100644
--- a/packages/core/src/HoverCard/HoverCard.doc.mjs
+++ b/packages/core/src/HoverCard/HoverCard.doc.mjs
@@ -135,17 +135,20 @@ export const docs = {
},
],
usage: {
- description: 'A hover or focus-triggered overlay for displaying rich, interactive content anchored to a trigger element. Use HoverCard for non-critical supplementary information and progressive disclosure. For plain text hints use Tooltip, and for menus use Popover.',
+ description: 'HoverCard shows additional information when the user hovers or focuses a trigger element. Use it for profile cards, link summaries, or inline definitions where the user needs more context without navigating away.',
bestPractices: [
{ guidance: true, description: 'Keep content supplementary — hover cards should enhance understanding without blocking the primary workflow.' },
{ guidance: true, description: 'Provide a dashed underline on text triggers so users know the element is hoverable.' },
+ { guidance: true, description: 'Use the hook API (useXDSHoverCard) when you need more control over timing or placement.' },
{ guidance: false, description: 'Place critical actions or required information inside a hover card — users may miss content that only appears on hover.' },
{ guidance: false, description: 'Use a hover card when a simple Tooltip or Popover would suffice.' },
+ { guidance: false, description: 'Use a HoverCard for content the user must interact with — it disappears when the cursor leaves.' },
],
anatomy: [
- {name: 'Header', required: false, description: 'Eyebrow header with optional copy and close buttons.'},
- {name: 'Body', required: true, description: 'Text pairings, icons, and media content.'},
- {name: 'Call to Action', required: false, description: 'Button for follow-up actions.'},
+ {name: 'Trigger', required: true, description: 'The element that opens the hover card on hover or focus — a button, link, or inline text.'},
+ {name: 'Card', required: true, description: 'The floating overlay with the preview content, anchored to the trigger.'},
+ {name: 'Body', required: true, description: 'The main content area — profile info, link summary, or any rich content.'},
+ {name: 'Actions', required: false, description: 'Optional buttons inside the card for follow-up actions like Follow or Message.'},
],
},
};
@@ -286,17 +289,14 @@ export const docsZh = {
},
],
usage: {
- description: 'A hover or focus-triggered overlay for displaying rich, interactive content anchored to a trigger element. Use HoverCard for non-critical supplementary information and progressive disclosure. For plain text hints use Tooltip, and for menus use Popover.',
+ description: 'HoverCard shows additional information when the user hovers or focuses a trigger element. Use it for profile cards, link summaries, or inline definitions where the user needs more context without navigating away.',
bestPractices: [
{ guidance: true, description: 'Keep content supplementary — hover cards should enhance understanding without blocking the primary workflow.' },
{ guidance: true, description: 'Provide a dashed underline on text triggers so users know the element is hoverable.' },
+ { guidance: true, description: 'Use the hook API (useXDSHoverCard) when you need more control over timing or placement.' },
{ guidance: false, description: 'Place critical actions or required information inside a hover card — users may miss content that only appears on hover.' },
{ guidance: false, description: 'Use a hover card when a simple Tooltip or Popover would suffice.' },
- ],
- anatomy: [
- {name: 'Header', required: false, description: 'Eyebrow header with optional copy and close buttons.'},
- {name: 'Body', required: true, description: 'Text pairings, icons, and media content.'},
- {name: 'Call to Action', required: false, description: 'Button for follow-up actions.'},
+ { guidance: false, description: 'Use a HoverCard for content the user must interact with — it disappears when the cursor leaves.' },
],
},
};
@@ -306,17 +306,10 @@ export const docsDense = {
description:
'Hover/focus triggered overlay for displaying rich, interactive content anchored to trigger element.',
usage: {
- description: 'A hover or focus-triggered overlay for displaying rich, interactive content anchored to a trigger element. Use HoverCard for non-critical supplementary information and progressive disclosure. For plain text hints use Tooltip, and for menus use Popover.',
+ description: 'HoverCard shows additional info on hover/focus. Use for profile cards, link summaries, inline definitions.',
bestPractices: [
- { guidance: true, description: 'Keep content supplementary — hover cards should enhance understanding without blocking the primary workflow.' },
- { guidance: true, description: 'Provide a dashed underline on text triggers so users know the element is hoverable.' },
- { guidance: false, description: 'Place critical actions or required information inside a hover card — users may miss content that only appears on hover.' },
- { guidance: false, description: 'Use a hover card when a simple Tooltip or Popover would suffice.' },
- ],
- anatomy: [
- {name: 'Header', required: false, description: 'Eyebrow header with optional copy and close buttons.'},
- {name: 'Body', required: true, description: 'Text pairings, icons, and media content.'},
- {name: 'Call to Action', required: false, description: 'Button for follow-up actions.'},
+ { guidance: true, description: 'Supplementary content only. Dashed underline on text triggers. Hook API for custom control.' },
+ { guidance: false, description: 'No critical actions — content disappears on cursor leave. Use Tooltip/Popover when simpler.' },
],
},
components: [