CLI 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 astryx docs cli/integrations/building-blocks.

For example, ship a carousel as an integration. Any app that installs it can find it with npx astryx 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 astryx docs cli/integrations/quick-start.

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, then install the Astryx CLI and Core for development.

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

• Start with "exports": {}: each component and template you add then writes the public import that integration verify resolves.
• Run the CLI as npx astryx, which runs the @astryxdesign/cli you installed as a devDependency.
• Component commands read Core, so they need @astryxdesign/core installed.

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

bash
npx astryx 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 astryx component AcmeCarousel

You now have an integration package with one exported component.

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 astryx 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 packs the package, unpacks it into a temporary app, and checks that the component resolves through its public import there. 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 astryx 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 astryx docs cli/integrations/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 astryx docs cli/integrations/ship/versioning; files and publishing in astryx docs cli/integrations/ship/publishing.

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.

From Astryx Integration: astryx 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 astryx docs cli/commands/integration-add.

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

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

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.

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 astryx docs cli/integrations/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 astryx 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 astryx docs cli/integrations/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 (astryx docs cli/integrations/quick-start).

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, but it cannot 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 astryx 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.
• Keep the doc beside the source and change both in the same pull request.
• If the module later exposes several related public exports, adapt this doc with astryx docs cli/integrations/building-blocks/components/describe-the-component/component-family.

ComponentDoc: The doc-type for a component directory's {Name}.doc.mjs. A discriminated union of SingleComponentDoc (props on the doc), MultiComponentDoc (a components array), and SubComponentDoc (a subComponentOf pointer). All three share the ComponentBaseDoc fields below; the variant is chosen by which of props / components / subComponentOf you set. Read it with astryx 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.'},
  ],
},

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.

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 astryx component AcmeCarousel
npx astryx 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.

From ComponentDoc: astryx 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.

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 astryx docs cli/integrations/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',
  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',
  subComponentOf: 'AcmeDialog',
  description: 'Labels an Acme Dialog and holds its close action.',
  props: [
    {
      name: 'title',
      type: 'string',
      description: 'The dialog title.',
      required: true,
    },
  ],
};

From ComponentDoc: astryx 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 child inherits family fields such as group, category, keywords, theming, and playground unless it overrides them.

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": {}.

integration verify installs the packed package in a temporary app, resolves each documented import, and checks that the module exports the documented component name.

bash
npx astryx 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 astryx docs cli/commands/integration-verify.

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 astryx component AcmeCarousel
npx astryx component --list
npx astryx search carousel

text
# 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 astryx docs cli/integrations/ship/test-in-an-app.

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: [],
};

