AGENTS.md

This file provides guidance to AI Agents when working with code in this repository.

Instruction Precedence for Agents

When instructions conflict, follow this order (highest to lowest):

Runtime or platform constraints from the agent host
Repository agent rules in AGENTS.md
Task-specific skill instructions in .claude/skills/*/SKILL.md
Documents explicitly required by a selected skill (for example, docs in projects/site/src/docs/internal/guidelines/)
General project documentation such as README.md

Notes:

README.md is primarily for orientation and setup; it does not override agent policy.
If a skill says you MUST review a referenced guideline, treat that guideline as required for that task.
If two same-level sources conflict, prefer the more specific and recently maintained source, and note the assumption in your response.

Repository Overview

Elements is a design language for AI/ML factories built as a monorepo containing framework agnostic Web Components (Lit), themes, styles, testing utilities, and starter templates. The repository uses pnpm workspaces with Wireit for build orchestration and Semantic Release for automated versioning/publishing.

Environment Requirements

mise: Toolchain manager for local development and CI (mise.toml)
Node.js: 26.4.0 (managed via mise and validated against .nvmrc and package.json engines)
pnpm: 11.9.0 (managed via mise and validated against package.json)
Go: 1.26.4 (managed via mise for the Go starter)
Git LFS: Required for visual test screenshots and videos (.gitattributes defines tracked files)
Playwright: Browser-based testing uses Chromium (installed via prepare script)
Vale: Prose linter for documentation and JSDoc (managed via mise)

Common Commands

Repository Setup

# Install required tools and run CI
curl https://mise.run | sh
# If mise is not on PATH yet, use ~/.local/bin/mise for the setup commands.
mise trust
mise run setup

Building and Testing

# Run full CI pipeline locally (lint, build, test)
pnpm run ci

# Run all tests and lighthouse tests
pnpm run ci:all

# Clean and reset repository
pnpm run ci:reset

# Format code
pnpm run format
pnpm run format:fix

# Prose lint (documentation and JSDoc)
pnpm run lint:vale

Individual Project Commands

Each project has a DEVELOPMENT.md file with the authoritative list of available pnpm scripts for that project. Consult projects/<name>/DEVELOPMENT.md before running commands. The common commands below are a quick reference. Run them from within the specific project directory (for example, cd projects/core):

# Development watch mode
mise exec -- pnpm run dev

# Build project
mise exec -- pnpm run build

# Run unit tests
mise exec -- pnpm run test

# Run single test suite
mise exec -- pnpm run test -- src/badge/badge.test.ts

# Run accessibility tests
mise exec -- pnpm run test:axe

# Run lighthouse performance tests
mise exec -- pnpm run test:lighthouse

# Run visual regression tests
mise exec -- pnpm run test:visual

# Run SSR tests
mise exec -- pnpm run test:ssr

# Lint project
mise exec -- pnpm run lint
mise exec -- pnpm run lint:fix

Architecture

Monorepo Structure

The repository contains a top-level workspace with individual project directories:

/projects/core - Core Elements Web Components library (Lit-based)
/projects/forms - Form control utilities, mixins, and schema validation
/projects/themes - Theme tokens and CSS custom properties
/projects/styles - CSS utilities for layout and typography
/projects/starters - Starter templates for supported frameworks, including React, Angular, Vue, and Svelte
/projects/cli - Command-line tooling for Elements development and project scaffolding
/projects/create - npm create @nvidia-elements wrapper around CLI project creation
/projects/code - Code authoring components, including syntax-highlighted code blocks
/projects/markdown - Markdown components and utilities
/projects/media - Media playback UI components
/projects/lint - Elements lint configurations and custom rules
/projects/monaco - Monaco editor integration
/projects/pages - GitHub Pages deployment project
/projects/site - Documentation site (11ty)
/projects/internals - Internal tooling (vite configs, eslint, patterns, metadata)

Component Architecture

Each component in /projects/core/src/ follows this structure:

component-name/
├── component-name.ts                 # Main component class (extends LitElement or applies a forms mixin)
├── component-name.css                # Component styles
├── component-name.examples.ts        # Example templates for documentation
├── component-name.test.ts            # Unit tests
├── component-name.test.axe.ts        # Accessibility tests
├── component-name.test.lighthouse.ts # Performance tests
├── component-name.test.visual.ts     # Visual regression tests
├── component-name.test.ssr.ts        # SSR tests
├── index.ts                          # Exports component class (no side effects)
└── define.ts                         # Registers component to customElementsRegistry

Components typically extend Lit's LitElement directly. Import forms mixins from @nvidia-elements/forms/mixins; reactive controllers and utilities remain under @nvidia-elements/core/internal for shared behavior such as keynav, state management, and i18n. Components use Lit decorators for properties, CSS custom properties for theming, and follow ARIA Authoring Practices Guide patterns.

When adding a new core component, also add its define.js import and export * to projects/core/src/bundle.ts (alphabetical order). This file is the entry point for the core CDN bundle. The no-missing-bundle-registration lint rule validates completeness in CI.

Component Definition

Components export both the class and auto-define:

// component-name.ts
export class ComponentName extends LitElement {
  static styles = useStyles([styles]);
  static readonly metadata = { tag: 'nve-component-name', version: '0.0.0' };

  @property({ type: String, reflect: true }) status?: 'success' | 'error';

  render() {
    return html`<div internal-host><slot></slot></div>`;
  }
}

// define.ts
import { define } from '@nvidia-elements/core/internal';
import { ComponentName } from '@nvidia-elements/core/component-name';

define(ComponentName);

declare global {
  interface HTMLElementTagNameMap {
    'nve-component-name': ComponentName;
  }
}

Build System

pnpm - Package manager with workspaces
Wireit - Build orchestration with caching and dependency management
Vite - Build tool for compiling TypeScript and bundling
Semantic Release - Automated versioning and publishing based on conventional commits

Wireit configurations in each package.json define dependencies between projects. The build system intelligently rebuilds only what changed.

Release Process

Releases are fully automated:

Commits follow conventional commit format: type(scope): message
Types: fix (patch), feat (minor), chore (no release)
Scopes map to project names: core, themes, forms, cli, code, etc.
Semantic Release analyzes commits and publishes packages
Changelogs are auto-generated from commit messages
More than one package can release in a single merge with dependency ordering

Releases happen automatically after CI passes on merge to main. No manual version bumping.

Development Guidelines

Branch Naming

Branches must use topic/ prefix for merge requests:

git checkout -b topic/fix-button-accessibility

Commit Messages

Follow conventional commit format with lowercase subjects (enforced by commitlint):

git commit -m "fix(core): resolve keyboard navigation in dropdown"
git commit -m "feat(themes): add dark mode color tokens"
git commit -m "chore(docs): update component examples"

Important: the subject line (first line after type(scope):) must be entirely lowercase. Avoid starting with proper nouns or using uppercase letters. For example, use "add feature," not "Add feature," and "update api," not "Update API."

Commit types:

fix - Bug fixes, performance fixes (triggers patch release)
feat - New features, components, APIs (triggers minor release)
chore - Non-production code modifications, build tooling, documentation (no release)

Common scopes:

docs - 11ty docs site and landing page (/projects/site)
core - Core Elements library (/projects/core)
themes - Theme tokens (/projects/themes)
styles - CSS utilities (/projects/styles)
starters - Starter templates (/projects/starters)
cli - Command-line tooling (/projects/cli)
code - Code authoring components (/projects/code)
create - npm create @nvidia-elements wrapper (/projects/create)
forms - Form control utilities (/projects/forms)
lint - Lint configurations and custom rules (/projects/lint)
markdown - Markdown components and utilities (/projects/markdown)
media - Media playback UI components (/projects/media)
monaco - Monaco editor integration (/projects/monaco)
pages - GitHub Pages deployment project (/projects/pages)
ci - Build/CI tooling (/projects/internals)

Prose Linting (Vale)

Vale enforces consistent technical writing across documentation (*.md) and JSDoc comments (*.ts). It uses the Google developer documentation style guide and write-good rules with project-specific customizations.

Key files:

.vale.ini: Root configuration defining style guides, disabled rules, and file-type settings
config/vale/styles/Elements/: Custom rules (branding, terminology)
config/vale/styles/config/vocabularies/Elements/accept.txt: Accepted vocabulary (project terms, component names, tech jargon)
mise.toml: Toolchain versions for Vale, Node.js, pnpm, Go, and Git LFS

When adding new technical terms, component names, or abbreviations that Vale flags as misspelled, add them to accept.txt. Run pnpm run lint:vale to verify changes pass. Vale also runs as a pre-commit hook on markdown files via lint-staged.

Documentation References

Read before making changes:

/projects/site/src/docs/internal/guidelines/testing.md - When writing or modifying any test files; provides overview of testing strategy and test types
/projects/site/src/docs/internal/guidelines/testing-unit.md - When writing .test.ts files; covers createFixture, elementIsStable patterns
/projects/site/src/docs/internal/guidelines/testing-accessibility.md - When writing .test.axe.ts files; covers axe-core usage and WCAG compliance testing
/projects/site/src/docs/internal/guidelines/testing-visual.md - When writing .test.visual.ts files; covers Playwright screenshot patterns and theme testing
/projects/site/src/docs/internal/guidelines/testing-ssr.md - When writing .test.ssr.ts files; covers server-side rendering compatibility patterns
/projects/site/src/docs/internal/guidelines/testing-lighthouse.md - When writing .test.lighthouse.ts files; covers performance, accessibility, and best practices scoring
/projects/site/src/docs/internal/guidelines/typescript.md - When working with TypeScript code; covers type safety, type guards, discriminated unions, exhaustive checking
/projects/site/src/docs/internal/guidelines/examples.md - When creating or modifying *.examples.ts files; covers naming conventions, summary guidelines, and example structure
/projects/site/src/docs/internal/guidelines/documentation.md - When modifying the documentation site or working with Eleventy shortcodes
/projects/site/src/docs/api-design/packaging.md - When working with package exports, entrypoints, or registration patterns; covers dependencies, build output, side effects
/projects/site/src/docs/api-design/properties-attributes.md - When adding or modifying component properties/attributes; covers @property decorator, reflect option, impossible states
/projects/site/src/docs/api-design/styles.md - When working with component styles or CSS custom properties; covers theming strategies and custom property patterns
/projects/site/src/docs/api-design/registration.md - When naming components or working with tag registration; covers tag prefixes and naming conventions
projects/*/DEVELOPMENT.md - When working within a specific project; lists all available pnpm scripts for that project
/projects/internals/BUILD.md - When modifying build configuration, Wireit scripts, or CI/CD pipeline
/projects/internals/RELEASE.md - When creating new projects or modifying release process; covers semantic release setup, CI artifacts, commit scopes, initial tags

