@astryxdesign/core 0.5.1 → 0.5.2-canary.00477a5

package/src/Kbd/Kbd.spec.md

@@ -0,0 +1,141 @@
+---
+schema_version: 1
+template_version: 3
+kind: component
+id: component:Kbd
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [theming]
+verified_by: [packages/core/src/Kbd/Kbd.test.tsx, scripts/check-knowledge.mjs]
+families: []
+design_specs: []
+architecture: [architecture:component-theming-surface]
+contributing: []
+system_specs: []
+---
+
+# Kbd component contract
+
+## Intent
+
+Kbd presents a keyboard shortcut as one or more painted key badges. This draft
+records current consumer anatomy and theming reachability without changing
+runtime behavior, styling, targets, or public API.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: additive documentation only; runtime, DOM, styling,
+  targets, aliases, and public API remain unchanged
+- Controlled/uncontrolled behavior: not applicable
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The shortcut group, its current `kbd` target, and the painted key badges it
+  renders from the supplied shortcut string.
+
+**Does not own / non-goals**
+
+- The action associated with the shortcut or how the shortcut is discovered —
+  owned by the product callsite.
+- Whether an individual key badge should gain a public target — unresolved by
+  this factual backfill.
+
+## Public concepts
+
+No new public concept is introduced. Consumer props and usage remain documented
+in `Kbd.doc.mjs`.
+
+## Behavioral and layout contract
+
+| ID  | Candidate invariant                                                                                          | Basis                           | Draft review state                                  |
+| --- | ------------------------------------------------------------------------------------------------------------ | ------------------------------- | --------------------------------------------------- |
+| FR1 | The current render contains one shortcut group and one painted key badge for every parsed key segment.       | Current source, docs, and tests | Verified current behavior; no new behavior decided  |
+| FR2 | The shortcut group carries the current `kbd` target; individual key badges currently carry no public target. | Current source, docs, and tests | Verified current behavior; theming intent unsettled |
+
+### Allowed variation
+
+- Platform-specific key text and caller-supplied shortcut combinations may vary
+  without changing the two-part anatomy recorded here.
+
+### Representative states
+
+- The same anatomy applies to single-key, multi-key, modifier, and
+  platform-resolved shortcuts.
+
+### Transformation and precedence order
+
+- No new parsing, layout, or styling precedence rule is introduced.
+
+### Performance and resources
+
+- No new performance or resource rule is introduced.
+
+## Accessibility contract
+
+This draft does not change or extend Kbd's existing accessible-name behavior.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                                 | Representation authority       | Hierarchy role | Component contract |
+| ---------------- | ------------------------------------------------------------------ | ------------------------------ | -------------- | ------------------ |
+| Shortcut         | Groups the complete shortcut and carries its accessible name.      | Current source and public docs | Supporting     | FR1, FR2           |
+| Key badge        | Paints one visible badge for each key in the supplied combination. | Current source and public docs | Prominent      | FR1, FR2           |
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Shortcut": {"target": "kbd"},
+  "Key badge": {
+    "none": {
+      "reason": "unsettled: No current public target reaches this part"
+    }
+  }
+}
+```
+
+The `none` disposition records current reachability while target exposure remains
+unsettled. It does not decide that key badges should remain without a public
+target.
+
+## Family and system relationships
+
+- `architecture:component-theming-surface` owns anatomy qualification, target
+  mapping, and the difference between factual reachability and intended public
+  theming API.
+
+## Verification map
+
+| Contract            | Verification                                     | Representative states           | Mutation or failure expectation                                                                  | Audit section       |
+| ------------------- | ------------------------------------------------ | ------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------- |
+| FR1                 | `Kbd.test.tsx` key rendering suites              | Single-key and multi-key output | Removing the group or a parsed badge fails existing role, element, or text assertions.           | `audit:Kbd/anatomy` |
+| FR2                 | Source inspection and current target inventories | Root target and child badges    | Adding or documenting a current target without updating the anatomy map fails repository checks. | `audit:Kbd/theming` |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                    | Canonical anatomy and targets   | Missing, extra, prefixed, stale, or alias-backed mappings fail repository validation.            | `audit:Kbd/theming` |
+
+## Decision log
+
+None. This draft records current facts and introduces no component-local design
+or theming decision.
+
+## Open questions
+
+- **OQ1 — Should each Key badge gain a stable public theming target?**
+  (`human-api`) Target exposure is unsettled; the current lack of reachability
+  does not decide the answer.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, current audit
+results, implementation steps, or system rules. It links to their owners.

package/src/Layout/Layout.doc.mjs

@@ -1,5 +1,35 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+  {
+    name: 'Page shell',
+    required: true,
+    description: 'Outer Layout container that arranges the named page regions.',
+  },
+  {
+    name: 'Header',
+    required: false,
+    description: 'Optional top region for page or application header content.',
+  },
+  {
+    name: 'Panel',
+    required: false,
+    description:
+      'Optional start or end side region; both positions use the same LayoutPanel part.',
+  },
+  {
+    name: 'Content area',
+    required: false,
+    description: 'Optional central region for the page content.',
+  },
+  {
+    name: 'Footer',
+    required: false,
+    description: 'Optional bottom region for page footer content.',
+  },
+];
+
 /** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
@@ -129,6 +159,7 @@ export const docs = {
       { guidance: false, description: 'Use Layout for simple stacking layouts; use HStack or VStack instead.' },
       { guidance: false, description: 'Nest multiple Layout components; use one per page shell and compose content within its slots.' },
     ],
+    anatomy,
   },
 };
 
@@ -159,5 +190,6 @@ export const docsDense = {
       { guidance: false, description: 'Use Layout for simple stacking layouts; use HStack or VStack instead.' },
       { guidance: false, description: 'Nest multiple Layout components; use one per page shell and compose content within its slots.' },
     ],
+    anatomy,
   },
 };

package/src/Layout/Layout.spec.md

@@ -0,0 +1,199 @@
+---
+schema_version: 1
+template_version: 3
+kind: component
+id: component:Layout
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [public-api, behavior, layout, theming, accessibility]
+verified_by:
+  [
+    packages/core/src/Layout/Layout.test.tsx,
+    packages/core/src/Layout/LayoutSlots.test.tsx,
+    packages/core/src/Layout/__tests__/childrenAsContent.test.tsx,
+    packages/core/src/Layout/__tests__/contentWidth.test.tsx,
+    packages/core/src/theme/themingTargets.test.ts,
+    scripts/check-knowledge.mjs,
+  ]
+families: [family:layout-regions]
+design_specs: []
+architecture:
+  [
+    architecture:container-padding,
+    architecture:component-theming-surface,
+    architecture:public-component-api,
+  ]
+contributing: []
+system_specs: []
+---
+
+# Layout component contract
+
+## Intent
+
+Layout provides the page shell that arranges optional Header, Panel, Content
+area, and Footer regions. This draft records the current aggregate consumer
+anatomy and theming ownership without changing runtime behavior, DOM, styling,
+targets, or public API.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: additive documentation only; runtime, DOM, styling,
+  targets, aliases, and public API remain unchanged
+- Controlled/uncontrolled behavior: not applicable
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The Page shell and its current `layout` target.
+- The aggregate Header, Panel, Content area, and Footer anatomy and their current
+  `layout-header`, `layout-panel`, `layout-content`, and `layout-footer` targets.
+- One Panel concept for both logical start and end positions.
+
+**Does not own / non-goals**
+
+- Product meaning or content supplied to any region — owned by the caller.
+- Automatic responsive substitution of regions — owned by the caller, AppShell,
+  or another higher-level composition.
+- Resize interaction — owned by useResizable and ResizeHandle.
+- Correcting current container-padding publication mismatches or preventing two
+  adjacent divider owners from both painting; those remain current gaps and
+  caller obligations recorded below.
+- New runtime behavior, API, target, alias, or region wrapper.
+
+## Public concepts
+
+No new public concept is introduced. Consumer props, slots, defaults, and usage
+remain documented in `Layout.doc.mjs` and the region subcomponent docs.
+`family:layout-regions` owns the shared region vocabulary.
+
+## Behavioral and layout contract
+
+| ID  | Candidate invariant                                                                                                                                                                                                               | Basis                                     | Draft review state                                 |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | -------------------------------------------------- |
+| FR1 | Layout renders one Page shell carrying the current `layout` target and places each supplied named region according to the existing shell topology.                                                                                | Current source, docs, tests, and family   | Verified current behavior; no new behavior decided |
+| FR2 | Header, Content area, and Footer use their current `layout-header`, `layout-content`, and `layout-footer` targets on the corresponding Layout region components.                                                                  | Current source and target metadata        | Verified current inventory; no target change       |
+| FR3 | A Panel in either logical start or end position is the same aggregate Panel part and uses the current `layout-panel` target; position does not create a second anatomy row or target.                                             | Current source, docs, tests, and family   | Verified current ownership; no API change          |
+| FR4 | `Layout.doc.mjs` is the canonical aggregate consumer document for all five current `layout*` targets; region subcomponent docs continue to document their own props and usage without duplicating the aggregate target inventory. | Current documentation organization        | Verified current ownership                         |
+| FR5 | LayoutContent and LayoutPanel retain their shipped automatic container-padding publication behavior, including the mismatches recorded by `architecture:container-padding`; this documentation does not claim exact parity.       | Current source and architecture record    | Current conformance gap; not fixed here            |
+| FR6 | When an adjacent ResizeHandle owns a panel divider, the caller must keep `LayoutPanel hasDivider={false}`; current composition does not prevent both components from painting the same boundary.                                  | Current source, docs, and family contract | Current caller obligation; not fixed here          |
+
+### Current evidence and gaps
+
+- LayoutContent does not republish a matching inline-end container-padding value
+  on its automatic no-end path, and its no-start path writes the outer inline
+  value to both inline geometry variables. LayoutPanel applies automatic outer
+  shell-edge padding while retaining baseline inner geometry variables. A
+  full-bleed descendant can therefore compensate against a published value that
+  differs from the region's applied padding. This is shipped evidence and a
+  runtime conformance gap, not behavior corrected or approved by this draft.
+- LayoutPanel and an adjacent ResizeHandle can both draw the same content-facing
+  divider. The current caller obligation is to set
+  `LayoutPanel hasDivider={false}` when ResizeHandle owns that line. This draft
+  does not add coordination or duplicate-divider prevention.
+
+### Allowed variation
+
+- **AV1 — Slot presence.** Header, start Panel, Content area, end Panel, and Footer
+  may be independently present or absent within the existing shell topology.
+- **AV2 — Panel position.** A Panel may occupy logical start or end, or Panels may
+  occupy both positions; all use the same conceptual part and target owner.
+- **AV3 — Region content.** Caller-provided region content retains its own
+  semantics and theming ownership.
+
+### Representative states
+
+| State                 | Required invariant                                                         | Allowed variation                                      |
+| --------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------ |
+| Content-only shell    | Page shell and Content area use their current targets.                     | Caller content and current height/width configuration. |
+| Header/content/footer | Each supplied region uses its corresponding aggregate part and target.     | Divider selection, size, padding, and caller content.  |
+| Start or end Panel    | Either logical position uses the one Panel part and `layout-panel` target. | Position, width, scrolling, padding, and caller role.  |
+| Two Panels            | Both instances remain one repeated conceptual Panel part.                  | Independent content, width, and local configuration.   |
+| ResizeHandle-adjacent | Divider ownership follows the current caller obligation in FR6.            | Resize state remains owned by the resize components.   |
+
+### Transformation and precedence order
+
+- No new slot, padding, content-width, divider, scrolling, sizing, or styling
+  precedence rule is introduced.
+
+### Performance and resources
+
+- No new performance or resource rule is introduced.
+
+## Accessibility contract
+
+This draft does not add inferred landmark semantics. LayoutHeader,
+LayoutContent, LayoutFooter, and LayoutPanel retain their current explicit
+caller-supplied role and label behavior.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                             | Representation authority                  | Hierarchy role | Component contract |
+| ---------------- | -------------------------------------------------------------- | ----------------------------------------- | -------------- | ------------------ |
+| Page shell       | Arranges the named page regions.                               | Current source, docs, and family contract | Supporting     | FR1                |
+| Header           | Presents optional top-region content.                          | Current source, docs, and family contract | Supporting     | FR1, FR2           |
+| Panel            | Presents optional side-region content at logical start or end. | Current source, docs, and family contract | Supporting     | FR1, FR3, FR6      |
+| Content area     | Presents optional central page content.                        | Current source, docs, and family contract | Prominent      | FR1, FR2, FR5      |
+| Footer           | Presents optional bottom-region content.                       | Current source, docs, and family contract | Supporting     | FR1, FR2           |
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Page shell": {"target": "layout"},
+  "Header": {"target": "layout-header"},
+  "Panel": {"target": "layout-panel"},
+  "Content area": {"target": "layout-content"},
+  "Footer": {"target": "layout-footer"}
+}
+```
+
+The exact map records the five current public targets. Start and end Panels are
+instances of the same stable conceptual part and therefore share one map row.
+
+## Family and system relationships
+
+- `family:layout-regions` owns the shared shell-region topology, logical
+  direction, boundaries, scrolling, and component ownership.
+- `architecture:container-padding` owns Layout inset publication and the current
+  LayoutContent/LayoutPanel conformance gap.
+- `architecture:component-theming-surface` owns anatomy qualification and exact
+  target mapping rules.
+- `architecture:public-component-api` owns the stable slots, props, exports, and
+  compatibility boundary; this documentation adds no API.
+
+## Verification map
+
+| Contract      | Verification                                                                  | Representative states                               | Mutation or failure expectation                                                                     | Audit section                |
+| ------------- | ----------------------------------------------------------------------------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ---------------------------- |
+| FR1–FR3       | Layout render, slot, children-as-content, and target inventory tests          | Content-only, all regions, logical start/end Panels | Removing a region or target fails existing structure, context, or target inventory assertions.      | `audit:Layout/anatomy`       |
+| FR4           | `scripts/check-knowledge.mjs`                                                 | Canonical aggregate doc and exact five-target map   | Duplicated, missing, extra, prefixed, or stale target mappings fail repository validation.          | `audit:Layout/theming`       |
+| FR5           | Source inspection plus `architecture:container-padding` verification evidence | Automatic outer-edge Content area and Panel paths   | This draft adds no parity assertion; a runtime correction requires separate compatibility evidence. | `audit:Layout/layout`        |
+| FR6           | LayoutPanel source/docs plus `family:layout-regions` verification evidence    | Panel beside a divider-owning ResizeHandle          | This draft adds no prevention assertion; changing ownership requires separate runtime coverage.     | `audit:Layout/layout`        |
+| Accessibility | `LayoutSlots.test.tsx` landmark assertions                                    | Header, Content area, Footer, and Panel roles       | Supplied role or label no longer reaches the region element.                                        | `audit:Layout/accessibility` |
+
+## Decision log
+
+None. This draft records current facts and introduces no component-local design,
+layout, API, target, or behavior decision.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables or examples, family region
+rules, container-padding mechanics, resize interaction, implementation steps,
+or system rules. It links to their owners.

