Skip to main content

​
Wireframe Variables — Documentation Template

This is the authoring guide for per-feature wireframe variable pages in the public docs. Every feature in sdk/docs/wireframe-variables/ should eventually have a matching MDX page in ui-customization/features/.... Use this template verbatim — consistency across features is the point.
Scope reminder. “Wireframe variables” here means the dynamic template tokens (e.g. {user.name}, {annotation.status}) that are read by velt-data / velt-if / velt-class inside a <velt-wireframe>. They are not CSS variables. CSS variables are documented separately under ui-customization/styling.mdx and feature-level variables.mdx pages.

​
1. When to use this template

  • Trigger: a feature has a source reference at sdk/docs/wireframe-variables/<feature>.md but no public-docs counterpart.
  • Output: one new MDX page per source file, placed inside the existing feature folder alongside the existing wireframes and primitives files.
  • Title (in frontmatter): always <Feature Name> Wireframe Variables, where <Feature Name> matches the feature’s group label in docs.json (e.g. Activity Logs, Comment Dialog, Notifications Panel).

​
Filename convention — match the siblings

Filenames in the docs repo are inconsistent across feature folders. Match the convention used by the sibling wireframes / primitives files in the same folder.
Sibling files look like…Use this filename
wireframes.mdx, primitives.mdx (bare)wireframe-variables.mdx
<feature>-wireframes.mdx, <feature>-primitives.mdx (prefixed)<feature>-wireframe-variables.mdx
Examples:

​
Source → docs map

Public docs page (to author)Source file
ui-customization/.../activity-logs/activity-logs-wireframe-variables.mdxsdk/docs/wireframe-variables/activity-log.md
ui-customization/.../comment-dialog/wireframe-variables.mdxsdk/docs/wireframe-variables/comment-dialog.md
ui-customization/.../comment-sidebar/wireframe-variables.mdxsdk/docs/wireframe-variables/sidebar.md
ui-customization/.../notifications/panel/wireframe-variables.mdxsdk/docs/wireframe-variables/notifications-panel.md
…one per file in sdk/docs/wireframe-variables/(25 source files total)

​
2. Mapped vs flat-config — pick one mode

The source README.md defines two access patterns. Pick the one that matches the feature and follow only that branch of the skeleton below.
PatternFeaturesVariable form in tables
MappedComment Dialog, Comments Sidebar, Comment Bubble, Inline Comments Section, Multi-Thread Comment Dialog, Text Comment, Notifications Panel, Notifications Tool, Activity LogBare names, e.g. user, annotation, darkMode
Flat-configCursor, Presence, Huddle, Recording, Transcription, View Analytics, Area, Arrow, Tag, Reactions, Selection, Rewriter, Comments Tool, Sidebar Button, AutocompleteExplicit prefix, e.g. componentConfig.user, componentConfig.cursorUsers
  • Mapped features → keep the four state buckets (App State / Data State / UI State / Feature State). Drop any bucket the source has nothing for. If the source MD has a separate “Per-instance Local UI State” bucket, fold it into UI State — do not add a fifth bucket.
  • Flat-config features → replace the four buckets with a single ## Component Config section, and keep the “flat-config” <Note> callout in the skeleton.

​
3. Page sections — required order

Every page follows this exact order. Sections in (optional) are included only when the source MD has the corresponding content.
  1. Frontmatter
  2. Intro <Note> linking to overview + template variables
  3. ## Overview (3-form usage table + mapped/flat-config note)
  4. ## App State / ## Data State / ## UI State / ## Feature State (mapped) or ## Component Config (flat-config)
  5. ## Common Props (optional — include only if the feature documents shared attributes / signal inputs)
  6. ## Context-Specific Variables (optional — only when the source has it; include the alias <Note> directly under the table when the source mentions aliases)
  7. ## Type Reference (optional — slim summary table linking out to data-models; include when the page references 2+ compound types)
  8. ## Subcomponents (optional — one ### <subcomponent> per item that has at least one of: extra variables, a shouldShow condition, a host class, or a meaningful example)
  9. ## Deeply-Nested Wireframe Tags (optional — flattens the long tail of leaf tags the source documents at the bottom)
  10. ## Putting it together (always — exactly one realistic combined example, in <Tabs>)
  11. ## Related (always — links to siblings + template-variables overview)

