Documentation Guidelines
API Guidelines for the Eleventy based documentation site for Elements. Eleventy Shortcodes provide a way to create reusable templates in markdown content.
Install Shortcode
Renders the install entrypoint of a given element API.
| Parameter | Description | Type |
|---|---|---|
| Name | Tag name of element API | string |
{% install 'nve-badge' %}
import '@nvidia-elements/core/badge/define.js';
<nve-badge>badge</nve-badge>
Example Shortcode
Renders an example template and its corresponding metadata.
| Parameter | Description | Type |
|---|---|---|
| Path | Fully qualified path to the examples file | string |
| Name | Case sensitive name of the example to render from file | string |
| Options | Optional settings | { "height": "150px", "align": "center", "summary": false, "layer": "highlight" } |
Example Default
{% example '@nvidia-elements/core/button/button.examples.json' 'Default' %}
Basic button component with standard appearance and behavior for primary user actions.
Example Options
{% example '@nvidia-elements/core/button/button.examples.json' 'Default' '{ "height": "150px", "align": "center", "summary": false, "layer": "highlight" }' %}
Example Tags Shortcode
Render the metadata tags of a given Example template.
| Parameter | Description | Type |
|---|---|---|
| Path | Fully qualified path to the examples file | string |
| Name | Case sensitive name of the example to render from file | string |
{% example-tags '@nvidia-elements/core/grid/grid.examples.json' 'PerformanceVirtualScroll' %}
Example Group Shortcode
The example-group shortcode visualizes many related examples in a single layout. Each example renders its summary/description alongside its example.
| Parameter | Description | Type |
|---|---|---|
| Paths | Fully qualified paths to the examples file and its example name | string |
| Content Slot | Extra context about related examples in example group | string |
### Single or Group
{% example-group '@nvidia-elements/core/accordion/accordion.examples.json:Single' '@nvidia-elements/core/accordion/accordion.examples.json:Multiple' %}
Leverage accordions alone or in conjunction with others to create progressive disclosure patterns.
{% endexample-group %}
Single or Group
Appearance
Account Settings
Privacy
Leverage accordions alone or in conjunction with others to create progressive disclosure patterns.
API Shortcode
Renders the description metadata of a given API. The identifier of the referenced API is optional. If you omit the identifier, the shortcode displays all API references of the provided type.
| Parameter | Description | Type |
|---|---|---|
| Tag Name | Tag name of element API | string |
| API | API metadata to render | description | event | property | slot | css-property | css-part |
| Identifier | Optional public API name | string |
API Description
{% api 'nve-button' 'description' %}
A button is a widget that enables users to trigger an action or event, such as submitting a form, opening a dialog, canceling an action, or performing a delete operation.
API Event
{% api 'nve-alert' 'event' 'close' %}
Dispatched when the alert closes within an alert group.
API Slot
{% api 'nve-page' 'slot' 'header' %}
The topmost section of the page, typically containing navigation, branding, or other global elements.
API CSS Part
{% api 'nve-dialog' 'css-part' 'close-button' %}
The inner template reference for the close button of the dialog.
API CSS Property
{% api 'nve-button' 'css-property' '--background' %}
API Property / Attribute
{% api 'nve-button' 'property' 'interaction' %}
The Interaction type provides a way to show the intent of an interactive element. This can help users quickly understand what each interaction does and reduce the potential for confusion or errors.
API Value
{% api 'nve-button' 'property' 'interaction' 'destructive' %}
Shows the interaction targets destructive actions such as deleting or removing.
API Type
If you omit the identifier, the shortcode displays all API references of the provided type.
{% api 'nve-avatar' 'property' %}
Defines a base color from the theme color palette
red-cardinal
gray-slate
gray-denim
blue-indigo
blue-cobalt
blue-sky
teal-cyan
green-mint
teal-seafoam
green-grass
yellow-amber
orange-pumpkin
red-tomato
pink-magenta
purple-plum
purple-violet
purple-lavender
pink-rose
green-jade
lime-pear
yellow-nova
brand-green
Controls the visual scale of an element to match its importance and available space.
sm Compact size for dense layouts or secondary elements with less visual prominence.
md Standard size that works well in most contexts and provides balanced visibility.
lg Larger size for emphasizing important elements or improving touch targets in spacious layouts.
xs
Design Token Shortcode
Renders a given subset of matching design tokens.
| Parameter | Description | Type |
|---|---|---|
| Name | Tag name of token subset | string |
{% tokens 'ref-border-color' %}
| Token | Value | Description | Demo | |
|---|---|---|---|---|
| --nve-ref-border-color | --nve-ref-color-neutral-800 | Use for default borders that match the standard color scheme | ||
| --nve-ref-border-color-emphasis | --nve-ref-color-neutral-1000 | Use for borders that need high contrast and emphasis | ||
| --nve-ref-border-color-muted | --nve-ref-color-neutral-700 | Use for subtle borders that blend with backgrounds | ||
| --nve-ref-border-color-inverse | --nve-ref-color-scheme-inverse | Use for borders on inverse color scheme backgrounds |
Do/Don't Shortcode
Renders the "Do/Don't" shortcode layout for guidance on potential anti-patterns.
| Parameter | Description | Type |
|---|---|---|
| Slot | Slot for two example shortcodes | string |
{% dodont %}
{% example '@nvidia-elements/core/grid/grid.examples.json' 'ValidColumnCount' '{ "summary": false }' %}
{% example '@nvidia-elements/core/grid/grid.examples.json' 'InvalidColumnCount' '{ "summary": false }' %}
{% enddodont %}
Split Layout Shortcode
{% split %}
{% example '@nvidia-elements/core/button/button.examples.json' 'Pressed' %}
{% api 'nve-button' 'property' 'pressed' %}
{% endsplit %}
Pressed state for toggle buttons marking active/selected state with clear visual feedback.
Indicates the current state of a toggle button that switches on or off. MDN
{% split %}
{% example '@nvidia-elements/core/button/button.examples.json' 'Interaction' %}
{% api 'nve-button' 'property' 'interaction' %}
{% endsplit %}
Interaction states that communicate button hierarchy, importance, and availability to users.
The Interaction type provides a way to show the intent of an interactive element. This can help users quickly understand what each interaction does and reduce the potential for confusion or errors.
Grouping Disjointed APIs
When comparing disjointed or non-enum based properties use the api value shortcode to explicitly render the api description for the given value.
### States
{% split %}
{% example '@nvidia-elements/core/button/button.examples.json' 'GroupStates' %}
| State | Usage |
| -------- | --------------------------------------------------- |
| selected | {% api 'nve-button' 'property' 'selected' 'true' %} |
| pressed | {% api 'nve-button' 'property' 'pressed' 'true' %} |
| disabled | {% api 'nve-button' 'property' 'disabled' 'true' %} |
{% endsplit %}
States
Button interaction states including hover, focus, pressed, selected, and disabled.
| State | Usage |
|---|---|
| selected | The element holds selection and represents the user's current choice within the group. |
| pressed | The button is in the pressed (on) state and the associated action or setting is active. |
| disabled | The element has a disabled state and does not accept interaction. |