docs(ai-knowledge-base): add on-demand reference for development for AI Assistants

[hinzzx]

Overview

As a part of the AI Initiative (Skills, Plugins, etc.), we are building a catalog of skills, plugins, and tools that teams can discover and leverage in the projects.

But not everything that guides an AI is a skill or a tool. Some of it is plain instruction: conventions, guardrails, and hard-won facts the assistants needs to write correct code in a given repo.

This contribution is that (second) kind. It is a knowledge base for the UI5 Web Components that AI assistants can load, so the AI produces more efficient and accurate output instead of re-deriving the same facts on every task.

What we add

A new ai-knowledge-base/ folder that documents how code is actually written in the project. It is a plain set of reference files, not a plugin, so an AI assistant (Claude, Cursor, Copilot) or a human reading it gets the same guidance.

The entry point is INDEX.md, that the AGENTS.md file points to.

It carries the non-negotiable rules and a routing table that maps a task ("adding a property", "writing a test", "CSS and theming") to the one reference file that covers it.

The references sit under ai-knowledge-base/references/ and split by concern: API design, component anatomy, core rules, testing, theming, accessibility, i18n, performance, and creating a new component.

What it helps with

It captures the failure modes that no linter reports and that cost real time to rediscover. An event with no doc block is silently private. A class doc block with no @class tag is skipped with no error. A boolean property that defaults to true is rejected by the manifest generator with a misspelled message.

These are the traps that send someone (or the AI Assistant) digging through the framework. They are now written down once.

It also settles the questions that come up on every change. Which mechanism fits, a property or a slot or a method. How to name a boolean so its default is false. Which JSDoc tags pass validation and in what shape. What each lifecycle hook is for.

That means it reduces the reasoning an AI assistant has to do, and the number of wrong guesses it makes, until it comes to the right solution/conclusion. Therefore a cheaper models could potentially be used, for the same level of accuracy of the outputs as models previously needed, that were using higher reasoning effort.

How it saves tokens and time

An assistant without such context explores the codebase to re-derive these facts or search from a compressed memory on every task. It greps for how events are declared, finds two decorator styles, and guesses. That exploration burns tokens and often lands on the wrong or semi-wrong answer.

With the knowledge base, that work collapses into reading one short reference. The load-on-demand design means a typical task pulls the index plus a instruction file/s, a few thousand tokens, rather than the full corpus.

The net effect is fewer tokens spent, fewer wrong guesses, and changes that match the patterns the team already follows instead of the legacy ones scattered through the tree.

Accuracy is the one thing this depends on. The concrete claims were verified against current source. They should be re-checked periodically, since specific references drift as unrelated code changes.

- fewer tokens, fewer wrong guesses, less time exploring, while:
+ more efficient & accurate output

[sap-ui5-webcomponents-release]

🚀 Deployed on https://pr-13909--ui5-webcomponents-preview.netlify.app

[vladitasev]

Review of ai-knowledge-base/references/api-design.md

Overall quality is high — dense, concrete, well-structured for machine consumption. Three factual/structural issues and a few language nits.

---

[Factual] Select.opened noAttribute claim is wrong

though it still reflects as an attribute since it isn't noAttribute

Select.opened is declared as @property({ type: Boolean }) with no noAttribute: true, so the "still reflects" part is correct. But the justification is backwards: the sentence implies that a @private property would normally not reflect, and noAttribute is the mechanism that would suppress it. That is the wrong mental model. The correct framing is: @private is a documentation annotation only; reflection is controlled by noAttribute. A reader who internalizes the current wording will think @private suppresses attributes by default.

Suggested fix:

Select tracks open state in opened (@private), so it is absent from the public API and docs. It still reflects as an attribute because @property({ type: Boolean }) does not set noAttribute: true — @private is a doc-visibility flag only, not a reflection guard.

---

[Factual] The "4 events" description doesn't match the code structure

fires ui5-selection-change and selection-change, then repeats the pair PascalCased (ui5-SelectionChange, SelectionChange)

The actual implementation is two calls to _fireEvent, each of which independently fires ui5-{name} + {name}. The Pascal branch fires only when kebabToPascalCase(name) !== name. So the structure is 2 + 2 (conditional), not a flat 4. The description is correct in outcome for multi-word names, but misleads on how it works — which matters when a reader tries to understand no-conflict suppression: suppressing selection-change does not suppress SelectionChange; they come from separate _fireEvent calls.

Also: for a single-word name like open, kebabToPascalCase("open") = "Open", so the Pascal branch does fire — the doc is correct that 4 events fire. But the explanation "because "Open" differs from the original" understates it; what matters is that _fireEvent is called a second time with a different name, so preventing the first pair does not prevent the second.

---

[Structural] Cross-reference density works against the load-on-demand design

The INDEX routes agents to one file per task. But api-design.md references core-rules.md, performance.md, accessibility.md, and new-component.md at least six times without loading them. An agent following the INDEX routing will arrive here expecting a self-contained reference and hit walls. Either:

• Inline the one-liners (e.g. the boolean-default rule is short enough to repeat here), or
• Add a preamble: "Load alongside core-rules.md for any API task — this file covers shape, that one covers invariants."

---

[Language] Boolean polarity — show* is a valid pattern, not a footnote

The table lists hide*, no*, prevent*, disable* as the four prefixes, then introduces show* as "the mirror case" in a separate sentence. An agent scanning the table won't absorb the sentence and will treat show* as unlisted/questionable. Move it into the table:

Prefix	For	Examples
show*	a non-default rendered element	showSuggestions, showClearIcon

---

[Language] Enum section: no way to distinguish old violators from new correct code

Much of the existing code violates this… Write the correct form; do not migrate neighbours as a drive-by.

An agent reading context will see ButtonDesign.Default in a neighbour file and either copy it (wrong) or refuse to reference any enum at all (also wrong). Add one line: "If the file you are editing already uses the old pattern, follow the new form only in the code you write — do not mix styles within a single expression."

---

[Language] @property on a setter — missing the "when not to" signal

The section says "this is how every state property with a side effect is written" — accurate, but without a counterpoint an agent will use a setter accessor for properties that have no side effect, adding unnecessary boilerplate. One sentence closes this: "A plain field is correct when the property change needs no side effect beyond invalidation."

[didip1000]

I tried to be thorough and I noticed that the AI likes to take one-off cases and label them as the rules. I think we should throw another eye on everything to make sure that it didnt make any stuff up elsewhere.

[didip1000]

I'm also not sure this works for slots too, by it's description it sounds like something you'd use extension for, like with button and toggle button

[hinzzx]

To me it sounds like reference to the Timeline and its TimelineItems, or the Menu and its MenuItems

[didip1000]

Menu Items aren't really "optional capability" theyre the main capability, otherwise Menu is just an empty container. Same goes for the Timeline.

To me it sounded more like Button badge, but my point was that the description doesnt fit because extension also fits this description eg. every item that extends list item base

[didip1000]

One more thing, the PR description really does not need to be that long, and while

- fewer tokens, fewer wrong guesses, less time exploring, while:
+ more efficient & accurate output

is amusing, I don't know if it's really relevant