​
4. Page skeleton (copy-paste scaffold)

Replace every <Feature Name>, every example variable, and the <!-- comments --> with real content from the source file. Delete sections that don’t apply.

​
5. Authoring rules

​
A. Frontmatter

FieldRule
titleExactly <Feature Name> Wireframe Variables. <Feature Name> matches the group label in docs.json.
descriptionOne sentence. Must mention velt-data, velt-if, velt-class so the page indexes well for in-site search.

​
B. Variable tables — table-shape depends on context

There are two table shapes used on the page. Match the right one to the context: Top-level state buckets (App State / Data State / UI State / Feature State / Component Config) and Context-Specific Variables — 4 columns:
VariableTypeDescriptionExample
(Context-Specific uses Available in instead of Description.) Subcomponent extra-variable tables — 3 columns (no Description):
VariableTypeExample
The Description column is dropped at the subcomponent level because the rows are typically nested-access shorthands (record.user, record.user.userId) where the example tells you everything you need.

​
C. Column rules (apply to both table shapes)

ColumnRule
VariableBackticks around the name. Mapped features use bare names (user). Flat-config features use the full path (componentConfig.user). Nested-access rows in subcomponent tables use dot paths (record.user.userId).
TypeBackticks. If compound (User, CommentAnnotation, Comment, Notification, ActivityRecord, etc.), make the type name a markdown link to /api-reference/sdk/models/data-models#<lowercased-type-name>. Union types: write outside the backticks and escape with | if inside a table cell, e.g. [`Comment`](...) | `null`. Array types: append [] outside the backticks, e.g. [`User`](...)`[]`.
Description (only on 4-col)One sentence. Start with the noun or verb — no leading “The …” / “A …”. Use the source’s “Notes” column when present; otherwise summarize the source’s sample-value comment.
ExampleOne usage form, chosen by type:
• booleans → velt-if / velt-class
• primitives & nested-access roots → velt-data
• arrays → velt-data with index
Use the HTML self-closing form (<velt-data field="…" />) inline. The React/Other Frameworks tabs are reserved for the <Tabs> blocks.

​
D. Subcomponent Property/Value tables

For each subcomponent, put metadata in a 2-column Property | Value table. Standard properties (omit any row that doesn’t apply):
Property rowUse whenExample value
Extra variablesAlways include this row.None — root only sees common variables. or None. or None beyond common variables.
shouldShowSource documents a shouldShow condition for the subcomponent.`isEnabled === true && isOpen === true`
Host classSource documents a CSS class always applied to the host element.`velt-activity-log--container` (always present)
If the subcomponent has extra variables, place the 3-col Variable | Type | Example table above the Property/Value table.

​
E. Type Reference section

Keep it slim. Do NOT inline full type field tables — that duplicates content from data-models.mdx. The section is just a quick lookup table:
The Description column is one short sentence — typically the type’s purpose plus its 3–5 most-used fields in parentheses. Include the section only when the page references 2 or more compound types.

​
F. Sample values — use Accordion sparingly

The source MD files include large JSON sample values per variable. Do not paste these into the variable tables. If a sample is genuinely useful (typically only for compound objects whose shape isn’t obvious from the linked data-models page), put it in a collapsible <Accordion> immediately after the relevant table:
Default is omit. The linked data-models page is the source of truth for shape.

​
G. Code examples — drop wrapper elements

Top-level rule: prefer attaching velt-if / velt-class directly to a real element rather than wrapping it in a structural container. Don’t use these wrappers in either tab:
Do put velt-if directly on the element it controls:
If the conditional truly wraps multiple elements, use a real DOM element (<div>, <span>, <section>) with velt-if as an attribute.

​
H. “Putting it together” example

  • Always exactly one realistic wireframe combining 2–4 variables — enough to show real-world usage, not a kitchen sink.
  • Always wrapped in <Tabs> with two tabs titled exactly "React / Next.js" and "Other Frameworks" (matches sibling pages).
  • React tab uses the dot-notation wireframe component (e.g. <VeltCommentDialogWireframe.ResolveButton>) wrapping HTML that still uses velt-if / velt-data attributes — the tokens themselves are framework-agnostic.
  • Other Frameworks tab uses the kebab-case web component (e.g. <velt-comment-dialog-resolve-button-wireframe>).
  • Position: place this section after Subcomponents and Deeply-Nested Wireframe Tags, before Related. It’s the closing example.
