Authoring

In global mode: users can install your integration for their computer, beside the global CLI. It then applies in folders outside any project, and inside a project only if the project installs it. See npx @astryxdesign/cli docs global and npx @astryxdesign/cli docs authoring/global-integrations.

An integration is a way to share things with Astryx users: a package you own and maintain, built on a framework Astryx gives you. Publish one, many, or any mix, and people install it in one step. It works with the Astryx CLI alongside Core. See each kind under npx @astryxdesign/cli docs authoring/building-blocks.

For example, ship a carousel as an integration. Any app that installs it can find it with npx @astryxdesign/cli search carousel, and the CLI uses it like any Astryx Core component.

An integration can also replace a built-in template or doc. To start, install @astryxdesign/cli and open npx @astryxdesign/cli docs authoring/quick-start.

Every field of every file you write for an integration is in npx @astryxdesign/cli docs authoring/field-reference.

Every integration runs npx @astryxdesign/cli integration check --strict in its own build: it is required, not optional, so a doc, prop, or link that stops matching the code fails your build instead of your users' apps. See npx @astryxdesign/cli docs authoring/ship/checks.

An integration starts as a normal npm package. Make a folder for it, create a package.json inside that folder, give the package a name, make it an ES module, then install the Astryx CLI, Core, and TypeScript for development.

bash
mkdir acme-widgets && cd acme-widgets
npm init -y
npm pkg set name=@acme/astryx-widgets type=module
npm pkg set 'exports={}' --json
npm install -D @astryxdesign/cli @astryxdesign/core typescript@6

• Set "type": "module": the .js files the CLI generates, such as a built theme, are ES modules, and Node fails to load them in a package marked "type": "commonjs", which npm init -y writes on npm 11.
• Start with "exports": {}: each component and template you add then writes the public import that integration verify resolves.
• Run the CLI as npx @astryxdesign/cli, which runs the @astryxdesign/cli you installed as a devDependency.
• Component commands read Core, so they need @astryxdesign/core installed.
• The checks compare your docs with your code through TypeScript's JavaScript compiler API, which typescript 5.0 through 6 has. TypeScript 7 does not ship that API: on TypeScript 7, also install @typescript/typescript6, its TypeScript 6 API package, and the checks use it.

An integration can ship several kinds of items. Start with a component named AcmeCarousel.

bash
npx @astryxdesign/cli integration add component AcmeCarousel

text
component contribution added
​
[ok] AcmeCarousel
​
Declare component root ./components in astryx.integration.mjs.
​
- components/AcmeCarousel.doc.mjs
- components/AcmeCarousel.tsx
- package.json
- astryx.integration.mjs

integration add creates the component source, its .doc.mjs, the package export, and astryx.integration.mjs. Update the generated doc so the CLI understands the component, then write the component itself.

Read it back the way an app will.

bash
npx @astryxdesign/cli component AcmeCarousel

You now have an integration package with one exported component.

Run integration check --strict in every build (npx @astryxdesign/cli docs authoring/ship/checks): a doc, prop, template, or link that drifts from the code then fails your build, not your users' apps. Set it up now, as the typecheck script, and run it.

bash
npm pkg set scripts.typecheck="astryx integration check --strict"
npm run typecheck

text
[ok] 0 errors, 0 warnings, 0 skipped. Every check passed.

• Run typecheck in CI and before every publish. When you add a tsconfig.json, put tsc --noEmit && in front of the check so the same script checks your types.
• What each check covers, and what --strict adds: npx @astryxdesign/cli docs authoring/ship/checks.

Run integration verify to check that an app would see the component, then make the .tgz file you install next. --pack-destination .. writes it beside the package folder, so the next pack does not ship it.

bash
npx @astryxdesign/cli integration verify
npm pack --pack-destination ..

text
Integration package ready
​
[ok] @acme/astryx-widgets@1.0.0
​
4 packed files; 3/3 required files present.

integration verify installs the packed package in a temporary app and confirms the component resolves through its public import there (npx @astryxdesign/cli docs authoring/ship/checks). It publishes nothing and leaves no .tgz file, so npm pack writes ../acme-astryx-widgets-1.0.0.tgz for the next step.

Install Core, the CLI, and your .tgz file in a new app. The app loads your package because it is a dependency, with no config.

bash
cd ..
mkdir my-app && cd my-app
npm init -y
npm install @astryxdesign/core @astryxdesign/cli ../acme-astryx-widgets-1.0.0.tgz
npx @astryxdesign/cli component AcmeCarousel

text
**Import:** `import {AcmeCarousel} from '@acme/astryx-widgets/components/AcmeCarousel';`

The next sections explain each package field and the integration file. To build the real component, continue with npx @astryxdesign/cli docs authoring/building-blocks/components.

An integration is an ordinary npm package. These six fields control how it is named, developed, checked, and published.

peerDependencies are packages the app supplies. devDependencies are packages you use while building the integration.

Peer ranges and releases are covered in npx @astryxdesign/cli docs authoring/ship/versioning; files and publishing in npx @astryxdesign/cli docs authoring/ship/publishing. Add "typecheck": "tsc --noEmit && astryx integration check --strict" to scripts so each run checks your types and that your docs, props, and links still match the code. It needs typescript and a tsconfig.json; see npx @astryxdesign/cli docs authoring/ship/checks.

The first integration add creates astryx.integration.mjs, and each later add updates it. You do not need to write or edit this file during the quick start.

• package.json defines the npm package, including its name, version, dependencies, published files, and exports.
• astryx.integration.mjs tells the CLI where the package keeps each kind of integration item.
• The integration item files live under those roots. For example, a component can have AcmeWidget.tsx for its source and AcmeWidget.doc.mjs for its documentation.

javascript
/** @type {import('@astryxdesign/cli/authoring').AstryxIntegration} */
export default {
  components: './components',
};

The file tells the CLI where this package keeps its integration items. Edit it only when you want a custom root or another optional setting. Paths are relative to package.json, and later adds keep a custom path you already set.

Every field is in npx @astryxdesign/cli docs authoring integration.

You can edit the package files by hand, but the CLI handles the normal workflow. These links always open the canonical command docs.

astryx integration add: Add one working contribution to an integration package. Read it with npx @astryxdesign/cli docs cli/commands/integration-add.

astryx integration verify: Check the package the way npm will publish it, before you publish. Read it with npx @astryxdesign/cli docs cli/commands/integration-verify.

astryx doctor integration: Check an integration package while authoring it. Read it with npx @astryxdesign/cli docs cli/commands/doctor-integration.

In global mode: users can also install your package for their computer, beside the global CLI (npm i -g @astryxdesign/cli your-package). It then applies in folders outside any project, and inside a project only if the project installs it. See npx @astryxdesign/cli docs global and npx @astryxdesign/cli docs authoring/global-integrations.

In global mode: every kind your package adds also applies outside projects when users install it for their computer, beside the global CLI; inside a project, only if the project installs it. See npx @astryxdesign/cli docs global and npx @astryxdesign/cli docs authoring/global-integrations.

These are everything you can add to an integration. Mix them however you like. You are not limited to any one thing.

• One component, or a whole library of them.
• Components together with themes and templates.
• Only docs, if that is all you need.
• Agent guidance, so the AI agents in an app follow your library.
• Codemods that update app code across your breaking changes.

Each kind below is its own guide. Open one to learn, in depth, how to add it and how to keep it healthy as your package grows.

In global mode: components from an integration installed for the computer show up outside projects; inside a project, only components from integrations the project installs. See npx @astryxdesign/cli docs global and npx @astryxdesign/cli docs authoring/global-integrations.

Choose a unique PascalCase name, such as AcmeCarousel. The name is the component's public export and CLI identity, so keep it stable. Use displayName when you only want to change the label people read.

• Prefer a name that describes the component's purpose in your product.
• Avoid a Core component name unless you are deliberately replacing that component.
• If replacement is truly required, read npx @astryxdesign/cli docs authoring/building-blocks/components/replace-a-core-component.

Run integration add component in your package with the name. It writes the component, its doc file, and the public import apps use.

bash
npx @astryxdesign/cli integration add component AcmeCarousel

text
component contribution added
​
[ok] AcmeCarousel
​
Declare component root ./components in astryx.integration.mjs.
​
- components/AcmeCarousel.doc.mjs
- components/AcmeCarousel.tsx
- package.json
- astryx.integration.mjs

integration add starts with one source export and one single-component .doc.mjs. Keep that shape for one public component. If the source exposes a family, choose the correct shape in npx @astryxdesign/cli docs authoring/building-blocks/components/describe-the-component.

Add never overwrites a file, and --dry-run shows what it would write. Component commands read Core, so install @astryxdesign/core in the package first (npx @astryxdesign/cli docs authoring/quick-start).

