Add prompts for AI coding agents

.github/CODEOWNERS

@@ -31,5 +31,10 @@ specs @rajsite @jattasNI @atmgrifter00 @mollykreis
 # .snyk security scanning configuration file
 /.snyk @chris468 @cameronwaterman @BKnight760 @rbell517 @jattasNI @prestwick
 
+# AI Instructions
+/.github/prompts @fredvisser
+copilot-instructions.md @fredvisser
+
 # Change files don't need explicit reviewers
 /change
+

.github/copilot-instructions.md

@@ -0,0 +1,58 @@
+# Nimble Design System – AI Coding Agent Instructions
+
+## Quick Orientation
+- Multi-framework system (Web Components + Angular, Blazor, React wrappers). Core packages live under `packages/`.
+- FAST Foundation is the underlying component model; tokens come from `@ni/nimble-tokens`.
+- Variants: Nimble (general), Spright (specialized), Ok (incubating). Each has its own `copilot-instructions.md` for details.
+
+For repo-wide processes and tooling details, see [`CONTRIBUTING.md`](../CONTRIBUTING.md).
+
+## Core Workflows
+```bash
+# Install & build everything
+npm install && npm run build
+
+# Watch mode (recommended): Command Palette → "Run Task" → "Create Watch Terminals"
+
+# Storybook + tests (run from repo root)
+
+npm run tdd:watch -w @ni/nimble-components
+npm run test-webkit -w @ni/nimble-components
+
+# Generate change files before PRs that touch published packages
+npm run change
+```
+
+## Change Management
+- Every PR impacting a published package needs a beachball change file (`npm run change`). See the "Beachball change file" section of [`CONTRIBUTING.md`](../CONTRIBUTING.md).
+- Keep builds/test scripts passing locally before queuing CI.
+
+## Component Development
+- **Guidelines**: Follow [`packages/nimble-components/CONTRIBUTING.md`](../packages/nimble-components/CONTRIBUTING.md).
+- **Snippets**: See [`packages/nimble-components/copilot-instructions.md`](../packages/nimble-components/copilot-instructions.md) for registration, styling, and testing templates.
+- **Registration**: Use `DesignSystem.getOrCreate().withPrefix(...)`.
+- **Bundling**: Update `src/all-components.ts`.
+
+## Styling & Storybook
+- **Styling**: Use design tokens (`theme-provider/design-tokens.ts`). See [`docs/css-guidelines.md`](../packages/nimble-components/docs/css-guidelines.md) for cascade layers and utilities.
+- **Storybook**: Required for all components (`.stories.ts`, `-matrix.stories.ts`, `.mdx`). See [`packages/storybook/CONTRIBUTING.md`](../packages/storybook/CONTRIBUTING.md).
+
+## Testing Expectations
+- Unit tests use Karma/Jasmine fixtures (`npm run tdd:watch -w @ni/nimble-components`).
+- Cross-browser coverage: Chrome, Firefox, WebKit (`npm run test-webkit -w @ni/nimble-components`).
+- Disable flaky tests only with an issue link and browser-specific skip tag as outlined in package CONTRIBUTING docs.
+
+## Common Pitfalls
+- ❌ Forgetting `npm run change` when touching published packages.
+- ❌ Styling component state via classes instead of attributes/behaviors.
+- ❌ Hardcoding tag names inside templates instead of importing tag constants.
+- ❌ Skipping Storybook docs/matrix updates when component APIs change.
+- ❌ Not running formatter/tests before pushing (`npm run format`, `npm run tdd:watch`).
+
+## Key References
+- Architecture: `../docs/Architecture.md`
+- Repo contributing guide: `../CONTRIBUTING.md`
+- Nimble component guide: `../packages/nimble-components/CONTRIBUTING.md`
+- CSS guidelines: `../packages/nimble-components/docs/css-guidelines.md`
+- Storybook authoring guide: `../packages/storybook/CONTRIBUTING.md`
+- Specs overview: `../specs/README.md`

.github/prompts/nimble.update-copilot-instructions.prompt.md

