Documentation for dev and copilot

.config/.jscpd.json

@@ -12,6 +12,7 @@
 		"**/.next/**",
 		"**/.nuxt/**",
 		"**/.output/**",
+		"**/agent/**",
 		"**/.vscode/**",
 		"**/*-example/index.html",
 		"**/*-showcase/index.html",

.github/workflows/01-build-outputs.yml

@@ -39,6 +39,12 @@ jobs:
           name: db-ux-stylelint-build
           path: packages/stylelint/build
 
+      - name: ⏬ Download agent-cli build
+        uses: actions/download-artifact@v4
+        with:
+          name: db-ux-agent-cli-build
+          path: packages/agent-cli/build
+
       - name: ⏬ Download output
         uses: actions/download-artifact@v4
         with:
@@ -51,7 +57,9 @@ jobs:
           install-command: npm i
 
       - name: 🔨 Build outputs
-        run: npm run build-outputs
+        run: |
+          npm run generate:agent
+          npm run build-outputs
 
       - name: ⏫ Upload outputs
         uses: actions/upload-artifact@v4

.github/workflows/01-build-packages.yml

@@ -48,6 +48,12 @@ jobs:
           name: db-ux-stylelint-build
           path: packages/stylelint/build
 
+      - name: ⏫ Upload agent-cli build
+        uses: actions/upload-artifact@v4
+        with:
+          name: db-ux-agent-cli-build
+          path: packages/agent-cli/build
+
       - name: 💀 Killing me softly
         uses: ./.github/actions/cancel-workflow
         if: failure()

.gitignore

@@ -1,5 +1,6 @@
 .DS_Store
 node_modules
+!packages/agent-cli/test/**/node_modules
 npm-debug.log
 .history
 .idea
@@ -66,3 +67,6 @@ showcases/patternhub/public/iframe-resizer/*
 /scripts/public/
 /scripts/gh-pages.tar.gz
 !/scripts/tests/fixtures/out
+/output/**/docs/
+/output/**/agent/
+/packages/agent-cli/test/.github/copilot-instructions.md

.markdownlintignore

