An open source design system that's fully customizable and agent ready
schema_version: 3 template_version: 7 kind: component id: component:Blockquote authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-10-26 owners: [cixzhang] review_triggers: [public-api, behavior, layout, theming, accessibility] verified_by: [ .github/visual-baseline/manifest.json, packages/core/src/Blockquote/Blockquote.test.tsx, packages/core/src/theme/themingTargets.test.ts, apps/storybook/stories/Blockquote.stories.tsx, scripts/check-knowledge.mjs, apps/storybook/rtl-audit/targets.json, ] modules: [] families: [] design_specs: [design:bidirectionality] architecture: [architecture:component-theming-surface, architecture:public-component-api] contributing: []
system_specs: [spec:AST-009]
Blockquote component contract
Contract at a glance
| Area | Contract |
|---|---|
| Public contract | A semantic blockquote holding children, with an optional cite attribution. |
| Behavior | The quote has an inline-start rule and secondary text; a renderable cite follows the content in a bare cite element. |
| End-user impact | Readers see quoted text set apart; screen-reader users get a native blockquote and no stray landmark from the attribution. |
| Builder impact | None; the record describes shipped behavior. |
| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. |
| Review checks | Reject a physical left rule, a footer around the attribution, or a non-blockquote root. |
| Governing rules | design:bidirectionality/DR3; architecture:public-component-api/INV5,INV6,INV8; architecture:component-theming-surface/INV2. |
This table is a review projection; the body below is authoritative.
Intent
Blockquote sets quoted content apart from surrounding text with native quote semantics. It owns the rule, inset, and color of the quote and the placement of its optional attribution.
Compatibility and migration
- Released default preserved:
yes - Compatibility class: records shipped behavior; no public prop, default, DOM, or styling output changes
- Controlled/uncontrolled behavior: not applicable
- Migration decision: none
Consumer migration instructions belong in consumer docs and release notes.
Ownership boundary
Owns
- The
blockquoteroot, its rule, inset, color, and zeroed margins. - The Attribution element and its placement after the quotation.
Does not own / non-goals
- The quoted content and attribution text — owned by the caller.
- Quotation marks, if wanted — owned by the caller's content.
- Markdown block quotes — owned by
component:Markdown.
Public concepts
| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
|---|---|---|---|---|---|---|---|
| Attribution | present; absent | Renders the source of the quote after it. | Always | absent | component:Blockquote |
Stable | false, true, null, undefined, and '' render nothing. |
Behavioral and layout contract
| ID | Invariant | Basis |
|---|---|---|
| FR1 | The root is a blockquote carrying the blockquote target, with a solid --spacing-0-5 rule in --color-border-emphasized on its inline-start edge, --spacing-4 inline-start padding, secondary text color, word breaking for long words, and all margins zero. |
Current source and tests |
| FR2 | children render first inside the root. A renderable cite renders after them in a bare cite element — never wrapped in footer — displayed as a block with --spacing-2 top margin, supporting type, and normal font style. |
Current source and tests |
| FR3 | In a right-to-left region the rule and its padding sit on the right edge: the root uses logical inline-start border and padding, never physical left ones. | Current source and docs |
| FR4 | ref reaches the blockquote. Supported DOM, ARIA, data, and event props reach it; xstyle, className, and style merge in that order after component styles. Blockquote renders on the server. |
Current source and tests |
Allowed variation
- AV1 — Theme paint. A theme may restyle
blockquote, including the rule, without changing semantics or attribution placement.
Representative states
| State | Required invariant | Allowed variation |
|---|---|---|
| Quote only | blockquote with rule and secondary text; no cite. |
Content. |
| With attribution | cite follows the content; no footer or landmark. |
Attribution. |
| Right-to-left | Rule and padding on the right edge. | — |
Transformation and precedence order
- ORD1 — Styling inputs. Component class → component styles →
xstyle→className→style→ remaining caller props.
Performance and resources
- PR1 — Static render. Blockquote holds no state and uses no hooks.
Accessibility contract
- AR1 — Native quote. The root is a native
blockquote. - AR2 — No stray landmark. The attribution is a bare
cite; it is never wrapped in afooter, which inside a sectioning root would surface as a content-information landmark.
Design relationships
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
|---|---|---|---|---|
| Rule | An emphasized line on the inline-start edge. | Current source and docs | Supporting | FR1, FR3 |
| Quotation | The quoted content in secondary text. | Current source and docs | Prominent | FR1, FR2 |
| Attribution | The source, in supporting type, below the quotation. | Current source and docs | Supporting | FR2, AR2 |
Theming anatomy
{
"Rule": {"target": "blockquote"},
"Quotation": {"inherits": "blockquote"},
"Attribution": {"inherits": "blockquote"}
}
The rule is a border of the root, so it shares the root's blockquote target.
Family and system relationships
design:bidirectionalityDR3 owns inline-start and inline-end placement; FR3 applies it to the rule.architecture:public-component-apiowns ref, passthrough, and styling-input rules; FR4 applies them to the root.
Verification map
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
|---|---|---|---|---|
| FR1, FR4 | Blockquote.test.tsx render, class, ref, passthrough, and server tests |
Quote only | A non-blockquote root, a lost target, ref, or caller prop, or a failed server render fails. The stable visual baseline core-blockquote--default (neutral, light and dark) returns a changed rule, padding, color, or margin for review. Gap: no unit test asserts those styles, word breaking, or the styling-input merge order. |
audit:Blockquote/behavior |
| FR2, AR2 | Blockquote.test.tsx cite tests |
With and without attribution | A missing cite or a landmark wrapper fails. Gap: no test asserts that the attribution follows the content, and its block display, margin, type, and font style have no automated check, and the visual baseline renders no attribution. |
audit:Blockquote/a11y |
| FR3 | @astryx/no-physical-properties lint rule; Blockquote.stories.tsx |
Right-to-left | A physical left border or padding in Blockquote's styles fails lint. Gap: no rendered right-to-left check confirms the rule sits on the right edge. | audit:Blockquote/i18n-rtl |
| Theming anatomy map | scripts/check-knowledge.mjs |
Consumer anatomy and current target | Missing, extra, or stale mappings fail repository validation. | audit:Blockquote/theming |
| AR1 | Blockquote.test.tsx render test |
Quote only | A non-blockquote root fails. |
audit:Blockquote/a11y |
| PR1 | Blockquote.test.tsx server-render test |
Quote only | A failed server render fails. Gap: no test fails if Blockquote adds state or hooks. | audit:Blockquote/behavior |
| AR1, AR2 | Accessibility-tree evidence (spec:AST-009 FR3) |
Quote with attribution | Gap: no accessibility-tree check proves the blockquote role or the absence of a landmark; the unit tests query the DOM. | audit:Blockquote/a11y |
| RTL relation | RTL audit curated D8 target (apps/storybook/rtl-audit/targets.json) on Blockquote / Default |
Inline-start padding; LTR and RTL | A logical start padding that stays on the same physical side in RTL fails D8. | audit:Blockquote/i18n-rtl |
Decision log
None recorded. The record describes shipped behavior.
Open questions
None.
Content boundary
This file does not duplicate consumer prop tables/examples, current audit results, implementation steps, or family/system rules. It links to their owners.