@@ -0,0 +1,68 @@
+---
+name: nimble.update-copilot-instructions
+description: Synchronize the AI coding agent instructions with the latest project documentation and patterns.
+---
+
+**Goal**: Synchronize the AI coding agent instructions (`copilot-instructions.md`) with the latest project documentation and patterns.
+
+**Role**: You are an expert maintainer of the Nimble Design System. Your job is to ensure that the instructions provided to AI agents are accurate, concise, and up-to-date.
+
+## Guiding Principles
+
+Follow GitHub's best practices for instruction files (see [Unlocking the Full Power of Copilot Code Review: Master Your Instructions Files](https://github.blog/ai-and-ml/unlocking-the-full-power-of-copilot-code-review-master-your-instructions-files/)):
+
+1. **Prefer Links Over Duplication**: Link to existing documentation (CONTRIBUTING.md, specs, guidelines) rather than duplicating content. This reduces maintenance burden and ensures single source of truth.
+2. **Essential Information Only**: Include only critical patterns, gotchas, and quick-reference snippets that AI agents need immediately. Detailed documentation belongs in the linked files.
+3. **Code Snippets for Common Patterns**: Include concise, verified code examples for frequently-used patterns (component registration, testing setup, templates, styles) that would otherwise require multiple file reads.
+4. **Maintainability**: Every duplicated line is a maintenance liability. Ask: "Does this need to be here, or can we link to it?"
+
+## Context Sources
+Read the following files to understand the current "source of truth":
+1.  `CONTRIBUTING.md` (Root)
+2.  `packages/nimble-components/CONTRIBUTING.md`
+4.  `packages/nimble-components/docs/css-guidelines.md`
+2.  `packages/spright-components/CONTRIBUTING.md`
+3.  `packages/ok-components/CONTRIBUTING.md`
+5.  `packages/storybook/CONTRIBUTING.md`
+6.  `packages/storybook/src/docs/component-status.mdx`
+
+## Target Files
+You will be updating the following instruction files:
+1.  `.github/copilot-instructions.md` (Global instructions)
+2.  `packages/nimble-components/copilot-instructions.md`
+3.  `packages/ok-components/copilot-instructions.md`
+4.  `packages/spright-components/copilot-instructions.md`
+
+## Instructions
+
+1.  **Analyze Changes**: Compare the "Context Sources" against the "Target Files". Look for:
+    *   New build commands or workflow steps.
+    *   Changes to file structure or naming conventions.
+    *   New required patterns (e.g., new testing requirements).
+    *   Deprecated patterns that should be removed from instructions.
+
+2.  **Verify Code Snippets**:
+    *   Check that the code snippets in `copilot-instructions.md` (e.g., `index.ts` boilerplate, `styles.ts` patterns) match the current best practices found in the codebase.
+    *   **Only include snippets that are**: (a) used frequently, (b) hard to infer from docs alone, (c) critical to get right.
+    *   *Tip*: You may need to read a few actual component files (e.g., `packages/nimble-components/src/button/index.ts`) to verify the patterns are still valid.
+
+3.  **Reduce Duplication**:
+    *   Review all duplicated content. Can it be replaced with a link + 1-sentence summary?
+    *   Keep: Command references, critical patterns, common pitfalls with examples.
+    *   Remove: Detailed explanations that exist in linked docs, policy details, extended rationale.
+
+4.  **Update Global Instructions** (`.github/copilot-instructions.md`):
+    *   Ensure links to documentation are correct.
+    *   Update "Common Pitfalls" if new recurring issues have been identified.
+    *   Keep it high-level: Architecture, Workflows, and Global Patterns.
+    *   Prefer "See [doc](link)" over copying paragraphs.
+
+5.  **Update Package Instructions**:
+    *   **Nimble**: Ensure specific implementation details (registration, testing fixtures) are accurate and minimal.
+    *   **Ok/Spright**: Ensure the "Requirements vs Nimble" comparison is still accurate.
+    *   Link to detailed guidelines rather than duplicating them.
+
+6.  **Output**:
+    *   Present the changes as file edits (using `replace_string_in_file` or by showing the diff).
+    *   If no changes are needed, explicitly state that the instructions are up-to-date.
+    *   If removing duplicated content, briefly explain what was removed and where to find it.

change/@ni-nimble-components-79471e83-b6f9-4e4c-87c1-b9f116082cbc.json

@@ -0,0 +1,7 @@
+{
+  "type": "none",
+  "comment": "add copilot instructions",
+  "packageName": "@ni/nimble-components",
+  "email": "[email protected]",
+  "dependentChangeType": "none"
+}

change/@ni-ok-components-569fa1f4-38db-428f-b9dc-063ea8792277.json