End every page with a ## Related section linking to:
  1. The sibling wireframes page — relative path matching the actual filename in this folder (./wireframes or ./<feature>-wireframes).
  2. The sibling primitives page — relative path matching the actual filename (./primitives or ./<feature>-primitives).
  3. /ui-customization/template-variables (absolute path).
This closes the loop between the three pages of every feature group.

​
J. Navigation registration (docs.json)

After authoring the page, register it in navigation:
  1. Open docs.json.
  2. Find the group matching the feature name (e.g. "group": "Activity Logs") under the UI Customization navigation tab.
  3. Add the new page path to its pages array, between the existing wireframes and primitives entries:
The same group label appears in multiple places in docs.json (Async Collaboration features, REST API, UI Customization). Make sure you edit the UI Customization entry, not the others.

​
K. Forbidden terminology — never use these words

The public docs are framework-neutral. The source MD files come from an Angular-heavy SDK codebase and use vocabulary that leaks framework details — strip it. Do not use any of these words anywhere on the page:
Don’t writeWhyUse instead
AngularFramework-specific name.”parent-child component composition”, or omit the framework reference entirely.
<ng-container>Angular structural-directive container.Drop the wrapper; put velt-if directly on the conditional element (see §G).
slot / sub-slotConflates with Web Components <slot> semantics; not what we mean here.”tag” (for the markup-level meaning of <velt-...-wireframe>) or “sub-component” (for the conceptual subdivision). Use “values” if “slot” was being used in the sense of “field/property”.
If a source MD file uses any of these words, translate them as part of authoring.

​
6. Anti-patterns — explicitly do NOT do these

  • ❌ Do not rename the four state buckets, even if the source mixes them. Keep App State, Data State, UI State, Feature State exactly as-is. Fold any “Per-instance Local UI State” rows into UI State — do not add a fifth bucket.
  • ❌ Do not inline full type field tables in the Type Reference section. Link out to data-models.mdx; only summarize.
  • ❌ Do not restate template-variable mechanics (operators, path resolution, safeEval, nested-access rules). Link to template-variables.mdx instead — DRY.
  • ❌ Do not add a CSS variables section. That’s covered by styling.mdx and feature-level variables.mdx (CSS-only) pages.
  • ❌ Do not paste large JSON sample values directly into variable tables. Use an <Accordion> only when the shape isn’t obvious from the linked type.
  • ❌ Do not invent variable names. If a name isn’t in the source MD file, it’s not supported — leave it out.
  • ❌ Do not use forbidden terminology (§K): no Angular, no <ng-container>, no slot/sub-slot.
  • ❌ Do not wrap a single <velt-data> in a <velt-if> or other structural container. Put velt-if directly on the element (§G).

​
7. Authoring checklist

Before merging a new wireframe-variables page, confirm:
  • Filename matches the sibling-files convention in the same folder (bare vs prefixed).
  • Frontmatter title matches the feature’s group label in docs.json.
  • Mapped vs flat-config decision matches the table in §2.
  • Top-level state buckets use the 4-col table (Variable | Type | Description | Example).
  • Subcomponent extra-variable tables use the 3-col table (Variable | Type | Example).
  • Subcomponent metadata uses the 2-col Property/Value table with the standard rows.
  • All compound types in the Type column link to the correct data-models anchor.
  • Type Reference section (if present) links out and does not inline field tables.
  • Each row’s Example uses the right form for its type (velt-data / velt-if / velt-class).
  • Code examples never use <ng-container> or <velt-if> as a single-element wrapper.
  • No forbidden terminology: search the page for angular, ng-container, slot (case-insensitive) — must return zero hits in prose, headings, and code.
  • Exactly one ## Putting it together block exists, wrapped in <Tabs> with both framework variants, positioned after Subcomponents and Deeply-Nested Wireframe Tags.
  • ## Related links resolve (relative paths match the sibling filenames; absolute /ui-customization/template-variables).
  • No ## Component Config section coexists with the four state buckets — pick one.
  • No CSS variables on this page.
  • docs.json updated under the UI Customization group (not API Reference or Async Collaboration), between the feature’s wireframes and primitives entries.