|
| 1 | +<!-- |
| 2 | +SPDX-FileCopyrightText: 2026 Siemens AG |
| 3 | +
|
| 4 | +SPDX-License-Identifier: MIT |
| 5 | +--> |
| 6 | + |
| 7 | +# AGENTS.md |
| 8 | + |
| 9 | +This guide is for humans and AI agents developing inside the Siemens IX monorepo. |
| 10 | + |
| 11 | +## Agent operating principles |
| 12 | + |
| 13 | +- Act as a senior maintainer: inspect existing patterns before changing code, keep changes scoped, and prefer correctness over speed. |
| 14 | +- Change source files, not generated artifacts. If generated output is affected, update the source and run the appropriate build/generation step. |
| 15 | +- Preserve unrelated user or maintainer changes in the working tree. Do not revert, reformat, or rewrite files outside the requested scope. |
| 16 | +- Use the smallest targeted validation that proves the change, then escalate only when needed. |
| 17 | +- Prefer explicit, type-safe fixes over broad fallbacks, silent returns, or catch-all error handling. |
| 18 | +- Update tests, documentation, examples, and changesets whenever the user-facing behavior, API, styling, accessibility, or package output changes. |
| 19 | + |
| 20 | +## Source of truth and precedence |
| 21 | + |
| 22 | +Use these resources together (in this order when conflicts appear): |
| 23 | + |
| 24 | +1. `CONTRIBUTING.md` |
| 25 | +2. `ARCHITECTURE.md` |
| 26 | +3. `.github/copilot-instructions.md` |
| 27 | +4. `.github/instructions/*.instructions.md` |
| 28 | + |
| 29 | +## Repository architecture (must-know) |
| 30 | + |
| 31 | +- `packages/core` is the source of truth (Stencil Web Components). |
| 32 | +- `packages/react`, `packages/angular`, `packages/vue` are wrapper packages generated from Stencil output targets. |
| 33 | +- Do not hand-edit generated proxy files (look for auto-generated comments). |
| 34 | +- Theme integrations for third-party libraries live in `packages/aggrid` and `packages/echarts`. |
| 35 | + |
| 36 | +## Environment and package manager |
| 37 | + |
| 38 | +- Use the package manager declared in `package.json`: `pnpm@10.17.0`. |
| 39 | +- Use Node.js `22.19.0`; Volta is configured for this version. |
| 40 | +- Install dependencies from the repository root with `pnpm install`. |
| 41 | +- Do not introduce new package managers, lockfiles, formatters, linters, or test runners. |
| 42 | +- Add dependencies only when they are required for the implementation, and keep workspace dependencies as `workspace:*` where applicable. |
| 43 | + |
| 44 | +## Development rules |
| 45 | + |
| 46 | +- Prefer changing `packages/core` first for component behavior, API, styling, accessibility, and docs metadata. |
| 47 | +- Keep component structure consistent: `<component>.tsx`, `<component>.scss`, tests in `test/`. |
| 48 | +- Use SPDX headers for new source files. |
| 49 | +- Use design tokens/CSS custom properties instead of hard-coded theme values. |
| 50 | +- Keep accessibility parity across frameworks. |
| 51 | +- Reuse existing helpers, utilities, tokens, test fixtures, and component patterns before adding new abstractions. |
| 52 | +- Avoid arbitrary waits, global side effects, and behavior changes that are not explicitly required. |
| 53 | +- For breaking changes, provide migration guidance and update `BREAKING_CHANGES.md`. |
| 54 | + |
| 55 | +## Package-specific guidance |
| 56 | + |
| 57 | +| Package area | Edit guidance | |
| 58 | +| --- | --- | |
| 59 | +| `packages/core` | Source of truth for Web Components, styles, accessibility, docs metadata, and generated wrapper input. | |
| 60 | +| `packages/react`, `packages/angular`, `packages/vue` | Do not edit generated proxy files. Only edit deliberate hand-written helpers, examples, or package-specific integration code. | |
| 61 | +| `packages/aggrid`, `packages/echarts` | Keep integrations aligned with IX design tokens and theme classes. Validate visual/theming impact. | |
| 62 | +| `packages/documentation` | Update docs generation logic only when documentation output or example extraction changes. | |
| 63 | +| `*-test-app` packages | Use for framework examples, previews, and documentation snippets. Keep examples consumer-realistic. | |
| 64 | + |
| 65 | +## Local workflow |
| 66 | + |
| 67 | +```bash |
| 68 | +pnpm install |
| 69 | +pnpm storybook |
| 70 | +pnpm build |
| 71 | +pnpm lint |
| 72 | +pnpm test |
| 73 | +``` |
| 74 | + |
| 75 | +Targeted commands: |
| 76 | + |
| 77 | +- Build single package: `pnpm build --filter @siemens/ix` |
| 78 | +- Core component tests (watch): `pnpm --filter @siemens/ix test.ct --watch` |
| 79 | +- Run visual regression (after build): `pnpm visual-regression` |
| 80 | +- Core unit tests: `pnpm --filter @siemens/ix test.spec` |
| 81 | +- Core component tests: `pnpm --filter @siemens/ix test.ct` |
| 82 | +- Package lint: `pnpm lint --filter <package-name>` |
| 83 | +- Package tests: `pnpm test --filter <package-name>` |
| 84 | + |
| 85 | +## Testing expectations |
| 86 | + |
| 87 | +- Build before tests when compiled artifacts, generated wrappers, styles, or visual/component tests depend on build output. |
| 88 | +- `packages/core` is the main place for component tests. Core component tests live at `packages/core/src/components/<component>/test/<component>.ct.ts`. |
| 89 | +- Use core component tests for component behavior, interaction, keyboard handling, accessibility, slots, events, and state changes. |
| 90 | +- Include accessibility coverage (`makeAxeBuilder`) and a basic hydration/render test in component test files. |
| 91 | +- Add or update unit tests for pure logic changes, component tests for interaction/accessibility changes, and visual tests only for meaningful UI or theme changes. |
| 92 | +- Prefer Playwright locators, user-visible assertions, and deterministic waits over implementation-detail selectors and timeouts. |
| 93 | + |
| 94 | +## Visual regression testing |
| 95 | + |
| 96 | +- Visual regression tests live in `testing/visual-testing`. |
| 97 | +- Visual regression tests run inside a Docker container so screenshots are operating-system agnostic and less affected by local fonts, browsers, or rendering differences. |
| 98 | +- Visual regression tests are slow. Keep them focused on visual contracts, not every behavior or edge case. |
| 99 | +- For a new feature, prefer one representative screenshot that covers the intended visual state instead of creating a separate screenshot for every feature branch, state, or testcase. |
| 100 | +- Use component tests in `packages/core` for exhaustive behavior coverage, and visual regression only to protect layout, theme, density, color, spacing, and screenshot-visible regressions. |
| 101 | +- For UI/theming changes, run relevant visual regression tests after `pnpm build --filter !documentation`; Docker must be available. |
| 102 | + |
| 103 | +## Documentation and examples |
| 104 | + |
| 105 | +- Component documentation is maintained in the separate `siemens/ix-docs` repository. |
| 106 | +- In this repository, update component JSDoc, metadata inputs, Storybook stories, or test-app examples when public usage changes. |
| 107 | +- If a change requires user-facing documentation updates, call out the needed `siemens/ix-docs` follow-up in the PR. |
| 108 | +- Keep docs and examples aligned across Web Components, Angular, React, and Vue when the behavior is framework-visible. |
| 109 | +- Do not document generated implementation details as public API. |
| 110 | +- Ensure examples use supported imports, current component names, and realistic consumer code. |
| 111 | + |
| 112 | +## Changesets and release impact |
| 113 | + |
| 114 | +- Any user-facing change needs a changeset in `.changeset/`. |
| 115 | +- This includes API changes, behavior changes, styling/theming updates, accessibility changes, and meaningful bug fixes. |
| 116 | +- If a change is internal-only, state that clearly in PR description/review context. |
| 117 | +- For breaking changes, update `BREAKING_CHANGES.md` and provide migration notes. |
| 118 | +- Choose affected packages based on what consumers install or observe, not only where source files changed. |
| 119 | +- Use `patch` for bug fixes and compatible styling/accessibility fixes, `minor` for new backwards-compatible APIs/features, and `major` for breaking API or behavior changes. |
| 120 | +- Keep changeset summaries consumer-focused: describe what changed and why it matters, not internal implementation details. |
| 121 | + |
| 122 | +## PR and commit expectations |
| 123 | + |
| 124 | +- PR title format: `<type>[optional <scope>]: <description>` (for example: `fix(core): correct button color`). |
| 125 | +- Link requirement context in PR description/commit message (GitHub issue or `IX-<number>`). |
| 126 | +- Explain user-facing impact and implementation details clearly. |
| 127 | +- Mention validation performed and any intentionally skipped validation with a reason. |
| 128 | +- Call out generated files, migration notes, and release impact when relevant. |
| 129 | + |
| 130 | +## Component-test conventions (core) |
| 131 | + |
| 132 | +- Use `regressionTest` from `@utils/test` (not plain Playwright `test`). |
| 133 | +- Use Playwright locators (including for Shadow DOM assertions). |
| 134 | +- Avoid arbitrary timeouts (`waitForTimeout`). |
| 135 | +- Register icons via mount config; do not fetch static SVG files directly in tests. |
| 136 | + |
| 137 | +## Security and contribution hygiene |
| 138 | + |
| 139 | +- Do not report security issues publicly in GitHub issues; follow `SECURITY.md` / `CONTRIBUTING.md` private reporting path. |
| 140 | +- Keep changes scoped and package-aware. |
| 141 | +- Do not edit unrelated files while implementing a focused change. |
| 142 | +- Never commit secrets, credentials, private tokens, local environment files, or machine-specific paths. |
| 143 | +- Treat public APIs, accessibility behavior, theming tokens, and generated package output as consumer contracts. |
| 144 | +- Do not add telemetry, network calls, or dependency downloads without a clear project-approved reason. |
| 145 | + |
| 146 | +## Quick execution checklist |
| 147 | + |
| 148 | +1. Confirm target package(s) and whether `core` is the correct edit point. |
| 149 | +2. Inspect nearby existing patterns, tests, docs, and package scripts. |
| 150 | +3. Implement changes in source (not generated output). |
| 151 | +4. Update tests, examples, docs, and generated inputs as needed. |
| 152 | +5. Run the smallest meaningful build/test/lint commands; run visual regression for relevant UI/theme changes. |
| 153 | +6. Add/update a changeset if the change is user-facing. |
| 154 | +7. Ensure PR summary includes impact, linked requirement, validation, affected packages, and migration notes if breaking. |
0 commit comments