@astryxdesign/cli 0.1.2 → 0.1.3-canary.102854d

package/CHANGELOG.md

@@ -1,5 +1,69 @@
 # @xds/cli
 
+# 0.1.3
+
+#### New Features
+
+- Add a hidden `astryx blog` command that reads the blog over the site's RSS feed and prints a post's plaintext (`.txt`) variant. The command is not shown in `--help` or the manifest and always reads from the canonical site origin.
+- Component discovery is now package-ownership aware: --package scoping, source resolution for integration components, and package-qualified JSON listings.
+- Strict config + integration v1 schema (integrations, issuesUrl, hooks.postCodemod) and new @astryxdesign/cli/integration export.
+- File-based codemod API (createCodemod/createConfigCodemod) with the @astryxdesign/cli/codemod export and integration codemod discovery in upgrade.
+- component, template, and upgrade now print a one-line non-blocking warning when a configured integration has validation issues, pointing to validate-integration.
+- Add a Kanban Board page template: color-coded status columns, draggable task cards with priority tags, and board toolbar.
+- Add frame-first layout guidance: new `astryx docs layout` topic (shell choice, region budgets, app archetypes, cards-vs-rows policy, responsive contracts), layout rules in the generated agent cheat sheet, and layout anti-patterns in `docs principles`.
+- Add a v0.1.3 config codemod that migrates astryx.config layout.components to experimental.xle.components.
+- Add v0.1.0 codemods for migrating `declare module "@xds/core/..."` type augmentations and `.xds-*` / `[data-xds-theme]` / `@layer xds-theme` CSS surfaces to their `@astryxdesign`/`astryx-*` equivalents.
+- Introduce the Project configuration API as the single entry point for reading resolved project config, components, templates, codemods, and issue routing, replacing loadConfig. Misconfigured integrations are now skipped with a warning during upgrade instead of hard-failing, and a new --skip-codemod flag lets you re-run past a failed codemod.
+- Add a Shell page-template category to the CLI: Top Nav, Side Nav, and Shell Nav app-shell scaffolds (#3245, #3246, #3247)
+- Static template authoring API (createPageTemplate/createBlockTemplate) with the @astryxdesign/cli/template export and type-driven, package-scoped template discovery.
+- Swizzle can now copy integration-owned components, rewrites escaping imports to the owning package, and routes maintainer feedback through config and integration issue URLs.
+- `astryx theme build --watch`: rebuild a theme automatically whenever the source file changes, until interrupted with Ctrl-C. Removes the manual re-run step (and the stale-CSS confusion that comes with forgetting it) from the theme-authoring loop. Each rebuild runs in a child process so a build error is contained and the watcher keeps running. Not supported with `--json`. (#3375)
+- Add the validate-integration command and integration issue model for checking an Astryx integration package's manifest and contributions.
+- XLE app-component registration moved into validated config under experimental.xle.components (object form), replacing the unvalidated layout.components read.
+
+#### Fixes
+
+- Align the CLI error-code type declarations with the runtime error codes (add the missing ERR_AMBIGUOUS_TEMPLATE declaration).
+- Correct the `doctor` theme-wiring hint to reference the real `astryx.theme` config field (was `xds.theme`) and update the agent-docs check wording to say "Astryx".
+- Update the API/CLI parity harness for the package-qualified `component --list` shape, and make the component API reject a non-string name with a clean error instead of throwing.
+- The XDS-prefix drop codemod now runs as a mandatory v0.1.0 upgrade step, so upgrading from 0.0.x rewrites prefixed imports (useXDSTheme, XDSButton, XDSIconRegistry, ...) to their bare names alongside the @xds/_ → @astryxdesign/_ scope rename.
+- upgrade now runs core codemods before loading config, so a config codemod can repair an otherwise-invalid config; dry-run reports a fixable config and suggests the command to apply it.
+
+#### Documentation
+
+- Blockquote: add "With Attribution" and "Testimonials" examples (#3385)
+- DateTimeInput and DateRangeInput: add example blocks so their docs pages have populated Examples sections and playground links (#2724)
+- Add copyable example blocks to 46 component docs pages that previously showed only a hero visual and an empty Examples section (#3481)
+- HoverCard: give the "Link Preview" example an interactive `Link` trigger so there is something to hover over (#2728)
+- Lightbox: add Gallery, Video, and Zoom examples and fix the playground preview (#3301)
+- Remove lingering references to the removed gap-report feature and swizzle gap flags; docs now reflect swizzle's maintainer feedback link.
+- Tab: add an interactive example showing `icon` and `selectedIcon` on the Tab docs page (#2765)
+- ToggleButtonGroup: add a vertical example block showing orientation="vertical" with single- and multi-select groups (#2707)
+
+#### Other Changes
+
+- Integration codemod and template-doc loading now use the shared module-loader util instead of duplicating the jiti/import logic.
+- Extract the shared module-loading + conventional-file-discovery helpers used by config and integration loading into one internal util (no behavior change).
+- Remove the standalone gap-report command. Swizzle now prints a short maintainer feedback link instead of filing issues.
+- Load and validate user-authored config, integration, codemod, and template modules through one shared module loader; create\* factories are now type-only and validation happens at load.
+- Remove the obsolete xds config-surface migration codemod and unify config codemod execution on the shared (file, api) runner used by integration codemods.
+
+#### Contributors
+
+Thanks to everyone who contributed to this release:
+
+- @AKnassa
+- @ejhammond
+- @ernestt
+- @harshavardhan194
+- @josephfarina
+- @kentonquatman
+- @mohitWeb-lab
+- @pollychen-lab
+- @thedjpetersen
+
+---
+
 # 0.1.2
 
 #### Breaking Changes
@@ -110,7 +174,6 @@ Thanks to everyone who contributed to this release:
 Thanks to everyone who contributed to this release:
 
 - @ejhammond
-- @joeyfarina
 - @josephfarina
 - @nynexman4464
 

package/README.md

@@ -62,8 +62,7 @@ Options:
 | `upgrade`     | Run codemods to migrate between versions                                                             |
 | `theme build` | Compile a defineTheme file to production CSS and JS                                                  |
 | `discover`    | Discover external packages and components                                                            |
-| `gap-report`  | Report a gap when a component doesn't meet your needs                                                |
-| `doctor`      | Diagnose your XDS setup and report problems with fixes (CI-friendly via exit code)                   |
+| `doctor`      | Diagnose your Astryx setup and report problems with fixes (CI-friendly via exit code)                |
 
 ### Global options
 
@@ -161,7 +160,6 @@ if (isError(result)) {
 | `ERR_INVALID_VERSION`    | A `--from`/`--to` value was not a valid semver string.                                 |
 | `ERR_DEP_MISSING`        | A required external dependency (e.g. jscodeshift) is missing.                          |
 | `ERR_GH_CLI`             | GitHub CLI (`gh`) is not installed or not authenticated.                               |
-| `ERR_GAP_REPORT_FAILED`  | Filing a gap report failed (disabled, or the integration errored).                     |
 
 ## Capability manifest (agent discovery)
 
@@ -172,7 +170,7 @@ discriminators each command can emit. Think of it as an OpenAPI spec for the CLI
 
 ```bash
 astryx manifest --json        # dedicated surface — type: "manifest"
-xds --json                 # bare invocation — embeds the same payload under data.manifest
+astryx --json                 # bare invocation — embeds the same payload under data.manifest
 ```
 
 Shape:
@@ -182,7 +180,7 @@ Shape:
   "apiVersion": 1,
   "type": "manifest",
   "data": {
-    "name": "xds",
+    "name": "astryx",
     "version": "0.0.14",
     "description": "Design system CLI — components, themes, and tooling",
     "globalOptions": [
@@ -249,14 +247,14 @@ the `JSON_SUPPORTED` allowlist and a small declarative `RESPONSE_TYPES` map in
 `src/lib/manifest.mjs`, guarded by a drift test (`manifest.test.mjs`) so adding a
 command without describing it fails CI.
 
-**Backwards-compat:** the bare `xds --json` envelope keeps `type: "help"` and its
+**Backwards-compat:** the bare `astryx --json` envelope keeps `type: "help"` and its
 original shallow fields (`name`, `version`, `commands` as a `string[]` of names,
 `jsonSupported`); the full structured manifest is additive under `data.manifest`.
 For the standalone manifest envelope (`type: "manifest"`), use `astryx manifest --json`.
 
 ## Programmatic API
 
-The same logic that powers `xds --json` is available as importable, type-safe functions:
+The same logic that powers `astryx --json` is available as importable, type-safe functions:
 
 ```typescript
 import {
@@ -269,20 +267,20 @@ import {
   AstryxError,
 } from '@astryxdesign/cli/api';
 
-// Same result as: xds --json component Button
+// Same result as: astryx --json component Button
 const btn = await component('Button');
 btn.type; // 'component.detail'
 btn.data.name; // 'Button' (typed as ComponentDoc)
 
-// Same result as: xds --json component --list
+// Same result as: astryx --json component --list
 const list = await component(undefined, {list: true});
 list.data; // Record<string, string[]>
 
-// Same result as: xds --json docs principles
+// Same result as: astryx --json docs principles
 const principles = await docs('principles');
-principles.data.title; // 'XDS Principles'
+principles.data.title; // 'Principles'
 
-// Same result as: xds --json hook useMediaQuery
+// Same result as: astryx --json hook useMediaQuery
 const useMediaQuery = await hook('useMediaQuery');
 useMediaQuery.data.params; // typed as HookParamDoc[]
 
@@ -296,7 +294,7 @@ try {
 }
 ```
 
-The CLI command handlers are thin wrappers around these functions: they parse args, call the API, then format the output (JSON or text). This guarantees that `@astryxdesign/cli/api` and `xds --json` always return identical data.
+The CLI command handlers are thin wrappers around these functions: they parse args, call the API, then format the output (JSON or text). This guarantees that `@astryxdesign/cli/api` and `astryx --json` always return identical data.
 
 ### Consumer utilities
 
@@ -326,43 +324,41 @@ detail.data.name; // already narrowed
 
 Every response has a `type` string that uniquely identifies it:
 
-| Command                                        | Type                        | Response                          |
-| ---------------------------------------------- | --------------------------- | --------------------------------- |
-| `xds --json component [--list]`                | `component.list`            | `ComponentListResponse`           |
-| `xds --json component --list --detail compact` | `component.brief`           | `ComponentBriefResponse`          |
-| `xds --json component --list --detail full`    | `component.full`            | `ComponentFullResponse`           |
-| `xds --json component <name>`                  | `component.detail`          | `ComponentDetailResponse`         |
-| `xds --json component <name> --props`          | `component.detail.props`    | `ComponentDetailPropsResponse`    |
-| `xds --json component <name> --source`         | `component.detail.source`   | `ComponentDetailSourceResponse`   |
-| `xds --json component <name> --showcase`       | `component.detail.showcase` | `ComponentDetailShowcaseResponse` |
-| `xds --json component <name> --blocks`         | `component.detail.blocks`   | `ComponentDetailBlocksResponse`   |
-| `xds --json discover`                          | `discover.list`             | `DiscoverListResponse`            |
-| `xds --json discover @scope/name`              | `discover.detail`           | `DiscoverDetailResponse`          |
-| `xds --json discover @scope/name/Comp`         | `discover.detail.doc`       | `DiscoverDetailDocResponse`       |
-| `xds --json discover <search>`                 | `discover.search`           | `DiscoverSearchResponse`          |
-| `xds --json docs`                              | `docs.list`                 | `DocsListResponse`                |
-| `xds --json docs <topic>`                      | `docs.detail`               | `DocsDetailResponse`              |
-| `xds --json docs <topic> <section>`            | `docs.detail.section`       | `DocsDetailSectionResponse`       |
-| `xds --json template [--list]`                 | `template.list`             | `TemplateListResponse`            |
-| `xds --json template <name>`                   | `template.show`             | `TemplateShowResponse`            |
-| `xds --json template <name> --skeleton`        | `template.skeleton`         | `TemplateSkeletonResponse`        |
-| `xds --json template <name> [path]`            | `template.copy`             | `TemplateCopyResponse`            |
-| `xds --json hook [--list]`                     | `hook.list`                 | `HookListResponse`                |
-| `xds --json hook --list --detail compact`      | `hook.brief`                | `HookBriefResponse`               |
-| `xds --json hook --list --detail full`         | `hook.full`                 | `HookFullResponse`                |
-| `xds --json hook <name>`                       | `hook.detail`               | `HookDetailResponse`              |
-| `xds --json hook <name> --params`              | `hook.detail.params`        | `HookDetailParamsResponse`        |
-| `xds --json search <query>`                    | `search`                    | `SearchResponse`                  |
-| `xds --json swizzle [--list]`                  | `swizzle.list`              | `SwizzleListResponse`             |
-| `xds --json swizzle <component>`               | `swizzle.copy`              | `SwizzleCopyResponse`             |
-| `xds --json theme build <file>`                | `theme.build`               | `ThemeBuildResponse`              |
-| `xds --json upgrade --list`                    | `upgrade.list`              | `UpgradeListResponse`             |
-| `xds --json upgrade [--apply]`                 | `upgrade.run`               | `UpgradeRunResponse`              |
-| `xds --json gap-report --list-categories`      | `gap-report.categories`     | `GapReportCategoriesResponse`     |
-| `xds --json gap-report --component X ...`      | `gap-report.file`           | `GapReportFileResponse`           |
-| `xds --json doctor`                            | `doctor`                    | `DoctorResponse`                  |
-| any error                                      | —                           | `CLIError`                        |
-| unsupported command                            | —                           | `CLIUnsupportedError`             |
+| Command                                           | Type                        | Response                          |
+| ------------------------------------------------- | --------------------------- | --------------------------------- |
+| `astryx --json component [--list]`                | `component.list`            | `ComponentListResponse`           |
+| `astryx --json component --list --detail compact` | `component.brief`           | `ComponentBriefResponse`          |
+| `astryx --json component --list --detail full`    | `component.full`            | `ComponentFullResponse`           |
+| `astryx --json component <name>`                  | `component.detail`          | `ComponentDetailResponse`         |
+| `astryx --json component <name> --props`          | `component.detail.props`    | `ComponentDetailPropsResponse`    |
+| `astryx --json component <name> --source`         | `component.detail.source`   | `ComponentDetailSourceResponse`   |
+| `astryx --json component <name> --showcase`       | `component.detail.showcase` | `ComponentDetailShowcaseResponse` |
+| `astryx --json component <name> --blocks`         | `component.detail.blocks`   | `ComponentDetailBlocksResponse`   |
+| `astryx --json discover`                          | `discover.list`             | `DiscoverListResponse`            |
+| `astryx --json discover @scope/name`              | `discover.detail`           | `DiscoverDetailResponse`          |
+| `astryx --json discover @scope/name/Comp`         | `discover.detail.doc`       | `DiscoverDetailDocResponse`       |
+| `astryx --json discover <search>`                 | `discover.search`           | `DiscoverSearchResponse`          |
+| `astryx --json docs`                              | `docs.list`                 | `DocsListResponse`                |
+| `astryx --json docs <topic>`                      | `docs.detail`               | `DocsDetailResponse`              |
+| `astryx --json docs <topic> <section>`            | `docs.detail.section`       | `DocsDetailSectionResponse`       |
+| `astryx --json template [--list]`                 | `template.list`             | `TemplateListResponse`            |
+| `astryx --json template <name>`                   | `template.show`             | `TemplateShowResponse`            |
+| `astryx --json template <name> --skeleton`        | `template.skeleton`         | `TemplateSkeletonResponse`        |
+| `astryx --json template <name> [path]`            | `template.copy`             | `TemplateCopyResponse`            |
+| `astryx --json hook [--list]`                     | `hook.list`                 | `HookListResponse`                |
+| `astryx --json hook --list --detail compact`      | `hook.brief`                | `HookBriefResponse`               |
+| `astryx --json hook --list --detail full`         | `hook.full`                 | `HookFullResponse`                |
+| `astryx --json hook <name>`                       | `hook.detail`               | `HookDetailResponse`              |
+| `astryx --json hook <name> --params`              | `hook.detail.params`        | `HookDetailParamsResponse`        |
+| `astryx --json search <query>`                    | `search`                    | `SearchResponse`                  |
+| `astryx --json swizzle [--list]`                  | `swizzle.list`              | `SwizzleListResponse`             |
+| `astryx --json swizzle <component>`               | `swizzle.copy`              | `SwizzleCopyResponse`             |
+| `astryx --json theme build <file>`                | `theme.build`               | `ThemeBuildResponse`              |
+| `astryx --json upgrade --list`                    | `upgrade.list`              | `UpgradeListResponse`             |
+| `astryx --json upgrade [--apply]`                 | `upgrade.run`               | `UpgradeRunResponse`              |
+| `astryx --json doctor`                            | `doctor`                    | `DoctorResponse`                  |
+| any error                                         | —                           | `CLIError`                        |
+| unsupported command                               | —                           | `CLIUnsupportedError`             |
 
 ## Doctor
 
@@ -383,7 +379,7 @@ astryx doctor — diagnosing your setup
       @astryxdesign/core v0.0.14 is in step with @astryxdesign/cli v0.0.14.
   ⚠ Theme packages
       No @astryxdesign/theme-* packages are installed.
-      → fix: Install a theme, e.g. `npm install @astryxdesign/theme-neutral`, then import its CSS or set xds.theme.
+      → fix: Install a theme, e.g. `npm install @astryxdesign/theme-neutral`, then import its CSS or set astryx.theme.
   ℹ astryx.config.mjs
       No astryx.config.mjs found — using defaults.
   ℹ AI agent docs
@@ -408,7 +404,7 @@ No failures — but review the ⚠ warnings above when you can.
 | Version alignment            | pass / warn / info   | Installed `@astryxdesign/core` is in step with `@astryxdesign/cli`   |
 | Theme packages               | pass / warn          | An `@astryxdesign/theme-*` package is installed and a theme is wired |
 | astryx.config.mjs            | pass / fail / info   | Config (if present) loads cleanly with a valid shape                 |
-| AI agent docs                | pass / warn / info   | Agent docs exist and contain the XDS section markers                 |
+| AI agent docs                | pass / warn / info   | Agent docs exist and contain the Astryx section markers              |
 | Peer dependencies            | pass / warn / info   | `@astryxdesign/core`'s peer deps (react, …) are installed            |
 | Package manager              | info                 | Reports the detected package manager                                 |
 
@@ -434,8 +430,6 @@ export default {
   templates: {
     get: async id => fetchTemplateFromAPI(id),
   },
-  gapReport: {
-    url: 'https://your-api.com/gaps',
-  },
+  issuesUrl: 'https://github.com/your-org/your-repo/issues',
 };
 ```

package/docs/browser-support.doc.mjs

@@ -0,0 +1,200 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../core/src/docs-types').ReferenceDoc} */
+
+export const docs = {
+  name: 'browser-support',
+  title: 'Browser Support',
+  category: 'guide',
+  description:
+    'What browsers Astryx targets, which modern platform features it depends on, and how to support older browsers for your own audience.',
+
+  sections: [
+    {
+      title: 'Overview',
+      content: [
+        {
+          type: 'prose',
+          text: 'Astryx is built on modern web platform features — the Popover API, CSS anchor positioning, and CSS `light-dark()`. These let components stay small, accessible, and dependency-free, but they also set a floor on which browsers render everything correctly.',
+        },
+        {
+          type: 'prose',
+          text: 'A design system does not own its traffic — the products built on it do. Their audiences range from evergreen-Chrome-only internal tools to public sites with meaningful older-Safari share. So Astryx does not declare a single hard browser floor the way an app would. Instead it defines tiers that describe what works at each level, and hands the final decision to you. Pick the tier that matches your audience.',
+        },
+      ],
+    },
+    {
+      title: 'Support Tiers',
+      content: [
+        {
+          type: 'prose',
+          text: 'Astryx officially supports Tier 1 and Tier 2. Tier 3 is best-effort: components will not crash, but positioning and theming may degrade.',
+        },
+        {
+          type: 'table',
+          headers: ['Tier', 'Baseline', 'Representative versions', 'What your users experience'],
+          rows: [
+            [
+              'Tier 1 — Full fidelity',
+              'Current Baseline (2026)',
+              'Chrome 125+, Edge 125+, Safari 26+, Firefox 147+',
+              'Everything works, including CSS anchor positioning. This is the reference target.',
+            ],
+            [
+              'Tier 2 — Functional',
+              'Baseline − 2 years (2024)',
+              'Chrome 114+, Edge 114+, Safari 17+, Firefox 125+',
+              'Components open, dismiss, and are fully usable. Only anchor positioning is missing, so layered surfaces (tooltips, menus, popovers) may not be positioned next to their trigger.',
+            ],
+            [
+              'Tier 3 — Below Tier 2',
+              'Older than Baseline − 2',
+              'Anything older',
+              'Best-effort. The only guarantee is "does not crash." `light-dark()` is unavailable, so theme colors may fall back to defaults.',
+            ],
+          ],
+        },
+      ],
+    },
+    {
+      title: 'Which Features Set the Floor',
+      content: [
+        {
+          type: 'prose',
+          text: 'Only three modern features carry a browser requirement. Everything else Astryx uses (`:has()`, `color-mix()`, container queries, the `<dialog>` element) has been widely available since 2023 or earlier and needs no special handling.',
+        },
+        {
+          type: 'table',
+          headers: ['Feature', 'Role in Astryx', 'Widely available'],
+          rows: [
+            [
+              'CSS Anchor Positioning',
+              'Positions layered surfaces relative to their trigger (tooltips, menus, popovers, dropdowns).',
+              'Baseline 2026 — the tightest requirement.',
+            ],
+            [
+              'Popover API',
+              'Opens, stacks, and light-dismisses layered surfaces via the top layer.',
+              'Baseline 2025.',
+            ],
+            [
+              'CSS light-dark()',
+              'Compiles every theme color tuple into a single value that responds to color scheme. Underpins the whole theming system.',
+              'Widely available since mid-2024.',
+            ],
+          ],
+        },
+        {
+          type: 'prose',
+          text: 'The gap that matters is between Tier 1 and Tier 2: the Popover API and `light-dark()` reached wide availability well before anchor positioning. So in Tier 2 browsers, layered surfaces open and dismiss correctly — they just are not positioned. This is the one feature most consumers will need to reason about.',
+        },
+      ],
+    },
+    {
+      title: 'Which Components Are Affected',
+      content: [
+        {
+          type: 'prose',
+          text: 'The browser requirement is concentrated in the layered-surface components — anything that renders content in an overlay positioned against a trigger:',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Tooltip',
+            'HoverCard',
+            'Popover',
+            'ContextMenu',
+            'Selector and MultiSelector (dropdown surfaces)',
+            'Tokenizer (suggestion menu)',
+            'Carousel (anchored controls)',
+          ],
+        },
+        {
+          type: 'prose',
+          text: 'If your product does not use any of these, it has no anchor-positioning requirement at all — it needs only `light-dark()` (Tier 2 and up) for correct theme colors. Layout, typography, forms, buttons, cards, tables, and navigation all work down to Tier 2 with no special handling.',
+        },
+      ],
+    },
+    {
+      title: 'What Astryx Guarantees',
+      content: [
+        {
+          type: 'list',
+          style: 'do',
+          items: [
+            'Components never throw on missing platform APIs. Where a browser lacks the Popover API, layers fall back to plain visibility instead of crashing.',
+            'Tier 1 and Tier 2 are officially supported and tested.',
+            'Non-layered components render correctly down to Tier 2.',
+          ],
+        },
+        {
+          type: 'list',
+          style: 'dont',
+          items: [
+            'Astryx does not guarantee correct layer positioning below Tier 1 (anchor positioning). Closing that gap for a Tier 2 audience is a consumer choice — see below.',
+            'Astryx does not ship a `light-dark()` fallback, so theme colors are not guaranteed below Tier 2.',
+          ],
+        },
+      ],
+    },
+    {
+      title: 'Supporting Older Browsers',
+      content: [
+        {
+          type: 'prose',
+          text: 'If your audience includes Tier 2 browsers and you need correct layer positioning, you have three options, cheapest first. All of them are decisions you make for your audience — Astryx does not impose one.',
+        },
+        {
+          type: 'list',
+          style: 'ordered',
+          items: [
+            'Polyfill anchor positioning. Load a CSS anchor positioning polyfill conditionally behind an `@supports` check so it costs nothing on Tier 1. This is the lowest-effort way to get correct positioning; note that polyfills may not cover every position-fallback feature.',
+            'Provide a JS positioning fallback. Detect missing support with `CSS.supports("anchor-name", "--x")` and position layers with a measurement-based library (e.g. a floating-element positioner) when it returns false. More code, full control.',
+            'Accept degraded positioning. Document for your users that on Tier 2 browsers, layered surfaces open correctly but may not sit next to their trigger. Cheapest, and often fine for internal tools on evergreen browsers.',
+          ],
+        },
+        {
+          type: 'prose',
+          text: 'Feature-detect at runtime rather than sniffing user agents:',
+        },
+        {
+          type: 'code',
+          lang: 'js',
+          label: 'Feature detection',
+          code: `// Popover API (Tier 2 and up)
+const hasPopover = typeof HTMLElement !== 'undefined'
+  && typeof HTMLElement.prototype.showPopover === 'function';
+
+// CSS anchor positioning (Tier 1)
+const hasAnchorPositioning = CSS.supports('anchor-name', '--x');
+
+// CSS light-dark() (Tier 2 and up)
+const hasLightDark = CSS.supports('color', 'light-dark(#000, #fff)');`,
+        },
+      ],
+    },
+    {
+      title: 'How These Tiers Move Over Time',
+      content: [
+        {
+          type: 'prose',
+          text: 'The tiers are rolling, not frozen to specific versions. They track the Web Baseline year:',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Tier 1 tracks the current Baseline year.',
+            'Tier 2 tracks Baseline minus two years.',
+            'Tier 3 is everything older, and remains best-effort.',
+          ],
+        },
+        {
+          type: 'prose',
+          text: 'This is not an arbitrary window: Baseline − 2 is close to where anchor positioning stops being available while the Popover API and `light-dark()` still are — so the tier boundary tracks a real capability edge, not a guessed date. The version floors above are reviewed and advanced roughly once a year as new Baseline years land. Always feature-detect rather than hardcoding version numbers, so your app adapts automatically as the platform moves.',
+        },
+      ],
+    },
+  ],
+};

package/docs/layout.doc.dense.mjs

@@ -0,0 +1,90 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../core/src/docs-types').ReferenceTranslationDoc} */
+
+export const docsDense = {
+  description:
+    'frame-first app layout: shell choice, region budgets, cards vs rows',
+  sections: [
+    {
+      title: 'Frame First',
+      content: [
+        {
+          type: 'prose',
+          text: 'decide frame before content. content-first (Card-wrapped sections in a scroll column) = prototype look.',
+        },
+        {
+          type: 'list',
+          items: [
+            'pick frame: AppShell (nav apps) | Layout+LayoutPanel+LayoutContent (multi-pane tools) | plain column (docs/forms)',
+            'budget regions in px first: side nav 240-280, rail 64-72, inspector 340-420, facet rail 220-260',
+            'container policy per region: dense data = rows; dashboards/galleries = card grids',
+            'write responsive contract up front',
+          ],
+        },
+        null,
+      ],
+    },
+    {
+      title: 'App Archetypes',
+      content: [
+        {
+          type: 'prose',
+          text: 'container choice tracks archetype, not preference.',
+        },
+        null,
+        {
+          type: 'prose',
+          text: 'start from matching template (astryx template --list), study with --skeleton.',
+        },
+      ],
+    },
+    {
+      title: 'Cards vs Rows',
+      content: [
+        {
+          type: 'prose',
+          text: 'Card = widget container, NOT list-item wrapper. dense/scannable/selectable data = rows: Table (columnar) or List/Item (single-line), edge-to-edge, 32-40px rows, dividers.',
+        },
+        {
+          type: 'list',
+          items: [
+            'Table+plugins: hosts, deployments, monitors, users',
+            'List/Item rows: issues, files, conversations',
+            'Card: KPI tiles, chart panels, gallery entries, settings groups',
+            'EmptyState for zero-match',
+          ],
+        },
+        {
+          type: 'list',
+          items: [
+            'no Card-wrapped list items (card soup)',
+            'no stacked full-width Cards as page structure',
+            'no Cards in Cards',
+            'no decorative Badge — counts/enums only; StatusDot/Token for status',
+          ],
+        },
+      ],
+    },
+    {
+      title: 'Panels and Inspectors',
+      content: [
+        {
+          type: 'prose',
+          text: 'master-detail: row select opens fixed-width inspector (LayoutPanel end slot + width budget + resizable/useResizable). overlay content <=1024px, do not compress.',
+        },
+        null,
+      ],
+    },
+    {
+      title: 'Responsive Contract',
+      content: [
+        {
+          type: 'prose',
+          text: 'declare breakpoint behavior as comment at frame root: which regions collapse/overlay/drop at which widths.',
+        },
+        null,
+      ],
+    },
+  ],
+};