@@ -0,0 +1,7 @@
+{
+  "type": "none",
+  "comment": "add copilot instructions",
+  "packageName": "@ni/ok-components",
+  "email": "[email protected]",
+  "dependentChangeType": "none"
+}

change/@ni-spright-components-d5cb586b-b2f6-4f9a-9390-2f81c4c8cdb2.json

@@ -0,0 +1,7 @@
+{
+  "type": "none",
+  "comment": "add copilot instructions",
+  "packageName": "@ni/spright-components",
+  "email": "[email protected]",
+  "dependentChangeType": "none"
+}

packages/nimble-components/copilot-instructions.md

@@ -0,0 +1,108 @@
+# Nimble Components – AI Instructions
+
+## Key References
+
+- [`CONTRIBUTING.md`](../../CONTRIBUTING.md) (repo) – build/test/change workflows.
+- [`packages/nimble-components/CONTRIBUTING.md`](CONTRIBUTING.md) – component lifecycle, Storybook, accessibility.
+- [`docs/css-guidelines.md`](docs/css-guidelines.md) – cascade layers, `display()` utility, attribute-driven states.
+- [`docs/coding-conventions.md`](docs/coding-conventions.md) – const-object enums, comment expectations.
+
+## Component Skeleton
+
+### `index.ts`
+
+```typescript
+import { attr } from '@ni/fast-element';
+import { DesignSystem, FoundationElement } from '@ni/fast-foundation';
+import { styles } from './styles';
+import { template } from './template';
+
+declare global {
+    interface HTMLElementTagNameMap {
+        'nimble-example': Example;
+    }
+}
+
+export class Example extends FoundationElement {
+    @attr({ attribute: 'my-attribute' })
+    public myAttribute?: string;
+}
+
+const nimbleExample = Example.compose({
+    baseName: 'example',
+    baseClass: FoundationElement,
+    template,
+    styles
+});
+
+DesignSystem.getOrCreate().withPrefix('nimble').register(nimbleExample());
+export const exampleTag = 'nimble-example';
+```
+
+- Always export the tag constant and update `src/all-components.ts` so bundles include the component.
+- Extend the FAST base (`baseClass`) whenever one exists; otherwise extend `FoundationElement`.
+- Add `tabIndex` reflection and `shadowOptions.delegatesFocus` when components contain focusable internals.
+
+### `styles.ts`
+
+```typescript
+import { css } from '@ni/fast-element';
+import { display } from '../utilities/style/display';
+import { bodyFont } from '../theme-provider/design-tokens';
+
+export const styles = css`
+    @layer base, hover, focusVisible, active, disabled, top;
+
+    ${display('flex')}
+
+    @layer base {
+        :host {
+            font: ${bodyFont};
+        }
+    }
+`;
+```
+
+- Use design tokens; never hardcode `var(--ni-nimble-*)` names.
+- Organize selectors by document order per `docs/css-guidelines.md`.
+- Prefer attribute selectors/behaviors to drive state instead of classes.
+
+### `tests/*.spec.ts`
+
+```typescript
+import { html } from '@ni/fast-element';
+import { fixture, type Fixture } from '../../utilities/tests/fixture';
+import { Example, exampleTag } from '..';
+
+describe('Example', () => {
+    async function setup(): Promise<Fixture<Example>> {
+        return fixture<Example>(html`<${exampleTag}></${exampleTag}>`);
+    }
+
+    it('constructs a nimble-example', () => {
+        expect(document.createElement(exampleTag)).toBeInstanceOf(Example);
+    });
+
+    it('updates when attribute changes', async () => {
+        const { element, connect, disconnect } = await setup();
+        await connect();
+
+        element.setAttribute('my-attribute', 'value');
+
+        expect(element.myAttribute).toBe('value');
+        await disconnect();
+    });
+});
+```
+
+- Use the fixture helpers for lifecycle management; disconnect in tests to prevent leaks.
+- Tag browser-specific skips with `#SkipChrome|Firefox|Webkit` and include an issue link.
+
+## Development Checklist
+
+- Create `index.ts`, `styles.ts`, `template.ts`, `types.ts` (const-object enums only), `tests/`, and `stories/` as required by the package CONTRIBUTING guide.
+- Register the component with the proper prefix (`nimble`, `spright`, `ok`) and export the tag constant.
+- Add Storybook artifacts: `*.stories.ts`, `*-matrix.stories.ts`, and `*.mdx`.
+- Update label-provider metadata and component status stories when APIs change.
+- **Testing**: Always use `fdescribe` or `fit` to focus on relevant test suites before running `npm run tdd -w @ni/nimble-components`. The full test suite takes too long and may have unrelated failures.
+- Run `npm run tdd:watch -w @ni/nimble-components`, `npm run storybook`, and `npm run format` before sending revisions.