package/src/Lightbox/Lightbox.doc.mjs

@@ -1,12 +1,63 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+  {
+    name: 'Viewer overlay',
+    required: true,
+    description:
+      'Full-viewport dialog overlay that contains the active media and controls.',
+  },
+  {
+    name: 'Media',
+    required: true,
+    description: 'Active image or video presented inside the viewer.',
+  },
+  {
+    name: 'Close button',
+    required: true,
+    description: 'Button that closes the viewer.',
+  },
+  {
+    name: 'Previous button',
+    required: false,
+    description: 'Gallery button that moves to the previous media item.',
+  },
+  {
+    name: 'Next button',
+    required: false,
+    description: 'Gallery button that moves to the next media item.',
+  },
+  {
+    name: 'Caption',
+    required: false,
+    description: 'Caller-provided caption displayed below the active media.',
+  },
+  {
+    name: 'Counter',
+    required: false,
+    description: 'Current position and total shown in gallery mode.',
+  },
+];
+
 /** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'Lightbox',
   displayName: 'Lightbox',
   category: 'Overlay',
-  keywords: ["lightbox","image","video","viewer","gallery","zoom","fullscreen","media","photo","preview"],
+  keywords: [
+    'lightbox',
+    'image',
+    'video',
+    'viewer',
+    'gallery',
+    'zoom',
+    'fullscreen',
+    'media',
+    'photo',
+    'preview',
+  ],
   props: [
     {
       name: 'isOpen',
@@ -28,7 +79,8 @@ export const docs = {
       // where a media object belongs. The shape and its legal values live in
       // the description instead (#1645).
       type: 'LightboxMedia | LightboxMedia[]',
-      description: "Media to display. Pass a single object for one item, or an array for gallery mode with prev/next navigation. Each item is {src: string, alt: string, caption?: ReactNode, type?: 'image' | 'video'}; type defaults to 'image', and zoom/pan is disabled for 'video'.",
+      description:
+        "Media to display. Pass a single object for one item, or an array for gallery mode with prev/next navigation. Each item is {src: string, alt: string, caption?: ReactNode, type?: 'image' | 'video'}; type defaults to 'image', and zoom/pan is disabled for 'video'.",
       required: true,
     },
     {
@@ -39,46 +91,70 @@ export const docs = {
     {
       name: 'onIndexChange',
       type: '(index: number) => void',
-      description: 'Callback when the gallery index changes via prev/next navigation.',
+      description:
+        'Callback when the gallery index changes via prev/next navigation.',
     },
     {
       name: 'hasZoom',
       type: 'boolean',
-      description: 'Enable zoom on double-click, or Enter/Space/+/- via keyboard (images only). When zoomed, drag or use arrow keys to pan.',
+      description:
+        'Enable zoom on double-click, or Enter/Space/+/- via keyboard (images only). When zoomed, drag or use arrow keys to pan.',
       default: 'false',
     },
     {
       name: 'defaultIndex',
       type: 'number',
-      description: 'Initial image index in gallery mode for uncontrolled usage.',
+      description:
+        'Initial image index in gallery mode for uncontrolled usage.',
       default: '0',
     },
     {
       name: 'hasAutoPlay',
       type: 'boolean',
-      description: 'Automatically start video playback when a video media item is shown.',
+      description:
+        'Automatically start video playback when a video media item is shown.',
       default: 'false',
     },
     {
       name: 'xstyle',
       type: 'StyleXStyles',
-      description: 'StyleX styles for layout customization. Must be stylex.create() value.',
+      description:
+        'StyleX styles for layout customization. Must be stylex.create() value.',
     },
   ],
   theming: {
-    targets: [
-      {className: 'astryx-lightbox', visualProps: []},
-    ],
+    targets: [{className: 'astryx-lightbox', visualProps: []}],
   },
   usage: {
+    anatomy,
     description:
       'A fullscreen overlay for viewing images and videos at full resolution. Supports single-item and gallery modes with prev/next navigation, optional zoom and pan for images, and native video controls.',
     bestPractices: [
-      { guidance: true, description: 'Always provide alt text for every image for screen reader accessibility.' },
-      { guidance: true, description: 'Use gallery mode with onIndexChange for multi-image sets.' },
-      { guidance: true, description: 'Enable hasZoom only when viewing high-resolution images that benefit from close inspection.' },
-      { guidance: false, description: 'Use the lightbox for non-image content; it is specialized for images.' },
-      { guidance: false, description: 'Nest interactive content inside captions; keep them plain text.' },
+      {
+        guidance: true,
+        description:
+          'Always provide alt text for every image for screen reader accessibility.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use gallery mode with onIndexChange for multi-image sets.',
+      },
+      {
+        guidance: true,
+        description:
+          'Enable hasZoom only when viewing high-resolution images that benefit from close inspection.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use the lightbox for non-image content; it is specialized for images.',
+      },
+      {
+        guidance: false,
+        description:
+          'Nest interactive content inside captions; keep them plain text.',
+      },
     ],
   },
   // The lightbox opens via showModal() and renders nothing while closed —
@@ -91,7 +167,8 @@ export const docs = {
       media: {
         src: '/template-assets/light-scene-horizontal-1.png',
         alt: 'Coastal shoreline with ocean waves',
-        caption: 'A scenic coastline with waves rolling onto a sandy beach beneath a clear sky.',
+        caption:
+          'A scenic coastline with waves rolling onto a sandy beach beneath a clear sky.',
       },
     },
   },
@@ -117,7 +194,8 @@ export const docsZh = {
     {
       name: 'media',
       type: 'LightboxMedia | LightboxMedia[]',
-      description: "要显示的媒体。传入单个对象或数组（用于画廊模式的上一张/下一张导航）。每项为 {src, alt, caption?, type?: 'image' | 'video'}；type 默认为 'image'，'video' 禁用缩放/平移。",
+      description:
+        "要显示的媒体。传入单个对象或数组（用于画廊模式的上一张/下一张导航）。每项为 {src, alt, caption?, type?: 'image' | 'video'}；type 默认为 'image'，'video' 禁用缩放/平移。",
       required: true,
     },
     {
@@ -139,39 +217,76 @@ export const docsZh = {
     {
       name: 'xstyle',
       type: 'StyleXStyles',
-      description: '用于布局自定义的 StyleX 样式。必须是 stylex.create() 的值。',
+      description:
+        '用于布局自定义的 StyleX 样式。必须是 stylex.create() 的值。',
     },
   ],
   theming: {
-    targets: [
-      {className: 'astryx-lightbox', visualProps: []},
-    ],
+    targets: [{className: 'astryx-lightbox', visualProps: []}],
   },
   usage: {
+    anatomy,
     description:
       'A fullscreen overlay for viewing images and videos at full resolution. Supports single-item and gallery modes with prev/next navigation, optional zoom and pan for images, and native video controls.',
     bestPractices: [
-      { guidance: true, description: 'Always provide alt text for every image for screen reader accessibility.' },
-      { guidance: true, description: 'Use gallery mode with onIndexChange for multi-image sets.' },
-      { guidance: true, description: 'Enable hasZoom only when viewing high-resolution images that benefit from close inspection.' },
-      { guidance: false, description: 'Use the lightbox for non-image content; it is specialized for images.' },
-      { guidance: false, description: 'Nest interactive content inside captions; keep them plain text.' },
+      {
+        guidance: true,
+        description:
+          'Always provide alt text for every image for screen reader accessibility.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use gallery mode with onIndexChange for multi-image sets.',
+      },
+      {
+        guidance: true,
+        description:
+          'Enable hasZoom only when viewing high-resolution images that benefit from close inspection.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use the lightbox for non-image content; it is specialized for images.',
+      },
+      {
+        guidance: false,
+        description:
+          'Nest interactive content inside captions; keep them plain text.',
+      },
     ],
   },
 };
 
 /** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
-  description: 'Fullscreen overlay for viewing images and videos at full resolution with gallery navigation and zoom.',
+  description:
+    'Fullscreen overlay for viewing images and videos at full resolution with gallery navigation and zoom.',
   usage: {
+    anatomy,
     description:
       'A fullscreen overlay for viewing images and videos at full resolution. Supports single-item and gallery modes with prev/next navigation, optional zoom and pan for images, and native video controls.',
     bestPractices: [
-      { guidance: true, description: 'Always provide alt text for every image.' },
-      { guidance: true, description: 'Use gallery mode with onIndexChange for multi-image sets.' },
-      { guidance: true, description: 'Enable hasZoom only when viewing high-resolution images that benefit from close inspection.' },
-      { guidance: false, description: 'Use for non-image content; specialized for images.' },
-      { guidance: false, description: 'Nest interactive content inside captions; keep them plain text.' },
+      {guidance: true, description: 'Always provide alt text for every image.'},
+      {
+        guidance: true,
+        description:
+          'Use gallery mode with onIndexChange for multi-image sets.',
+      },
+      {
+        guidance: true,
+        description:
+          'Enable hasZoom only when viewing high-resolution images that benefit from close inspection.',
+      },
+      {
+        guidance: false,
+        description: 'Use for non-image content; specialized for images.',
+      },
+      {
+        guidance: false,
+        description:
+          'Nest interactive content inside captions; keep them plain text.',
+      },
     ],
   },
   propDescriptions: {
@@ -180,7 +295,8 @@ export const docsDense = {
     media: 'Single media object or array for gallery mode.',
     index: 'Current index in gallery mode.',
     onIndexChange: 'Callback when gallery index changes.',
-    hasZoom: 'Enable zoom (double-click, Enter/Space, or +/-) and pan (drag or arrow keys) for images.',
+    hasZoom:
+      'Enable zoom (double-click, Enter/Space, or +/-) and pan (drag or arrow keys) for images.',
     xstyle: 'StyleX styles for layout customization.',
   },
 };