From ComponentDoc: astryx 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 earlier integration add theme and integration add doc --parent wrote.
• 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 astryx doctor integration components
npx astryx component SideNav
npx astryx component AcmeSideNav
npx astryx 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.

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 astryx template --list
npx astryx 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 astryx template. To change a label, edit the doc (astryx docs cli/integrations/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 (astryx docs cli/integrations/building-blocks/templates/document-the-template/replace-a-core-template).

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

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

bash
npx astryx integration add template acme-dashboard
npx astryx 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 (astryx docs cli/integrations/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.

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.

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

From TemplateDoc: astryx docs authoring template-doc

• Set type to the kind you chose in astryx docs cli/integrations/building-blocks/templates/start-a-template. It decides which other fields the doc accepts.
• The file name sets the template id (astryx docs cli/integrations/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 astryx docs cli/integrations/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. astryx search matches them as it matches the description, and astryx build ranks page templates on them, 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 astryx docs cli/integrations/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 (astryx docs cli/integrations/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 astryx --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').TemplateDoc} */
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,
};

From TemplateDoc: astryx docs authoring template-doc

• Set category to the most specific supported {Group} - {Variant} value. Its words become search terms for astryx 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').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.

From TemplateDoc: astryx docs authoring template-doc

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

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.

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.

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 (astryx docs cli/integrations/building-blocks/templates/start-a-template).

• Sharing a Core id without replaces does not replace Core. It makes the bare id ambiguous, so astryx 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 astryx --json template --list --package @astryxdesign/core

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

From TemplateDoc: astryx docs authoring template-doc

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

Declare the CLI floor from the field above as an optional peer (astryx docs cli/integrations/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, an older CLI drops that template and hides your doc topics.

bash
# Receives the active replacement
npx astryx template shell-side-nav src/app
​
# Receives the original Core template
npx astryx 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 astryx 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.

astryx 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 astryx template acme-account src/app/account
​
# Block: src/features/account/acme-stat-card.tsx
npx astryx template acme-stat-card src/features/account
​
# Exact destination for either kind
npx astryx 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, VStack} from '@astryxdesign/core/Stack';
import {Text} from '@astryxdesign/core/Text';
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 (astryx docs cli/integrations/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, or browser APIs 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 (astryx docs cli/integrations/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 astryx docs cli/integrations/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 (astryx docs cli/integrations/building-blocks/templates/build-the-template/package-and-test/export-template-assets). In a TypeScript app, this import type-checks only when the app 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 (astryx docs cli/integrations/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 (astryx docs cli/integrations/building-blocks/templates/build-the-template/package-and-test/export-template-assets).

When you test the template in an app (astryx docs cli/integrations/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 (astryx docs cli/integrations/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 (astryx docs cli/integrations/building-blocks/templates/build-the-template/package-and-test/export-template-assets).

When you test the template in an app (astryx docs cli/integrations/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 (astryx docs cli/integrations/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 (astryx docs cli/integrations/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 astryx docs cli/integrations/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 astryx 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. astryx docs cli/integrations/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 astryx doctor integration templates for those.
• How the template scores on quality.

Install the packed package in a clean app as described in astryx docs cli/integrations/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 astryx --json template --list --package @acme/astryx-widgets
​
# Inspect source without writing
npx astryx template acme-dashboard --package @acme/astryx-widgets
​
# Copy a page and a block to their real app locations
npx astryx template acme-dashboard --package @acme/astryx-widgets src/app/acme-dashboard
npx astryx 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 (astryx docs cli/integrations/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 astryx docs cli/integrations/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 (astryx docs cli/integrations/building-blocks/templates/build-the-template/package-and-test/test-template-in-app).
4. To have an agent grade and improve the template, use astryx docs cli/integrations/building-blocks/templates/write-good-templates/grade-template-with-agent.

Keep each scorecard with its package revision and rubric version.

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.

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

Count raw icon markup in the copied file. astryx docs cli/integrations/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.

Prefer Astryx component props and design tokens. 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. Use Layout or Center as the page root. A template whose category starts with Shell - uses AppShell because global chrome is its purpose.
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 astryx docs cli/integrations/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 astryx docs cli/integrations/building-blocks/templates/start-a-template, displayName is readable, and a browsable page has a specific category (astryx docs cli/integrations/building-blocks/templates/document-the-template/page-template). Slug length is guidance, not a scored condition.

Inspect every image reference in the copied file against astryx docs cli/integrations/building-blocks/templates/build-the-template/template-assets/template-images-media.

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 astryx docs cli/integrations/building-blocks/templates/write-good-templates --full`.
2. Read `npx astryx docs cli/integrations/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 astryx integration verify` in the package.
5. Follow `npx astryx docs cli/integrations/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.

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 --import, 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 astryx 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 astryx 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. oceanTheme.doc.mjs describes it with type: 'theme', name, displayName, description, and maintained; theme list shows its name, description, and maintained. The command also declares ./themes/ocean and ./themes/ocean.css package exports. Every descriptor field is in astryx docs authoring.

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 --import to record and import the built module and stylesheets; plain theme add still copies source while that default is deprecated. See astryx docs cli/integrations/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 astryx 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 (astryx docs cli/integrations/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.

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 and keep enough contrast to read.

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 astryx docs cli/integrations/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 astryx theme palette generate themes/ocean/palette.config.json
# Write the palette and its receipt
npx astryx 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

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. The full list of config fields and options is in astryx docs cli/commands/theme-palette-generate.

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 the theme disappears from theme list. npx astryx theme template writes a file that explains every defineTheme field. For the full token set, scope selectors, and component theming, read astryx 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. The derived theme keeps a live link to the base and inherits its later changes — unlike --from, which forks a copy (astryx docs cli/integrations/building-blocks/themes/add-a-theme).

ts
import {defineTheme} from '@astryxdesign/core/theme';
import {oceanTheme} from './oceanTheme';
​
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: a browser without light-dark() drops the declaration, and the stop form is the one that degrades safely.

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 astryx 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 --import 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. If the app loads the same family outside the generated module, Doctor warns because it cannot prove the loader, 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 or one of its packed files cannot resolve.

Before publishing, run integration verify. Then install the package in a clean app, run theme add --import, 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 --import 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. Plain theme add still copies source while that default is deprecated.

bash
npm install @acme/astryx-widgets
npx astryx theme add ocean --import --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 astryx 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 astryx docs cli/integrations/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']},
});

Give your theme a doc topic that extends the core theme topic, so an app that lists your package sees your theme at the end of astryx docs theme. Add it with extends: 'theme' (astryx docs cli/integrations/building-blocks/docs/extend-or-replace).

javascript
// docs/ocean-theme.doc.mjs
/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
export default {
  type: 'generic',
  name: 'ocean-theme',
  extends: 'theme',
  title: 'Ocean theme',
  description: 'Use the Ocean theme from @acme/astryx-widgets.',
  sections: [
    {
      id: 'use-the-ocean-theme',
      title: 'Use the Ocean theme',
      content: [
        {
          type: 'prose',
          text: 'Install @acme/astryx-widgets, then run astryx theme add ocean --import --package @acme/astryx-widgets and apply it from the generated app theme module.',
        },
      ],
    },
  ],
};

Keep the section short: how to install the package, run theme add --import, apply the generated module (astryx docs cli/integrations/building-blocks/themes/use-a-theme-in-an-app), and customize with extends. When the theme uses a custom font, name the families and the optional exported font stylesheet that theme add --import imports (astryx docs cli/integrations/building-blocks/themes/fonts-and-assets). Extend theme rather than a topic another package replaces, or an app that lists that package first drops your section.

Do not put theme usage in agentDocs. Agent lines land in every app's agent file and are for guidance needed every session; a theme's install-and-use steps belong in a doc topic that people and agents read on demand. See astryx docs cli/integrations/building-blocks/configuration/agent-guidance.

integration add codemod writes a codemod into a folder named after a version. Apps run it with astryx upgrade to migrate their code.

bash
npx astryx integration add codemod rename-delay --to 0.7.0

text
codemods/
  0.7.0/
    rename-delay.mjs         # the codemod
    rename-delay.test.mjs    # skipped: a test file
    __tests__/               # skipped: a test folder

The first add declares codemods: './codemods' in astryx.integration.mjs. The codemod's id is its path inside the version folder, without the extension: rename-delay. An id must be unique across all version folders in the package.

The loader skips *.test.*, *.spec.*, and *.fixture.* files and everything under __tests__/ or __fixtures__/, so tests can sit beside the codemod. The folder name decides when an app runs the codemod; see "Choose when a codemod runs".

A codemod default-exports a plain object with a type, a title, and a transform function. transform returns the new source, or null to leave the file as it is.

js
// codemods/0.7.0/rename-delay.mjs
/** @type {import('@astryxdesign/cli/authoring').AstryxCodemod} */
export default {
  type: 'code',
  title: 'Rename AcmeCarousel delay to interval',
  description: 'Renames the delay prop on AcmeCarousel.',
  fileExtensions: ['.tsx', '.jsx'],
  transform(file, api) {
    const j = api.jscodeshift;
    const root = j(file.source);
    const props = root
      .find(j.JSXOpeningElement, {name: {name: 'AcmeCarousel'}})
      .find(j.JSXAttribute, {name: {name: 'delay'}});
    if (props.size() === 0) return null;
    props.forEach(path => {
      path.node.name.name = 'interval';
    });
    return root.toSource();
  },
};