An open source design system that's fully customizable and agent ready
TypeScript
docs(spec): AST-050 ranks a theme's description as prose and names the add command for the CLI's stage (#7040)
Cindy Zhang8d216bb9141b
diff --git a/docs/specs/AST-050-app-themes/spec.md b/docs/specs/AST-050-app-themes/spec.mdindex c736ca676c..b05b6a5fbe 100644--- a/docs/specs/AST-050-app-themes/spec.md+++ b/docs/specs/AST-050-app-themes/spec.md@@ -236,11 +236,17 @@ described.- **FR14 — Search finds the themes the list shows.** `astryx search` MUST indexeach theme `theme list` shows as a `theme` result, which `--type theme`selects. A theme result MUST carry its slug as `name`, its display name, its- description, the package that ships it, and the `theme add` command FR13- names. Searching themes MUST NOT need `@astryxdesign/core`, because listing- them does not, so an open search outside an app includes them (DEC-8). Help,- the manifest, and the API reference MUST list the `theme` domain and its- result fields.+ description, the package that ships it, and the `theme add` command for the+ CLI's FR12 stage: `theme add <slug>` in a CLI without `--import`,+ `theme add --import <slug>` while the copy default is deprecated, and+ `theme add <slug>` after the cleanup (FR13). A theme's slug and display name+ are its names, and its description is prose (DEC-9): a query word the theme+ shares only through its description ranks it as a description mention, never+ as a name or keyword match, so that word alone never ranks the theme above a+ result that matches it by name, title, or keyword. Searching themes MUST NOT+ need `@astryxdesign/core`, because listing them does not, so an open search+ outside an app includes them (DEC-8). Help, the manifest, and the API+ reference MUST list the `theme` domain and its result fields.### Platform support@@ -259,8 +265,8 @@ described.deprecated and leave `theme add` in a scheduled minor (FR12); `theme eject`,`theme remove`, and `theme use` join the `theme` command; `theme list` gainsits app fields and lists local themes;-- `astryx search` finds the themes `theme list` shows, as the `theme` domain- (FR14);+- `astryx search` finds the themes `theme list` shows, as the `theme` domain,+ and ranks a word found only in a theme's description as prose (FR14);- `architecture:cli-surface` INV19: integration themes are importable packages,and editable source is an explicit eject;- `integration add theme` writes theme exports, and `integration verify` checks@@ -290,7 +296,7 @@ unchanged.| FR11 | Doctor tests, one planted fault per check | each of the ten faults; a correct app | A check passes on its fault, or passes without positive evidence || FR12 | Lifecycle tests against the latest stable CLI, migration tests on a project it made, and docs tests | plain `theme add`; the cleanup build; a copy made by the latest stable `theme add`; the upgrade codemod run twice; no theme module | Before the cleanup, plain `theme add` stops copying, changes its exit status, stdout, or `theme.add` fields, omits the deprecation id, or warns more than once; after it, plain `theme add` copies; a theme command or doctor fails on an unmigrated copy; the codemod changes more than the descriptor or changes anything on its second run; a copy is moved or deleted; or doctor fails a project with no theme module || FR13 | Docs and agent-docs tests | theme guide, integration guide, agent block, init next steps | A surface teaches copying as the way to use a theme, or names a different import command than the current lifecycle stage |-| FR14 | Search tests and CLI runs | a bundled theme; an integration theme; `--type theme` and an open search outside an app; help and the manifest | A theme `theme list` shows is missing from search, a theme result lacks a field or names another command than FR13, a themes-only search needs Core, or help, the manifest, or the API reference omits the domain |+| FR14 | Search tests and CLI runs | bundled and integration themes; `--type theme` and an open search outside an app; a word only in a theme's description, such as `focus`; an exact slug or display name; a CLI with and without `--import`; help and the manifest | A theme `theme list` shows is missing from search, a theme result lacks a field or names another command than its FR12 stage, a word only in a theme's description ranks it as a name or keyword match or above a result matching that word by name, title, or keyword, a themes-only search needs Core, or help, the manifest, or the API reference omits the domain |## Decision log@@ -441,6 +447,20 @@ has not set up an app yet can still find a theme by how it looks.Rejected: requiring Core for every domain but docs, which fails a themes-onlysearch where `theme list` works.+### DEC-9 — A theme's description is prose++**Reference:** `spec:AST-050/DEC-9`+**Decider:** `cixzhang`, `2026-10-06`++A theme's description is a sentence written for a person choosing a look. Its+words describe a mood, so a word in it is a passing mention, ranked like any+other description, and not a label the theme's author chose for search. A+theme's names are its slug and its display name, and a theme declares no+keywords.++Rejected: reading every description word as a keyword, which ranks a theme first+for any word its description happens to use.+## Open questionsNone.