authoring-components

Authoring Components

You MUST review the component creation guideline before creating or modifying components.

When to Use This Skill

• Creating a new component from scratch
• Understanding the required file structure for components
• Setting up test boilerplate for all 5 test types
• Choosing the appropriate base class or mixin (ButtonFormControlMixin vs LitElement)
• Understanding component metadata and registration patterns
• Setting up JSDoc comments for components

Must Read File

Read the component creation guide to get critical context for component creation guidance.

Workflow

1. Gather requirements: confirm the component name (kebab-case), purpose, and whether to use LitElement directly or apply ButtonFormControlMixin for button-like interactive components.
2. Study a reference: read the closest reference component listed below to understand the pattern in practice.
3. Create the 10 required files in projects/core/src/<component-name>/:
   • component-name.ts:component class with metadata, JSDoc, and render method
   • component-name.css:styles using CSS custom properties
   • component-name.examples.ts:example templates with @summary JSDoc
   • component-name.test.ts:unit tests
   • component-name.test.axe.ts:accessibility tests
   • component-name.test.visual.ts:visual regression tests
   • component-name.test.ssr.ts:SSR tests
   • component-name.test.lighthouse.ts:lighthouse tests
   • define.ts:registration using define() helper with HTMLElementTagNameMap
   • index.ts:side-effect-free export
4. Update shared entry points:
   • Add only import '@nvidia-elements/core/<component-name>/define.js' to projects/core/src/bundle.ts in alphabetical order. Keep this registration bundle import-only. Export the public API from the component index.ts and expose its entry point through the package exports map.
   • Add the definition import to the js-modules list in projects/core/src/index.test.lighthouse.ts so the combined direct-import benchmark measures the component.
5. Measure payloads: run mise exec -- pnpm run test:lighthouse from projects/core. Increase a bundle-size limit only when the measured payload exceeds the current limit.
6. Verify: confirm all files follow the templates in the component creation guide, then run mise exec -- pnpm run lint and mise exec -- pnpm run test from projects/core.

References

• Component Creation Guide - Complete component creation workflow
• TypeScript Guidelines - Type safety patterns
• Examples Guidelines - Example file structure
• Testing Guidelines - Testing strategy
• API Design - Properties - Property design patterns
• API Design - Styles - CSS custom properties

Reference Components

• /projects/core/src/button/ - ButtonFormControlMixin pattern example
• /projects/core/src/badge/ - LitElement pattern example
• /projects/core/src/card/ - Composition with slots example