Examples
Examples are stateless HTML templates demonstrating UI patterns for the Elements design system. Well defined examples are critical for providing a portable documentation format for the CLI, MCP and documentation site. This document provides guidance on creating well-written example templates. (*.examples.ts).
Core Principles
Example Title
The example title name should be no more than three words. This name references the function and renders in API/Documentation endpoints.
- Use PascalCase for all example names (for example,
Default, StatusFlat, FormSubmit) - Names should describe what the example shows, not how it works; explain how in the summary.
Single-Word Names
Use single words for basic API features and properties:
| Pattern | Examples |
| Default/basic usage | Default |
| API properties | Status, Size, Color, Position, Alignment |
| Container variants | Flat, Inline |
| States | Pressed, Selected, Disabled |
| Slots/content | Content, Actions |
| Features | Closable, Events, Overflow |
Compound Names (2-3 words)
Use compound PascalCase for combinations or specific features and patterns:
| Pattern | Examples |
| Property + variant | StatusFlat, StatusIcon, SelectedFlat |
| Feature + modifier | OpenDelay, DynamicTrigger, ScrollContent |
| Concept + variant | GroupStatus, FormSubmit, FormControl |
| Layout variants | VerticalTabs, BorderlessTabs |
Special Prefixes
| Prefix | Usage | Examples |
Legacy | Deprecated patterns | LegacyTrigger, LegacyBehaviorTrigger |
Invalid | Anti-patterns | InvalidLinkButton |
Valid | Correct patterns (when contrasting with invalid) | ValidLinkButton |
What to Avoid
- ❌ Component names in titles: Use
Status not BadgeStatus - ❌ Implementation details: Use
ScrollContent not OverflowAutoScrollContent - ❌ Vague names: Use
DynamicTrigger not Example1 - ❌ Overly long names: Keep to 3 words max
Examples
// ✅ Good: Clear, semantic names
export const Default = { /* ... */ };
export const Status = { /* ... */ };
export const StatusFlat = { /* ... */ };
export const FormSubmit = { /* ... */ };
// ❌ Bad: Component name in title
export const BadgeDefault = { /* ... */ };
export const BadgeStatus = { /* ... */ };
// ❌ Bad: Too verbose or unclear
export const Example1 = { /* ... */ };
export const TestCase = { /* ... */ };
export const DefaultBadgeWithStatusColors = { /* ... */ };
// ✅ Good: Clear, semantic names
export const Default = { /* ... */ };
export const Status = { /* ... */ };
export const StatusFlat = { /* ... */ };
export const FormSubmit = { /* ... */ };
// ❌ Bad: Component name in title
export const BadgeDefault = { /* ... */ };
export const BadgeStatus = { /* ... */ };
// ❌ Bad: Too verbose or unclear
export const Example1 = { /* ... */ };
export const TestCase = { /* ... */ };
export const DefaultBadgeWithStatusColors = { /* ... */ };
When the build produces examples for API consumption, it automatically attaches extra metadata such as the associated element/component reference and a UUID to ensure each example has a unique identifier across all projects.
Every example must include a @summary JSDoc comment that explains:
- Descriptions must be concise one or two sentences only.
- What the example demonstrates
- Why this pattern is useful
- When to use this approach
- How it improves the user experience
When appropriate use NVIDIA or NVIDIA Autonomous Vehicle program for UX use cases
/**
* @summary Basic badge component with default styling. Use for simple non-interactive labels or status indicators.
*/
export const Default = {
render: () => html`<nve-badge>badge</nve-badge>`
};
/**
* @summary Basic badge component with default styling. Use for simple non-interactive labels or status indicators.
*/
export const Default = {
render: () => html`<nve-badge>badge</nve-badge>`
};
Limit summaries to a max of 400 characters. This restriction ensures the documentation stays portable across all platforms including docs, CLI and MCPs.
Stateless Examples by Default
Examples should be stateless when possible, focusing on demonstrating the component's capabilities rather than complex interactions:
export const Status = {
render: () => html`
<div nve-layout="row gap:xs">
<nve-badge status="scheduled">scheduled</nve-badge>
<nve-badge status="queued">queued</nve-badge>
<nve-badge status="pending">pending</nve-badge>
</div>
`
};
export const Status = {
render: () => html`
<div nve-layout="row gap:xs">
<nve-badge status="scheduled">scheduled</nve-badge>
<nve-badge status="queued">queued</nve-badge>
<nve-badge status="pending">pending</nve-badge>
</div>
`
};
Use Plain HTML/CSS/JS
Examples should use standard web technologies without unnecessary abstractions:
// ✅ Good: Plain HTML with inline styles when needed
export const Overflow = {
render: () => html`
<nve-badge status="pending" style="--width: 150px">
some really long content
</nve-badge>
`
};
// ✅ Good: Simple script tags for interactive examples
export const ScrollPosition = {
render: () => html`
<nve-grid id="scroll-position-grid" style="height: 402px">
<!-- grid content -->
</nve-grid>
<script type="module">
const grid = document.querySelector('#scroll-position-grid');
const button = document.querySelector('#scroll-top-button');
button.addEventListener('click', () => {
grid.scrollTo({ top: 0, behavior: 'smooth' });
});
</script>
`
};
// ✅ Good: Plain HTML with inline styles when needed
export const Overflow = {
render: () => html`
<nve-badge status="pending" style="--width: 150px">
some really long content
</nve-badge>
`
};
// ✅ Good: Simple script tags for interactive examples
export const ScrollPosition = {
render: () => html`
<nve-grid id="scroll-position-grid" style="height: 402px">
<!-- grid content -->
</nve-grid>
<script type="module">
const grid = document.querySelector('#scroll-position-grid');
const button = document.querySelector('#scroll-top-button');
button.addEventListener('click', () => {
grid.scrollTo({ top: 0, behavior: 'smooth' });
});
</script>
`
};
Example Structure Patterns
Basic Component Examples
/**
* @summary [Brief description of what this demonstrates and when to use it]
*/
export const ExampleName = {
render: () => html`
<!-- Simple, focused HTML demonstrating the pattern -->
`
};
/**
* @summary [Brief description of what this demonstrates and when to use it]
*/
export const ExampleName = {
render: () => html`
<!-- Simple, focused HTML demonstrating the pattern -->
`
};
Status/Variant Examples
/**
* @summary Status badges with predefined colors for different states.
* Ideal for showing job status, task progress, or system states.
*/
export const Status = {
render: () => html`
<div nve-layout="row gap:xs align:wrap">
<nve-badge status="scheduled">scheduled</nve-badge>
<nve-badge status="queued">queued</nve-badge>
<nve-badge status="pending">pending</nve-badge>
</div>
`
};
/**
* @summary Status badges with predefined colors for different states.
* Ideal for showing job status, task progress, or system states.
*/
export const Status = {
render: () => html`
<div nve-layout="row gap:xs align:wrap">
<nve-badge status="scheduled">scheduled</nve-badge>
<nve-badge status="queued">queued</nve-badge>
<nve-badge status="pending">pending</nve-badge>
</div>
`
};
Interactive Examples (When Necessary)
/**
* @summary [Description of the interactive behavior and when it's useful]
*/
export const InteractiveExample = {
render: () => html`
<!-- HTML structure -->
<script type="module">
// Simple, focused JavaScript for the interaction
const element = document.querySelector('#example-element');
element.addEventListener('click', () => {
// Minimal interaction logic
});
</script>
`
};
/**
* @summary [Description of the interactive behavior and when it's useful]
*/
export const InteractiveExample = {
render: () => html`
<!-- HTML structure -->
<script type="module">
// Simple, focused JavaScript for the interaction
const element = document.querySelector('#example-element');
element.addEventListener('click', () => {
// Minimal interaction logic
});
</script>
`
};
Complex Component Examples (Grid, Tables, etc.)
/**
* @summary [Summary of the pattern,
* including accessibility considerations and use cases]
*/
export const ComplexPattern = {
render: () => html`
<nve-grid>
<nve-grid-header>
${Array(5).fill('').map((_, i) => html`
<nve-grid-column>column ${i}</nve-grid-column>
`)}
</nve-grid-header>
${Array(10).fill('').map((_, r) => html`
<nve-grid-row>
${Array(5).fill('').map((_, c) => html`
<nve-grid-cell>cell ${r}-${c}</nve-grid-cell>
`)}
</nve-grid-row>
`)}
</nve-grid>
`
};
/**
* @summary [Summary of the pattern,
* including accessibility considerations and use cases]
*/
export const ComplexPattern = {
render: () => html`
<nve-grid>
<nve-grid-header>
${Array(5).fill('').map((_, i) => html`
<nve-grid-column>column ${i}</nve-grid-column>
`)}
</nve-grid-header>
${Array(10).fill('').map((_, r) => html`
<nve-grid-row>
${Array(5).fill('').map((_, c) => html`
<nve-grid-cell>cell ${r}-${c}</nve-grid-cell>
`)}
</nve-grid-row>
`)}
</nve-grid>
`
};
Summary Writing Guidelines
Good Summaries
- Specific and actionable: "Use for simple non-interactive labels or status indicators"
- Context-aware: "Ideal for showing job status, task progress, or system states"
- UX-focused: "Perfect for dense layouts or when you want less visual weight"
- Accessibility-conscious: "using aria-label for accessibility"
Summary Structure
- Opening: What the example demonstrates
- Context: When/why to use this pattern
- Benefits: How it improves UX or solves problems
- Technical notes: Any important implementation details
Examples of Well-Written Summaries
/**
* @summary Badges with predefined status colors for different states.
* Ideal for showing job status, task progress, or system states.
*/
/**
* @summary Flat container badges with status colors for a more subtle appearance. Ideal for dense layouts or when you want less visual weight.
*/
/**
* @summary The datagrid follows the [ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/patterns/grid/examples/data-grids/#kbd_label)
* for standardized keyboard navigation.
*/
/**
* @summary Multi Select rows use a checkbox as the first focusable item within the row. When selected set the `selected` attribute/property on the row. This will ensure selected styles as well as the proper `ariaSelected` state for accessibility.
*/
/**
* @summary Badges with predefined status colors for different states.
* Ideal for showing job status, task progress, or system states.
*/
/**
* @summary Flat container badges with status colors for a more subtle appearance. Ideal for dense layouts or when you want less visual weight.
*/
/**
* @summary The datagrid follows the [ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/patterns/grid/examples/data-grids/#kbd_label)
* for standardized keyboard navigation.
*/
/**
* @summary Multi Select rows use a checkbox as the first focusable item within the row. When selected set the `selected` attribute/property on the row. This will ensure selected styles as well as the proper `ariaSelected` state for accessibility.
*/
Anti-Patterns to Avoid
Avoid Poor Summaries or Unclear Use Cases
Summaries should provide UX intent. Do not describe what the reader can already infer from the source code.
/**
* @summary Default badge example.
*/
/**
* @summary Badge examples with status colors.
*/
/**
* @summary Default badge example.
*/
/**
* @summary Badge examples with status colors.
*/
Avoid Overly Complex State
Avoid complex/stateful examples. Use cases vary widely across frameworks/tools so simple stateless examples are necessary to support all users.
export const OverlyComplex = {
render: () => html`<!-- Complex state logic that obscures the example -->`
};
export const OverlyComplex = {
render: () => html`<!-- Complex state logic that obscures the example -->`
};
Best Practices Summary
- Always include
@summary - Every example needs clear documentation - Keep examples stateless - Focus on component capabilities, not complex interactions
- Use plain HTML/CSS/JS - Avoid unnecessary abstractions
- Write descriptive summaries - Explain what, why, when, and how
- Include accessibility notes - Use ARIA attributes when appropriate
- Provide context - Explain the UX benefits and use cases
- Keep examples focused - One clear concept per example
- Use semantic naming - Example names should show their purpose
Example Checklist
Before submitting an example, ensure:
- [ ] Example includes a title
- [ ]
@summary JSDoc comment is present and comprehensive - [ ] Description explains the UX intent and use cases
- [ ] Example is stateless (unless demonstrating specific state patterns)
- [ ] Uses plain HTML/CSS/JS without unnecessary abstractions
- [ ] Includes accessibility considerations when relevant