Cloud Agent Specific Instructions

These notes are for cloud agents running in the prebuilt VM (dependencies already installed by the startup update script). They capture non-obvious caveats, not full setup steps.

Toolchain access

mise manages the toolchain, and the VM image already includes it. ~/.local/bin sits on PATH and mise activate runs from ~/.bashrc, so node (26.4.0), pnpm (11.9.0), go, vale, and git-lfs resolve directly. If a fresh shell ever lacks them, prefix commands with mise exec -- (for example, mise exec -- pnpm ...) or run mise run <task>.
Run all repo commands through mise to guarantee the pinned versions, exactly as the root AGENTS.md examples show.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

AGENTS.md

Instruction Precedence for Agents

Repository Overview

Environment Requirements

Common Commands

Repository Setup

Building and Testing

Individual Project Commands

Architecture

Monorepo Structure

Component Architecture

Component Definition

Build System

Release Process

Development Guidelines

Branch Naming

Commit Messages

Prose Linting (Vale)

Documentation References

Cloud Agent Specific Instructions

Toolchain access

Uh oh!

FilesExpand file tree

AGENTS.md

Latest commit

History

AGENTS.md

File metadata and controls

AGENTS.md

Instruction Precedence for Agents

Repository Overview

Environment Requirements

Common Commands

Repository Setup

Building and Testing

Individual Project Commands

Architecture

Monorepo Structure

Component Architecture

Component Definition

Build System

Release Process

Development Guidelines

Branch Naming

Commit Messages

Prose Linting (Vale)

Documentation References

Cloud Agent Specific Instructions

Toolchain access