Review Doc

Review a BEEQ Documentation Page

When to Use

• Before merging a new or migrated MDX page in apps/beeq-docs/components/
• Before merging a non-component MDX page in 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
• For generating a brand-new page from scratch → use doc-component

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 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 <style> — no wrapper at-rule needed
• No @scope { :scope {} } — this is the old light-DOM approach; flag any remaining instances as errors
• No @scope (.class-name) — same reason
• No <style scoped> — not a real browser feature
• @media and @supports used normally inside <style> (no nesting restriction)
• Every <script> inside a code prop wrapped in an IIFE: (() => { ... })()
• Scripts use previewRoot to query elements, not document.currentScript
• Scripts avoid document.querySelector in shadow mode because it cannot cross the shadow boundary; iframe mode may use document only when the script intentionally targets the isolated iframe document
• No unnecessary wrapper <div> added only for alignment — use the preview mode's layout tools instead
• When a wrapper <div> is genuinely needed, it has a BEM-style class name and is styled via a plain selector inside <style>