To document a component your package already has, write its doc beside the source file and name the doc after that file, such as acme-gallery.doc.mjs beside acme-gallery.tsx. Set name to the export apps import, such as name: 'AcmeGallery', and keep both files inside the components root that astryx.integration.mjs declares. The file does not have to be named after the component; npx @astryxdesign/cli docs authoring/building-blocks/components/component-imports shows how apps then find it.

In global mode: when users install your package for their computer, beside the global CLI, your components show up in folders outside any project; inside a project, only if the project installs your package. See npx @astryxdesign/cli docs global and npx @astryxdesign/cli docs authoring/global-integrations.

A component's .doc.mjs is part of the integration's public contract, not optional commentary. Astryx uses it for CLI output and search, and people and agents read it to decide whether the component fits and how to use it.

• Change the source and its .doc.mjs together.
• Update the doc whenever the public name, import, behavior, props, defaults, examples, or accessibility requirements change.
• integration verify checks the doc shape and packed import, and doctor integration components compares each props table with the component's TypeScript props (npx @astryxdesign/cli docs authoring/building-blocks/components/describe-the-component/check-the-props). Neither can prove the prose still matches the component.

Every component doc has one stable identity and enough usage guidance for a reader to choose it correctly. Pick the shape below that matches your module.

After every source or doc change, read the component back. This output is what people and agents receive.

bash
npx @astryxdesign/cli component AcmeCarousel

integration add component creates the normal doc for one public component. Keep the generated identity and import, then replace its sample text and props with the component's real public contract.

javascript
/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
export default {
  type: 'component',
  name: 'AcmeCarousel',
  displayName: 'Acme Carousel',
  import: '@acme/astryx-widgets/components/AcmeCarousel',
  usage: {
    description:
      'Cycles through slides one at a time. Use it for a small set of related cards.',
  },
  props: [
    {
      name: 'slides',
      type: 'ReactNode[]',
      description: 'The slides to show, in order.',
      required: true,
    },
  ],
};

• Keep props on the top-level doc. Private implementation helpers do not need entries.
• Name the doc after the source file beside it, such as AcmeCarousel.doc.mjs beside AcmeCarousel.tsx, and change both in the same pull request.
• If the module later exposes several related public exports, adapt this doc with npx @astryxdesign/cli docs authoring/building-blocks/components/describe-the-component/component-family.

Every field is in npx @astryxdesign/cli docs authoring component-doc.

Write usage.description so a person or agent can decide whether this is the right component without opening its source. Say what it does, when to use it, and the most important boundary with a nearby alternative.

javascript
usage: {
  description:
    'Cycles through slides one at a time. Use it for a small set of related cards. Use a static list when every item should stay visible.',
  bestPractices: [
    {guidance: true, description: 'Keep the slide order stable while someone interacts with the carousel.'},
    {guidance: false, description: 'Hide information that must remain visible for comparison.'},
  ],
},

Set keywords to the words people search for: synonyms and the task the component does, such as keywords: ['slider', 'slideshow', 'rotating cards']. npx @astryxdesign/cli search ranks a match on a component's name or keywords above one in its description, so without keywords a search for the component's task can list Core components first. Check with the words a person would type:

bash
npx @astryxdesign/cli search "rotating cards" --type component

Copy the public prop names and types from the source. Explain the behavior a caller controls, not only the TypeScript type.

javascript
props: [
  {
    name: 'slides',
    type: 'ReactNode[]',
    description: 'The slides to show, in order.',
    required: true,
  },
  {
    name: 'interval',
    type: 'number',
    description: 'Milliseconds between automatic slide changes.',
    default: '5000',
  },
],

• Set required: true only when every caller must pass the prop.
• Write default exactly as the value should appear in documentation.
• Skip styling escape hatches such as xstyle, className, and style.
• npx @astryxdesign/cli doctor integration components lists a documented prop the code lacks, a public prop the doc misses, and a wrong required. See npx @astryxdesign/cli docs authoring/building-blocks/components/describe-the-component/check-the-props.

Add short examples for important usage that the prop table does not make obvious. Each example should teach one complete pattern and use only public imports.

javascript
examples: [
  {
    label: 'Automatic rotation',
    code: '<AcmeCarousel slides={slides} interval={5000} />',
  },
],

Read the component after every source or doc change. Confirm that its purpose, import, props, defaults, and examples match the source, then verify the packed package.

bash
npx @astryxdesign/cli component AcmeCarousel
npx @astryxdesign/cli doctor integration components
npx @astryxdesign/cli integration verify

Start with a complete single-component doc. Convert its top-level props into a components array only when one source module or component directory exposes several public components or hooks as one family. The family doc keeps the shared usage guidance; each array entry owns one public export.

• Put the primary or most-used export first.
• Use a full entry when this file owns that export's description and signature.
• Use props for a component entry. Use params and returns for a hook entry.
• Do not add private implementation helpers or exports that people should not use directly.

Every field is in npx @astryxdesign/cli docs authoring component-doc.

javascript
/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
export default {
  type: 'component',
  name: 'AcmeTabs',
  displayName: 'Acme Tabs',
  import: '@acme/astryx-widgets/components/AcmeTabs',
  usage: {
    description:
      'Switches between related views without leaving the page.',
  },
  components: [
    {
      name: 'AcmeTabs',
      displayName: 'Acme Tabs',
      description: 'Owns selection and lays out the tab list and panels.',
      props: [
        {
          name: 'value',
          type: 'string',
          description: 'The selected tab value.',
          required: true,
        },
      ],
    },
    {
      name: 'AcmeTab',
      displayName: 'Acme Tab',
      description: 'Selects one view in Acme Tabs.',
      props: [
        {
          name: 'value',
          type: 'string',
          description: 'The value this tab selects.',
          required: true,
        },
      ],
    },
  ],
};

The public module named by import must export every component or hook named by a full entry. Apps then list, search and open each component in the family by its own name. A full entry the module does not export is not listed, and integration verify does not report it: check the family with npx @astryxdesign/cli component --list. When import names output your pack lifecycle builds (such as dist), the members are listed once that output exists, and integration verify compares them as they are listed after the pack builds it.

A member's source is the .tsx file in the family doc's folder, or below it, that declares it: the one the family's own file or the module import names reaches, else the one in that folder that declares the name, as when import names built output. A member that only a bundle or a file outside that folder declares is still listed, with no source for --source or swizzle. A member is not listed when a doc's file or a Core name your package replaces already has its name. A member that shares a name with Core opens with --package.

When one family member needs its own doc, replace its full entry with {name: 'MemberName'} and move the details into a sibling doc. The parent keeps the family relationship without copying the child's content. Continue with npx @astryxdesign/cli docs authoring/building-blocks/components/describe-the-component/subcomponent.

Start with a component family doc. Move one public member into a sibling doc when it has its own source and enough behavior, props, or usage guidance to maintain separately. The parent still lists the member, but only by name.

• Keep a small member inline when its whole contract stays clear in the family doc.
• Use a sibling doc when the member needs focused search results, examples, usage guidance, or independent maintenance.
• Give each member one documentation owner. Do not keep a full parent entry and a sibling doc for the same name.

javascript
/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
export default {
  type: 'component',
  name: 'AcmeDialog',
  displayName: 'Acme Dialog',
  import: '@acme/astryx-widgets/components/AcmeDialog',
  usage: {description: 'Presents a focused task above the current page.'},
  components: [
    {
      name: 'AcmeDialog',
      displayName: 'Acme Dialog',
      description: 'Owns the modal surface and open state.',
      props: [],
    },
    {name: 'AcmeDialogHeader'},
  ],
};

The name-only entry keeps AcmeDialogHeader in the family. Its description and props come only from the sibling file.

javascript
/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
export default {
  type: 'component',
  name: 'AcmeDialogHeader',
  displayName: 'Acme Dialog Header',
  import: '@acme/astryx-widgets/components/AcmeDialogHeader',
  subComponentOf: 'AcmeDialog',
  description: 'Labels an Acme Dialog and holds its close action.',
  props: [
    {
      name: 'title',
      type: 'string',
      description: 'The dialog title.',
      required: true,
    },
  ],
};

Every field is in npx @astryxdesign/cli docs authoring component-doc.

• subComponentOf must exactly match the parent doc's name.
• description explains this member's role in the family. usage is optional; add it when the member needs guidance beyond that sentence.
• The CLI does not copy family fields such as group, category, or keywords from the parent to the child. Set any the child needs in its own doc.

doctor integration components compares every props table in your component docs, hidden docs and every family entry included, with the props the component's TypeScript declares. Run it in your package after you change a component or its doc.

bash
npx @astryxdesign/cli doctor integration components

text
severity:  [warn]
component: AcmeCarousel
prop:      loop
kind:      not_in_code
message:   "loop" is documented, but AcmeCarousel's props have no "loop".
doc:       components/AcmeCarousel.doc.mjs
source:    components/AcmeCarousel.tsx
docType:   boolean
​
1 prop(s) differ between the docs and the code in 1 of 1 component(s) compared (TypeScript 6.0.3). These are warnings: update the doc, or the code if the doc is right.

