Skip to content

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

TypeScript

feat(core): add XDSBlockquote component (#1149) (#2198)

Andrey Goder670ef4879fdb
diff --git a/apps/storybook/stories/Blockquote.stories.tsx b/apps/storybook/stories/Blockquote.stories.tsx
new file mode 100644
index 0000000000..d635e1031c
--- /dev/null
+++ b/apps/storybook/stories/Blockquote.stories.tsx
@@ -0,0 +1,105 @@
+import type {Meta, StoryObj} from '@storybook/react';
+import {XDSBlockquote} from '@xds/core/Blockquote';
+import {XDSCard} from '@xds/core/Card';
+import {XDSSection} from '@xds/core/Section';
+import {XDSVStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+
+const meta: Meta<typeof XDSBlockquote> = {
+ title: 'Core/Blockquote',
+ component: XDSBlockquote,
+ tags: ['autodocs'],
+ argTypes: {
+ cite: {
+ control: 'text',
+ description: 'Optional attribution for the quote',
+ },
+ },
+};
+
+export default meta;
+type Story = StoryObj<typeof XDSBlockquote>;
+
+export const Default: Story = {
+ args: {
+ children:
+ 'Design is not just what it looks like and feels like. Design is how it works.',
+ },
+ render: args => (
+ <XDSSection variant="muted">
+ <XDSCard>
+ <XDSBlockquote {...args} />
+ </XDSCard>
+ </XDSSection>
+ ),
+};
+
+export const WithCitation: Story = {
+ render: () => (
+ <XDSSection variant="muted">
+ <XDSCard>
+ <XDSBlockquote cite="Steve Jobs">
+ Design is not just what it looks like and feels like. Design is how it
+ works.
+ </XDSBlockquote>
+ </XDSCard>
+ </XDSSection>
+ ),
+};
+
+export const InContent: Story = {
+ render: () => (
+ <XDSSection variant="muted">
+ <XDSCard>
+ <XDSVStack gap={3}>
+ <XDSText type="body">
+ In a 2003 interview, the importance of design thinking was
+ emphasized:
+ </XDSText>
+ <XDSBlockquote cite="Steve Jobs">
+ Design is not just what it looks like and feels like. Design is how
+ it works.
+ </XDSBlockquote>
+ <XDSText type="body">
+ This philosophy has guided product development for decades.
+ </XDSText>
+ </XDSVStack>
+ </XDSCard>
+ </XDSSection>
+ ),
+};
+
+export const NestedContent: Story = {
+ render: () => (
+ <XDSSection variant="muted">
+ <XDSCard>
+ <XDSBlockquote>
+ <XDSText type="body">
+ The best way to predict the future is to invent it.
+ </XDSText>
+ <XDSText type="supporting">From a talk at PARC in 1971.</XDSText>
+ </XDSBlockquote>
+ </XDSCard>
+ </XDSSection>
+ ),
+};
+
+export const MultipleParagraphs: Story = {
+ render: () => (
+ <XDSSection variant="muted">
+ <XDSCard>
+ <XDSBlockquote cite="Alan Kay">
+ <XDSVStack gap={2}>
+ <XDSText type="body">
+ The best way to predict the future is to invent it.
+ </XDSText>
+ <XDSText type="body">
+ People who are really serious about software should make their own
+ hardware.
+ </XDSText>
+ </XDSVStack>
+ </XDSBlockquote>
+ </XDSCard>
+ </XDSSection>
+ ),
+};
diff --git a/packages/cli/templates/blocks/components/Blockquote/BlockquoteShowcase.doc.mjs b/packages/cli/templates/blocks/components/Blockquote/BlockquoteShowcase.doc.mjs
new file mode 100644
index 0000000000..ec92c77b08
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Blockquote/BlockquoteShowcase.doc.mjs
@@ -0,0 +1,12 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'Blockquote',
+ name: 'Blockquote — Showcase',
+ description:
+ 'Blockquote with and without citation. A quick visual reference for the blockquote component.',
+ isReady: true,
+ isShowcase: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Blockquote', 'Layout'],
+};
diff --git a/packages/cli/templates/blocks/components/Blockquote/BlockquoteShowcase.tsx b/packages/cli/templates/blocks/components/Blockquote/BlockquoteShowcase.tsx
new file mode 100644
index 0000000000..469ec750fb
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Blockquote/BlockquoteShowcase.tsx
@@ -0,0 +1,26 @@
+'use client';
+
+import {XDSBlockquote} from '@xds/core/Blockquote';
+import {XDSStack} from '@xds/core/Layout';
+import * as stylex from '@stylexjs/stylex';
+
+const styles = stylex.create({
+ root: {
+ width: 500,
+ },
+});
+
+export default function BlockquoteShowcase() {
+ return (
+ <XDSStack direction="vertical" gap={4} xstyle={styles.root}>
+ <XDSBlockquote>
+ Design is not just what it looks like and feels like. Design is how it
+ works.
+ </XDSBlockquote>
+ <XDSBlockquote cite="Steve Jobs">
+ The people who are crazy enough to think they can change the world are
+ the ones who do.
+ </XDSBlockquote>
+ </XDSStack>
+ );
+}
diff --git a/packages/core/package.json b/packages/core/package.json
index 2bd821840b..791b0f8893 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -103,6 +103,12 @@
"import": "./dist/Banner/index.mjs",
"require": "./dist/Banner/index.js"
},
+ "./Blockquote": {
+ "source": "./src/Blockquote/index.ts",
+ "types": "./dist/Blockquote/index.d.ts",
+ "import": "./dist/Blockquote/index.mjs",
+ "require": "./dist/Blockquote/index.js"
+ },
"./Breadcrumbs": {
"source": "./src/Breadcrumbs/index.ts",
"types": "./dist/Breadcrumbs/index.d.ts",
diff --git a/packages/core/src/Blockquote/Blockquote.doc.mjs b/packages/core/src/Blockquote/Blockquote.doc.mjs
new file mode 100644
index 0000000000..1fe71bc25a
--- /dev/null
+++ b/packages/core/src/Blockquote/Blockquote.doc.mjs
@@ -0,0 +1,95 @@
+
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'Blockquote',
+ keywords: ["blockquote","quote","citation","pullquote","quotation","cite","excerpt"],
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Content of the blockquote.',
+ required: true,
+ },
+ {
+ name: 'cite',
+ type: 'ReactNode',
+ description: 'Optional attribution for the quote. Rendered in a <footer> with <cite>.',
+ },
+ {
+ name: 'xstyle',
+ type: 'StyleXStyles',
+ description:
+ 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}.',
+ },
+ ],
+ theming: {
+ targets: [
+ {className: 'xds-blockquote', visualProps: []},
+ ],
+ },
+ usage: {
+ description: 'A styled quotation block with an accent-colored left border and secondary text color. Use to highlight quoted content, testimonials, or excerpts.',
+ bestPractices: [
+ { guidance: true, description: 'Use for quoted text, testimonials, or highlighted excerpts from external sources.' },
+ { guidance: true, description: 'Provide a cite prop when the source of the quote is known.' },
+ { guidance: false, description: 'Use for callout boxes or informational notes — use XDSBanner for those.' },
+ ],
+ },
+};
+
+/** @type {import('../docs-types').ComponentDoc} */
+export const docsZh = {
+ name: 'Blockquote',
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: '引用块的内容。',
+ required: true,
+ },
+ {
+ name: 'cite',
+ type: 'ReactNode',
+ description: '引用的可选出处。在 <footer> 中以 <cite> 渲染。',
+ },
+ {
+ name: 'xstyle',
+ type: 'StyleXStyles',
+ description:
+ '用于布局自定义的 StyleX 样式(边距、定位、尺寸)。必须是 stylex.create() 的值 — 不能是 style={{}} 这样的内联样式对象。',
+ },
+ ],
+ theming: {
+ targets: [
+ {className: 'xds-blockquote', visualProps: []},
+ ],
+ },
+ usage: {
+ description: '带有强调色左边框和次要文本颜色的引用块。用于突出显示引用内容、推荐语或摘录。',
+ bestPractices: [
+ { guidance: true, description: '用于引用文本、推荐语或来自外部来源的高亮摘录。' },
+ { guidance: true, description: '当引用来源已知时,提供 cite 属性。' },
+ { guidance: false, description: '用于提示框或信息说明 — 应使用 XDSBanner。' },
+ ],
+ },
+};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsDense = {
+ description: 'styled quotation block w/ accent left border, secondary text, optional citation',
+ usage: {
+ description: 'A styled quotation block with an accent-colored left border and secondary text color. Use to highlight quoted content, testimonials, or excerpts.',
+ bestPractices: [
+ { guidance: true, description: 'Use for quoted text, testimonials, or highlighted excerpts.' },
+ { guidance: true, description: 'Provide cite when source is known.' },
+ { guidance: false, description: 'Use for callouts/notes — use XDSBanner instead.' },
+ ],
+ },
+ propDescriptions: {
+ children: 'blockquote content',
+ cite: 'optional attribution rendered in <footer><cite>',
+ xstyle: 'StyleX styles for layout; must be stylex.create() value',
+ },
+};
diff --git a/packages/core/src/Blockquote/XDSBlockquote.test.tsx b/packages/core/src/Blockquote/XDSBlockquote.test.tsx
new file mode 100644
index 0000000000..9cc4a6fe7f
--- /dev/null
+++ b/packages/core/src/Blockquote/XDSBlockquote.test.tsx
@@ -0,0 +1,88 @@
+/**
+ * @file XDSBlockquote.test.tsx
+ * @input Uses vitest, @testing-library/react, XDSBlockquote component
+ * @output Unit tests for XDSBlockquote component behavior
+ * @position Testing; validates XDSBlockquote.tsx implementation
+ *
+ * SYNC: When XDSBlockquote.tsx changes, update tests to match new behavior
+ */
+
+import {describe, it, expect, vi} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import {XDSBlockquote} from './XDSBlockquote';
+
+describe('XDSBlockquote', () => {
+ it('renders children in a blockquote element', () => {
+ render(<XDSBlockquote data-testid="bq">A quoted statement.</XDSBlockquote>);
+ const element = screen.getByTestId('bq');
+ expect(element).toBeInTheDocument();
+ expect(element.tagName).toBe('BLOCKQUOTE');
+ expect(element).toHaveTextContent('A quoted statement.');
+ });
+
+ it('renders xds-* class name for theme targeting', () => {
+ render(<XDSBlockquote data-testid="bq">Quote</XDSBlockquote>);
+ const element = screen.getByTestId('bq');
+ expect(element.className).toContain('xds-blockquote');
+ });
+
+ it('renders without cite by default', () => {
+ render(<XDSBlockquote data-testid="bq">Quote</XDSBlockquote>);
+ const element = screen.getByTestId('bq');
+ expect(element.querySelector('footer')).toBeNull();
+ expect(element.querySelector('cite')).toBeNull();
+ });
+
+ it('renders cite when provided', () => {
+ render(
+ <XDSBlockquote cite="Steve Jobs" data-testid="bq">
+ Design is not just what it looks like.
+ </XDSBlockquote>,
+ );
+ const element = screen.getByTestId('bq');
+ const footer = element.querySelector('footer');
+ expect(footer).toBeInTheDocument();
+ const cite = element.querySelector('cite');
+ expect(cite).toBeInTheDocument();
+ expect(cite).toHaveTextContent('Steve Jobs');
+ });
+
+ it('renders cite as ReactNode', () => {
+ render(
+ <XDSBlockquote
+ cite={<span data-testid="custom-cite">Custom attribution</span>}
+ data-testid="bq">
+ Quote
+ </XDSBlockquote>,
+ );
+ expect(screen.getByTestId('custom-cite')).toBeInTheDocument();
+ expect(screen.getByTestId('custom-cite')).toHaveTextContent(
+ 'Custom attribution',
+ );
+ });
+
+ it('forwards ref correctly', () => {
+ const ref = vi.fn();
+ render(<XDSBlockquote ref={ref}>Quote</XDSBlockquote>);
+ expect(ref).toHaveBeenCalledWith(expect.any(HTMLElement));
+ });
+
+ it('passes through additional props', () => {
+ render(
+ <XDSBlockquote data-testid="bq" aria-label="Important quote">
+ Quote
+ </XDSBlockquote>,
+ );
+ const element = screen.getByTestId('bq');
+ expect(element).toHaveAttribute('aria-label', 'Important quote');
+ });
+
+ it('renders ReactNode children', () => {
+ render(
+ <XDSBlockquote data-testid="bq">
+ <p data-testid="child-p">Paragraph inside blockquote</p>
+ </XDSBlockquote>,
+ );
+ expect(screen.getByTestId('child-p')).toBeInTheDocument();
+ });
+});
diff --git a/packages/core/src/Blockquote/XDSBlockquote.tsx b/packages/core/src/Blockquote/XDSBlockquote.tsx
new file mode 100644
index 0000000000..a8d302c13f
--- /dev/null
+++ b/packages/core/src/Blockquote/XDSBlockquote.tsx
@@ -0,0 +1,116 @@
+'use client';
+
+/**
+ * @file XDSBlockquote.tsx
+ * @input Uses React, stylex, spacing and color tokens
+ * @output Exports XDSBlockquote component and XDSBlockquoteProps
+ * @position Blockquote component; renders styled quotations with optional attribution
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Blockquote/Blockquote.doc.mjs
+ * - /packages/core/src/Blockquote/XDSBlockquote.test.tsx
+ * - /apps/storybook/stories/Blockquote.stories.tsx
+ * - /packages/cli/templates/blocks/components/Blockquote/ (showcase blocks)
+ */
+
+import {type ReactNode} from 'react';
+import type {XDSBaseProps} from '../XDSBaseProps';
+import * as stylex from '@stylexjs/stylex';
+import type {StyleXStyles} from '@stylexjs/stylex';
+import {colorVars, spacingVars, typeScaleVars} from '../theme/tokens.stylex';
+import {xdsClassName, mergeProps} from '../utils';
+
+export interface XDSBlockquoteProps extends XDSBaseProps<HTMLQuoteElement> {
+ /** Ref forwarded to the root <blockquote> element */
+ ref?: React.Ref<HTMLQuoteElement>;
+ /** Content of the blockquote */
+ children: ReactNode;
+ /**
+ * Optional attribution for the quote. Rendered in a <footer> with <cite>.
+ */
+ cite?: ReactNode;
+ /**
+ * StyleX styles created via `stylex.create()`. Merged with the component's
+ * base styles inside a single `stylex.props()` call for optimal deduplication.
+ *
+ * @example
+ * ```
+ * const overrides = stylex.create({ root: { marginBottom: 8 } });
+ * <XDSBlockquote xstyle={overrides.root}>Quote</XDSBlockquote>
+ * ```
+ */
+ xstyle?: StyleXStyles;
+ /**
+ * CSS class name(s) appended to the root element.
+ * If you're using StyleX, prefer `xstyle` for optimal style deduplication.
+ */
+ className?: string;
+ /**
+ * Inline styles to apply to the root element. Spread after StyleX
+ * inline styles, so these values take priority.
+ */
+ style?: React.CSSProperties;
+}
+
+const styles = stylex.create({
+ root: {
+ borderInlineStartWidth: spacingVars['--spacing-0-5'],
+ borderInlineStartStyle: 'solid',
+ borderInlineStartColor: colorVars['--color-border-emphasized'],
+ paddingInlineStart: spacingVars['--spacing-4'],
+ color: colorVars['--color-text-secondary'],
+ marginInlineStart: 0,
+ marginInlineEnd: 0,
+ marginBlockStart: 0,
+ marginBlockEnd: 0,
+ },
+ cite: {
+ display: 'block',
+ marginBlockStart: spacingVars['--spacing-2'],
+ fontSize: typeScaleVars['--text-supporting-size'],
+ lineHeight: typeScaleVars['--text-supporting-leading'],
+ fontStyle: 'normal',
+ },
+});
+
+/**
+ * Blockquote component for displaying quoted content.
+ *
+ * Renders a semantic `<blockquote>` with an accent-colored left border
+ * and secondary text color, matching the XDS visual language.
+ *
+ * @example
+ * ```
+ * <XDSBlockquote>Design is not just what it looks like.</XDSBlockquote>
+ * ```
+ */
+export function XDSBlockquote({
+ children,
+ cite,
+ xstyle,
+ className,
+ style,
+ ref,
+ ...props
+}: XDSBlockquoteProps) {
+ return (
+ <blockquote
+ ref={ref}
+ {...mergeProps(
+ xdsClassName('blockquote'),
+ stylex.props(styles.root, xstyle),
+ className,
+ style,
+ )}
+ {...props}>
+ {children}
+ {cite != null && (
+ <footer>
+ <cite {...stylex.props(styles.cite)}>{cite}</cite>
+ </footer>
+ )}
+ </blockquote>
+ );
+}
+
+XDSBlockquote.displayName = 'XDSBlockquote';
diff --git a/packages/core/src/Blockquote/index.ts b/packages/core/src/Blockquote/index.ts
new file mode 100644
index 0000000000..57023805cf
--- /dev/null
+++ b/packages/core/src/Blockquote/index.ts
@@ -0,0 +1,13 @@
+'use client';
+
+/**
+ * @file index.ts
+ * @input Imports from XDSBlockquote.tsx
+ * @output Exports XDSBlockquote component and props type
+ * @position Package entry point for Blockquote
+ *
+ * SYNC: When modified, update /packages/core/src/Blockquote/Blockquote.doc.mjs
+ */
+
+export {XDSBlockquote} from './XDSBlockquote';
+export type {XDSBlockquoteProps} from './XDSBlockquote';
diff --git a/packages/core/src/Markdown/XDSMarkdown.tsx b/packages/core/src/Markdown/XDSMarkdown.tsx
index 2f84c01323..092c4024ae 100644
--- a/packages/core/src/Markdown/XDSMarkdown.tsx
+++ b/packages/core/src/Markdown/XDSMarkdown.tsx
@@ -26,6 +26,7 @@ import {
import {XDSCodeBlock, XDSCode} from '../CodeBlock';
import {XDSCheckboxList} from '../CheckboxList/XDSCheckboxList';
import {XDSCheckboxListItem} from '../CheckboxList/XDSCheckboxListItem';
+import {XDSBlockquote} from '../Blockquote/XDSBlockquote';
import {XDSList} from '../List/XDSList';
import {XDSListItem} from '../List/XDSListItem';
import {XDSTable} from '../Table/XDSTable';
@@ -338,16 +339,6 @@ const styles = stylex.create({
noMarginBlockEnd: {
marginBlockEnd: 0,
},
- // Blockquote
- blockquote: {
- borderInlineStartWidth: spacingVars['--spacing-0-5'],
- borderInlineStartStyle: 'solid',
- borderInlineStartColor: colorVars['--color-border-emphasized'],
- paddingInlineStart: spacingVars['--spacing-4'],
- color: colorVars['--color-text-secondary'],
- marginInlineStart: 0,
- marginInlineEnd: 0,
- },
// Table
codeBlockWrapper: {
maxWidth: '100%',
@@ -1163,20 +1154,19 @@ function renderBlock(
return <BlockquoteComp key={index}>{bqC}</BlockquoteComp>;
}
return (
- <blockquote
+ <XDSBlockquote
key={index}
- {...stylex.props(
- styles.blockquote,
+ xstyle={[
spacing,
contentWidthValue != null
? dynamicStyles.proseWidth(contentWidthValue)
- : null,
+ : undefined,
contentAlign !== 'start'
? dynamicStyles.proseAlign(ALIGN_MARGIN[contentAlign])
- : null,
+ : undefined,
isFirst && styles.noMarginBlockStart,
isLast && styles.noMarginBlockEnd,
- )}>
+ ]}>
{node.children.map((c, i) =>
renderBlock(
c,
@@ -1194,7 +1184,7 @@ function renderBlock(
components,
),
)}
- </blockquote>
+ </XDSBlockquote>
);
}
case 'list': {
@@ -1407,7 +1397,16 @@ function renderBlock(
node.alignments[i] === 'right' && cellAlignStyles.right,
]}>
{h.children.map((c, j) =>
- renderInline(c, j, onLinkClick, cursor, citationCtx, linkComponent, inlinePlugins, components),
+ renderInline(
+ c,
+ j,
+ onLinkClick,
+ cursor,
+ citationCtx,
+ linkComponent,
+ inlinePlugins,
+ components,
+ ),
)}
</XDSTableHeaderCell>
))}
@@ -1425,7 +1424,16 @@ function renderBlock(
node.alignments[j] === 'right' && cellAlignStyles.right,
]}>
{cell.children.map((c, k) =>
- renderInline(c, k, onLinkClick, cursor, citationCtx, linkComponent, inlinePlugins, components),
+ renderInline(
+ c,
+ k,
+ onLinkClick,
+ cursor,
+ citationCtx,
+ linkComponent,
+ inlinePlugins,
+ components,
+ ),
)}
</XDSTableCell>
));
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 9ee12ca407..45722719fc 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -18,6 +18,7 @@ export * from './AspectRatio';
export * from './Avatar';
export * from './Badge';
export * from './Banner';
+export * from './Blockquote';
export * from './Breadcrumbs';
export * from './Button';
export * from './IconButton';