Skip to content

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

TypeScript

Improve Link docs page and block examples (#1595)

Ted McDonaldecec819cf7c1
diff --git a/packages/cli/templates/blocks/components/Link/LinkExternalLinks.doc.mjs b/packages/cli/templates/blocks/components/Link/LinkExternalLinks.doc.mjs
index c475d98985..9d20894edb 100644
--- a/packages/cli/templates/blocks/components/Link/LinkExternalLinks.doc.mjs
+++ b/packages/cli/templates/blocks/components/Link/LinkExternalLinks.doc.mjs
@@ -6,5 +6,5 @@ export const doc = {
'A vertical list of external links that open in a new tab with an indicator icon.',
isReady: true,
aspectRatio: 4 / 3,
- componentsUsed: ['Link'],
+ componentsUsed: ['Link', 'VStack'],
};
diff --git a/packages/cli/templates/blocks/components/Link/LinkExternalLinks.tsx b/packages/cli/templates/blocks/components/Link/LinkExternalLinks.tsx
index 39ac779e23..0a66b818f4 100644
--- a/packages/cli/templates/blocks/components/Link/LinkExternalLinks.tsx
+++ b/packages/cli/templates/blocks/components/Link/LinkExternalLinks.tsx
@@ -1,10 +1,11 @@
'use client';
import {XDSLink} from '@xds/core/Link';
+import {XDSVStack} from '@xds/core/Layout';
export default function LinkExternalLinks() {
return (
- <div style={{display: 'flex', flexDirection: 'column', gap: 8}}>
+ <XDSVStack gap={2}>
<XDSLink
label="GitHub"
href="https://github.com"
@@ -27,6 +28,6 @@ export default function LinkExternalLinks() {
isStandalone>
React Documentation
</XDSLink>
- </div>
+ </XDSVStack>
);
}
diff --git a/packages/cli/templates/blocks/components/Link/LinksWithTooltips.doc.mjs b/packages/cli/templates/blocks/components/Link/LinksWithTooltips.doc.mjs
index 0cd2d0cae5..745c2408fa 100644
--- a/packages/cli/templates/blocks/components/Link/LinksWithTooltips.doc.mjs
+++ b/packages/cli/templates/blocks/components/Link/LinksWithTooltips.doc.mjs
@@ -6,5 +6,5 @@ export const doc = {
'Horizontal row of standalone links with descriptive hover tooltips.',
isReady: true,
aspectRatio: 4 / 3,
- componentsUsed: ['Link'],
+ componentsUsed: ['Link', 'HStack'],
};
diff --git a/packages/cli/templates/blocks/components/Link/LinksWithTooltips.tsx b/packages/cli/templates/blocks/components/Link/LinksWithTooltips.tsx
index 1c7ecb8c61..820f2fe14c 100644
--- a/packages/cli/templates/blocks/components/Link/LinksWithTooltips.tsx
+++ b/packages/cli/templates/blocks/components/Link/LinksWithTooltips.tsx
@@ -1,10 +1,11 @@
'use client';
import {XDSLink} from '@xds/core/Link';
+import {XDSHStack} from '@xds/core/Layout';
export default function LinksWithTooltips() {
return (
- <div style={{display: 'flex', gap: 16, alignItems: 'center'}}>
+ <XDSHStack gap={4} vAlign="center">
<XDSLink
label="Settings"
href="/settings"
@@ -27,6 +28,6 @@ export default function LinksWithTooltips() {
isStandalone>
Help
</XDSLink>
- </div>
+ </XDSHStack>
);
}
diff --git a/packages/core/src/Link/Link.doc.mjs b/packages/core/src/Link/Link.doc.mjs
index 4432df3e96..086e0d538a 100644
--- a/packages/core/src/Link/Link.doc.mjs
+++ b/packages/core/src/Link/Link.doc.mjs
@@ -98,12 +98,13 @@ export const docs = {
],
usage: {
description:
- 'Link is a styled anchor element for inline and standalone text navigation with external link support and polymorphic rendering. Use it for navigating between pages or to external URLs within body text or as standalone actions.',
+ 'A styled anchor for inline and standalone text navigation. Supports external links, underline variants, tooltips, and custom link components for router integration. Use it for navigating between pages or to external URLs.',
bestPractices: [
- { guidance: true, description: 'Write descriptive, concise link text that clearly communicates the destination or action.' },
- { guidance: true, description: 'Use isStandalone when the link appears outside of inline text, so it receives proper base font sizing.' },
- { guidance: false, description: 'Use icon-only links without a visible text label — always include descriptive text.' },
+ { guidance: true, description: 'Write descriptive, concise link text that clearly communicates the destination.' },
+ { guidance: true, description: 'Set `isStandalone` when the link appears outside of inline text, so it receives proper base font sizing.' },
{ guidance: false, description: 'Use Link for actions that do not navigate — use a Button instead.' },
+ { guidance: false, description: 'Use generic text like "click here" or "read more" — describe the destination.' },
+ { guidance: false, description: 'Use icon-only links without a visible text label.' },
],
anatomy: [
{name: 'Label', required: true, description: 'The visible text of the link.'},
@@ -212,12 +213,13 @@ export const docsZh = {
],
usage: {
description:
- 'Link is a styled anchor element for inline and standalone text navigation with external link support and polymorphic rendering. Use it for navigating between pages or to external URLs within body text or as standalone actions.',
+ 'A styled anchor for inline and standalone text navigation. Supports external links, underline variants, tooltips, and custom link components for router integration. Use it for navigating between pages or to external URLs.',
bestPractices: [
- { guidance: true, description: 'Write descriptive, concise link text that clearly communicates the destination or action.' },
- { guidance: true, description: 'Use isStandalone when the link appears outside of inline text, so it receives proper base font sizing.' },
- { guidance: false, description: 'Use icon-only links without a visible text label — always include descriptive text.' },
+ { guidance: true, description: 'Write descriptive, concise link text that clearly communicates the destination.' },
+ { guidance: true, description: 'Set `isStandalone` when the link appears outside of inline text, so it receives proper base font sizing.' },
{ guidance: false, description: 'Use Link for actions that do not navigate — use a Button instead.' },
+ { guidance: false, description: 'Use generic text like "click here" or "read more" — describe the destination.' },
+ { guidance: false, description: 'Use icon-only links without a visible text label.' },
],
anatomy: [
{name: 'Label', required: true, description: 'The visible text of the link.'},
@@ -233,12 +235,13 @@ export const docsDense = {
'Styled anchor links w/ multiple variants + polymorphic link infra for custom link components (Next.js Link, React Router Link, etc.).',
usage: {
description:
- 'Link is a styled anchor element for inline and standalone text navigation with external link support and polymorphic rendering. Use it for navigating between pages or to external URLs within body text or as standalone actions.',
+ 'A styled anchor for inline and standalone text navigation. Supports external links, underline variants, tooltips, and custom link components for router integration. Use it for navigating between pages or to external URLs.',
bestPractices: [
- { guidance: true, description: 'Write descriptive, concise link text that clearly communicates the destination or action.' },
- { guidance: true, description: 'Use isStandalone when the link appears outside of inline text, so it receives proper base font sizing.' },
- { guidance: false, description: 'Use icon-only links without a visible text label — always include descriptive text.' },
+ { guidance: true, description: 'Write descriptive, concise link text that clearly communicates the destination.' },
+ { guidance: true, description: 'Set `isStandalone` when the link appears outside of inline text, so it receives proper base font sizing.' },
{ guidance: false, description: 'Use Link for actions that do not navigate — use a Button instead.' },
+ { guidance: false, description: 'Use generic text like "click here" or "read more" — describe the destination.' },
+ { guidance: false, description: 'Use icon-only links without a visible text label.' },
],
anatomy: [
{name: 'Label', required: true, description: 'The visible text of the link.'},