• A doc's own props describe the export its name names. In a family doc, each entry describes its own export. A hook entry documents parameters and returns, so it is not compared.
• It reads props with the typescript your package installs, and reads your package's tsconfig.json the way tsc -p does. It finds TypeScript the way the docs check does, TypeScript 7 included (npx @astryxdesign/cli docs authoring/building-blocks/docs/check-your-docs). Without a usable one it prints [skip] Props not compared and the reason.
• Findings are warnings and leave the exit code at 0. Read them before you publish. With --json, they are in data.propDrift.findings.

Each finding's kind says what differs. Fix the doc, or the code if the doc is right.

For a prop your package declares, the check also compares the documented type, but only where both sides read exactly. It never guesses, so a type it cannot judge is listed, not reported. It needs TypeScript 4.8 or later: with an older one it prints [skip] Prop types not judged and judges none.

text
severity:  [warn]
component: AcmeCarousel
prop:      interval
kind:      type_mismatch
message:   "interval" is documented as string, but the code declares number.
doc:       components/AcmeCarousel.doc.mjs
source:    components/AcmeCarousel.tsx
docType:   string
codeType:  number

• Write the type as the source writes it, such as ReactNode[] or (index: number) => void. Parameter names, member order, quotes and whitespace may differ. Text that writes readonly must match exactly, parameter names included; only whitespace may differ. React.X names React's own X where the prop is declared, so it matches a bare X only where that name is React's: React.KeyboardEvent is not the DOM's KeyboardEvent.
• Name a type as the file that declares the prop names it, so an import renamed there (Item as BaseItem) is written as that file writes it. A field (cfg.level) takes its prop's file, even when the field's own type is declared in another file.
• A type written another way is judged only when both sides are built from exact parts: primitives such as string and number, string, number and boolean literals, string enum members, arrays and unions of these, and type names that stand for them. Union members may come in any order, and a member another covers adds nothing, as TypeScript passes it there: undefined beside void, or string[] beside (string | number)[].
• A mutable array type matches a readonly one, because callers can pass it. A readonly one documented for a mutable array is a mismatch.
• When a prop's variants give a field different types, as {value: string} | {value: number} does, document every variant's type (string | number). The types of only some variants are listed: the prop's variants give this field different types. With more than six variant types, any other type is listed too.
• To name an alias and show its values, write AcmeSize = 'sm' | 'md' or AcmeSize ('sm' | 'md'). Both parts must match.
• An optional prop's undefined is set aside on both sides. With exactOptionalPropertyTypes, the doc shows undefined exactly when the code declares it.
• Anything else, such as an object, a tuple, a generic with arguments, keyof, an intersection, or a mapped or conditional type written another way, is not compared.

The check prints how many documented types it judged, then lists the rest by reason: not a form the check judges exactly, a field the prop's variants give different types, a standard prop, or a prop declared outside the package. With --json, they are in data.propDrift.typesNotCompared.

text
[info] Documented prop types judged: 2; not compared: 0. A type is judged when the doc writes it the same as the source (exactly, if it contains `readonly`), or when both are primitives, literals, arrays and unions of those, or names for them.

When the check cannot read a component's props exactly, it lists the component under [info] Props not compared, with the reason, instead of reporting findings that might be wrong.

text
[info] Props not compared for 1 documented component(s):
​
component: AcmeCarousel
doc:       components/AcmeCarousel.doc.mjs
reason:    AcmeCarousel depends on `@acme/motion` (imported in AcmeCarousel.tsx), which the compiler could not resolve, usually a dependency that is not installed. Install the package's dependencies and run this check again

Apps copy the component doc's import field into their code, so that exact specifier must resolve from your packed package. integration add writes it together with an exports entry in package.json.

json
"exports": {
  "./components/AcmeCarousel": "./components/AcmeCarousel.tsx"
}

Add writes the entry only when package.json already has an exports map, so start every package with "exports": {}.

A file does not have to be named after its component. When Slides.tsx exports AcmeCarousel and nothing named Slides, keep the doc beside it as Slides.doc.mjs and set its name to AcmeCarousel: apps list, search and open the component by that name, and integration verify checks that its import exports AcmeCarousel. A file that exports its own name keeps that name. A package that names its files in kebab case works the same way: acme-gallery.doc.mjs beside acme-gallery.tsx sets name: 'AcmeGallery'.

The file name still opens the doc. A name that Core or another doc's file already has stays theirs, and so does a Core name your package replaces: with Badge.doc.mjs naming AcmeBadge, npx @astryxdesign/cli component Badge opens Core's Badge, and --package with your package name reaches yours.

integration verify unpacks the packed package into a temporary app, resolves each documented import, and checks that the module exports the documented component name. Its --json output names each failure by code.

bash
npx @astryxdesign/cli integration verify

• component_import_unresolvable means the exports map has no entry for the documented import.
• component_export_missing means the module does not export the documented name, or package.json has no exports map.
• typescript_extension_in_specifier means the public import ends in .ts or .tsx.

To import from the package root, set import: '@acme/astryx-widgets' and re-export the component from the file that exports["."] points to. See npx @astryxdesign/cli docs cli/commands/integration-verify.

In global mode: outside a project, imports the CLI prints name packages installed for the computer, which a new app must install before it can build them; inside a project, only packages the project installs are printed. See npx @astryxdesign/cli docs global and npx @astryxdesign/cli docs authoring/global-integrations.

An app that installs your package sees the component beside Core components, with its package name and public import. The app needs no config.

bash
npx @astryxdesign/cli component AcmeCarousel
npx @astryxdesign/cli component --list
npx @astryxdesign/cli search carousel

text
package: @acme/astryx-widgets
​
# AcmeCarousel
​
Cycles through slides one at a time. Use it for a small set of related cards.
​
**Import:** `import {AcmeCarousel} from '@acme/astryx-widgets/components/AcmeCarousel';`

component --list shows it as import: @acme/astryx-widgets/components/AcmeCarousel [@acme/astryx-widgets]. The same commands work in your package while you build it.

Install the packed package in a test app before publishing. Then run the same detail, list, and search commands there. See npx @astryxdesign/cli docs authoring/ship/test-in-an-app.

In global mode: to check your package in an app, install it in that app; a copy installed for your computer is not used inside a project. To check it outside projects, install it for your computer beside the CLI. See npx @astryxdesign/cli docs global and npx @astryxdesign/cli docs authoring/global-integrations.

Most components should not use replaces. Give a new component its own name and let apps choose it explicitly. Replace Core only when your component must become the default for one Core identity everywhere the integration is active.

• Your component intentionally serves the same role as one specific Core component.
• Every app that loads the integration should get your component from unqualified component detail, component --list, search, swizzle <Name>, and issue routing.
• You have tested both the replacement and explicit access to the original Core component.

• Your component is an alternative, variant, wrapper, or product-specific extension. Give it a unique name instead.
• You only need to resolve an accidental name collision.
• You want the replacement in only one screen or workflow. Replacement applies across the app wherever the integration is active.

javascript
/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
export default {
  type: 'component',
  name: 'AcmeSideNav',
  displayName: 'Acme Side Nav',
  replaces: 'SideNav',
  import: '@acme/astryx-widgets/components/AcmeSideNav',
  usage: {description: 'Product navigation for Acme apps.'},
  props: [],
};

Every field is in npx @astryxdesign/cli docs authoring component-doc.

The replacement turns on only when your package declares the first CLI release that applies it. Add this to its package.json:

json
{
  "peerDependencies": {"@astryxdesign/cli": ">=0.6.7"},
  "peerDependenciesMeta": {"@astryxdesign/cli": {"optional": true}}
}

• Any @astryxdesign/cli range that starts at that release or later turns it on, including the >=0.7.0 that integration add doc --parent wrote in published 0.6.4 and 0.6.5, and integration add theme in published 0.6.5.
• Without such a range, the component keeps its own name, the Core component stays selected (a component named like its target stays ambiguous by that bare name, as before), and doctor integration components warns with the range to add. Apps that load such a package see no change.
• replaces names the Core ComponentDoc identity, not its display label, import path, or a standalone hook.
• Your component may keep a distinct name or use the same name as the target. A distinct name remains directly addressable on older CLIs that ignore replaces.
• --package @astryxdesign/core always selects the original Core component, and --package with your package selects your component by either name.
• Replacing SideNav replaces only that name. SideNavItem and the other SideNav parts stay Core components; document any parts your package provides under their own names.
• swizzle --list lists Core components, including the one you replace. swizzle SideNav copies your component, and swizzle SideNav --package @astryxdesign/core copies the original.

bash
npx @astryxdesign/cli doctor integration components
npx @astryxdesign/cli component SideNav
npx @astryxdesign/cli component AcmeSideNav
npx @astryxdesign/cli component SideNav --package @astryxdesign/core

