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

[hinzzx]

I guess it is a little amibiguous, i'll rewrite it.

[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

[didip1000]

Ok but the statement is still wrong

[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

[hinzzx]

Deleted a comment by mistake in api-design.md. It is addressed though.

[unazko]

Typo

Title uses British spelling "Internationalisation" → should be "Internationalization" (consistent with sibling docs and tech convention).
Opening paragraph

The packages/localization sentence drops in without transition. Suggest adding a lead-in like: "Note: packages/localization is a separate package for CLDR/calendar/date logic — not UI strings. Do not confuse it with the pipeline described here."
"The pipeline" section

Missing an opening sentence that says what the section is about before diving into implementation.
"Two independent halves; adding a key covers only the first." is a confusing opener — the reader doesn't know what the two halves are yet.
"The build targets that drive this are..." feels like a mid-thought sentence.
Suggest restructuring: open with what the pipeline produces (TypeScript defaults + locale JSON assets), then show the diagram, then explain the dev-server caveat.

Section 1 — "Add the key"

The annotation comment is described as "the only context translators get" but never explains why that matters. Suggest one sentence: translators work without seeing the UI, so without the comment they may produce an inaccurate translation.
The annotation code list is described as "most common first" — implicitly incomplete. Consider linking to an authoritative reference for the full set.
Legacy outliers (#ACC:, #FLD:) are flagged as wrong but there's no reason given. Suggest adding a short note that they predate the standard.

Section 2 — "Name it"

Title is too vague — "Name what?" Consider renaming to "Name the key" or "Key naming conventions".
"Never duplicate a generic key under a new prefix" is hard to parse. A concrete example would help: don't create BUTTON_DELETE when the shared DELETE key already exists.
"Never reuse another component's key even if the English matches" — the why is stated but could use a brief example (e.g. "Close" may translate differently depending on grammatical context of each component).

Section 4 — "Use it in the component"

The decision between @i18n, getI18nBundle, and new I18nBundle is buried in a dense paragraph. A short 3-line decision rule at the top of that block would make it easier to follow.
Possible additions (not mandatory)

A full end-to-end example (messagebundle key → generated constant → component class) might be useful for AI to generate correct boilerplate — docs/07-development/09-internationalization.md has a good one.
The fact that the bundle name corresponds to the name field in package.json is not mentioned — could be useful for developers working on custom packages.
A note that package consumers must import dist/Assets.js to enable non-English languages is currently only in the package setup doc, not here.

[unazko]

The variable tiers" section

• The sentence "No --sap* token is defined in this monorepo..." drops in without context. Suggest adding a lead-in like: "A common point of confusion: --sap* tokens are not defined in this repo — they are only imported from @sap-theming/theming-base-content."
• The second paragraph explains --ui5* and --ui5_/--ui5- in one dense block. The distinction (component-private vs cross-boundary) is important but hard to parse — consider splitting into two short paragraphs, one per tier.

"How CSS reaches the component" section

• themeAware: true is described as re-rendering on theme change, but there's no mention that it's opt-in (default is false). An AI generating a new component wouldn't know whether to include it.

"Where each file goes" section

• "but chains exist" — chains is undefined jargon. Suggest replacing with a plain description: "some files extend another theme's file and override only what differs."
• The theme list (sap_horizon + variants, sap_fiori_3 + variants) has no intro. Suggest one line: "These are all supported themes — a new --ui5* parameter needs a value in every theme folder."
• The parameters-bundle.css registration concept starts without a transition from the file layout above. Suggest a linking sentence: "Adding a parameters file is not enough — it must also be imported in the theme's parameters-bundle.css or it has no effect."

"Selectors" section

• "...breaks under tag scoping" — tag scoping is not defined. Suggest replacing with a plain explanation: "...breaks when the framework applies tag-name isolation — use the attribute form [ui5-button] instead of the element form ui5-button."
• The noAttribute: true rule feels out of place in a Selectors section. A short transition would help: "This ties directly to the selector rule above: if CSS reads a state via [attribute], the property must be reflected."

"Right-to-left" section

• post-edit-lint.sh is mentioned without being introduced. Suggest a brief lead-in like: "A local git hook (post-edit-lint.sh) catches some violations automatically, but only a subset..."

"Density" section

• The distinction between --ui5_content_density and --_ui5_content_density is important but buried in a very long sentence. Consider breaking it into two explicit points:
  --ui5_content_density (no leading _) — build-time directive, read by the postcss plugin inside -parameters.css files only.
  --_ui5_content_density (leading _) — runtime signal, set by SystemCSSVars.css.
• The slotted children rule states the constraint before the reason. Easier to follow if the reason comes first: "A -parameters.css declaration is merged into a shared stylesheet adopted into every shadow root — so ::slotted() there would target slots across all components. That's why density blocks styling slotted children belong in component CSS, not in -parameters.css."

"Focus, animation, high contrast" section

• The table groups three unrelated concerns with no intro. Suggest one sentence before it: "A few cross-cutting rules apply to sizing, motion, and accessibility."

Possible additions (not mandatory)

• docs/2-advanced/13-theming-part2.md notes that --sap* variables are browsable in the @sap-theming/theming-base-content npm package. A reference link in the variable tiers section could help developers discover available tokens.
• docs/3-frameworks/05-Tailwind.md explains that UI5 intentionally sets styles on :host to make components externally customisable — this why behind the :host pattern is not mentioned in the skill file and could add useful context to the Selectors or "How CSS reaches the component" section.