Block template

Describe a smaller composition, choose its preview shape, and connect it to component examples only when that relationship is real.

Start with a standalone block

Most blocks stand alone. Start with this shape unless the block is specifically the example or showcase for one component.

templates/acme-stat-card.doc.mjs

javascript
/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
export default {
  type: 'block',
  name: 'acme-stat-card',
  displayName: 'Acme Stat Card',
  description:
    'A compact metric card with a current value, period delta, and supporting trend. KPI, scorecard, summary, or dashboard statistic.',
  isReady: false,
  aspectRatio: 4 / 3,
  componentsUsed: ['Card', 'HStack', 'Text', 'VStack'],
};

Do not add exampleFor only because the block uses a component. componentsUsed records composition; exampleFor declares that one component owns the example.

Choose the component relationship

Field	Type	Required	Description
exampleFor	string	no	Block templates only: optional component ownership. Set this when the block is specifically an example of one component. Omit it for a standalone composition.
alsoExampleFor	string[]	no	Block templates only: additional component/hook doc pages whose Examples section should include this block.
alsoShowcaseFor	string[]	no	Block templates only: additional doc pages whose hero showcase should reuse this block (secondary placements; does not change the primary showcase).
componentsUsed	string[]	no	Block templates only: component names this block uses, for 'See also'/'Used in' cross-references (not primary attribution).
isShowcase	boolean	no	Block templates only: when true this block is the canonical hero showcase for its `exampleFor` component. Requires `exampleFor`.

From TemplateDoc: astryx docs authoring template-doc

Keep one clear primary owner. Use the also* fields only for intentional secondary placements.

templates/acme-status-card-showcase.doc.mjs

javascript
/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
export default {
  type: 'block',
  name: 'acme-status-card-showcase',
  displayName: 'Acme Status Card Showcase',
  description:
    'An account-health summary that demonstrates status, trend, and action states for AcmeStatusCard.',
  isReady: true,
  exampleFor: 'AcmeStatusCard',
  isShowcase: true,
  alsoExampleFor: ['AcmeDashboard'],
  aspectRatio: 4 / 3,
  componentsUsed: ['AcmeStatusCard', 'Button', 'HStack', 'VStack'],
};

Then check the package-scoped template list (astryx docs cli/integrations/building-blocks/templates/document-the-template/template-doc-overview) and confirm the entry carries the relationship you set. astryx component does not show integration blocks, so the list is where to check.

Choose a useful preview

Field	Type	Required	Description
aspectRatio	number	no	Block templates only (required): width-to-height ratio for preview containers (e.g. 16/9, 1, 3/4).

From TemplateDoc: astryx docs authoring template-doc

Start from the value for the closest shape below, render the block at that ratio, and adjust it until it neither clips nor leaves large empty space. These are starting points, not contract defaults.

Block shape	Starting value
Wide navigation, banner, toolbar, or tabs	`16 / 4`
Square button, badge, avatar, icon, spinner, or status	`1`
Tall navigation, calendar, list, or tree	`3 / 4`
Content card, dialog, table, or form group	`4 / 3`

scale affects only Astryx's own block previews. Integration blocks can leave it out.