@@ -7,3 +7,4 @@ build-outputs/**
 build-showcases/**
 showcases/**/public/**
 CODE-OF-CONDUCT.md
+**/agent/**

docs/adr/adr-05-copilot-developer-doc.md

@@ -0,0 +1,77 @@
+# ADR 2025-06-10: Documentation strategy for GitHub Copilot and developer docs
+
+## Context
+
+We need a consistent, maintainable documentation approach that serves both developers and AI-assisted coding
+tools (GitHub Copilot) without duplicating effort. The documentation must cover component usage, variants, props,
+examples, and allow Copilot to answer questions like "What variants does the Button support?" without manually
+opening multiple files.
+
+Key requirements:
+
+- Single source of truth for component documentation.
+- Automatic inclusion of context in Copilot Chat for both IDEs, VS Code and IntelliJ.
+- Developer-friendly Markdown for manual reading and static site generation.
+- Compatibility with LLM context conventions (llms.txt) and Copilot Custom Instructions (copilot-instructions.md).
+
+## Decision
+
+1. Documentation Format & Location
+
+    - Use Markdown files per component, stored in packages/components/docs/ or packages/components/src/components/docs/.
+    - Central table of contents in docs/llms.txt listing all component docs with relative paths.
+
+2. Copilot Custom Instructions
+
+    - Place copilot-instructions.md in the project root (under .github/) to provide global guidance.
+    - Instruct Copilot Chat to load this file automatically; it will include links to llms.txt and recommended file paths.
+
+3. Automatic Context Loading
+
+    - In VS Code and IntelliJ, Copilot Chat will automatically read .github/copilot-instructions.md on new chats.
+    - To surface specific details, embed documentation (e.g., Button.md) directly in copilot-instructions.md.
+
+4. Interactive Context Attachment
+
+    - For deeper or ad-hoc queries, use the "Attach Context" feature in Copilot Chat to load component Markdown files during the session.
+
+5. Static Site & Developer Docs
+
+    - Integrate component docs via Astro as a package in the monorepo, referencing Markdown sources in packages/components/... .
+    - Render pages dynamically under /components/[slug] and /api/[slug] for manual browsing.
+
+6. Automated Propagation of Copilot Instructions
+
+    We add a `postinstall` hook to our component package that:
+
+    - copies or appends the package-specific file `.github/copilot-instructions.md` to the target project,
+    - uses unique markers to automatically replace outdated blocks during future installations,
+    - handles missing or already existing files as well as idempotent updates cleanly, ensuring that every installation immediately provides the latest Copilot context for our package.
+
+7. Automate generation and propagation of Copilot instructions on package build.
+
+    - Define `generate:copilot-instructions` in `package.json` and hook into `prepare`.
+    - Only include `*.md` files whose filename matches the parent directory converted to PascalCase (e.g. `custom-select` → `CustomSelect.md`), ensuring no unrelated MDs are merged.
+
+## Alternatives Considered
+
+- Rely solely on Code Search: Let Copilot use workspace search to locate docs dynamically. Rejected due to inconsistency and limited to agent mode.
+- TypeDoc-only approach: Generate API docs from TypeScript. Provides type detail but lacks usage narratives and cross-framework examples.
+- Mitosis Metadata Model: Embed JSON metadata via useMetadata and generate docs. Promising, but requires custom plugins and not widely adopted yet.
+
+## Consequences
+
+- Pros:
+
+    - Clear separation: manual design guidance (Markdown) vs. AI context (Instructions + llms.txt snippets).
+    - Maintains single source (docs in packages/components/docs).
+    - Enables Copilot to provide accurate, component-specific suggestions without manual file opening.
+    - Developer site generation remains straightforward via Astro.
+    - Consumers always receive the latest Copilot context without manual steps.
+    - Guarantees that only the intended component documentation is merged into Copilot instructions.
+
+- Cons:
+    - Requires maintaining excerpts in copilot-instructions.md when docs change.
+    - Copilot cannot truly auto-load all linked docs; manual attachment or excerpt embedding needed for deep context.
+    - Postinstall hooks may be disabled for security reasons, making it impossible to automate the copying of the copilot instructions.
+    - Relies on strict naming conventions; any divergence between folder and file names will cause a component’s docs to be skipped.

output/angular/README.md

@@ -113,6 +113,17 @@ There are 3 ways to use Events in Angular:
 ></db-input>
 ```
 
+## Documentation for AI Agents
+
+We provide a documentation for every component in the DB UX Design System via `docs` folder.
+To consume those documentation for AI Agents the best way is to copy the `docs` folder into your project.
+
+We provide a CLI tool to do this automatically, which you can run with:
+
+```shell
+npx @db-ux/agent-cli
+```
+
 ## Deutsche Bahn brand
 
 As we'd like to perfectly support our users and customers on their digital journey, the usage of Deutsche Bahn brand and trademarks are bound of clear guidelines and restrictions even if being used with the code that we're providing with this product; Deutsche Bahn fully reserves all rights regarding the Deutsche Bahn brand, even though that we're providing the code of DB UX Design System products free to use and release it under the Apache 2.0 license.

output/angular/package.json

@@ -10,9 +10,15 @@
   "main": "dist/fesm5.js",
   "module": "dist/fesm5.js",
   "types": "dist/core.d.ts",
+  "files": [
+    "dist/",
+    "agent"
+  ],
   "scripts": {
     "build": "ng build",
+    "mv:agent": "cpr agent ../../build-outputs/angular/agent -o",
     "ng": "ng",
+    "postbuild": "npm-run-all -p mv:*",
     "start": "ng serve"
   },
   "devDependencies": {

output/react/README.md

@@ -59,6 +59,17 @@ import { DBButton } from '@db-ux/react-core-components';
 ...
 ```
 
+## Documentation for AI Agents
+
+We provide a documentation for every component in the DB UX Design System via `docs` folder.
+To consume those documentation for AI Agents the best way is to copy the `docs` folder into your project.
+
+We provide a CLI tool to do this automatically, which you can run with:
+
+```shell
+npx @db-ux/agent-cli
+```
+
 ## Deutsche Bahn brand
 
 As we'd like to perfectly support our users and customers on their digital journey, the usage of Deutsche Bahn brand and trademarks are bound of clear guidelines and restrictions even if being used with the code that we're providing with this product; Deutsche Bahn fully reserves all rights regarding the Deutsche Bahn brand, even though that we're providing the code of DB UX Design System products free to use and release it under the Apache 2.0 license.

output/react/package.json

@@ -11,11 +11,13 @@
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
-    "dist/"
+    "dist/",
+    "agent"
   ],
   "scripts": {
     "build": "npm-run-all tsc",
     "mv:dist": "cpr dist ../../build-outputs/react/dist --overwrite",
+    "mv:agent": "cpr agent ../../build-outputs/react/agent -o",
     "mv:package.json": "cpr package.json ../../build-outputs/react/package.json --overwrite",
     "mv:readme": "cpr README.md ../../build-outputs/react/README.md --overwrite",
     "open:report": "npx playwright show-report",

output/stencil/README.md

@@ -74,6 +74,16 @@ If you don't have it already, add a VS Code settings folder and file at the root
 }
 ```
 
+## Documentation for AI Agents
+
+We provide a documentation for every component in the DB UX Design System via `docs` folder.
+To consume those documentation for AI Agents the best way is to copy the `docs` folder into your project.
+
+We provide a CLI tool to do this automatically, which you can run with:
+
+```shell
+npx @db-ux/agent-cli
+```
 
 ## Deutsche Bahn brand
 

output/stencil/package.json

@@ -17,12 +17,14 @@
     }
   },
   "files": [
-    "dist/"
+    "dist/",
+    "agent"
   ],
   "scripts": {
     "build": "stencil build",
     "build:cem": "cem analyze",
     "mv:dist": "cpr dist ../../build-outputs/wc-core-components/dist -o",
+    "mv:agent": "cpr agent ../../build-outputs/wc-core-components/agent -o",
     "mv:package.json": "cpr package.json ../../build-outputs/wc-core-components/package.json -o",
     "mv:readme": "cpr README.md ../../build-outputs/wc-core-components/README.md -o",
     "postbuild": "npm-run-all --parallel build:* --parallel mv:*",

output/stencil/scripts/packageLinkPhase.js

@@ -166,7 +166,7 @@ const resolveAllUnions = (resolvedData, resolvedProps, resolvedUnions) => {
 };
 
 const resolveManifestTypes = (resolvedUnions, manifestValues) =>
-	manifestValues.map((manifestValue) => {
+	manifestValues?.map((manifestValue) => {
 		if (!manifestValue.type) {
 			// those are methods
 			return manifestValue;
@@ -219,12 +219,12 @@ export const packageLinkPhase = (
 	resolveAllUnions(resolvedData, resolvedProps, resolvedUnions);
 
 	customElementsManifest.modules = customElementsManifest.modules
-		.filter(
+		?.filter(
 			// We just need the .tsx files for elements
 			(module) => module.path.endsWith('.tsx')
 		)
 		.map((module) => {
-			const declarations = module.declarations.map((declaration) => {
+			const declarations = module.declarations?.map((declaration) => {
 				const members = resolveManifestTypes(
 					resolvedUnions,
 					declaration.members
@@ -234,7 +234,7 @@ export const packageLinkPhase = (
 					declaration.attributes
 				);
 
-				const slots = declaration.slots.map((slot) => ({
+				const slots = declaration.slots?.map((slot) => ({
 					name: slot.name,
 					description:
 						resolvedUnions[

output/vue/README.md

@@ -95,6 +95,17 @@ Both Inputs in this example do the same:
 </template>
 ```
 
+## Documentation for AI Agents
+
+We provide a documentation for every component in the DB UX Design System via `docs` folder.
+To consume those documentation for AI Agents the best way is to copy the `docs` folder into your project.
+
+We provide a CLI tool to do this automatically, which you can run with:
+
+```shell
+npx @db-ux/agent-cli
+```
+
 ## Deutsche Bahn brand
 
 As we'd like to perfectly support our users and customers on their digital journey, the usage of Deutsche Bahn brand and trademarks are bound of clear guidelines and restrictions even if being used with the code that we're providing with this product; Deutsche Bahn fully reserves all rights regarding the Deutsche Bahn brand, even though that we're providing the code of DB UX Design System products free to use and release it under the Apache 2.0 license.

output/vue/package.json

@@ -23,13 +23,15 @@
     }
   },
   "files": [
-    "dist/"
+    "dist/",
+    "agent"
   ],
   "scripts": {
     "build": "npm-run-all build:*",
     "build:01_vite": "vite build",
     "build:02_types": "vue-tsc --declaration --emitDeclarationOnly",
     "mv:dist": "cpr dist ../../build-outputs/vue/dist --overwrite",
+    "mv:agent": "cpr agent ../../build-outputs/vue/agent -o",
     "mv:package.json": "cpr package.json ../../build-outputs/vue/package.json --overwrite",
     "mv:readme": "cpr README.md ../../build-outputs/vue/README.md --overwrite",
     "postbuild": "npm-run-all --parallel mv:*",