• Once the package declares the range, a missing target, invalid value, second replacement for one target in the same package, or a replacement named after a different Core component is an error. Without the range, doctor integration components reports each of these as a warning.
• When several integrations replace one target, explicit configuration beats the automatic pick. Among explicitly configured integrations, the later package wins and Doctor warns. Among autolinked integrations alone, the dependency listed later in package.json wins and Doctor warns.

In global mode: a replacement from a package installed for the computer applies in folders outside any project; inside a project, only replacements from packages the project installs apply. See npx @astryxdesign/cli docs global and npx @astryxdesign/cli docs authoring/global-integrations.

In global mode: templates from an integration installed for the computer show up outside projects; inside a project, only templates from integrations the project installs. See npx @astryxdesign/cli docs global and npx @astryxdesign/cli docs authoring/global-integrations.

Unlike a component, a template becomes app code: an app copies it into its own code and adapts it to its product.

A component stays a package dependency and updates with the package. A copied template does not, so updating the package never rewrites the app's copy.

bash
# How an app finds a template and copies it
npx @astryxdesign/cli template --list
npx @astryxdesign/cli template acme-dashboard src/app/dashboard

Templates help other people build apps faster while keeping a consistent visual language across products. Share one when people need more than one component to get started: a template brings the right components, layout, content structure, and interaction wiring already assembled.

Do not turn a product-specific page into a rigid component only to share its structure. Share it as a template and let each app adapt its copy.

Choose a stable lowercase kebab-case id, such as acme-dashboard. The id becomes the source and doc file name, the package export, and the value apps pass to npx @astryxdesign/cli template. To change a label, edit the doc (npx @astryxdesign/cli docs authoring/building-blocks/templates/document-the-template/template-doc-overview); never rename the id.

• Start with your product or package name, then name the reusable pattern, so the id stays distinct from Core and other integrations.
• Do not end the id with -page, -app, -view, or -screen.
• Do not reuse a Core id by accident: the bare id becomes ambiguous in every app that installs your package. To take over a Core template on purpose, declare replaces (npx @astryxdesign/cli docs authoring/building-blocks/templates/document-the-template/replace-a-core-template).

bash
# See the Core ids
npx @astryxdesign/cli --json template --list --package @astryxdesign/core

Pages are the default. Pass --type block to add a block.

bash
npx @astryxdesign/cli integration add template acme-dashboard
npx @astryxdesign/cli integration add template acme-stat-card --type block

text
template contribution added
​
[ok] acme-dashboard
​
Declare template root ./templates in astryx.integration.mjs.
​
- templates/acme-dashboard.doc.mjs
- templates/acme-dashboard.tsx
- package.json
- astryx.integration.mjs

The command writes templates/<id>.tsx for the UI and templates/<id>.doc.mjs for its metadata, and declares the templates directory in astryx.integration.mjs. When package.json has an exports map, it also adds the ./templates/<id> export (npx @astryxdesign/cli docs authoring/building-blocks/templates/build-the-template/package-and-test/export-template-assets).

It never overwrites an existing source or doc file. Add --dry-run to see every planned write first.

In global mode: when users install your package for their computer, beside the global CLI, your templates show up in folders outside any project; inside a project, only if the project installs your package. See npx @astryxdesign/cli docs global and npx @astryxdesign/cli docs authoring/global-integrations.

Every template has a source file and a doc file. For acme-dashboard, the source is templates/acme-dashboard.tsx and the doc is templates/acme-dashboard.doc.mjs. Both begin with acme-dashboard, which is how Astryx knows they belong together.

The integration manifest points Astryx to the templates directory; it does not list each template. Change the source and doc together whenever the purpose, preview, readiness, or replacement behavior changes. No automated check can tell whether the doc still describes the rendered UI.

The fields below apply to every page and block. The page, block, and replacement guides add the fields unique to each.

Every field is in npx @astryxdesign/cli docs authoring template-doc.

• Set type to the kind you chose in npx @astryxdesign/cli docs authoring/building-blocks/templates/start-a-template. It decides which other fields the doc accepts.
• The file name sets the template id (npx @astryxdesign/cli docs authoring/building-blocks/templates/start-a-template). Labels live in the doc: the terminal list prints name, and JSON listings print displayName. Changing either never changes the id.
• Write the description for someone choosing between templates. The Doc metadata category in npx @astryxdesign/cli docs authoring/building-blocks/templates/write-good-templates/template-grading-rubric defines what a complete description covers.
• Name the ideas the template serves in keywords: the domains, tasks, and other names a builder might use for it, in lowercase, such as ['monitoring', 'uptime', 'on-call'] for a service-health dashboard. How search and build use them is in npx @astryxdesign/cli docs authoring/field-reference, so the description can stay about the layout.
• Add isReady: false as soon as you generate the doc, because a doc without isReady is listed as ready. Keep it until the template passes npx @astryxdesign/cli docs authoring/building-blocks/templates/build-the-template/package-and-test/test-template-in-app and the quality review.

Note: keywords needs @astryxdesign/cli 0.6.6 or later. A stable CLI before 0.6.6 rejects the field and drops that template, and one before 0.6.4 also hides your doc topics: template --list and search print one warning, and docs and build say nothing. Declare the CLI floor as an optional peer (npx @astryxdesign/cli docs authoring/ship/versioning); integration verify fails until you do.

Read the package-scoped template list after every doc change. Confirm the id, visible name, description, type, readiness, and package.

bash
npx @astryxdesign/cli --json template --list --package @acme/astryx-templates

json
{
  "id": "acme-dashboard",
  "name": "acme-dashboard",
  "displayName": "Acme Dashboard",
  "description": "An analytics dashboard for reviewing account health and recent trends.",
  "type": "page",
  "package": "@acme/astryx-templates",
  "isReady": false
}

integration add template writes a page doc by default. Replace its sample description, then add the page-only fields below.

javascript
/** @type {import('@astryxdesign/cli/authoring').IntegrationTemplateDoc} */
export default {
  type: 'page',
  name: 'acme-dashboard',
  displayName: 'Acme Analytics Dashboard',
  description:
    'A filterable account-health dashboard with headline metrics, trends, and a recent-activity table. Dashboard, reporting, analytics, or status overview.',
  category: 'Dashboard - Analytics',
  isReady: false,
};

Every field is in npx @astryxdesign/cli docs authoring template-doc.

• Set category to the most specific supported {Group} - {Variant} value. Its words become search terms for npx @astryxdesign/cli search, and it appears in the JSON template list.
• Set scaffold: true only for a deliberately sparse starting shell. The JSON template list reports it, so tools and galleries can tell a scaffold from a finished page.
• Fields that only Astryx's own gallery reads, such as isHiddenFromOverview, have no effect on integration templates.

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

javascript
/** @type {import('@astryxdesign/cli/authoring').IntegrationTemplateDoc} */
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.

Every field is in npx @astryxdesign/cli docs authoring template-doc.

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

javascript
/** @type {import('@astryxdesign/cli/authoring').IntegrationTemplateDoc} */
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 (npx @astryxdesign/cli docs authoring/building-blocks/templates/document-the-template/template-doc-overview) and confirm the entry carries the relationship you set. npx @astryxdesign/cli component does not show integration blocks, so the list is where to check.

Every field is in npx @astryxdesign/cli docs authoring template-doc.

Set aspectRatio 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.

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

Use with care: replace a Core template only when every app using this integration should receive your source for an existing Core id by default. An alternative, a product-specific variation, or a different kind of template gets its own id instead (npx @astryxdesign/cli docs authoring/building-blocks/templates/start-a-template).

• Sharing a Core id without replaces does not replace Core. It makes the bare id ambiguous, so npx @astryxdesign/cli template <id> fails until the app adds --package, and doctor integration templates reports an accidental collision.
• A replacement can keep the Core id or use its own. replaces is what makes it the default.

Find the exact Core id and kind first.

bash
npx @astryxdesign/cli --json template --list --package @astryxdesign/core

javascript
/** @type {import('@astryxdesign/cli/authoring').IntegrationTemplateDoc} */
export default {
  type: 'page',
  name: 'acme-app-shell',
  displayName: 'Acme App Shell',
  description:
    'An Acme application shell with product navigation, account controls, and a responsive content region.',
  replaces: 'shell-side-nav',
  isReady: true,
  category: 'Shell - Left Sidebar',
};

Every field is in npx @astryxdesign/cli docs authoring template-doc.

Declare replaces on the template doc, never in astryx.integration.mjs.

Declare the CLI floor that integration verify names as an optional peer (npx @astryxdesign/cli docs authoring/ship/versioning).

json
{
  "peerDependencies": {
    "@astryxdesign/cli": ">=0.6.4"
  },
  "peerDependenciesMeta": {
    "@astryxdesign/cli": {
      "optional": true
    }
  }
}

integration verify reports replaces_needs_cli when that peer is missing or too old. Without it, published 0.6.3 and earlier drop that template and hide your doc topics.

