--- name: review-doc description: 'Audit a BEEQ Mintlify MDX documentation page against the documentation guidelines — component docs, non-component docs, CodeLivePreview behavior, code tab rules, source accuracy, tone, and accessibility guidance. Also supports temporary Zeroheight-to-Mintlify migration audits when explicitly requested or confirmed.' argument-hint: 'Component name (e.g. "card") or path to an .mdx file in apps/beeq-docs/' metadata: internal: true --- # Review a BEEQ Documentation Page ## When to Use - Before merging a new or migrated MDX page in [apps/beeq-docs/components/](../../../apps/beeq-docs/components/) - Before merging a non-component MDX page in [apps/beeq-docs/](../../../apps/beeq-docs/) such as foundations, theming, setup, framework integrations, or usage guides - When normalizing pages for consistency across the docs site - When a docs reviewer flags structure or tone issues - When migrating a page from Zeroheight to Mintlify and you want to verify the result _(see Step 0)_ ## When NOT to Use - For component code review → use [review-component](../review-component/SKILL.md) - For generating a brand-new page from scratch → use [doc-component](../doc-component/SKILL.md) --- ## Step 0 — Temporary Zeroheight migration check (optional) This is a temporary migration-only check. Use it only when the user explicitly mentions a Zeroheight migration or when the current task context references Zeroheight. Do not run this check for ordinary docs reviews after the migration work is complete. If either condition is met, ask for confirmation before proceeding: > "This looks like a migrated Zeroheight page. Do you want me to cross-check against the original Zeroheight source as part of this review?" If the user confirms, use the `mcp_beeq_zeroheig` tools to fetch the original page content before starting Step 3: ``` mcp_beeq_zeroheig_list-pages → find the page by component name mcp_beeq_zeroheig_get-page → fetch the original content mcp_beeq_zeroheig_get-page-images → fetch image references ``` Use the Zeroheight content to: - Cross-check that all **When to use**, **Anatomy**, **Design guidelines**, and **Best practices** content has been migrated — not silently dropped - Verify that image descriptions and anatomy part labels are preserved - Flag any content present in Zeroheight that has no equivalent in the new MDX page - Flag stale values or wording that conflict with current source Add a **Zeroheight Migration** section to the report (see Step 4) if this step is executed. --- ## 1. Load the authoritative rules Read [.github/instructions/documentation.instructions.md](../../../.github/instructions/documentation.instructions.md) in full before starting any checks. Every checklist item below maps to a rule in that file. --- ## 2. Locate and read the files Resolve the target file: - If `$ARGUMENTS` is a component name → `apps/beeq-docs/components/$ARGUMENTS.mdx` - If `$ARGUMENTS` is a file path → read it directly Read the full MDX file before running any checks. If the target is a component page in `apps/beeq-docs/components/`, read the component source to verify API table accuracy: - `packages/beeq/src/components/$ARGUMENTS/bq-$ARGUMENTS.tsx` — `@Prop`, `@Event`, `@slot`, `@part`, `@cssprop` - `packages/beeq/src/components/$ARGUMENTS/scss/bq-$ARGUMENTS.variables.scss` — CSS custom properties and defaults - `packages/beeq/cem/` — Custom Elements Manifest as canonical API reference If the target is a non-component page, read the source files that define the documented behavior, values, or utilities. Examples include Tailwind theme files, reset styles, global CSS variables, integration setup files, or snippets used by the page. Current repo source is canonical over older docs. --- ## 3. Audit checklist ### A. Page structure and section order — component pages - [ ] Frontmatter present with `title` and `description` - [ ] All imports immediately after frontmatter, using absolute paths (e.g. `/snippets/…`); no unused imports - [ ] Overview `Frame` with light + dark image pair is the first content after imports - [ ] Introduction paragraph (1–2 sentences, no `##` heading) immediately follows the overview frame - [ ] Optional `Note` present only when there is a gotcha that affects **all** uses - [ ] **When to use** section present as a 2-column `CardGroup` - [ ] Optional **Patterns** section present only when real-world contexts genuinely add value - [ ] **Anatomy** section present with `Frame` + parts table (Part / Element / Description columns) - [ ] **Design guidelines** section present using `CardTile`, `Steps`, or `Note` as appropriate - [ ] **Usage** section present with at least one `CodeLivePreview` + `CodeGroup` - [ ] **Options** section present for additional configurations - [ ] **Best practices** section present as a 2×2 `CardGroup` (minimum 4 Do/Don't pairs = 8 cards) - [ ] **Accessibility** section present - [ ] **API reference** section present with all four subsections - [ ] **Resources** section is the **last** section with Storybook + GitHub source links ### A2. Page structure and flow — non-component pages - [ ] Frontmatter present with `title` and `description` - [ ] Imports immediately after frontmatter, using absolute paths; no unused imports - [ ] Introduction clearly states what the page helps the reader understand or do - [ ] Page explains what BEEQ provides, recommends, or deliberately leaves to the consuming app - [ ] Core concepts are source-backed and written in a practical order - [ ] Values, utilities, classes, tokens, or setup steps match current source - [ ] Practical examples match the rendered `CodeLivePreview` - [ ] Usage guidelines are concise and scannable, using `AccordionGroup`, `CardTile`, or prose where appropriate - [ ] Accessibility, constraints, or implementation gotchas are included when relevant - [ ] Resources section appears last and links to relevant docs or source files - [ ] No visible `Keywords` section remains in migrated content ### B. Images - [ ] Component image paths follow `/components/images/[component]/[component]-[variant]-[light|dark].svg` - [ ] Every image appears **twice**: `className="block dark:hidden"` (light) and `className="hidden dark:block"` (dark) - [ ] Overview `Frame` uses the `-overview-` variant; anatomy `Frame` uses the `-anatomy-` variant - [ ] No overview image re-used in the anatomy section - [ ] Non-component images are present only when they support a clear visualization; intentionally deferred placeholder assets are called out but not treated as content failures ### C. When to use section - [ ] 2-column `CardGroup` with exactly one Do card and one Don't card - [ ] Do card: `thumbs-up` icon, `color="var(--bq-stroke--success)"` - [ ] Don't card: `thumbs-down` icon, `color="var(--bq-stroke--danger)"` - [ ] Both cards use bullet lists, not prose paragraphs ### D. CodeLivePreview isolation - [ ] Every `CodeLivePreview` passes `mode` explicitly - [ ] New examples prefer `mode="iframe"` for full isolation from Mintlify CSS, scripts, and layout - [ ] Every iframe preview includes an explicit `height` - [ ] Iframe examples use `removePadding` when default preview padding would hide the real layout behavior - [ ] Shadow mode is used only for small, component-local examples that will not disrupt or be affected by the Mintlify page - [ ] Iframe examples use normal document CSS selectors inside the preview, not `:host` for preview layout - [ ] Shadow-mode examples use `:host { ... }` to override the shadow host layout — **not** `@scope` - [ ] Shadow-mode `:host` overrides use `!important` for properties that the `CodeLivePreview` stylesheet already defines (e.g., `flex-direction`, `justify-content`, `gap`, `padding`) - [ ] Descendant selectors (`.my-class`, `bq-button`, etc.) are plain selectors at the top level of `