@astryxdesign/cli 0.7.12 → 0.7.13-canary.9993f4c

package/api/icon/use/use.d.mts

@@ -2,14 +2,18 @@
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
 /**
- * Make an installed set the project's icon set.
+ * Make an installed set the project's main icon set, with backup sets in
+ * order. A copied template takes each icon from the first set in the list
+ * that has its meaning.
  * Experimental (spec:AST-017 FR27): may change or be removed in a patch
  * release.
  * @experimental
  * @param {string} selector a set name, or `<package>/<set>`
- * @param {{cwd?: string}} [options]
+ * @param {{cwd?: string, backups?: string[]}} [options] `backups`: the
+ *   backup sets, in order
  * @returns {Promise<import('../icon.type.mjs').IconUseResponse>}
  */
-export function iconUse(selector: string, { cwd }?: {
+export function iconUse(selector: string, { cwd, backups }?: {
     cwd?: string;
+    backups?: string[];
 }): Promise<import("../icon.type.mjs").IconUseResponse>;

package/api/icon/use/use.mjs

@@ -1,8 +1,10 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `icon.use` leaf (AST-084 FR8): choose the project's icon set by
- * writing `experimental.iconSet` in astryx.config.
+ * @file `icon.use` leaf (AST-084 FR8): choose the project's main icon set,
+ * and any backup sets in order, by writing `experimental.iconSet` in
+ * astryx.config. With no backup it writes the set name as a string; with
+ * backups it writes a list, the main set first.
  *
  * @output the `icon.use` envelope
  * @position api/icon/use — dispatched by the `experimental icon use` command
@@ -15,21 +17,51 @@ import {
   iconSetConfigCliWarning,
   iconSetKey,
   loadIconProject,
+  ICON_USE_ORDER_COMMAND,
   refuseOutsideProject,
-  setConfigString,
+  setConfigValue,
+  unlistedIconSets,
 } from '../_adapter.mjs';
 import {setsNamed, unusableSet} from '../_records.mjs';
 
 /**
- * Make an installed set the project's icon set.
+ * The one installed set a selector names, or the error that says why not.
+ * @param {import('../../../foundation/discovery/icon-set-discovery.mjs').DiscoveredIconSet[]} sets
+ * @param {import('../../../foundation/discovery/icon-set-discovery.mjs').WithdrawnIconSet[]} withdrawn
+ * @param {string} selector
+ */
+function oneSet(sets, withdrawn, selector) {
+  const named = setsNamed(sets, selector);
+  if (named.length === 0) throw unusableSet(sets, withdrawn, selector);
+  if (named.length > 1) {
+    throw new AstryxError(
+      `Two installed packages ship an icon set named "${selector}"; name it with its package.`,
+      named.map(set => ({
+        name: iconSetKey(set),
+        reason: `the set in ${set.package}`,
+      })),
+      ERROR_CODES.ERR_INVALID_ARGUMENT,
+    );
+  }
+  return named[0];
+}
+
+/**
+ * Make an installed set the project's main icon set, with backup sets in
+ * order. A copied template takes each icon from the first set in the list
+ * that has its meaning.
  * Experimental (spec:AST-017 FR27): may change or be removed in a patch
  * release.
  * @experimental
  * @param {string} selector a set name, or `<package>/<set>`
- * @param {{cwd?: string}} [options]
+ * @param {{cwd?: string, backups?: string[]}} [options] `backups`: the
+ *   backup sets, in order
  * @returns {Promise<import('../icon.type.mjs').IconUseResponse>}
  */
-export async function iconUse(selector, {cwd = process.cwd()} = {}) {
+export async function iconUse(
+  selector,
+  {cwd = process.cwd(), backups = []} = {},
+) {
   if (typeof selector !== 'string' || selector.trim() === '') {
     throw new AstryxError(
       'Name the icon set to use',
@@ -38,27 +70,31 @@ export async function iconUse(selector, {cwd = process.cwd()} = {}) {
           name: 'astryx experimental icon --list',
           reason: 'list the installed sets',
         },
+        {
+          name: ICON_USE_ORDER_COMMAND,
+          reason: 'choose a main set and backup sets, in order',
+        },
       ],
       ERROR_CODES.ERR_MISSING_ARGUMENT,
     );
   }
   refuseOutsideProject(cwd, 'experimental icon use', 'the app project');
   const {projectDir, sets, withdrawn} = await loadIconProject(cwd);
-  const named = setsNamed(sets, selector);
-  if (named.length === 0) throw unusableSet(sets, withdrawn, selector);
-  if (named.length > 1) {
+  const main = oneSet(sets, withdrawn, selector);
+  const backupSets = backups.map(each => oneSet(sets, withdrawn, each));
+  const listed = [main, ...backupSets];
+  const repeated = listed.find((set, index) => listed.indexOf(set) !== index);
+  if (repeated) {
     throw new AstryxError(
-      `Two installed packages ship an icon set named "${selector}"; name it with its package.`,
-      named.map(set => ({
-        name: iconSetKey(set),
-        reason: `the set in ${set.package}`,
-      })),
+      `"${iconSetKey(repeated)}" is in the list twice; name each set once, the main set first.`,
+      [{name: ICON_USE_ORDER_COMMAND, reason: 'each set once, in order'}],
       ERROR_CODES.ERR_INVALID_ARGUMENT,
     );
   }
+  const value = backups.length > 0 ? [selector, ...backups] : selector;
   let written;
   try {
-    written = setConfigString(projectDir, 'experimental.iconSet', selector);
+    written = setConfigValue(projectDir, 'experimental.iconSet', value);
   } catch (error) {
     // A protected config, or an unreadable protection source, keeps the
     // stable code every consumer-file writer uses (spec:AST-040 FR4, FR6).
@@ -73,17 +109,31 @@ export async function iconUse(selector, {cwd = process.cwd()} = {}) {
       stable ?? ERROR_CODES.ERR_WRITE_FAILED,
     );
   }
-  // An older CLI the project may still run refuses the key just written.
-  const warning = iconSetConfigCliWarning(projectDir);
+  // An older CLI the project may still run refuses the value just written.
+  const warning = iconSetConfigCliWarning(projectDir, {
+    list: Array.isArray(value),
+  });
+  // Doctor fails a project that installs several sets and leaves one out.
+  const unlisted = sets.filter(set => !listed.includes(set)).map(iconSetKey);
+  const left =
+    unlisted.length > 0
+      ? unlistedIconSets(sets.length, selector, backups, unlisted)
+      : null;
   return {
     type: 'icon.use',
     data: {
       iconSet: selector,
-      set: iconSetKey(named[0]),
+      set: iconSetKey(main),
+      backups: backups.map((each, index) => ({
+        iconSet: each,
+        set: iconSetKey(backupSets[index]),
+      })),
       config: path.relative(projectDir, written.file).split(path.sep).join('/'),
       created: written.created,
       previous: written.previous,
       changed: written.changed,
+      unlisted,
+      ...(left ? {next: `${left.problem}. ${left.fix}`} : {}),
       ...(warning ? {warning} : {}),
     },
   };

package/api/integration/validate-integration.d.mts

@@ -97,6 +97,10 @@ export type ValidateResult = {
      * what the public-import check could not judge
      */
     publicImports?: import("./validate-integration.type.mjs").PublicImportsReport | undefined;
+    /**
+     * the template icon imports the undeclared-icon check could not judge
+     */
+    templateIconsUnchecked?: import("../../foundation/discovery/template-icon-notes.mjs").TemplateIconUnchecked[] | undefined;
 };
 import { validateLoadedIntegration } from '../../foundation/integrations/validate-contributions.mjs';
 import { isListedIssue } from '../../foundation/integrations/validate-contributions.mjs';

package/api/integration/validate-integration.mjs

@@ -41,7 +41,10 @@ import {
   iconSetIssues,
 } from '../../foundation/discovery/icon-set-checks.mjs';
 import {olderCliNotes} from '../../foundation/discovery/doc-stability.mjs';
-import {templateIconNotes} from '../../foundation/discovery/template-icon-notes.mjs';
+import {
+  templateIconNotes,
+  templateIconUndeclaredNotes,
+} from '../../foundation/discovery/template-icon-notes.mjs';
 import {integrationDocConsistency} from '../../foundation/discovery/doc-consistency.mjs';
 import {
   integrationDocCommands,
@@ -123,6 +126,8 @@ export {validateLoadedIntegration, isListedIssue};
  * @property {import('../../foundation/discovery/doc-stability.mjs').OlderCliNote[]} [olderCliNotes]
  * @property {import('./validate-integration.type.mjs').PublicImportsReport} [publicImports]
  *   what the public-import check could not judge
+ * @property {import('../../foundation/discovery/template-icon-notes.mjs').TemplateIconUnchecked[]} [templateIconsUnchecked]
+ *   the template icon imports the undeclared-icon check could not judge
  */
 
 /**
@@ -554,6 +559,16 @@ async function validateAtPackageDir(
     // with its fix, never an issue (spec:AST-084 FR10).
     const iconNotes = await templateIconNotes(loaded, packageDir);
     if (iconNotes.length > 0) (result.notes ??= []).push(...iconNotes);
+    // An icon a template imports but never declares, in a package whose
+    // templates declare `icons`: a note until the next minor makes it a
+    // warning.
+    const undeclared = await templateIconUndeclaredNotes(loaded, packageDir);
+    if (undeclared.notes.length > 0)
+      (result.notes ??= []).push(
+        ...undeclared.notes.map(note => ({...note, next: true})),
+      );
+    if (undeclared.unchecked.length > 0)
+      result.templateIconsUnchecked = undeclared.unchecked;
   }
 
   return result;
@@ -900,7 +915,10 @@ export async function validateIntegration(pkg, options = {}) {
   if (integration?.docs) {
     notes.push(...(await docCommandNotes(integration)));
     notes.push(
-      ...(await docTargetNotes(integration)).map(note => ({...note, next: true})),
+      ...(await docTargetNotes(integration)).map(note => ({
+        ...note,
+        next: true,
+      })),
     );
   }
   return {
@@ -942,6 +960,18 @@ export async function validateIntegration(pkg, options = {}) {
             },
           }
         : {}),
+      // Template icon imports the check cannot judge (a name-only match, a
+      // generic renderer, or an import not used as an icon): listed, never
+      // failed on.
+      ...(result.found && result.templateIconsUnchecked
+        ? {
+            templateIcons: {
+              status: 'checked',
+              findings: [],
+              unchecked: result.templateIconsUnchecked,
+            },
+          }
+        : {}),
       // What the public-import check could not judge: listed, never failed on.
       ...(result.found && result.publicImports
         ? {publicImports: result.publicImports}

package/api/integration/validate-integration.type.d.mts

@@ -47,6 +47,11 @@ export type ValidateIntegrationResponse = {
      *   `showcase_not_standalone` and `template_asset_not_packed`, what a
      *   package's examples need (next minor; a block's `alsoShowcaseFor` names
      *   count as shown);
+     *   `template_icon_undeclared`, an icon a template imports but does not
+     *   declare in `icons`, in a package whose templates declare `icons` (next
+     *   minor; an import that matches an icon by its name only, a generic
+     *   renderer, and an import the template does not use as an icon are listed
+     *   in `templateIcons` as not checked instead);
      *   `cli_peer_version`, the running CLI outside the package's
      *   `@astryxdesign/cli` peer range; and
      *   the package layout findings added after the last minor release, each with
@@ -87,6 +92,16 @@ export type ValidateIntegrationResponse = {
             }>;
         };
         publicImports?: PublicImportsReport;
+        templateIcons?: {
+            status: "checked";
+            findings: [];
+            unchecked: Array<{
+                file: string;
+                icon: string;
+                module: string;
+                reason: string;
+            }>;
+        };
         iconSets?: IconSetCoverage[];
         olderCliNotes?: OlderCliNote[];
     };

package/api/integration/validate-integration.type.mjs

@@ -39,7 +39,7 @@
  * "healthy" — the two are otherwise byte-identical.
  * @typedef {object} ValidateIntegrationResponse
  * @property {'integration.validate'} type
- * @property {{validated: boolean, name: string | null, version: string | null, issues: import('../../foundation/integrations/issue').AstryxIntegrationIssue[], notes?: Array<{code: string, message: string, next?: boolean}>, docTypes?: DocTypesReport, docNames?: DocNamesReport, blockComponents?: BlockComponentsReport, exampleAssets?: {status: 'checked', findings: [], unchecked: Array<{file: string, asset: string, reason: string}>}, publicImports?: PublicImportsReport, iconSets?: IconSetCoverage[], olderCliNotes?: OlderCliNote[]}} data
+ * @property {{validated: boolean, name: string | null, version: string | null, issues: import('../../foundation/integrations/issue').AstryxIntegrationIssue[], notes?: Array<{code: string, message: string, next?: boolean}>, docTypes?: DocTypesReport, docNames?: DocNamesReport, blockComponents?: BlockComponentsReport, exampleAssets?: {status: 'checked', findings: [], unchecked: Array<{file: string, asset: string, reason: string}>}, publicImports?: PublicImportsReport, templateIcons?: {status: 'checked', findings: [], unchecked: Array<{file: string, icon: string, module: string, reason: string}>}, iconSets?: IconSetCoverage[], olderCliNotes?: OlderCliNote[]}} data
  *   `iconSets` is experimental: it may change or be removed in a patch
  *   release.
  *   `notes`: information beside the issues. A note fails nothing by default;
@@ -51,6 +51,11 @@
  *   `showcase_not_standalone` and `template_asset_not_packed`, what a
  *   package's examples need (next minor; a block's `alsoShowcaseFor` names
  *   count as shown);
+ *   `template_icon_undeclared`, an icon a template imports but does not
+ *   declare in `icons`, in a package whose templates declare `icons` (next
+ *   minor; an import that matches an icon by its name only, a generic
+ *   renderer, and an import the template does not use as an icon are listed
+ *   in `templateIcons` as not checked instead);
  *   `cli_peer_version`, the running CLI outside the package's
  *   `@astryxdesign/cli` peer range; and
  *   the package layout findings added after the last minor release, each with

package/api/template/copy/copy.mjs

@@ -100,8 +100,10 @@ export function templateCopy(
     demoContentReplaced,
     demoMediaReplaced,
   } = replaceTemplateDemos(fs.readFileSync(match.filePath, 'utf-8'));
-  // Icons follow the project's icon set (AST-084 FR9). An icon with no match
-  // keeps its import, so its library stays a needed dependency below.
+  // Icons follow the project's icon set and its backups (AST-084 FR9). An
+  // icon no set in the list draws a placeholder the file declares, so the
+  // library the template imported it from is no longer a needed dependency
+  // below.
   const {source: outputSource, icons} = mapTemplateIcons(
     withMedia,
     iconSets,

package/api/template/template.type.d.mts

@@ -117,7 +117,7 @@ export type TemplateCopyResponse = {
 /**
  * How a template's icons follow the project's icon set (AST-084 FR10).
  * Without a project icon set (`status` `none`, `ambiguous`, or `missing`)
- * the source is unchanged and both lists are empty.
+ * the source is unchanged and every list is empty.
  */
 export type TemplateIconsReport = {
     /**
@@ -125,15 +125,19 @@ export type TemplateIconsReport = {
      */
     status: "selected" | "none" | "ambiguous" | "missing" | "withdrawn";
     /**
-     * The project's icon set as `<package>/<set>`, when selected.
+     * The project's main icon set as `<package>/<set>`, when selected.
      */
     set: string | null;
+    /**
+     * The main set and each backup set as `<package>/<set>`, in the order icons are looked up; present when the project lists backups.
+     */
+    order?: string[] | undefined;
     /**
      * Why the project has that set, or none.
      */
     reason: string;
     /**
-     * Icons rewritten to the project's set, and the rule that chose each one: a reviewed `exact` or `strong` match, or the icon the set's `map` names for the icon definition the template declares. `dropped` names the library's sizing props (`size`, `strokeWidth`, `absoluteStrokeWidth`) removed from the icon's elements: an icon set's icons take their size from CSS.
+     * Icons rewritten to the first set in the project's list that has them, and the rule that chose each one: a reviewed `exact` or `strong` match, or the icon the set's `map` names for the icon definition the template declares. `target.set` names the set used. `dropped` names the library's sizing props (`size`, `strokeWidth`, `absoluteStrokeWidth`) removed from the icon's elements: an icon set's icons take their size from CSS. `variant` is present when the template's icon draws a look the set's icon does not have: the look asked for and the set's default look used instead.
      */
     mapped: Array<{
         source: {
@@ -149,9 +153,35 @@ export type TemplateIconsReport = {
         };
         by: "match" | "definition";
         dropped?: string[];
+        variant?: {
+            asked: string;
+            used: string | null;
+        };
     }>;
     /**
-     * Icons left as the template wrote them, with why, and a `likely` reviewed match as a suggestion when the project set has one. Every declared key is mapped or kept; `module` is null for a key the template does not import, and `export` is `default` for a default import and `*` for a namespace import.
+     * Icons with a meaning that no set in the project's list has. The template's original import is removed. The written code declares a small placeholder component once (`target.local`, `MissingIcon` unless the file already uses that name), and each use of the icon renders it, with a comment that names the meaning. It needs no package. `fixes` are the commands that give it a real icon: map the definition in the main set, or add a backup set that has it.
+     */
+    placeholder: Array<{
+        source: {
+            module: string;
+            export: string;
+        };
+        target: {
+            local: string;
+        };
+        definitions: string[];
+        fixes: string[];
+        dropped?: string[];
+        suggestion?: {
+            set: string;
+            id: string;
+            module: string;
+            export: string;
+            confidence: "likely";
+        };
+    }>;
+    /**
+     * Icons left as the template wrote them, with why, and a `likely` reviewed match as a suggestion when the project set has one. Every declared key is mapped, a placeholder, or kept; `module` is null for a key the template does not import, and `export` is `default` for a default import and `*` for a namespace import.
      */
     kept: Array<{
         module: string | null;
@@ -165,6 +195,14 @@ export type TemplateIconsReport = {
             confidence: "likely";
         };
     }>;
+    /**
+     * Each set the mapped icons come from, as `<package>/<set>`, with its license and how many icons it gave.
+     */
+    sets: Array<{
+        set: string;
+        license: string;
+        icons: number;
+    }>;
 };
 /**
  * astryx --json template --cdn [path]

package/api/template/template.type.mjs

@@ -56,7 +56,7 @@
  * @property {string} data.source
  * @property {number} data.demoMediaReplaced Astryx demo media references (images, posters, videos) replaced in the returned source: images with a neutral placeholder, videos with an empty source. Swap in your own media at those points; no media is installed. 0 when the template carried none.
  * @property {number} data.demoContentReplaced Astryx docs-only demo content elements (such as a playing card's face in a motion example) replaced in the returned source with a `<Text>Card content</Text>` placeholder. Put your own content there. 0 when the template carried none.
- * @property {TemplateIconsReport} [data.icons] Experimental, present only when the project sets `experimental.iconSet`: how the template's icons follow the project's icon set, each icon `mapped` (source and target) or `kept`, and the icon-set state. It may change or be removed in a patch release.
+ * @property {TemplateIconsReport} [data.icons] Experimental, present only when the project sets `experimental.iconSet`: how the template's icons follow the project's icon set, each icon `mapped` (source and target), a `placeholder`, or `kept`, the sets used with their licenses, and the icon-set state. It may change or be removed in a patch release.
  */
 
 /**
@@ -86,20 +86,23 @@
  * @property {string[]} data.notes Setup notes: what the template needs that the project lacks (missing packages, missing StyleX compiler). Each note is one actionable line. Empty when the template needs nothing the project lacks.
  * @property {string[]} data.missingPackages External package names the template imports that are not in the project's dependencies. Empty when none are missing.
  * @property {string | null} data.installCommand A ready-to-run install command for the missing packages, using the project's package manager and the CLI workspace's version ranges. Null when no packages are missing, or when several lockfiles leave the package manager undetermined; missingPackages still names the packages.
- * @property {TemplateIconsReport} [data.icons] Experimental, present only when the project sets `experimental.iconSet`: how the written file's icons follow the project's icon set, each icon `mapped` (source and target) or `kept`, and the icon-set state. It may change or be removed in a patch release.
+ * @property {TemplateIconsReport} [data.icons] Experimental, present only when the project sets `experimental.iconSet`: how the written file's icons follow the project's icon set, each icon `mapped` (source and target), a `placeholder`, or `kept`, the sets used with their licenses, and the icon-set state. It may change or be removed in a patch release.
  */
 
 /**
  * How a template's icons follow the project's icon set (AST-084 FR10).
  * Without a project icon set (`status` `none`, `ambiguous`, or `missing`)
- * the source is unchanged and both lists are empty.
+ * the source is unchanged and every list is empty.
  * @experimental May change or be removed in a patch release.
  * @typedef {object} TemplateIconsReport
  * @property {'selected' | 'none' | 'ambiguous' | 'missing' | 'withdrawn'} status The project's icon-set state.
- * @property {string | null} set The project's icon set as `<package>/<set>`, when selected.
+ * @property {string | null} set The project's main icon set as `<package>/<set>`, when selected.
+ * @property {string[]} [order] The main set and each backup set as `<package>/<set>`, in the order icons are looked up; present when the project lists backups.
  * @property {string} reason Why the project has that set, or none.
- * @property {Array<{source: {module: string, export: string}, target: {set: string, package: string, id: string, module: string, export: string}, by: 'match' | 'definition', dropped?: string[]}>} mapped Icons rewritten to the project's set, and the rule that chose each one: a reviewed `exact` or `strong` match, or the icon the set's `map` names for the icon definition the template declares. `dropped` names the library's sizing props (`size`, `strokeWidth`, `absoluteStrokeWidth`) removed from the icon's elements: an icon set's icons take their size from CSS.
- * @property {Array<{module: string | null, export: string, reason: string, suggestion?: {set: string, id: string, module: string, export: string, confidence: 'likely'}}>} kept Icons left as the template wrote them, with why, and a `likely` reviewed match as a suggestion when the project set has one. Every declared key is mapped or kept; `module` is null for a key the template does not import, and `export` is `default` for a default import and `*` for a namespace import.
+ * @property {Array<{source: {module: string, export: string}, target: {set: string, package: string, id: string, module: string, export: string}, by: 'match' | 'definition', dropped?: string[], variant?: {asked: string, used: string | null}}>} mapped Icons rewritten to the first set in the project's list that has them, and the rule that chose each one: a reviewed `exact` or `strong` match, or the icon the set's `map` names for the icon definition the template declares. `target.set` names the set used. `dropped` names the library's sizing props (`size`, `strokeWidth`, `absoluteStrokeWidth`) removed from the icon's elements: an icon set's icons take their size from CSS. `variant` is present when the template's icon draws a look the set's icon does not have: the look asked for and the set's default look used instead.
+ * @property {Array<{source: {module: string, export: string}, target: {local: string}, definitions: string[], fixes: string[], dropped?: string[], suggestion?: {set: string, id: string, module: string, export: string, confidence: 'likely'}}>} placeholder Icons with a meaning that no set in the project's list has. The template's original import is removed. The written code declares a small placeholder component once (`target.local`, `MissingIcon` unless the file already uses that name), and each use of the icon renders it, with a comment that names the meaning. It needs no package. `fixes` are the commands that give it a real icon: map the definition in the main set, or add a backup set that has it.
+ * @property {Array<{module: string | null, export: string, reason: string, suggestion?: {set: string, id: string, module: string, export: string, confidence: 'likely'}}>} kept Icons left as the template wrote them, with why, and a `likely` reviewed match as a suggestion when the project set has one. Every declared key is mapped, a placeholder, or kept; `module` is null for a key the template does not import, and `export` is `default` for a default import and `*` for a namespace import.
+ * @property {Array<{set: string, license: string, icons: number}>} sets Each set the mapped icons come from, as `<package>/<set>`, with its license and how many icons it gave.
  */
 
 /**

package/assets/discover/official-packages.json

@@ -200,6 +200,10 @@
           "kind": "component",
           "name": "TabBarItem"
         },
+        {
+          "kind": "component",
+          "name": "TabBarMoreList"
+        },
         {
           "kind": "component",
           "name": "ThreeDBar"

package/assets/docs/tree/icon-sets.doc.mjs

@@ -356,16 +356,100 @@ export const brand = defineTheme({name: 'brand', icons: themeIcons});`,
           lang: 'bash',
           code: `astryx experimental icon delete              # ranked matches with import lines
 astryx experimental icon outline/bin         # one icon and every variant
-astryx experimental icon --list              # installed sets and their definition coverage
-astryx experimental icon use outline         # make it the project's icon set`,
+astryx experimental icon --list              # installed sets, their order, and definition coverage
+astryx experimental icon use outline         # make it the project's main icon set
+astryx experimental icon use outline --backup brand   # a main set, then a backup`,
         },
         {
           type: 'prose',
-          text: "A template declares, in its descriptor's `icons`, the definition each imported icon draws (`{TrashIcon: 'delete'}`). Once the project sets `experimental.iconSet` in astryx.config (`experimental icon use` writes it), each declared icon becomes the set's icon for that definition. An icon the set does not map keeps its original import, and the copy reports every icon as mapped or kept. Nothing is guessed from names. A mapped icon loses its library's sizing props (`size`, `strokeWidth`, `absoluteStrokeWidth`), since a set's icons take their size from CSS; the report names them as `dropped`. Comments on a rewritten import line are kept.",
+          text: "A template declares, in its descriptor's `icons`, the definition each imported icon draws (`{TrashIcon: 'delete'}`). Once the project sets `experimental.iconSet` in astryx.config (`experimental icon use` writes it), each declared icon becomes the icon for that definition from the first set in the project's list that maps it. An icon that no set in the list has draws a placeholder instead (see When no set has an icon, below); it never keeps the template's original library import. The copy reports every icon as mapped, a placeholder, or kept. Nothing is guessed from names. A mapped icon loses its library's sizing props (`size`, `strokeWidth`, `absoluteStrokeWidth`), since a set's icons take their size from CSS; the report names them as `dropped`. Comments on a rewritten import line are kept.",
         },
         {
           type: 'prose',
-          text: "Each `icons` key is the name the template imports from its module, not a local alias. When a template imports the same name from two modules, such as `TrashIcon` from a library's outline and solid modules, one key covers both: both draw the same definition. Each then becomes the project set's variant of the same name when its module belongs to an installed set that declares the variant (so solid stays solid), else the set's default.",
+          text: "Each `icons` key is the name the template imports from its module, not a local alias. When a template imports the same name from two modules, such as `TrashIcon` from a library's outline and solid modules, one key covers both: both draw the same definition. Each then becomes the chosen set's variant of the same name when its module belongs to an installed set that declares the variant (so solid stays solid). When the chosen set's icon has no such variant, it draws the set's default look, and the report names both looks as `variant: {asked, used}`. A missing look never moves an icon to a backup set.",
+        },
+      ],
+    },
+    {
+      id: 'main-and-backup-sets',
+      title: 'Choose a main set and backups',
+      content: [
+        {
+          type: 'prose',
+          text: 'A project uses one main icon set. Backup sets fill the meanings the main set does not map, in the order you list them. Each icon comes from exactly one set: the first in the list that maps its meaning. Two sets that both map a meaning never mix; the list order decides.',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: `astryx experimental icon use outline --backup @acme/brand-icons/brand --backup lines`,
+        },
+        {
+          type: 'prose',
+          text: "`use` writes `experimental.iconSet` in astryx.config. With no `--backup`, it writes the set name as a string. With backups, it writes a list, the main set first. Name a set as `<set>`, or as `<package>/<set>` when two packages ship a set with that name. Every set in the list must be installed, and each set appears once. When the project's `@astryxdesign/cli` range also admits an older release that refuses the value written, `use` warns and names the range to require; the CLI you run now reads it either way.",
+        },
+        {
+          type: 'code',
+          lang: 'js',
+          label: 'astryx.config.mjs',
+          code: `export default {
+  experimental: {
+    // One main set:
+    // iconSet: 'outline',
+    // A main set, then backups in order:
+    iconSet: ['outline', '@acme/brand-icons/brand', 'lines'],
+  },
+};`,
+        },
+        {
+          type: 'prose',
+          text: "`astryx experimental icon --list` shows the order: the project's `order` (each set as `<package>/<set>`), and each set's `role` (`main`, `backup`, or not listed) and `rank`. Its coverage columns count the definitions each set maps: `builtIn` of the built-in names (a valid set maps them all, and `missing` lists any it lacks), and `definitions` of every Astryx definition. When two or more sets are installed and none is the main set, `--list` says so with the command to run, `astryx experimental icon use <main> --backup <set>`. The `use` receipt (`icon.use`) names the main set (`iconSet`, `set`) and each backup (`backups`), and lists installed sets the list leaves out (`unlisted`) with the command that adds them (`next`): `astryx doctor` fails a project that installs more than one set and leaves one out of the list.",
+        },
+        {
+          type: 'prose',
+          text: "Only the main set's theme map feeds `defineTheme({icons})`. Backups never change the theme. The copy report lists each set it used, with its license (`icons.sets`).",
+        },
+      ],
+    },
+    {
+      id: 'missing-icons',
+      title: 'When no set has an icon',
+      content: [
+        {
+          type: 'prose',
+          text: "When no set in the list maps an icon's meaning, the copied file removes that icon from the template's library import. It declares a small `MissingIcon` component once (another free name when the file already uses `MissingIcon`), and each place the icon was renders it, so the page still builds and needs no new package. The placeholder is a dashed square, 1em in size, in the current text color. It is hidden from screen readers unless that use gives it an `aria-label`. A comment beside each use records the meaning.",
+        },
+        {
+          type: 'code',
+          lang: 'tsx',
+          code: `<Icon icon={MissingIcon /* missing icon: cut */} size="sm" />`,
+        },
+        {
+          type: 'prose',
+          text: '`astryx template` prints a note for each placeholder, and the JSON report lists it in `icons.placeholder` with its `definitions` and `fixes`. Give the meaning a real icon in one of these ways:',
+        },
+        {
+          type: 'list',
+          style: 'ordered',
+          items: [
+            'Add a backup set that has the meaning: `astryx experimental icon use <main> --backup <set>`. `astryx discover --type icon-set` lists the sets your sources offer, with the definitions each maps; install one first.',
+            'If you author your main set (its package is yours, not an installed dependency), map the meaning there: `astryx experimental icon map cut <icon> --set <main>`.',
+            'For a built-in meaning (`astryx experimental icon --definitions` marks them), render the theme icon by name instead: `<Icon icon="close" />`. Every set maps the built-in names, so this needs no import.',
+            'Otherwise, write your own icon component and pass it where `MissingIcon` was (`astryx docs icons custom-icons`).',
+          ],
+        },
+        {
+          type: 'prose',
+          text: 'After the first two, copy the template again, or replace each use of `MissingIcon` with the icon `astryx experimental icon <meaning>` prints, which finds the icon once a set in your list maps the meaning, and delete the `MissingIcon` declaration. `astryx doctor` warns while copied code still uses the placeholder (the `icon-placeholders` check), and names each file and meaning.',
+        },
+      ],
+    },
+    {
+      id: 'label-template-icons',
+      title: 'Label every template icon',
+      content: [
+        {
+          type: 'prose',
+          text: "A template follows a project's icon sets only for the icons its `icons` declares. In a package whose templates declare `icons`, `astryx integration check` notes each icon a template imports but does not declare (`template_icon_undeclared`). The note fails `--strict --next` now, and `--strict` from the next minor release. It counts an import from another package as an icon when a template in the package declares an icon from the same module, and the template renders it as an element with no children (`<Scissors />`) or passes it as a value (`icon={Scissors}`). Any other import from that module, such as a type, a function the template calls, or a provider with children, is listed as not checked: declaring it would make `astryx template` swap it for an icon. An import whose name ends in `Icon`, from any other module, matches by name only, so the check lists it as not checked. A generic renderer (a bare `Icon`, or a component every use gives an `icon`, `iconNode`, `name` or `src` prop, such as lucide's `DynamicIcon`) draws no one definition, so it is listed as not checked too, whatever its module. Neither fails anything. Add the key with the definition it draws; `astryx experimental icon --definitions` lists the definitions, and `astryx experimental icon new-definition` adds one your set needs.",
         },
       ],
     },
@@ -383,7 +467,7 @@ astryx experimental icon use outline         # make it the project's icon set`,
           rows: [
             [
               '`experimental.iconSet` in astryx.config',
-              "The project's icon set, by set name or as `<package>/<set>`, and the opt-in: templates, discover, and doctor read icon sets only when it is set. `astryx experimental icon` ranks its icons first, and without it treats the only installed set as the project's. `astryx experimental icon use` writes it.",
+              "The project's main icon set, by set name or as `<package>/<set>`, or a list: the main set first, then backup sets in order. It is the opt-in: templates, discover, and doctor read icon sets only when it is set. `astryx experimental icon` ranks the main set's icons first, and without it treats the only installed set as the project's. `astryx experimental icon use <main> --backup <set>` writes it.",
             ],
             [
               '`experimental.iconSets` in the integration manifest',
@@ -391,7 +475,7 @@ astryx experimental icon use outline         # make it the project's icon set`,
             ],
             [
               "A template descriptor's `icons`",
-              "The icon definition each imported icon draws (`{TrashIcon: 'delete'}`): a named import by the name it imports, a default import by its local name. `astryx template`, shown or copied, then writes the set's icons and reports `icons` (status, set, mapped, kept): every key is mapped, or kept with why (no match, a namespace or type-only import, a re-export, an Astryx or project-set import, or no import at all). `integration check` notes a key the template's source never imports (`template_icon_not_imported`), never failing.",
+              "The icon definition each imported icon draws (`{TrashIcon: 'delete'}`): a named import by the name it imports, a default import by its local name. `astryx template`, shown or copied, then writes the icons from the first set in the list that has each meaning and reports `icons` (status, set, order, mapped, placeholder, kept, sets): every key is mapped, a placeholder when no set has its meaning, or kept with why (a namespace or type-only import, a re-export, an Astryx import or one from a set in the list, no import at all, or an icon that draws no definition and has no match). `integration check` notes a key the template's source never imports (`template_icon_not_imported`), never failing, and notes an imported icon the package's templates do not declare (`template_icon_undeclared`), which fails `--strict --next`.",
             ],
             [
               '`astryx discover`',
@@ -399,7 +483,7 @@ astryx experimental icon use outline         # make it the project's icon set`,
             ],
             [
               '`astryx doctor`',
-              'In an app, the `icon-sets` check: fails when `experimental.iconSet` names a set that is not installed or was withdrawn (an invalid set, or one whose module does not resolve), saying why, and warns when two packages ship a set by that name or a set was withdrawn. In your icon-set package, check with `astryx integration check` instead: plain `doctor` diagnoses an app.',
+              'In an app, the `icon-sets` check: fails when `experimental.iconSet` names a set, main or backup, that is not installed, was withdrawn (an invalid set, or one whose module does not resolve), or that two packages ship by that name, saying why; fails when more than one set is installed and the list leaves one out; and warns when another installed set was withdrawn. The `icon-placeholders` check warns while copied code uses the placeholder for a missing icon, naming each file and meaning. In your icon-set package, check with `astryx integration check` instead: plain `doctor` diagnoses an app.',
             ],
             [
               'JSON types',

package/assets/icons/definitions/alignBottom.doc.mjs

@@ -0,0 +1,9 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').IconDefinitionDoc} */
+export default {
+  type: 'icon-definition',
+  name: 'alignBottom',
+  description: 'Align items to the bottom edge.',
+  words: ['bottom align', 'align end vertical'],
+};

package/assets/icons/definitions/alignJustify.doc.mjs

@@ -0,0 +1,9 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').IconDefinitionDoc} */
+export default {
+  type: 'icon-definition',
+  name: 'alignJustify',
+  description: 'Justify text so each line fills the full width.',
+  words: ['justify', 'full width text'],
+};

package/assets/icons/definitions/alignMiddle.doc.mjs

@@ -0,0 +1,9 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').IconDefinitionDoc} */
+export default {
+  type: 'icon-definition',
+  name: 'alignMiddle',
+  description: 'Center items between the top and bottom edges.',
+  words: ['vertical center', 'middle align'],
+};