chore(docs): fix markdown lint errors

Signed-off-by: Cory Rylan <crylan@nvidia.com>

Author: coryrylan

projects/internals/eslint/src/local/example-approved-domains.js

@@ -1,6 +1,6 @@
 import { findHtmlTemplate, getTemplateText, hasTag } from './example-helpers.js';
 
-const APPROVED_DOMAINS = ['nvidia.com', 'github.com'];
+const APPROVED_DOMAINS = ['nvidia.com', 'github.com', 'huggingface.co'];
 const URL_ATTRIBUTES = ['href', 'src', 'srcset'];
 const URL_ATTRIBUTE_PATTERN = new RegExp(`\\b(${URL_ATTRIBUTES.join('|')})\\s*=\\s*("([^"]*)"|'([^']*)')`, 'gi');
 

projects/site/eslint.config.js

@@ -11,6 +11,33 @@ export default [
   ...browserTypescriptConfig,
   ...appConfig,
   ...jsonConfig,
+  {
+    // These examples intentionally demonstrate incomplete and hypothetical component APIs.
+    files: ['src/docs/api-design/**/*.md', 'src/docs/internal/guidelines/**/*.md'],
+    rules: {
+      '@nvidia-elements/lint/no-missing-control-label': 'off',
+      '@nvidia-elements/lint/no-missing-slotted-elements': 'off',
+      '@nvidia-elements/lint/no-unknown-tags': 'off'
+    }
+  },
+  {
+    // These examples intentionally demonstrate deprecated APIs.
+    files: ['src/docs/about/migration.md'],
+    rules: {
+      '@nvidia-elements/lint/no-deprecated-tags': 'off',
+      '@nvidia-elements/lint/no-deprecated-attributes': 'off',
+      '@nvidia-elements/lint/no-deprecated-global-attributes': 'off',
+      '@nvidia-elements/lint/no-deprecated-popover-attributes': 'off',
+      '@nvidia-elements/lint/no-deprecated-icon-names': 'off',
+      '@nvidia-elements/lint/no-unexpected-attribute-value': 'off',
+      '@nvidia-elements/lint/no-unstyled-typography': 'off',
+      '@nvidia-elements/lint/no-missing-control-label': 'off',
+      '@nvidia-elements/lint/no-missing-slotted-elements': 'off',
+      '@nvidia-elements/lint/no-unexpected-global-attribute-value': 'off',
+      '@nvidia-elements/lint/no-restricted-container-full': 'off',
+      '@nvidia-elements/lint/no-unknown-tags': 'off'
+    }
+  },
   {
     files: ['src/_11ty/**/*.js'],
     rules: {

projects/site/package.json

@@ -201,6 +201,7 @@
       "command": "eslint -c ./eslint.config.js --color --cache --cache-location .eslintcache/",
       "files": [
         "src/**/*.js",
+        "src/**/*.md",
         "src/**/*.ts",
         "eslint.config.js"
       ],

projects/site/src/docs/api-design/composition.md

@@ -16,7 +16,7 @@ Elements should default to using composition when possible. This approach is to
 
 ```html
 <nve-button>
-  button <nve-icon name="info"></nve-icon>
+  button <nve-icon name="information-circle"></nve-icon>
 </nve-button>
 ```
 
@@ -36,7 +36,7 @@ Going further this runs into layout conflicts. If the icon needs to change posit
 
 ```html
 <nve-button>
-  <nve-icon name="info"></nve-icon> button
+  <nve-icon name="information-circle"></nve-icon> button
 </nve-button>
 ```
 
@@ -64,6 +64,8 @@ Elements should provide reasonable defaults for better developer experience for
 
 The alert can internally provide the default icon style for the status in the system. But as above with the button, the alert element runs the risk of absorbing parts of the icon API. To mitigate this, use a documented named slot as the customization hook.
 
+<!-- eslint-disable @nvidia-elements/lint/no-unexpected-attribute-value -->
+
 ```html
 <!-- nve-alert template -->
 <div>
@@ -80,12 +82,16 @@ The alert can internally provide the default icon style for the status in the sy
 </nve-alert>
 ```
 
+<!-- eslint-enable @nvidia-elements/lint/no-unexpected-attribute-value -->
+
 Slots can provide default content if the consumer supplies no content. Here the template sets an internal icon with a status icon that matches the status of the alert. If the consumer wants to customize the icon, they can project their own icon into the `icon` slot and override the default. This makes `icon` an explicit public slot API, while avoiding a series of icon-specific inherited attributes or properties on the alert.
 
 ## Semantic Obfuscation - anti-pattern
 
 When building composition based APIs the developer should push the semantics of the HTML up into the light DOM or the control of the consumer. In this example the card element embeds the h1 heading. This creates an incorrect DOM structure as only one given h1 can exist within the page. This also applies as the page structure should work down from h1-h6.
 
+<!-- eslint-disable @nvidia-elements/lint/no-unexpected-slot-value -->
+
 {% dodont %}
 
 ```html
@@ -100,15 +106,15 @@ When building composition based APIs the developer should push the semantics of
 
 <!-- consumer API -->
 <nve-card status="warning">
-  <h2 slot="header">Card Header</h2>
-  <p>card content</p>
+  <h2 slot="header" nve-text="heading">Card Header</h2>
+  <p nve-text="body">card content</p>
 </nve-card>
 ```
 
 ```html
 <!-- nve-card template -->
 <div>
-  <h1><slot name="header"></slot></h1>
+  <h1 nve-text="heading"><slot name="header"></slot></h1>
   <div>
   	<slot></slot>
   </div>
@@ -118,12 +124,14 @@ When building composition based APIs the developer should push the semantics of
 <!-- consumer API -->
 <nve-card status="warning">
   <div slot="header">Card Header</div>
-  <p>card content</p>
+  <p nve-text="body">card content</p>
 </nve-card>
 ```
 
 {% enddodont %}
 
+<!-- eslint-enable @nvidia-elements/lint/no-unexpected-slot-value -->
+
 While composition based APIs may be more verbose at times, they lower the API surface area to learn in the system and help ensure there is a singular way to use the element. Once a consumer learns an element API, that API usage remains predictable and reliable throughout the system.
 
 Consumer apps/plugins can add opinionated abstractions. This can provide a more opinionated terse API in which consumers can always “escape” or access the elements of the base library as needed. It's easier to add abstraction layers, it's much more difficult to pull apart the wrong base abstraction.

projects/site/src/docs/api-design/index.md

@@ -23,9 +23,9 @@ This document is not intended to define the best practices and API design of hig
   <nve-alert status="danger">Don't: a practice to avoid</nve-alert>
   <nve-alert status="accent">Tip: helpful details on rationale for a given guideline</nve-alert>
   <nve-alert status="warning">details on the risks of not following a guideline</nve-alert>
-  <nve-alert><nve-icon slot="icon">🏁</nve-icon> Performance: detail about how a guideline impacts performance</nve-alert>
-  <nve-alert><nve-icon slot="icon">🎓</nve-icon> Learn: resource to learn more about a guideline topic</nve-alert>
-  <nve-alert><nve-icon slot="icon">🚧</nve-icon> WIP: details on any work in progress guidance</nve-alert>
+  <nve-alert><nve-icon slot="icon" name="flag"></nve-icon> Performance: detail about how a guideline impacts performance</nve-alert>
+  <nve-alert><nve-icon slot="icon" name="academic-cap"></nve-icon> Learn: resource to learn more about a guideline topic</nve-alert>
+  <nve-alert><nve-icon slot="icon" name="traffic-cone"></nve-icon> WIP: details on any work in progress guidance</nve-alert>
 </div>
 
 ## Terminology
@@ -70,7 +70,7 @@ Consistent element APIs provide consistent developer experience. The recommendat
 ```html
 <!-- HTML/JavaScript -->
 <nve-alert status="success">
-  <p>hello there!</p>
+  <p nve-text="body">hello there!</p>
 </nve-alert>
 
 <script type="module">
@@ -82,22 +82,22 @@ Consistent element APIs provide consistent developer experience. The recommendat
 
 <!-- Angular -->
 <nve-alert status="success" [closable]="boolProp" (close)="handle($event)">
-  <p>hello there!</p>
+  <p nve-text="body">hello there!</p>
 </nve-alert>
 
 <!-- Lit -->
 <nve-alert status="success" ?closable=${boolProp} @close=${e => this.handle(e)}>
-  <p>hello there!</p>
+  <p nve-text="body">hello there!</p>
 </nve-alert>
 
 <!-- Vue -->
 <nve-alert status="success" :closable="boolProp" @close="handle">
-  <p>hello there!</p>
+  <p nve-text="body">hello there!</p>
 </nve-alert>
 
 <!-- React/Preact -->
 <nve-alert status="success" closable={this.state.boolProp} onClose={this.handle}>
-  <p>hello there!</p>
+  <p nve-text="body">hello there!</p>
 </nve-alert>
 ```
 

projects/site/src/docs/api-design/logs.md

@@ -60,7 +60,7 @@ This warning appears when invalid elements are slotted into a component. Example
 
 ```html
 <nve-tree>
-  <nve-tree-node></nve-tree-node>
+  <nve-tree-node>Node</nve-tree-node>
 </nve-tree>
 
 <nve-grid-row>
@@ -73,7 +73,7 @@ This warning appears when invalid elements are slotted into a component. Example
 ```html
 <nve-tree>
   <div>
-    <nve-tree-node></nve-tree-node>
+    <nve-tree-node>Node</nve-tree-node>
   </div>
 </nve-tree>
 
@@ -102,11 +102,15 @@ This warning appears when a component tries to reference an element by ID that d
 
 <nve-alert status="danger">Invalid</nve-alert>
 
+<!-- eslint-disable @nvidia-elements/lint/no-missing-popover-trigger -->
+
 ```html
 <nve-button popovertarget="my-popover">show tooltip</nve-button>
 <nve-tooltip id="incorrect-id">tooltip</nve-tooltip>
 ```
 
+<!-- eslint-enable @nvidia-elements/lint/no-missing-popover-trigger -->
+
 To resolve this warning:
 
 - Ensure the referenced element exists in the DOM

projects/site/src/docs/api-design/packaging.md

@@ -45,7 +45,7 @@ Build outputs should target the latest ES2020+. Build outputs should not compile
 
 <nve-alert status="warning">Warning: avoid alternate build targets as it increases complexity and is unnecessary with modern build tools and browsers.</nve-alert>
 
-<nve-alert><nve-icon slot="icon">🎓</nve-icon> Learn: <a href="https://justinfagnani.com/2019/11/01/how-to-publish-web-components-to-npm/">publishing Web Components</a></nve-alert>
+<nve-alert><nve-icon slot="icon" name="academic-cap"></nve-icon> Learn: <a href="https://justinfagnani.com/2019/11/01/how-to-publish-web-components-to-npm/">publishing Web Components</a></nve-alert>
 
 ## Entrypoints
 
@@ -95,8 +95,8 @@ The `package.json` should use a `sideEffects` array that lists registration and
 
 This enables tools like Webpack and Rollup to preserve explicit registration entrypoints while still tree-shaking side-effect-free component modules.
 
-<nve-alert><nve-icon slot="icon">🎓</nve-icon> Learn about <a href="/docs/integrations/lit-library/">Lit Library integration</a></nve-alert>
+<nve-alert><nve-icon slot="icon" name="academic-cap"></nve-icon> Learn about <a href="/docs/integrations/lit-library/">Lit Library integration</a></nve-alert>
 
-<nve-alert><nve-icon slot="icon">🎓</nve-icon> Learn: <a href="https://github.com/webcomponents/polyfills/tree/master/packages/scoped-custom-element-registry">scoped element registry</a></nve-alert>
+<nve-alert><nve-icon slot="icon" name="academic-cap"></nve-icon> Learn: <a href="https://github.com/webcomponents/polyfills/tree/master/packages/scoped-custom-element-registry">scoped element registry</a></nve-alert>
 
-<nve-alert><nve-icon slot="icon">🎓</nve-icon> Learn: <a href="https://www.youtube.com/watch?v=QmDToR6mLhk">case study</a></nve-alert>
+<nve-alert><nve-icon slot="icon" name="academic-cap"></nve-icon> Learn: <a href="https://www.youtube.com/watch?v=QmDToR6mLhk">case study</a></nve-alert>

projects/site/src/docs/api-design/properties-attributes.md

@@ -30,7 +30,7 @@ Properties (`@property`) in Lit enable setting the property on the element via J
 ```
 
 <nve-alert>
-  <nve-icon slot="icon">🎓</nve-icon> 
+  <nve-icon slot="icon" name="academic-cap"></nve-icon>
   <p nve-text="body">Learn: by default when you set a property, Lit does not update the corresponding attribute in the DOM for performance. If the attribute serves as a style hook example, <code nve-text="code">:host([disabled])</code> then you can add the <code nve-text="code">reflect</code> option to the property decorator.</p>
 </nve-alert>
 
@@ -56,7 +56,7 @@ Properties/Attributes should avoid enabling “impossible states”. Conflicting
 
 {% enddodont %}
 
-<nve-alert><nve-icon slot="icon">🎓</nve-icon> Learn:&nbsp;<a href="https://kentcdodds.com/blog/make-impossible-states-impossible" nve-text="link">make impossible states impossible</a></nve-alert>
+<nve-alert><nve-icon slot="icon" name="academic-cap"></nve-icon> Learn:&nbsp;<a href="https://kentcdodds.com/blog/make-impossible-states-impossible" nve-text="link">make impossible states impossible</a></nve-alert>
 
 ## Boolean Types
 
@@ -81,20 +81,20 @@ Boolean property/attribute type behave the same as native HTML element boolean t
 While Lit keeps both properties and attributes in sync, do not use complex types like `object` and `array` on the API. Since HTML cannot represent JavaScript objects, Lit must JSON parse attributes and reflect them anytime there is a change to ensure the JavaScript property and HTML attribute are in sync. This can be expensive to parse when using an object or array and cause unexpected behaviors such as lost object references for the user.
 
 <nve-alert status="success">
-  Use <code>string | number | boolean</code>
+  Use <code nve-text="code">string | number | boolean</code>
 </nve-alert>
 
 <nve-alert status="danger">
-  Avoid <code>object | array</code>
+  Avoid <code nve-text="code">object | array</code>
 </nve-alert>
 
 Complex types cause compatibility and usability issues as it can require the developer to use JavaScript to render content. This can make it difficult for user-generated content like CMS systems or SSR (Server Side Rendering) to easily render static HTML.
 
 <nve-alert status="warning">
-  Warning: avoid using <code>@property</code> on built in properties/attributes on the <code>HTMLElement</code> as the decorator overrides the getter/setter and can cause unexpected behavior.&nbsp;<a href="https://github.com/vmware-clarity/core/blob/main/projects/core/build/eslint-rules/reserved-property-names.js" nve-text="link">read more</a>
+  Warning: avoid using <code nve-text="code">@property</code> on built in properties/attributes on the <code nve-text="code">HTMLElement</code> as the decorator overrides the getter/setter and can cause unexpected behavior.&nbsp;<a href="https://github.com/vmware-clarity/core/blob/main/projects/core/build/eslint-rules/reserved-property-names.js" nve-text="link">read more</a>
 </nve-alert>
 
-<nve-alert><nve-icon slot="icon">🎓</nve-icon>
+<nve-alert><nve-icon slot="icon" name="academic-cap"></nve-icon>
 Learn about <a href="https://developers.google.com/web/fundamentals/web-components/best-practices#attributes-properties" nve-text="link">Web Fundamentals Attributes vs Properties</a>.
 </nve-alert>
 
@@ -147,6 +147,6 @@ export class Sparkline extends LitElement implements DataElement<number[]> {
 
 <nve-alert status="warning">
   <p nve-text="relaxed">
-    Warning: only use <code>DataElement</code> for data structures that have no reasonable declarative HTML representation. If primitive attributes, slots, or child elements can represent the content, prefer those approaches.
+    Warning: only use <code nve-text="code">DataElement</code> for data structures that have no reasonable declarative HTML representation. If primitive attributes, slots, or child elements can represent the content, prefer those approaches.
   </p>
 </nve-alert>

projects/site/src/docs/api-design/registration.md

@@ -31,6 +31,6 @@ Tag names should avoid using verbs or actions within the name. The properties an
 
 {% enddodont %}
 
-<nve-alert><nve-icon slot="icon">🎓</nve-icon> Learn: elements should follow common and established names for existing UI patterns. See &nbsp;<a href="https://open-ui.org" nve-text="link">openui.org</a>&nbsp; for more details on upcoming specs.</nve-alert>
+<nve-alert><nve-icon slot="icon" name="academic-cap"></nve-icon> Learn: elements should follow common and established names for existing UI patterns. See &nbsp;<a href="https://open-ui.org" nve-text="link">openui.org</a>&nbsp; for more details on upcoming specs.</nve-alert>
 
-<nve-alert><nve-icon slot="icon">🎓</nve-icon> Learn: learn common component names from the Open UI &nbsp;<a href="https://open-ui.org/research/component-matrix" nve-text="link">component name matrix</a>.</nve-alert>
+<nve-alert><nve-icon slot="icon" name="academic-cap"></nve-icon> Learn: learn common component names from the Open UI &nbsp;<a href="https://open-ui.org/research/component-matrix" nve-text="link">component name matrix</a>.</nve-alert>

projects/site/src/docs/api-design/slots.md

@@ -20,7 +20,7 @@ Slots provide flexibility for content controlled by the host application that a
 
 ```html
 <nve-alert status="success">
-  <p>Hello <strong>There</strong>!</p>
+  <p nve-text="body">Hello <strong>There</strong>!</p>
 </nve-alert>
 ```
 
@@ -31,12 +31,12 @@ Slots enable an easy way for component composition and decoupling from precise u
 ```html
 <nve-card>
   <nve-card-header>
-    <h3>Plugin</h3>
+    <h3 nve-text="heading">Plugin</h3>
     <a href="#">Learn More</a>
   </nve-card-header>
-  <nve-card-body>
-    <p>Cool new plugin features!</p>
-  </nve-card-body>
+  <nve-card-content>
+    <p nve-text="body">Cool new plugin features!</p>
+  </nve-card-content>
   <nve-card-footer>
     <nve-button>Enable</nve-button>
   </nve-card-footer>
@@ -73,21 +73,21 @@ Composition based APIs also provide flexibility for the host application to choo
 
 ```html
 <nve-tree>
-  <nve-tree-item>item</nve-tree-item>
-  <nve-tree-item>item</nve-tree-item>
-  <nve-tree-item>item</nve-tree-item>
+  <nve-tree-node>item</nve-tree-node>
+  <nve-tree-node>item</nve-tree-node>
+  <nve-tree-node>item</nve-tree-node>
 </nve-tree>
 ```
 
 ```html
 <nve-tree>
-  <nve-tree-item>item</nve-tree-item>
-  <nve-tree-item>item</nve-tree-item>
-  <nve-tree-item expanded>
-  	<nve-tree-item>item</nve-tree-item>
-    <nve-tree-item>item</nve-tree-item>
-    <nve-tree-item>item</nve-tree-item>
-  </nve-tree-item>
+  <nve-tree-node>item</nve-tree-node>
+  <nve-tree-node>item</nve-tree-node>
+  <nve-tree-node expanded>
+	<nve-tree-node>item</nve-tree-node>
+    <nve-tree-node>item</nve-tree-node>
+    <nve-tree-node>item</nve-tree-node>
+  </nve-tree-node>
 </nve-tree>
 ```
 
@@ -96,14 +96,14 @@ By leveraging composition the host application has full render control in their
 ```html
 <!-- Angular -->
 <nve-tree>
-  <nve-tree-item *ngFor="let item of items">{{item.id}}</nve-tree-item>
+  <nve-tree-node *ngFor="let item of items">{{item.id}}</nve-tree-node>
 </nve-tree>
 ```
 
 ```tsx
 // JSX
 <nve-tree>
-  {items.map(item => <nve-tree-item>{item.id}</nve-tree-item>)}
+  {items.map(item => <nve-tree-node>{item.id}</nve-tree-node>)}
 </nve-tree>
 ```
 
@@ -113,7 +113,7 @@ This enables full control of conditional rendering of tree nodes as well as more
 <!-- Angular, only create nodes if the item meets a certain condition -->
 <nve-tree>
   <ng-container *ngFor="let item of items">
-    <nve-tree-item *ngIf="item.active">{{item.id}}</nve-tree-item>
+    <nve-tree-node *ngIf="item.active">{{item.id}}</nve-tree-node>
   </ng-container>
 </nve-tree>
 ```