Skip to main content

​
Doc Type: CoPilot UI Reference

Tier: Reference | Reader phase: Refining & Details
Back to tier overview: reference/index.md

​
What it is

A CoPilot UI Reference document describes a specific page or panel in the Aviatrix CoPilot interface: its purpose, the fields it contains, and the actions that can be performed on it. It covers both the meaning of fields and how to execute individual actions (Create, Edit, Delete, Enable, and similar). One document covers one UI page or logical panel grouping. Documents are organized to mirror the CoPilot navigation structure. These documents answer two questions: What do these fields mean? and How do I execute this action? UI Reference docs are the canonical home for individual actions. Configuration Guides include these steps directly — readers should not have to flip between documents to complete a task. To avoid maintaining duplicate source, action steps can be extracted into snippets that both the UI Reference accordion and the Configuration Guide import.

​
Goal

After reading a CoPilot UI Reference document, the reader understands the purpose and meaning of every field on this page and knows how to execute any action available on it. They can complete a single action or look up a field value without consulting another document.

​
Primary personas

​
When to create a new UI Reference document

Create a new UI Reference document when:
  • A new page or significant panel is added to CoPilot
  • An existing page gains fields or controls significant enough to require documentation
  • A Configuration Guide references a UI panel that has no corresponding reference page
One document per CoPilot page or logical panel group. Do not create a document per individual field.

​
Required sections

Each page follows the same three-section structure — Purpose, Elements, Actions — in that order. For tabbed pages, repeat all three sections inside each <Tab>.
  1. Purpose — 2–4 sentences describing what this page is for, what information it surfaces, and who uses it. The first sentence names the page (or, inside a <Tab>, the tab) in bold, matching the page/tab title exactly, for example: “The Specialty Gateways page lets you view the list of configured Specialty Gateways and their details.” Do not open with a bare pronoun (“This page…”) or an unbolded page name.
  2. Elements — An image of the page followed by a bullet list of every UI element with a brief description. Format: - **Element Name**: Description. Include all visible controls, fields, dropdowns, buttons, and data columns. An image is required. Each element is its own bullet, on its own line, starting with a list marker (- or *) at the start of the line. Never join two or more elements onto one line with an inline - or — separator (for example, **Element A**: description. - **Element B**: description.) — that renders as a single run-on paragraph with no bullets instead of a list. This most often happens when a long list survives a bulk edit (a find/replace pass, an automated style-normalization script, or manual conflict resolution during a merge/rebase) that reflows the text without preserving each line’s leading marker. After any bulk edit that touches an Elements list — and especially after resolving a merge/rebase conflict in one of these files — re-render the page (or check the generated file under docs/enterprise/<version>/...) and visually confirm every element still appears as its own bullet, not merged into the previous one. Immediately before committing a change to any file under snippets/enterprise/pages/reference/ui/, run npx prettier --write (or --check) on that file if it is not listed in .prettierignore. A list that has collapsed into a run-on paragraph will not be “fixed” by Prettier — Prettier reformats lists, it does not reconstruct one from mangled prose — so this check only catches the corruption, it does not repair it. Reconstruct the bullets by hand (one element per line, matching what the live UI actually shows) whenever this pattern is found.
  3. Actions — An <AccordionGroup> containing one <Accordion> per action. Order the accordions View, Create, Edit, Delete, followed by any other actions (Enable, Disable, and similar) in the order their controls appear in Elements. Each accordion opens with a one-line intro sentence stating the goal of the action (for example, “To create a gateway:”), followed by numbered steps to execute the action, followed by a Parameter Details table (CoPilot Parameter Name | Description) covering the parameters involved. Actions are self-contained — the reader should not need another document to complete them. Configuration Guides reference individual actions here as steps in a larger workflow. A Parameter Details table must always be nested inside the <Accordion> for the one action that opens the dialog/form it describes. Never place a ### Parameter Details heading as its own standalone section between Elements and Actions — that duplicates (and drifts from) the Elements bullets describing the same fields, and the table has no action for the reader to complete. If a table of fields belongs to the page itself rather than a specific action’s dialog (for example, columns of a data table shown on load), describe those fields in Elements as bullets instead — do not give them a ### Parameter Details heading outside an accordion. scripts/lint_docs.py enforces this as a hard CI error. For the “other actions” that follow View, Create, Edit, Delete, order them in the same top-to-bottom (and left-to-right, for side-by-side cards or panels) sequence the corresponding elements appear on the live UI — the same order used in Elements. Do not order those remaining accordions arbitrarily or by any scheme that diverges from the page layout; a reader scanning the page should be able to find the matching accordion at the same relative position among the non-CRUD actions. Whether to group top-level accordions under category-header <Accordion>s depends on the count of top-level accordions in that Actions section (or that single <Tab>’s Actions section):
    • Fewer than 5 — leave them as one flat list. Do not group.
    • 5–7 — group them only if there is a clear, natural way to split them into distinct groups (for example, the accordions already fall into obvious clusters by feature/card, matching a grouping already visible in Elements). If no such natural split exists, leave the list flat rather than forcing an artificial grouping.
    • More than 7 — always group them under category-header <Accordion>s instead of leaving one long flat list.
    This cap is a hard limit on every accordion container, not just the top level: no single <AccordionGroup> and no single group <Accordion> may directly contain more than 7 child accordions. If grouping a long flat list still leaves one group with more than 7 actions, split that group further into two or more sibling groups (each named for its own sub-cluster of actions) rather than exceeding 7 in any one container. This keeps nesting at two levels either way — it adds more sibling groups, not a third level of nesting. Name each group accordion after the feature/card it configures (for example, Configure Transit Gateway, Manage Gateway Attachments, Actions on Transit Gateway, Configure Global BGP Communities Support), matching the grouping already used in Elements. A single action that has no natural sibling can stay top-level and ungrouped rather than being forced into an artificial group of one. See the Transit Gateways, Spoke Gateways, and Settings tabs in snippets/enterprise/pages/reference/ui/cloud-fabric/gateways-v101.mdx for the canonical pattern. Nest no more than two levels deep: <AccordionGroup> → group <Accordion> → action <Accordion>. Never add a third level — no group nested inside another group, and no <Accordion> nested inside an action <Accordion>. For example, never do this:
    Attachments here is a second group level nested inside Configure Gateway — flatten it instead: either fold Attach a Gateway (and its siblings) directly into Configure Gateway, or promote Attachments to its own top-level group accordion, whichever better matches the page layout. Indentation must match nesting depth, and every sibling accordion must be indented identically. MDX does not require this to render correctly, so drift will not fail the build — but it makes the file unreadable and hard to diff, and it is the most common way a stray third nesting level or an orphaned/duplicated </Accordion> gets introduced unnoticed (usually while copy-pasting an existing accordion to create a new sibling, or while wrapping a run of existing accordions in a new group accordion). Before committing any change to an Actions section:
    • A tag’s own opening and closing lines (<Accordion title="..."> … </Accordion>) must use the same leading whitespace.
    • Every sibling accordion at the same level — inside the same <AccordionGroup> or the same group <Accordion> — must use the same leading whitespace as the sibling immediately before and after it. Do not indent one sibling deeper “for clarity,” and do not leave one shallower after a copy-paste.
    • When you wrap an existing run of top-level accordions in a new group <Accordion> (per the grouping rule above), re-indent that entire run to its new depth — do not leave the group’s <Accordion>/</Accordion> at the old depth while its children stay unindented, and do not add indentation for indentation’s sake if the file’s existing convention keeps nested accordions flush with their parent (check neighboring tabs in the same file for the established convention before choosing one).
    • After the edit, verify tag balance and matching indentation by re-reading the diff: every - (removed) opening/closing tag should pair with exactly one + (added) tag at the same nesting position, and no </Accordion> should appear without a corresponding open at the same depth.

