blackbaud/skyux/add-skyux-component

Add a SKY UX Component (end-to-end)

Use this skill to take a new component from scaffold to a fully wired, tested, and documented addition to a published @skyux/* library. It ties together the repo's scoped instruction files; read each referenced instruction file when you reach that step rather than guessing.

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

When to Use

• Adding a new component, directive, or service to an existing library under

libs/components/<library>/.

• Wiring a new public type/component into a library's src/index.ts barrel.

Do NOT use this skill to create a brand-new library/package — use the add-skyux-library skill first, then return here to add the suite's first component. Do not use this skill to modify build tooling.

Conventions at a Glance

• Library source lives at

libs/components/<library>/src/lib/modules/<module>/.

• Component files follow the pattern:
• <name>.component.ts, .html, .scss, .spec.ts
• a NgModule (<name>.module.ts) that imports the standalone component

and exports the public-facing one.

• Components are standalone; do NOT set standalone: true explicitly in

the decorator. Use ChangeDetectionStrategy.OnPush, input()/output(), and signals. Follow angular.instructions.md. The thin NgModule wrapper above is the SKY UX public-API surface for the standalone component and does not conflict with that file's "standalone over NgModules" guidance.

• The public API is the src/index.ts barrel. Public exports MUST be

prefixed with sky/Sky (e.g. SkyThingComponent, SkyThingModule, SkyThingHarness). Export a new component or directive by its own name (e.g. export { SkyThingComponent } from './lib/.../thing.component';). Some existing libraries export older components/directives under obscured aliases (e.g. as λ1); that is a legacy pattern — do NOT use it for new exports.

Procedure

Work top to bottom. Mirror an existing sibling component in the same library for exact style; do not invent new patterns.

1. Confirm placement. Identify the target <library> (directory name,

not package name) and the <module> folder. Inspect a sibling component in that library and copy its structure. If the library does not exist yet, create it first with the add-skyux-library skill.

1. Scaffold the component. Create the .ts, .html, .scss, and

.module.ts files following Angular best practices in angular.instructions.md.

1. Export from the barrel. Add the module and any public types to

libs/components/<library>/src/index.ts, using the sky/Sky prefix. Export a new component or directive by its own name (not an obscured as λN alias).

1. Write the component spec. Add <name>.component.spec.ts. Most

libs/components/* projects enforce 100% coverage and run on Karma + Jasmine (SKY UX styles are loaded, so computed styles are assertable).

1. Add a test harness. Create the harness, filters, and harness spec

under libs/components/<library>/testing/src/modules/<module>/ per component-harnesses.instructions.md. Export the harness and filters from testing/src/public-api.ts.

1. Add visual tests. Create a Storybook story for the component in the

library's e2e app per the add-component-visual-tests skill.

1. Add a code example + tests. Create an example under

libs/components/code-examples/src/lib/modules/<library>/<component>/<example-name>/ and its example.spec.ts per the add-skyux-code-example skill.

1. Update documentation. Add the new doc IDs to the library's

documentation.json (development, testing, and codeExamples sections) so the manifest picks them up.

1. Verify. Run the affected tests, lint, and format before committing:

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

1. Commit. Use a Conventional Commit with the matching

components/<library> scope per commit-message.instructions.md.

Definition of Done

• Component, module, spec, harness (+ spec), visual-test story, and code

example (+ spec) exist and follow a sibling component's structure.

• Public types are exported with the sky/Sky prefix from src/index.ts

and testing/src/public-api.ts.

• documentation.json lists the new development, testing, and code-example

doc IDs.

• Affected tests pass at the project's coverage threshold, lint is clean, and

files are formatted.