bash
# Receives the active replacement
npx @astryxdesign/cli template shell-side-nav src/app
​
# Receives the original Core template
npx @astryxdesign/cli template shell-side-nav --package @astryxdesign/core src/app

When several integrations replace the same Core template, one wins:

• An integration explicitly listed in astryx.config.mjs wins over one that is only installed and picked automatically.
• When several explicitly configured integrations replace the same target, the one listed later wins and Astryx reports the ambiguity.
• When no integration is configured explicitly, the package listed later in the app's package.json dependencies wins. Configure the intended integration explicitly instead of relying on that order.

bash
npx @astryxdesign/cli doctor integration templates

Replacement resolution is safe by default. A missing source, invalid doc, missing target, wrong kind, or conflicting declaration never hands the Core id to a questionable replacement: Astryx reports the issue and keeps the Core template. Fix every issue before publishing.

npx @astryxdesign/cli template copies exactly one source file. It does not copy sibling helpers, stylesheets, fonts, icons, images, or media. Plan for that before you add supporting files.

bash
# Page: src/app/account/page.tsx
npx @astryxdesign/cli template acme-account src/app/account
​
# Block: src/features/account/acme-stat-card.tsx
npx @astryxdesign/cli template acme-stat-card src/features/account
​
# Exact destination for either kind
npx @astryxdesign/cli template acme-stat-card src/features/account/StatusCard.tsx

Astryx refuses to replace an existing file unless the caller passes --overwrite or -f.

Put every helper that the app is expected to edit in the template source. Small local components, example data, constants, and event handlers can live above or below the default component in the same file.

• Inline a helper when it is part of the editable starting point.
• Move a helper into the integration package only when it should stay package-owned and update with the package.
• Do not import ./helper, ./styles, or any other sibling file.
• Do not create routes, configuration, or extra files at runtime. Give the app one explicit source file to own.

After the copy, imports resolve from the app, not from the template directory. Every bare import must name a package the app installs, and every package path must be public.

tsx
import {Button} from '@astryxdesign/core/Button';
import {Card} from '@astryxdesign/core/Card';
import {HStack} from '@astryxdesign/core/HStack';
import {Text} from '@astryxdesign/core/Text';
import {VStack} from '@astryxdesign/core/VStack';
import {AcmeStatusCard} from '@acme/astryx-widgets/components/AcmeStatusCard';
​
const metrics = [
  {label: 'Healthy accounts', value: '1,248'},
  {label: 'Needs review', value: '37'},
];
​
function MetricRow({label, value}: {label: string; value: string}) {
  return (
    <HStack justify="between">
      <Text>{label}</Text>
      <Text>{value}</Text>
    </HStack>
  );
}
​
export default function AcmeAccountSummary() {
  return (
    <Card>
      <VStack gap={4}>
        <AcmeStatusCard />
        {metrics.map(metric => <MetricRow key={metric.label} {...metric} />)}
        <Button label="Review accounts" />
      </VStack>
    </Card>
  );
}

• Import Astryx components from their public Core paths.
• Import integration-owned components, helpers, icons, or styles only through paths the package exports (npx @astryxdesign/cli docs authoring/building-blocks/templates/build-the-template/package-and-test/export-template-assets).
• Avoid adding another library when Astryx or platform APIs already provide the behavior.

The source must default-export one React component. Named helpers inside the file are fine.

• Add use client as the first statement only when hooks, event handlers, browser APIs, or a component passed as a prop, such as icon={BellIcon}, need a client boundary.
• Keep a static template server-compatible when it needs no client behavior.

The copied file does not bring sibling assets with it (npx @astryxdesign/cli docs authoring/building-blocks/templates/build-the-template/write-the-template-file). Give every asset exactly one owner:

Do not make a template look self-contained while it relies on an undocumented package file or app convention.

Use Astryx component props, layout primitives, and design tokens before writing custom CSS. This keeps the copied result aligned with the host theme and reduces the styling contract an app inherits.

• Use Stack and Grid spacing props instead of margins between children.
• Use component variants, sizes, padding, and alignment props before restyling internals.
• Use public theme token exports for a value that Astryx does not expose as a prop.
• Do not copy private generated class names or target component internals with selectors.

When a style belongs to the editable starting point, define it in the template file.

tsx
import * as stylex from '@stylexjs/stylex';
import {colorVars} from '@astryxdesign/core/theme/tokens.stylex';
​
const styles = stylex.create({
  trend: {
    color: colorVars['--color-success'],
    minWidth: 0,
  },
});
​
// Later: <Text xstyle={styles.trend}>Up 12%</Text>

Use custom declarations only when no Astryx prop or token fits. Each one counts in the Custom CSS category of npx @astryxdesign/cli docs authoring/building-blocks/templates/write-good-templates/template-grading-rubric.

When a stylesheet must stay package-owned, import it from the template by its public package path.

tsx
import '@acme/astryx-widgets/styles/acme-dashboard.css';

Then export that path and include the file in the package (npx @astryxdesign/cli docs authoring/building-blocks/templates/build-the-template/package-and-test/export-template-assets). TypeScript 6 and later check side-effect imports by default, so this import type-checks only when the app or its framework declares *.css modules.

Use Astryx typography components and theme values unless the template must demonstrate a specific licensed typeface. A copied template should normally inherit the app typography instead of installing a new global font.

• Do not add a font only to make sample content look more polished.
• Do not override the app body font from a template.
• Use a custom face only for a real product or content requirement that the integration package owns.

Keep the font files beside a package-owned stylesheet. The stylesheet can use relative url() paths because it stays in the package, and the template imports the stylesheet by its public path (npx @astryxdesign/cli docs authoring/building-blocks/templates/build-the-template/template-assets/template-styles).

css
@font-face {
  font-family: 'Acme Sans';
  src: url('../assets/fonts/acme-sans-regular.woff2') format('woff2');
  font-style: normal;
  font-weight: 400;
  font-display: swap;
}
​
.acme-dashboard-title {
  font-family: 'Acme Sans', sans-serif;
}

• Ship WOFF2 when it satisfies the supported browsers. Add another format only when those browsers require it.
• Declare every weight and style the template uses. Do not make the browser synthesize bold or italic because a file is missing.
• Use font-display: swap unless the product requirement and performance test justify another value.
• Confirm that the font license permits redistribution in the integration package.

Exporting the stylesheet does not publish the font files it points to. Include the font directory in the package as well (npx @astryxdesign/cli docs authoring/building-blocks/templates/build-the-template/package-and-test/export-template-assets).

When you test the template in an app (npx @astryxdesign/cli docs authoring/building-blocks/templates/build-the-template/package-and-test/test-template-in-app), also confirm the following.

• Every font request succeeds from the built asset path.
• Computed styles show the requested family, weight, and style.
• Text stays readable with the fallback stack when a font loads slowly or fails.

Use Icon for a standalone icon. For a component icon prop, pass what that prop accepts: most, such as Button and IconButton, take an element like <Icon icon={BellIcon} />, and some menu and navigation items also accept the icon definition itself. This keeps sizing, color, and accessibility aligned with the system.

tsx
import {Button} from '@astryxdesign/core/Button';
import {Icon} from '@astryxdesign/core/Icon';
import {BellIcon} from '@heroicons/react/24/outline';
​
<Icon icon={BellIcon} size="sm" />
<Button label="Alerts" icon={<Icon icon={BellIcon} />} />

• Use one supported icon set consistently inside a template.
• Give an icon-only control its required visible or assistive label through the Astryx control API.
• Do not paste raw svg and path markup when an existing icon definition fits.
• Do not render a library icon directly when Icon or the receiving Astryx component can render it.
• Declare an icon library other than Astryx as a dependency (npx @astryxdesign/cli docs authoring/building-blocks/templates/build-the-template/package-and-test/export-template-assets).

A product mark or missing domain symbol can stay package-owned. Export a compatible icon definition from a public package path, then import that path from the template.

tsx
import {Icon} from '@astryxdesign/core/Icon';
import {AcmePulseIcon} from '@acme/astryx-widgets/icons/AcmePulseIcon';
​
<Icon icon={AcmePulseIcon} size="sm" label="Account health" />

Export the icon path and include its file in the package (npx @astryxdesign/cli docs authoring/building-blocks/templates/build-the-template/package-and-test/export-template-assets).

When you test the template in an app (npx @astryxdesign/cli docs authoring/building-blocks/templates/build-the-template/package-and-test/test-template-in-app), also confirm the following.

• Every icon state renders, including selected, disabled, loading, and narrow layouts.
• Meaningful icons have an accessible name, and decorative icons add no duplicate spoken text.
• No missing icon leaves an empty control.

A reference such as ./hero.png or ../assets/demo.mp4 stays unchanged in the copied file and normally breaks.

• Use a stable public URL when the integration owner will continue to host the media.
• Use an explicit app-owned placeholder when every app must supply product-specific media.
• Use a package-owned JS or CSS entrypoint only when every supported app toolchain can resolve and emit the underlying asset.
• Do not assume that a file inside node_modules is automatically served at a browser URL.