​
Optional sections

  • Related Tasks — Links to Configuration Guides for the most common tasks performed on this page
  • Permissions — When specific CoPilot roles or permissions are required to view or interact with this page
  • Notes and Limitations — Known UI behaviors, data refresh rates, or display limitations worth documenting

​
Tone & voice

Two modes — descriptive for elements, instructional for actions. Elements: write descriptions as short noun phrases or sentences. “Dropdown to select time period.” State what it does; no need to explain why. Keep it brief. Actions: use imperative mood (“Go to…”, “Click…”, “Set…”) for steps within each accordion. Keep each action self-contained and minimal — only the steps to execute that one action. Do not explain why the action exists or when to use it; that belongs in a Configuration Guide or Component doc.

​
Length guidance

50–200 lines per page. Simple configuration pages run 50–80 lines. Complex dashboard pages or heavily tabbed pages run 150–200 lines. If a page’s documentation exceeds 200 lines, consider whether it should be split by tab or panel into multiple documents.

​
Frontmatter

See Frontmatter Standards for field definitions and formatting rules. The title must match the CoPilot page name exactly as it appears in the navigation.

​
Format examples

Purpose section:
Elements section:
Wrong — do not do this. Elements merged onto shared lines with an inline dash instead of one bullet per element:
This renders as a single paragraph with no bullets at all. If an Elements list looks like this (or you notice list items are missing their leading -/* after a bulk edit or merge), rebuild it as one bullet per element, matching the wrapping style shown in the correct example above. Actions section:
Accordion order in this example — View, then Create — illustrates the required View, Create, Edit, Delete ordering; add Edit and Delete accordions the same way when the page supports them. Grouping many actions: When a tab’s Actions section has more than 7 top-level accordions (or 5–7 with a clear natural split), group the related ones under a category-header <Accordion> instead of one flat list:
Configure Gateway and Manage Gateway Attachments are category-header accordions, each wrapping its own set of action accordions. Enable or Disable Rollback on Gateway Creation Error has no sibling action, so it stays top-level and ungrouped.

​
Mintlify components

See Style Guide for component definitions and usage rules. Use <Tabs> for tabbed UI pages (mirror the UI structure), <Accordion> for individual actions in the Actions section, <Frame> for annotated screenshots, and <Note> for unexpected UI behaviors. <Steps> may be used within an action accordion if the action involves more than three sequential steps; otherwise use a numbered list.

​
Linking

  • Link in from: Configuration Guides that use this page, Component docs for the feature this page manages
  • Link out to: No fixed outbound relationship

​
Dos and don’ts