Doc Component

Write documentation for BEEQ components

When to use

• When creating a new MDX page in apps/beeq-docs/components/ for an existing bq-* component.
• When migrating a Zeroheight docs page to Mintlify.
• When refilling missing sections on a partially-written page.
• Before merging a new or migrated MDX page in apps/beeq-docs/components/.
• When normalizing pages for consistency across the docs site.
• When a docs reviewer flags structure or tone issues.

When NOT to use this skill

• When the page already exists and only needs an audit → use review-doc.
• When the component itself is missing or incomplete — finish the component first with create-component and review-component.
• For non-component pages such as foundations, theming, getting started, guides, framework integrations, or migration docs. Follow the shared documentation instructions and use review-doc for review.

Before You Start

1. Read the instructions files for this task, in full before writing a single line:
   • Documentation instructions. It defines the mandatory component page structure, non-component page guidance, component usage patterns, CSS isolation rules, and code tab ordering.
2. Read the component source
   • These files are the ground truth for the API reference. Do not document any prop, event, slot, part, or CSS variable that does not exist in the source:
     • packages/beeq/src/components/<name>/bq-<name>.tsx — @Prop, @Event, @Method, class-level JSDoc (@slot, @part, @cssprop, @attr)
     • packages/beeq/src/components/<name>/bq-<name>.types.ts — prop type unions and constants
     • packages/beeq/src/components/<name>/scss/bq-<name>.variables.scss — all --bq-<name>-* CSS custom properties with their defaults
   • Cross-check against the Custom Elements Manifest output in packages/beeq/cem/ — it is the canonical machine-readable description of every component's public API and should match what you put in the API tables.
   • Do not infer props, events, slots, shadow parts, or CSS custom properties from Zeroheight or old docs. Migrated content is reference material for tone and concepts, not API truth.
   • Also read an existing complete documentation page as a structural reference: apps/beeq-docs/components/icon.mdx or apps/beeq-docs/components/badge.mdx.

Procedure

1. Mandatory page structure (exact order)

Write the page in this section order — do not skip or reorder:

1. Frontmatter (title, description)
2. Imports (at top, after frontmatter; only import what is used)
3. Overview Frame (light + dark SVG pair, using block dark:hidden / hidden dark:block)
4. Introduction paragraph (1–2 sentences: what the component is and its primary purpose)
5. Note (optional — only for a gotcha that affects all uses)
6. When to use (2-column CardGroup with Do / Don't cards using bullet lists)
7. Patterns (optional — common real-world contexts)
8. Anatomy (light + dark anatomy SVG in a Frame, followed by a parts table)
9. Design guidelines (CardTile, Steps, Note as appropriate)
10. Usage (primary variants with CodeLivePreview + CodeGroup)
11. Options (additional configurations with CodeLivePreview + CodeGroup)
12. Best practices (2×2 CardGroup, 4 Do/Don't pairs minimum)
13. Accessibility (built-in behaviors + developer responsibilities)
14. API reference (Properties, Slots, Shadow parts, CSS custom properties)
15. Resources (2-column CardGroup with Storybook + GitHub source links)

2. Key patterns to apply

Image paths

All images follow: /components/images/<name>/<name>-[variant]-[light|dark].svg

Every image appears twice — once with className="block dark:hidden" and once with className="hidden dark:block".

When to use cards

<CardGroup cols={2}>
  <Card>
    <span className="flex items-center mr-2 text-lg font-medium" role="heading">
      <Icon className="mr-2" icon="thumbs-up" iconType="solid" size={20} color="var(--bq-stroke--success)" />
      Use [component] when
    </span>
    - bullet 1
    - bullet 2
  </Card>
  <Card>
    <span className="flex items-center mr-2 text-lg font-medium" role="heading">
      <Icon className="mr-2" icon="thumbs-down" iconType="solid" size={20} color="var(--bq-stroke--danger)" />
      Do not use [component] when
    </span>
    - bullet 1
    - bullet 2
  </Card>
</CardGroup>

CodeLivePreview isolation

Prefer mode="iframe" for new CodeLivePreview examples. Iframe mode gives the example a full document sandbox, so Mintlify layout, CSS, and page scripts cannot influence the preview, and preview scripts cannot disrupt the docs page.

Always pass the mode explicitly:

<CodeLivePreview mode="iframe" height="12rem" code={`...`} />

Use iframe mode whenever an example includes layout behavior, scripts, overlays, popovers, fixed or absolute positioning, responsive containers, page-like composition, or anything that could conflict with the Mintlify documentation shell. Always include an explicit height; use removePadding when preview padding would hide the real layout behavior.

Shadow mode is still allowed for small, component-local examples that will not disrupt the Mintlify page and do not need full document isolation. In shadow mode, CodeLivePreview injects code into a shadow root. beeq.css is loaded automatically, and CSS custom properties (--bq-*) still inherit through the boundary.

In shadow mode, override the host (.preview) layout with :host inside a <style> block. Override properties require !important to beat the CodeLivePreview stylesheet:

<style>
  :host { flex-direction: column !important; gap: var(--bq-spacing-m) !important; }
  .my-wrapper { display: flex; gap: 1rem; }
</style>

Do not use @scope — it was the old light-DOM approach and is no longer needed. Do not use <style scoped> — not a real browser feature.

Every <script> block must use previewRoot to query elements inside the preview. In iframe mode, previewRoot is the iframe document. In shadow mode, previewRoot is the shadow root. document.currentScript is always null for dynamically created scripts. Wrap in an IIFE to prevent variable leakage:

<script>
  (() => {
    const btn = previewRoot.querySelector('bq-button');
    btn?.addEventListener('bqClick', () => { /* ... */ });
  })();
</script>

Do not wrap examples in unnecessary <div>s for alignment purposes. In shadow mode, use :host overrides for preview layout. In iframe mode, use normal document CSS inside the preview.