/template-assets/<path> is a preview-only fixture path. During copy, Astryx replaces a complete static image reference with an inline neutral SVG placeholder. It replaces a complete static video reference with an empty string because it cannot create a valid inline video.

• Supported preview image suffixes are SVG, PNG, JPG, JPEG, GIF, WebP, AVIF, and ICO.
• Supported preview video suffixes are MP4, WebM, MOV, OGV, and M4V.
• Keep the preview path as one complete static string. Concatenation, interpolation, method calls, module imports, and unknown file formats are rejected when Astryx cannot replace them safely.
• Use this path only when a placeholder is the intended copied result. It is not a way to ship required product media.
• Astryx serves /template-assets only in its own docs. A preview you host must serve that path itself.

When the app must provide the final asset, keep the replacement point obvious in the copied source. Preserve enough surrounding layout and example data that the template still teaches the pattern without pretending the final content is included.

tsx
const HERO_IMAGE = '/acme-dashboard-hero.jpg';
// Replace HERO_IMAGE with an app-owned public URL before shipping the page.
​
<img
  src={HERO_IMAGE}
  alt="Account health trends for the current quarter"
  width={1200}
  height={675}
/>

• Use accurate alternative text for informative images and alt="" for decoration.
• Provide dimensions or an aspect-ratio container so loading does not shift the page.
• For video, provide controls, a useful poster, and captions when the content requires them.
• Do not leave an inaccessible, expiring, authenticated, or environment-specific URL in copied source.

When you test the template in an app (npx @astryxdesign/cli docs authoring/building-blocks/templates/build-the-template/package-and-test/test-template-in-app), also confirm the following.

• The copied source shows the placeholder substitutions you expect.
• The network log has no missing, redirected, blocked, or unauthorized media requests.
• Each placeholder keeps the layout and says what the app must replace.

integration verify resolves each template through a public package path without a file extension, such as ./templates/acme-dashboard, and fails when that path is missing.

json
{
  "exports": {
    "./templates/acme-dashboard": "./templates/acme-dashboard.tsx"
  }
}

• integration add writes this entry when package.json has an exports map (npx @astryxdesign/cli docs authoring/building-blocks/templates/start-a-template). Without a map it writes nothing, because creating one would make existing deep imports private. Add the map yourself, then the entry.
• Keep the public path without .tsx. Only the target file ends in .tsx.
• Do not point the entry at a barrel file that loses the template default export.

Add a public path for every package-owned component, helper, icon, or stylesheet that the copied source imports. Keep implementation-only files private.

json
{
  "exports": {
    "./templates/acme-dashboard": "./templates/acme-dashboard.tsx",
    "./components/AcmeStatusCard": "./components/AcmeStatusCard.tsx",
    "./icons/AcmePulseIcon": "./icons/AcmePulseIcon.tsx",
    "./styles/acme-dashboard.css": "./styles/acme-dashboard.css"
  }
}

If a block is also loaded directly as a live .tsx preview, add a pattern that keeps the extension, such as "./templates/*.tsx": "./templates/*.tsx". Keep the generated entry too; integration verify resolves the template through it.

An export can point to a file that npm leaves out. When package.json#files exists, list the integration manifest, the templates directory, and every directory the copied file depends on.

json
{
  "files": [
    "astryx.integration.mjs",
    "templates",
    "components",
    "icons",
    "styles",
    "assets/fonts"
  ],
  "sideEffects": ["**/*.css"]
}

• integration add appends the manifest and templates directory when a files list already exists. Add the other directories yourself.
• If package.json sets sideEffects, include CSS in it, as above, so bundlers keep side-effect stylesheet imports.
• Run npm pack --dry-run and read the real file list instead of reasoning from the workspace.

A copied file imports from the app, so the app must install every package it imports. Declare the Astryx peers as described in npx @astryxdesign/cli docs authoring/ship/versioning. For other packages:

Use only ranges you test. A package that resolves only because a workspace hoisted it is not declared.

bash
npx @astryxdesign/cli integration verify

integration verify runs npm pack, including lifecycle scripts, unpacks the .tgz file into a temporary app without installing its dependencies, and checks the unpacked integration. It publishes nothing and removes the .tgz file and the temporary app.

1. It validates the manifest, every template doc, its source file, and the templates directory.
2. It checks that the manifest and every template file are in the .tgz file.
3. It checks that each packed template keeps the same id, type, name, and replaces as your working copy. It does not compare template source or other doc fields.
4. It resolves each template through its public package path in the unpacked package.
5. It checks that the resolved template module has a default export.
6. It checks the CLI peer that features such as template replacement require.

Each failure prints a [fail] line with its message; add --json to see each issue code. npx @astryxdesign/cli docs authoring/help/troubleshooting lists the common messages and their fixes. Fix every error, and review every warning before publishing.

integration verify checks the packed templates and their public entrypoints. It does not copy a template into an app or run a browser build, so it cannot show the following.

• Whether a relative helper or stylesheet survives the copy.
• Whether the copied file type-checks in every supported app toolchain.
• Whether package-owned CSS, fonts, icons, images, or media load in a browser.
• Whether layout, color modes, keyboard and pointer input, and real content work.
• Whether a template id collides with Core, or whether a replaces target exists. Run npx @astryxdesign/cli doctor integration templates for those.
• How the template scores on quality.

Install the packed package in a clean app as described in npx @astryxdesign/cli docs authoring/ship/test-in-an-app. Also install every library the copied source imports, such as its icon library. Pack and reinstall after every change.

bash
# Confirm discovery and metadata
npx @astryxdesign/cli --json template --list --package @acme/astryx-widgets
​
# Inspect source without writing
npx @astryxdesign/cli template acme-dashboard --package @acme/astryx-widgets
​
# Copy a page and a block to their real app locations
npx @astryxdesign/cli template acme-dashboard --package @acme/astryx-widgets src/app/acme-dashboard
npx @astryxdesign/cli template acme-stat-card --package @acme/astryx-widgets src/components

• Confirm the copied files: src/app/acme-dashboard/page.tsx and src/components/acme-stat-card.tsx.
• Inspect the copied source for placeholder substitutions and relative references.
• Import the copied block into a real page. A file that is never imported has not been tested.

