Skip to content

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

TypeScript

docs(Citation): add docsite showcase and examples (#2639)

Cindy Zhang26f933ac1bd1
diff --git a/packages/cli/templates/blocks/components/Citation/CitationInlineText.doc.mjs b/packages/cli/templates/blocks/components/Citation/CitationInlineText.doc.mjs
new file mode 100644
index 0000000000..dbb9e500bb
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Citation/CitationInlineText.doc.mjs
@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'Citation',
+ name: 'Citation — Inline Text',
+ displayName: 'Citation — Inline Text',
+ description:
+ 'Citations embedded within a paragraph of text, showing how they flow inline with surrounding content.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Citation', 'Text'],
+};
diff --git a/packages/cli/templates/blocks/components/Citation/CitationInlineText.tsx b/packages/cli/templates/blocks/components/Citation/CitationInlineText.tsx
new file mode 100644
index 0000000000..0008996729
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Citation/CitationInlineText.tsx
@@ -0,0 +1,42 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {XDSCitation} from '@xds/core/Citation';
+import {XDSText} from '@xds/core/Text';
+import {XDSStack} from '@xds/core/Layout';
+
+export default function CitationInlineText() {
+ return (
+ <XDSStack direction="vertical" gap={4} style={{maxWidth: 560}}>
+ <XDSText type="body">
+ React uses a virtual DOM to minimize expensive DOM operations
+ <XDSCitation
+ source={{title: 'React Documentation', url: 'https://react.dev'}}
+ number={1}
+ variant="number"
+ />
+ . This approach was inspired by earlier functional UI frameworks
+ <XDSCitation
+ source={{title: 'Elm Architecture', url: 'https://guide.elm-lang.org/architecture/'}}
+ number={2}
+ variant="number"
+ />
+ .
+ </XDSText>
+ <XDSText type="body">
+ StyleX compiles atomic CSS at build time for optimal performance
+ <XDSCitation
+ source={{
+ title: 'StyleX Documentation',
+ url: 'https://stylexjs.com',
+ icon: 'https://stylexjs.com/img/favicon.ico',
+ }}
+ number={3}
+ variant="label"
+ />
+ .
+ </XDSText>
+ </XDSStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/Citation/CitationShowcase.doc.mjs b/packages/cli/templates/blocks/components/Citation/CitationShowcase.doc.mjs
new file mode 100644
index 0000000000..da83240cd0
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Citation/CitationShowcase.doc.mjs
@@ -0,0 +1,15 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'Citation',
+ name: 'Citation — Showcase',
+ displayName: 'Citation — Showcase',
+ description:
+ 'All citation variants at a glance: label chips and numbered badges, with and without icons and links.',
+ isReady: true,
+ isShowcase: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Citation', 'Layout', 'Text'],
+};
diff --git a/packages/cli/templates/blocks/components/Citation/CitationShowcase.tsx b/packages/cli/templates/blocks/components/Citation/CitationShowcase.tsx
new file mode 100644
index 0000000000..cf87fca674
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Citation/CitationShowcase.tsx
@@ -0,0 +1,62 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {XDSCitation} from '@xds/core/Citation';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+
+export default function CitationShowcase() {
+ return (
+ <XDSStack direction="vertical" gap={6}>
+ <XDSStack direction="vertical" gap={2}>
+ <XDSText type="supporting" color="secondary">
+ Label variant
+ </XDSText>
+ <XDSStack direction="horizontal" gap={2} style={{flexWrap: 'wrap'}}>
+ <XDSCitation
+ source={{title: 'React Documentation', url: 'https://react.dev'}}
+ number={1}
+ variant="label"
+ />
+ <XDSCitation
+ source={{
+ title: 'GitHub',
+ url: 'https://github.com',
+ icon: 'https://github.githubassets.com/favicons/favicon.svg',
+ }}
+ number={2}
+ variant="label"
+ />
+ <XDSCitation
+ source={{title: 'Internal reference'}}
+ number={3}
+ variant="label"
+ />
+ </XDSStack>
+ </XDSStack>
+ <XDSStack direction="vertical" gap={2}>
+ <XDSText type="supporting" color="secondary">
+ Number variant
+ </XDSText>
+ <XDSStack direction="horizontal" gap={2}>
+ <XDSCitation
+ source={{title: 'TypeScript Handbook', url: 'https://typescriptlang.org'}}
+ number={1}
+ variant="number"
+ />
+ <XDSCitation
+ source={{title: 'MDN Web Docs', url: 'https://developer.mozilla.org'}}
+ number={2}
+ variant="number"
+ />
+ <XDSCitation
+ source={{title: 'W3C Specification'}}
+ number={3}
+ variant="number"
+ />
+ </XDSStack>
+ </XDSStack>
+ </XDSStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/Citation/CitationSourceList.doc.mjs b/packages/cli/templates/blocks/components/Citation/CitationSourceList.doc.mjs
new file mode 100644
index 0000000000..ccb9f32ab5
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Citation/CitationSourceList.doc.mjs
@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'Citation',
+ name: 'Citation — Source List',
+ displayName: 'Citation — Source List',
+ description:
+ 'A list of citation sources with icons, as you might show at the end of an AI-generated response or article footer.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Citation', 'Layout', 'Text'],
+};
diff --git a/packages/cli/templates/blocks/components/Citation/CitationSourceList.tsx b/packages/cli/templates/blocks/components/Citation/CitationSourceList.tsx
new file mode 100644
index 0000000000..af67999874
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Citation/CitationSourceList.tsx
@@ -0,0 +1,49 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {XDSCitation} from '@xds/core/Citation';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+
+const sources = [
+ {
+ title: 'React Documentation',
+ url: 'https://react.dev',
+ icon: 'https://react.dev/favicon-32x32.png',
+ },
+ {
+ title: 'TypeScript Handbook',
+ url: 'https://www.typescriptlang.org/docs/handbook/',
+ icon: 'https://www.typescriptlang.org/favicon-32x32.png',
+ },
+ {
+ title: 'MDN Web Docs',
+ url: 'https://developer.mozilla.org',
+ icon: 'https://developer.mozilla.org/favicon-48x48.cbbd161b.png',
+ },
+ {
+ title: 'W3C WAI-ARIA Specification',
+ url: 'https://www.w3.org/TR/wai-aria/',
+ },
+];
+
+export default function CitationSourceList() {
+ return (
+ <XDSStack direction="vertical" gap={3}>
+ <XDSText type="supporting" color="secondary">
+ Sources
+ </XDSText>
+ <XDSStack direction="horizontal" gap={2} style={{flexWrap: 'wrap'}}>
+ {sources.map((source, i) => (
+ <XDSCitation
+ key={source.title}
+ source={source}
+ number={i + 1}
+ variant="label"
+ />
+ ))}
+ </XDSStack>
+ </XDSStack>
+ );
+}
diff --git a/packages/core/src/Citation/Citation.doc.mjs b/packages/core/src/Citation/Citation.doc.mjs
index 08a138b84d..4c38e65fbd 100644
--- a/packages/core/src/Citation/Citation.doc.mjs
+++ b/packages/core/src/Citation/Citation.doc.mjs
@@ -9,10 +9,75 @@ export const docs = {
category: 'Content',
usage: {
- description: '',
+ description:
+ 'Citations display inline references to external sources. Use them to attribute information within AI-generated responses, articles, or anywhere provenance and source links are needed.',
+ bestPractices: [
+ {
+ guidance: true,
+ description:
+ 'Use the label variant when the source title adds meaningful context for the reader.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Use the number variant for compact inline references within body text, like footnotes.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Mix label and number variants in the same paragraph. Pick one style per context for visual consistency.',
+ },
+ ],
+ anatomy: [
+ {
+ name: 'Container',
+ required: true,
+ description:
+ 'The interactive wrapper — renders as an anchor when a URL is provided, or a span otherwise.',
+ },
+ {
+ name: 'Icon',
+ required: false,
+ description:
+ 'An optional favicon or source icon displayed before the label text. Only available in the label variant.',
+ },
+ {
+ name: 'Label text',
+ required: false,
+ description:
+ 'The source title, truncated with ellipsis when it exceeds the max width. Shown in the label variant.',
+ },
+ {
+ name: 'Number',
+ required: false,
+ description:
+ 'The citation index displayed as a superscript badge. Shown in the number variant.',
+ },
+ ],
},
- props: [],
+ props: [
+ {
+ name: 'source',
+ type: 'XDSCitationSource',
+ description:
+ 'The citation source object containing title, url, and optional icon.',
+ required: true,
+ },
+ {
+ name: 'number',
+ type: 'number',
+ description: 'The display index for this citation.',
+ required: true,
+ },
+ {
+ name: 'variant',
+ type: "'label' | 'number'",
+ description:
+ 'Display style — a label chip showing the source title or a compact numbered badge.',
+ default: "'label'",
+ },
+ ],
};
/** @type {import('../docs-types').TranslationDoc} */
diff --git a/packages/core/src/Citation/XDSCitation.tsx b/packages/core/src/Citation/XDSCitation.tsx
index 3ad5b24ab2..2d54506e04 100644
--- a/packages/core/src/Citation/XDSCitation.tsx
+++ b/packages/core/src/Citation/XDSCitation.tsx
@@ -10,6 +10,7 @@
*
* SYNC: When modified, update these files to stay in sync:
* - /packages/core/src/Citation/index.ts (exports if types change)
+ * - /packages/cli/templates/blocks/components/Citation/ (showcase blocks)
*/
import type React from 'react';