packages/ok-components/copilot-instructions.md

@@ -0,0 +1,32 @@
+# Ok Components – AI Instructions
+
+## Key References
+
+- [`CONTRIBUTING.md`](CONTRIBUTING.md) – Ownership, code quality, and documentation requirements.
+
+## Context
+
+- **Package**: `@ni/ok-components` (incubating experiments built on Nimble patterns).
+- **Prefix**: `ok-` when registering custom elements via `DesignSystem.getOrCreate().withPrefix('ok')`.
+- **Ownership**: Feature team owns implementation; Nimble team owns shared tooling and reviews for repo health.
+
+## Build & Workflow
+
+- Use the same commands as Nimble components (see [`../nimble-components/copilot-instructions.md`](../nimble-components/copilot-instructions.md)).
+- Generate beachball change files whenever the package changes.
+- Provide Storybook docs/matrix + unit tests for every new component, even while incubating.
+
+## Requirements vs Nimble
+
+| Area                 | Nimble             | Ok                                                |
+| -------------------- | ------------------ | ------------------------------------------------- |
+| Spec completeness    | Required           | Optional – document scope gaps in Storybook       |
+| Accessibility polish | Required           | In-progress allowed, but note limitations         |
+| Framework wrappers   | Required over time | Optional unless feature explicitly needs wrappers |
+| Owner team           | Nimble             | Contributing feature team                         |
+
+## Expectations
+
+- Follow the coding, styling, and testing conventions in the Nimble instructions; only deviate if explicitly documented in the component specs.
+- Clearly call out incubating gaps in docs (e.g., Storybook banner, component status table ⚠️ entry).
+- Contributing team is responsible for addressing regressions, flaky tests, and build perf issues originating from this package.

packages/spright-components/copilot-instructions.md

@@ -0,0 +1,41 @@
+# Spright Components – AI Instructions
+
+## Key References
+
+- [`CONTRIBUTING.md`](CONTRIBUTING.md) – Ownership, code quality, and documentation requirements.
+
+## Context
+
+- **Package**: `@ni/spright-components` (specialized components that must still align with Nimble quality).
+- **Prefix**: `spright-` (`DesignSystem.getOrCreate().withPrefix('spright')`).
+- **Ownership**: Shared between the Nimble team and the feature team delivering the Spright experience.
+
+## Development Guidelines
+
+- Build/test/storybook commands mirror Nimble components (see [`../nimble-components/copilot-instructions.md`](../nimble-components/copilot-instructions.md)).
+- Implement the same component skeleton (registration, template, styles, tests, docs). Link to the Nimble instructions rather than duplicating snippets.
+- Document any domain-specific deviations (tokens, behaviors, wrappers) inside the component specs and Storybook docs.
+
+## Requirements vs Nimble
+
+|                        | `nimble-components` | `spright-components` |
+| ---------------------- | :-----------------: | :------------------: |
+| Approved spec          |         🟢          |          🟢          |
+| Unit tests             |         🟢          |          🟢          |
+| Storybook visual tests |         🟢          |          🟢          |
+| Storybook API docs     |         🟢          |          🟢          |
+| Storybook usage docs   |         🟢          |          🟡          |
+| Approved VxD\*         |         🟢          |          🟡          |
+| Approved IxD\*         |         🟢          |          🟡          |
+| Angular/Blazor support |         🟢          |          🟡          |
+| Proper a11y            |         🟢          |          🟡          |
+| Minimal tech debt      |         🟢          |          🟡          |
+| Mobile support         |         🟡          |          🟡          |
+
+🟢 = required, 🟡 = optional\*By an interaction and/or visual designer
+
+## Code Ownership
+
+- Nimble team reviews for architecture, tokens, accessibility, and repo health.
+- Contributing team owns roadmap delivery, bug fixes, and maintenance for Spright-specific behaviors.
+- Coordinate on design tokens and shared utilities to avoid divergence from Nimble.