Run the type check (npx tsc --noEmit, or the app's own script) and the production build in every framework or bundler the integration supports. One toolchain passing does not prove another.

bash
npx tsc --noEmit
npm run build

• Every import resolves from the copied location.
• Production builds keep required side-effect CSS.
• No import bypasses exports, and no dependency resolves only through workspace hoisting.

Check the rendered hierarchy, reading order, focus order, clipping, overflow, and fallback states. A screenshot of one default state is not a complete test.

Grade the exact packed revision using the evidence from this test (npx @astryxdesign/cli docs authoring/building-blocks/templates/write-good-templates).

A good template does more than render. It gives an app a clear product starting point that is easy to understand, safe to change, and complete after Astryx copies it out of the package. A rubric scores that quality so you can grade as you build.

• Its purpose and primary task are clear before someone reads every detail.
• It composes Astryx components instead of rebuilding their behavior with raw HTML or custom styles.
• Its hierarchy, spacing, interactions, and reading order still work at narrow widths and in every supported color mode.
• Its source, imports, styles, fonts, icons, images, and media still work from the copied location.
• Its metadata makes the template easy to find and accurately explains when to use it.
• Its example content is realistic enough to expose overflow, empty-space, and hierarchy problems.

Grade the first runnable version, again after each source, doc, dependency, or asset change, and in full before every release. Grade the source, doc, copied file, and rendered app together; none of them is enough alone.

1. Read every scoring rule in npx @astryxdesign/cli docs authoring/building-blocks/templates/write-good-templates/template-grading-rubric.
2. Fix publication blockers first, then every reasonable deduction.
3. Repeat the full grade on the packed package in a clean app (npx @astryxdesign/cli docs authoring/building-blocks/templates/build-the-template/package-and-test/test-template-in-app).
4. To have an agent grade and improve the template, use npx @astryxdesign/cli docs authoring/building-blocks/templates/write-good-templates/grade-template-with-agent.

Keep each scorecard with its package revision and rubric version.

Start with npx @astryxdesign/cli docs is-my-code-good: it owns the shared Astryx quality criteria. This rubric adds template weights, counting rules, and template-only checks, and each category that scores a shared criterion names it.

Template rubric 1.4 scores seven categories for 100 points. Aim for 100; B (75) is the publication floor, not the target. Each category below lists its weight. Never award points for anything you did not inspect.

Keep improving while a deduction has a reasonable fix. A score below 100 is fine only when the remaining tradeoff is intentional and recorded. A template is not ready if the copied file fails to build or a required asset is missing, whatever its score.

Version 1.4 counts public integration components as Astryx components and grades assets and imports after the copy. Record the version with every score so results stay comparable.

This category scores the Astryx components criterion in npx @astryxdesign/cli docs is-my-code-good. Count every JSX opening tag in the copied .tsx source. An Astryx element is a component imported from @astryxdesign/core or from a public component export of the integration package. A raw HTML element is any lowercase intrinsic JSX tag. Count occurrences, not only unique tag names.

Do not count fragments or a PascalCase helper defined in the same file. Inspect that helper and count the raw HTML inside it. For each raw element, decide with that guide whether it is necessary because Astryx has no equivalent, or unnecessary because an Astryx component can replace it.

• Do not deduct for an img when no general Astryx image component fits and its source passes the Image handling category.
• Do not deduct for a form that wraps FormLayout to provide native submission semantics.
• Do not deduct for input type="hidden" when it carries native form state.

This category scores the Icons criterion in npx @astryxdesign/cli docs is-my-code-good. Count raw icon markup in the copied file. npx @astryxdesign/cli docs authoring/building-blocks/templates/build-the-template/template-assets/template-icons shows how to render icons through Astryx instead.

• Count every raw svg, path, circle, rect, line, polyline, polygon, ellipse, or g used as an icon.
• Count an inline SVG component defined in the template.
• Count an icon component rendered directly instead of through Icon or an Astryx icon prop.

This category scores the Styling criterion in npx @astryxdesign/cli docs is-my-code-good. Count individual CSS properties inside stylex.create and inline style objects. Count each className and stylex.props use once. Do not count Astryx props such as gap, padding, variant, size, color, level, columns, contentPadding, or height.

This category scores styles authored in the copied source. A package stylesheet is graded through its effect on portability and the rendered app, not as a way to hide custom declarations from this count.

1. Choose the page root with the Layout criterion in npx @astryxdesign/cli docs is-my-code-good. In a template, only a category that starts with Shell - owns global chrome, so it uses AppShell; every other page template uses Layout or Center.
2. Outside a Shell - template, leave global navigation to the host app. Put in-page navigation in a LayoutPanel and page headings in LayoutHeader.
3. Use Grid with columns={{minWidth: 280}} for responsive collections. Do not fix the column count or rebuild the grid in raw CSS.
4. Use Center for centered content instead of custom flexbox workarounds.
5. Render one page from one source file. Links may be inert examples, but the template does not create nested routes or router integration.

1. Do not wrap a block in AppShell. A block renders inside a preview or page container.
2. Keep the block focused on one pattern or component usage.
3. Keep the composition substantial enough to teach the pattern and small enough to adapt. About 20-100 lines is the normal range.

Score field accuracy for 6 points, the description for 3 points, and naming for 1 point. Read the source and doc together. A field that exists but disagrees with the source is not complete.

• Page: type, name, displayName, description, explicit isReady, and a specific category when the page is meant for browsing.
• Block: type, name, displayName, description, explicit isReady, positive aspectRatio, and complete componentsUsed.
• Relationship and preview fields follow npx @astryxdesign/cli docs authoring/building-blocks/templates/document-the-template/block-template. A value that contradicts that guide is an inaccuracy.

A strong description covers four slots: the archetype, the job someone does, the structural or behavioral differentiator, and the alternate words people may search. Use at least six distinct content words after removing generic words such as page, screen, app, view, and component names. Describe the reusable shape, not only the sample data.

The id follows npx @astryxdesign/cli docs authoring/building-blocks/templates/start-a-template, displayName is readable, and a browsable page has a specific category (npx @astryxdesign/cli docs authoring/building-blocks/templates/document-the-template/page-template). Slug length is guidance, not a scored condition.

This category scores the Images and assets criterion in npx @astryxdesign/cli docs is-my-code-good. Inspect every image reference in the copied file against npx @astryxdesign/cli docs authoring/building-blocks/templates/build-the-template/template-assets/template-images-media.

This category scores the Code health criterion in npx @astryxdesign/cli docs is-my-code-good, plus conditions only a template has. Award 2 points for each condition. Grade the copied file, not only the package source.

Grade one exact package revision against template rubric 1.4. Give the agent the template id, the package name, and a clean app that can install the packed package, then use this prompt. Replace every angle-bracket value. The first pass is read-only so the original score and findings stay visible.

text
Grade integration template <id> from <package> at <revision>.
​
Before scoring:
1. Read `npx @astryxdesign/cli docs authoring/building-blocks/templates/write-good-templates --full`.
2. Read `npx @astryxdesign/cli docs authoring/building-blocks/templates/write-good-templates/template-grading-rubric --full` and every guide it links.
3. Inspect the template source, its matching .doc.mjs file, package.json exports and files, and astryx.integration.mjs.
4. Run `npx @astryxdesign/cli integration verify` in the package.
5. Follow `npx @astryxdesign/cli docs authoring/building-blocks/templates/build-the-template/package-and-test/test-template-in-app --full`: install the packed package in the clean app, copy the template, build the app, and render the behavior matrix.
​
Score all seven rubric categories. Cite file and line evidence for every deduction. Do not award points for a state you did not inspect. If browser or build evidence is unavailable, say so and mark the template not publishable.
​
Return the rubric version, package revision, numeric score, letter grade, category scorecard, publishable yes/no verdict, detailed findings, and the top three fixes. Treat 100 as the target. Name every remaining deduction and say whether it is an intentional tradeoff or still needs work. Do not edit files during this first pass.

markdown
# Template grade: <id>
​
**Rubric:** 1.4
**Package revision:** <revision>
**Type:** page | block
**Grade:** <letter> (<score>/100)
**Publishable:** yes | no
​
| Category | Points | Max | Evidence |
| --- | ---: | ---: | --- |
| Astryx component purity | X | 30 | |
| Icon purity | X | 15 | |
| Custom CSS | X | 15 | |
| Layout & structure | X | 15 | |
| Doc metadata | X | 10 | |
| Image handling | X | 5 | |
| Code quality | X | 10 | |
| **Total** | **X** | **100** | |
​
## Detailed findings
- <file:line, rubric rule, observed problem, and deduction>
​
## Publication blockers
- <failed pack, copy, build, asset, browser, theme, responsive, or input check>
​
## Top three fixes
1. <highest-value fix>
2. <second fix>
3. <third fix>

The category scores must add exactly to the total, and the grade comes from the published bands. The verdict is yes only when the score is 75 or higher and every package, copy, build, asset, and rendered-app check passes.

1. Fix publication blockers first.
2. Fix every reasonable deduction without hiding it behind helper components or package CSS.
3. Pack again, copy into a fresh app, and have the agent repeat the full grade. Keep the earlier scorecard so the improvement is visible.
4. Stop only when no reasonable fix remains, and record every intentional tradeoff that still costs points.

In global mode: outside projects, the theme list includes themes from integrations installed for the computer, and theme add there only shows them; inside a project, it lists only themes from integrations the project installs. See npx @astryxdesign/cli docs global and npx @astryxdesign/cli docs authoring/global-integrations.

A theme contribution has editable defineTheme source plus a built module and production CSS. integration add theme scaffolds the source and declares the package exports; theme build writes the built outputs. An app installs the package, runs theme add, applies the theme from its generated app module, and customizes it with extends instead of copying source.

These guides cover the whole path: scaffold the source, generate its palette, define and build the theme, ship fonts and assets, run integration verify, and document how apps add and extend it. Applying a theme, including mode and SSR, works the same for every theme; see npx @astryxdesign/cli docs use-a-theme.

Run integration add theme with a lowercase kebab-case slug. It writes a blank theme — a defineTheme skeleton and its descriptor — into a folder named after the slug.

bash
npx @astryxdesign/cli integration add theme ocean

text
theme contribution added
​
[ok] ocean
​
Declare theme root ./themes in astryx.integration.mjs.
​
- themes/ocean/oceanTheme.ts
- themes/ocean/oceanTheme.doc.mjs
- package.json
- astryx.integration.mjs

oceanTheme.ts exports oceanTheme, a defineTheme source, and oceanTheme.doc.mjs is the descriptor that theme list reads. The command also declares ./themes/ocean and ./themes/ocean.css package exports. Every field is in npx @astryxdesign/cli docs authoring theme-doc.

The source and built outputs ship in your package. Build the source with theme build, then run integration verify before publishing. An app runs theme add to record and import the built module and stylesheets; theme eject creates an independent source fork. See npx @astryxdesign/cli docs authoring/building-blocks/themes/use-a-theme-in-an-app.

To begin from an existing theme instead of a blank one, pass --from. It copies that theme as your starting point to diverge from — a fork, with no link back.

bash
npx @astryxdesign/cli integration add theme ocean --from neutral

The copy keeps the packages the base theme uses, such as lucide-react for its icons: --from adds them to your dependencies, so an app that installs your package gets them too. Install your dependencies again before you build the theme.

Use --from when you want to change a lot. For a small change that should stay linked to a base theme, use extends instead (npx @astryxdesign/cli docs authoring/building-blocks/themes/define-the-theme).

A package can ship more than one theme. Run integration add theme once per slug; each theme gets its own folder and descriptor, and theme list shows them all.

In global mode: when users install your package for their computer, beside the global CLI, your themes are listed in folders outside any project, where theme add lists but writes nothing; inside a project, only if the project installs your package. See npx @astryxdesign/cli docs global and npx @astryxdesign/cli docs authoring/global-integrations.

A theme needs dozens of related colors — shades of each brand color for backgrounds, borders, text, and states, in both light and dark mode. A palette is that full set of shades. Rather than hand-pick every one, you name a few seed colors and generate the rest, so the shades stay consistent.

You write a short config naming each color family and its seed, then run theme palette generate. It expands each seed into a full light and dark ramp — the scale of shades — and writes the result into the theme folder, where your theme tokens point at it (see npx @astryxdesign/cli docs authoring/building-blocks/themes/define-the-theme). Keep the config and the generated palette together in that folder.

The smallest config is one color family: an id to name it and a seed color to grow it from. Save it as themes/ocean/palette.config.json:

json
{"families": [{"id": "ocean", "seed": "#0074e2"}]}

bash
# Print the palette without writing files
npx @astryxdesign/cli theme palette generate themes/ocean/palette.config.json
# Write the palette and its receipt
npx @astryxdesign/cli theme palette generate themes/ocean/palette.config.json \
  --out themes/ocean/tokens/ocean.palette.ts

text
[ok] Wrote themes/ocean/tokens/ocean.palette.ts
​
[ok] Wrote themes/ocean/tokens/ocean.palette.receipt.json
​
Review and edit the candidate before adopting it as theme-owned palette data.

The command writes two files. ocean.palette.ts is the palette your theme tokens will read: it exports black, white, and palette — a ramp of 21 shades (stops 0 to 100) for both light and dark. The .receipt.json beside it records the exact seeds and settings, so you can regenerate the same palette later. A second run leaves both files alone unless you pass --overwrite.

Add --preview <file>.html to also get a web page showing every shade, so you can eyeball the palette in a browser. Write it outside themes/ so it does not ship in your package. Every option is in npx @astryxdesign/cli docs cli/commands/theme-palette-generate, and the config it reads is described in npx @astryxdesign/cli docs cli/api/functions/generate-tonal-palette.

A theme token is a named slot that Astryx components read for a value — --color-accent for the accent color, and so on. Components never read your palette directly; they read tokens. Defining a theme means pointing each token at a palette shade, so the components wear your colors.

Import the palette in oceanTheme.ts and point your tokens at its stops. Each token takes a [light, dark] pair — the shade to use in light mode and the one in dark mode.

ts
// themes/ocean/oceanTheme.ts
import {defineTheme} from '@astryxdesign/core/theme';
import {palette} from './tokens/ocean.palette';
​
const {light, dark} = palette.ocean;
​
export const oceanTheme = defineTheme({
  name: 'ocean',
  tokens: {
    '--color-accent': [light['45'], dark['70']],
  },
});

Local imports must stay inside the theme folder. One that leaves it, such as ../../shared/colors, fails with invalid_theme, and every theme in the package disappears from theme list. npx @astryxdesign/cli theme template writes a file that explains every defineTheme field. For the full token set and component theming, read npx @astryxdesign/cli docs author-a-theme.

To base a theme on an existing one, extends it: import the base theme and override only the tokens you change. Add the derived theme with integration add theme ocean-contrast, and import the base from its built package export, since local imports cannot leave the theme folder. The derived theme keeps a live link to the base and picks up its later changes when you rebuild it — unlike --from, which forks a copy (npx @astryxdesign/cli docs authoring/building-blocks/themes/add-a-theme).

ts
// themes/ocean-contrast/oceanContrastTheme.ts
import {defineTheme} from '@astryxdesign/core/theme';
import {oceanTheme} from '@acme/astryx-widgets/themes/ocean';
​
export const oceanContrastTheme = defineTheme({
  name: 'ocean-contrast',
  extends: oceanTheme,
  tokens: {
    '--color-accent': ['#0051a3', '#4aa3ff'],
  },
});

Each [light, dark] pair compiles to a light-dark() value, which switches only colors. Give it colors. For a value that is not a plain color — a gradient — put light-dark() on each color stop, not around the whole value: light-dark() takes two colors, so wrapping whole gradients makes the value invalid where the token is used, and theme build does not warn.

Core private variables start with --_, such as --_field-radius. They are internals and can change in any Core release, so theme build reports each one it finds as an [error]. Set the standard CSS property instead — borderRadius, padding — and let the build emit the internal variable where Core needs it.

The theme imports @astryxdesign/core/theme, so declare Core as a peer dependency, with the range of Core versions you test the theme against — a range, not an exact version, so a Core patch release does not force a republish. integration add theme already declared the optional @astryxdesign/cli peer that reads themes:

json
"peerDependencies": {
  "@astryxdesign/core": "^0.7.0",
  "@astryxdesign/cli": ">=0.6.4"
},
"peerDependenciesMeta": {
  "@astryxdesign/cli": {"optional": true}
}

A theme names its typefaces in typography: body, heading, and code, each with a family and fallbacks. These set the --font-family-* tokens every component reads. Always give real fallbacks so text stays readable before the font loads, or if it never does. heading inherits family and fallbacks from body when you omit them.

ts
// themes/ocean/oceanTheme.ts
export const oceanTheme = defineTheme({
  name: 'ocean',
  typography: {
    body: {family: 'Acme Sans', fallbacks: 'system-ui, sans-serif'},
    code: {family: 'Acme Mono', fallbacks: 'ui-monospace, monospace'},
  },
  // ...your tokens
});

The full type scale and font roles are in npx @astryxdesign/cli docs author-a-theme.

Naming a family does not load it. When the theme uses non-system fonts, add <slug>.fonts.css beside the built module and production CSS, then export it as ./themes/<slug>.fonts.css. theme add imports that stylesheet with the built theme.

json
"exports": {
  "./themes/ocean": "./themes/ocean/ocean.js",
  "./themes/ocean.css": "./themes/ocean/ocean.css",
  "./themes/ocean.fonts.css": "./themes/ocean/ocean.fonts.css"
}

The stylesheet can contain self-hosted @font-face rules or import a hosted stylesheet. A hosted @import is simple, but it delays loading compared with a preconnected <link>; choose that trade-off deliberately. Doctor warns when it cannot prove the loader — a hosted @import, or no font stylesheet while the app loads the family itself — but the warning does not fail the app.

css
/* themes/ocean/ocean.fonts.css */
@font-face {
  font-family: 'Acme Sans';
  src: url('./fonts/acme-sans.woff2') format('woff2');
  font-weight: 100 900;
  font-style: normal;
  font-display: swap;
  unicode-range: U+0000-00FF, U+0131, U+0152-0153;
}

• Load every weight and style the theme uses. Do not let the browser synthesize bold or italic.
• Include self-hosted font files and their licenses in the packed package.
• Keep CSS and font assets side-effectful so a bundler does not remove the loader.
• Run integration verify; it fails when an exported font stylesheet cannot resolve, but it does not check the font files the stylesheet names.

Before publishing, run integration verify. Then install the package in a clean app, run theme add, apply the generated theme, and open it in a browser. The source, packed exports, and applied result form one chain; check the last step too.

• Text renders in the named families at every weight and style — the italic face resolves, not a synthesized slant.
• Every font request succeeds; nothing silently falls back to a system font.
• Color pairs still meet contrast in both light and dark mode.

Install the integration, then run theme add with its slug and package. The command records the package owner and regenerates one app theme module that imports the built theme, production CSS, and optional font CSS. Use theme eject only to copy source into an independent local fork.

bash
npm install @acme/astryx-widgets
npx @astryxdesign/cli theme add ocean --package @acme/astryx-widgets

tsx
import {Theme} from '@astryxdesign/core/theme';
import {themes, defaultThemeSlug} from './astryx-themes';
​
<Theme theme={themes[defaultThemeSlug]}>
  <App />
</Theme>

theme list shows the available, added, and default themes. Use theme use <slug> to change the default, theme remove <slug> to stop importing one, and theme eject <slug> only when the app needs an independent source fork. Applying a theme — mode, SSR, and the production build — works the same for every theme; see npx @astryxdesign/cli docs use-a-theme.

For ordinary customization, do not copy the package source. Import the built theme and derive a new one with defineTheme({extends: importedTheme, ...}), overriding only the tokens the app changes. Use theme eject only when the app must own an independent source fork. See npx @astryxdesign/cli docs authoring/building-blocks/themes/define-the-theme.

ts
import {defineTheme} from '@astryxdesign/core/theme';
import {oceanTheme} from '@acme/astryx-widgets/themes/ocean';
​
export const productTheme = defineTheme({
  name: 'product',
  extends: oceanTheme,
  tokens: {'--color-accent': ['#0051a3', '#4aa3ff']},
});