blackbaud/skyux/add-skyux-code-example

Add a Code Example for a Component

Use this skill to author a documentation code example (a runnable demo) for a component in a published @skyux/* library. Examples live in the @skyux/code-examples package and are rendered in the docs and StackBlitz.

The conventions for both the example component and its spec live in component-code-examples.instructions.md (it auto-applies to libs/components/code-examples/**) — read it before writing code rather than guessing. This skill covers the workflow around those conventions: picking a sibling, wiring the barrel/routes/docs, and the verification gate.

Read AGENTS.md first if you are not already familiar with the monorepo's conventions (Nx tasks, public API discipline, the Karma vs. Jest split, and Conventional Commits).

When to Use

• A component needs a new documentation example, or an existing example needs

to demonstrate additional capability.

Do NOT use this skill for:

• The library component itself — use

add-skyux-component.

• Test harnesses — use

add-component-harness.

Conventions at a Glance

All file-layout, naming, @title, standalone, barrel, route, and documentation.json conventions are defined in component-code-examples.instructions.md. The steps below are the workflow that applies them.

Procedure

Work top to bottom. Follow the conventions in the instruction file; open a sibling example only to look up facts (which module to import, the route/docs wiring), not to copy its structure.

1. Pick a sibling example for reference. Open an existing example under

libs/components/code-examples/src/lib/modules/ to confirm the current layout and which module(s) to import.

1. Author the example component. Create example.ts and example.html

(plus any service the example needs) per the component conventions in the instruction file (class name, @title JSDoc, standalone, imports) and Angular best practices in angular.instructions.md.

1. Export from the barrel. Add the example to

libs/components/code-examples/src/index.ts:

``ts export { <Class> } from './lib/modules/<library>/<component>/<example-name>/example'; ``

1. Regenerate the routes. The route registry at

libs/components/code-examples/routes/src/index.ts is auto-generated from the barrel — do not edit it by hand. Regenerate it:

``bash npx nx run code-examples:prebuild ``

1. Wire documentation. Add the example class name to the owning library's

documentation.json under groups.<library>.codeExamples.docsIds.

1. Write the example spec. Add example.spec.ts following

component-code-examples.instructions.md. The spec should be a thorough showcase of the component's test harness (all public methods, filters, and relevant sub-harnesses), not a smoke test, and reach the project's coverage threshold.

1. Verify. Run the code-examples specs headless, then lint and format:

``bash npx nx test code-examples --configuration=ci npm run lint:affected nx format --files=<changed-file-paths> ``

1. Commit. Use a Conventional Commit with the components/<library> scope

per commit-message.instructions.md.

Definition of Done

• example.ts/.html (+ spec) exist under

libs/components/code-examples/src/lib/modules/<library>/<component>/<example-name>/ and follow the instruction file's conventions (class named <Library><Component><ExampleName>Example, @title JSDoc).

• The example is exported from code-examples/src/index.ts, the routes file

has been regenerated via code-examples:prebuild, and the class is listed in the library's documentation.json codeExamples.docsIds.

• npx nx test code-examples --configuration=ci passes at the project's

coverage threshold, lint is clean, and changed files are formatted.