`), so it is
+keyboard-operable, focusable, and announced as a button with no extra work. Do not rebuild this
+with a clickable ``.
+
+```tsx
+import { Button } from "@cloudoperators/juno-ui-components"
+
+declare function save(): void
+
+function SaveAction() {
+ return save()} />
+}
+```
+
+Use `href` for navigation (renders an anchor) and `onClick` for actions (renders a button). Picking
+the element that matches the outcome is the "clarity and predictability" rule in code: buttons look
+and behave like buttons, links like links (`docs/ux/interaction-guidelines.md`, "Clarity and
+Predictability").
+
+### Give every icon-only control an accessible name
+
+An icon with no visible text has no accessible name by default. Juno surfaces one through `title`.
+
+For `Button`, `title` falls back to `label`; a label-less icon button therefore needs an explicit
+`title` (or `label`), otherwise it is announced as an empty button:
+
+```tsx
+import { Button } from "@cloudoperators/juno-ui-components"
+
+declare function remove(): void
+
+function DeleteButton() {
+ // icon-only button: title supplies the accessible name
+ return remove()} />
+}
+```
+
+A standalone `Icon` renders an SVG with `role="img"` and a ``; pass `title` whenever the icon
+carries meaning (if it is interactive, prefer giving it an `onClick`/`href` so it becomes a real
+control):
+
+```tsx
+import { Icon } from "@cloudoperators/juno-ui-components"
+
+function InfoMark() {
+ return <Icon icon="info" title="More information" />
+}
+```
+
+Pair the name with the action, not the glyph: `title="Delete item"`, not `title="Trash icon"`
+(`docs/ux/accessibility.md`, "Labels and Accessible Names").
+
+### Label inputs with the component's own label prop
+
+Juno form inputs wire a real `<label>` to the input (`htmlFor`/`id`) when you pass `label` — you do
+not add your own `<label>`, and you never use `placeholder` as a stand-in for a label.
+
+```tsx
+import { TextInput } from "@cloudoperators/juno-ui-components"
+
+function EmailField({ value, onChange }: { value: string; onChange: (v: string) => void }) {
+ return (
+ <TextInput label="Email address" type="email" required value={value} onChange={(e) => onChange(e.target.value)} />
+ )
+}
+```
+
+`placeholder` is a hint that disappears on input; it is not an accessible name. Always pass `label`
+(`docs/ux/accessibility.md`, "Labels and Accessible Names").
+
+### Group related inputs under one labelled group
+
+A set of related checkboxes or radios must be announced as a single named group, not a loose pile
+of inputs. Use `CheckboxGroup`/`RadioGroup` with a `label` — `RadioGroup` renders `role="radiogroup"`
+and both associate their `label` and `helptext`/`errortext` with the group.
+
+```tsx
+import { CheckboxGroup, Checkbox } from "@cloudoperators/juno-ui-components"
+
+function Permissions() {
+ return (
+ <CheckboxGroup label="Permissions" helptext="Choose all that apply">
+ <Checkbox value="read" label="Read" />
+ <Checkbox value="write" label="Write" />
+ <Checkbox value="admin" label="Admin" />
+ </CheckboxGroup>
+ )
+}
+```
+
+(`docs/ux/accessibility.md`, "Labels and Accessible Names" — groups of related inputs.)
+
+### Keep keyboard operation and the focus ring intact
+
+Every interactive element must be reachable and operable by keyboard, with tab order following the
+visual reading order, and disabled elements out of the tab order (`docs/ux/accessibility.md`,
+"Keyboard Navigation and Focus"). Juno components provide a visible focus ring —
+`focus-visible:ring-2` on `Button`, for example. **Never override or hide it.** Mark unavailable
+controls with the component's `disabled` prop (which also removes them from the tab order) rather
+than hiding them with CSS or a non-interactive element.
+
+```tsx
+import { Button } from "@cloudoperators/juno-ui-components"
+
+declare function submit(): void
+
+function Submit({ busy }: { busy: boolean }) {
+ // disabled is announced and removed from tab order; focus ring is left untouched
+ return <Button variant="primary" label="Submit" disabled={busy} onClick={() => submit()} />
+}
+```
+
+### Let Modal manage focus; always give it an accessible name
+
+`Modal` traps focus while open and returns focus to the trigger on close (via `focus-trap-react`),
+is dismissible with ESC by default, and renders `role="dialog"`. Its accessible name comes from
+`title`/`heading` (referenced by `aria-labelledby`); only when the modal has neither do you supply
+`ariaLabel`. Do not build your own overlay — you would have to re-implement all of this.
+
+```tsx
+import { Modal } from "@cloudoperators/juno-ui-components"
+
+function ConfirmDelete({ open, onClose }: { open: boolean; onClose: () => void }) {
+ return (
+ <Modal open={open} title="Delete project" confirmButtonLabel="Delete" onCancel={onClose} onConfirm={onClose}>
+ This action cannot be undone.
+ </Modal>
+ )
+}
+```
+
+Focus containment is legitimate here — Modals and overlays are the one place intentional focus
+trapping is expected (`docs/ux/interaction-guidelines.md`, "Keyboard and Focus").
+
+### Signal status with more than color, and announce it
+
+Do not rely on color alone to convey information — pair every color signal with text or an icon
+(`docs/ux/accessibility.md`, "Colour and Contrast"). Dynamic content (loading, success, errors
+appearing after an action) must also be announced to screen readers via an aria-live role
+(`docs/ux/accessibility.md`, "Dynamic Content").
+
+`Status` does both: it always shows a title/body (text, not just color) and sets `role="alert"`
+when `status="error"` and `role="status"` otherwise, so a status that appears after a fetch is
+announced automatically.
+
+```tsx
+import { Status } from "@cloudoperators/juno-ui-components"
+
+function LoadResult({ error }: { error?: Error }) {
+ if (error) {
+ // role="alert" — announced immediately
+ return <Status status="error" title="Could not load" body={error.message} />
+ }
+ // role="status" — announced politely
+ return <Status status="progress" title="Loading…" />
+}
+```
+
+For application-driven updates that are **not** a Juno status component (e.g. a custom inline count
+that changes), you own the announcement — read
+[announcing dynamic content](references/announcing-dynamic-content.md) for the `role="status"` /
+`role="alert"` / `aria-live` decision and a worked live-region example.
+
+For the full semantic-HTML landmark, heading-order, and `aria-describedby` guidance that goes beyond
+single components, read [semantic foundations](references/semantic-foundations.md).
+
+## Common mistakes
+
+- **CRITICAL — Clickable `<div>`/`<span>` instead of a `Button`/`<a>`.** A non-semantic element is
+ not focusable or keyboard-operable and is announced with no role, so keyboard and screen-reader
+ users cannot use it. Use `Button` (or an anchor for navigation); only make a `<div>` interactive
+ when unavoidable, and then add every role, state, and key handler yourself.
+ (`docs/ux/accessibility.md`, "Semantic HTML as the Foundation".)
+- **CRITICAL — Icon-only control with no accessible name.** A `Button icon="…"` with no `label`,
+ `title`, or `aria-label`, or an `Icon` with no `title`, is announced as empty. Always name the
+ action: `<Button icon="deleteForever" title="Delete item" />`.
+ (`docs/ux/accessibility.md`, "Labels and Accessible Names".)
+- **HIGH — `placeholder` used as the label.** Placeholder text disappears on input and is not a
+ reliable accessible name. Pass the component's `label` prop instead.
+ (`docs/ux/accessibility.md`, "Labels and Accessible Names".)
+- **HIGH — Hiding or overriding the focus ring.** Removing the visible focus indicator (e.g.
+ `outline: none` or overriding Juno's ring) strands keyboard users. Leave the component's focus
+ styles in place. (`docs/ux/accessibility.md`, "Keyboard Navigation and Focus".)
+- **HIGH — Color as the only status signal.** A red/green border or dot with no text or icon is
+ invisible to color-blind and screen-reader users. Pair color with a text label or icon; `Status`
+ and the form components' `errortext`/`successtext` already do this.
+ (`docs/ux/accessibility.md`, "Colour and Contrast".)
+- **HIGH — Hand-rolled modal/overlay.** A custom overlay typically omits focus trapping, focus
+ return, ESC-to-close, and `role="dialog"`/`aria-labelledby`. Use `Modal`, which supplies them.
+ (`docs/ux/interaction-guidelines.md`, "Keyboard and Focus".)
+- **MEDIUM — Silent dynamic updates.** Content that appears or changes after an action (results,
+ errors, counts) with no aria-live region is never announced. Use `Status` (which sets the role)
+ or an explicit live region for custom content. (`docs/ux/accessibility.md`, "Dynamic Content";
+ `docs/ux/interaction-guidelines.md`, "Feedback".)
+- **MEDIUM — Loose related inputs with no group name.** Separate checkboxes/radios without a
+ wrapping labelled group are announced individually with no shared context. Wrap them in
+ `CheckboxGroup`/`RadioGroup` with a `label`. (`docs/ux/accessibility.md`, "Labels and Accessible
+ Names".)
+
+## Completion
+
+Verify:
+
+1. No clickable `<div>`/`<span>`: every action is a `Button` and every navigation is an anchor
+ (`Button` with `href`).
+2. Every icon-only `Button`/`Icon` has a `title` (or `label`/`aria-label`) naming the action.
+3. Every input uses its `label` prop; no `placeholder`-as-label; related inputs are grouped.
+4. The focus ring is visible on every interactive element when tabbing; nothing suppresses it.
+5. Overlays use `Modal` (focus trap + ESC + accessible name), not a hand-rolled container.
+6. Every status/dynamic update shows text or an icon (not color alone) and is in an aria-live
+ region (`Status`, or an explicit live region for custom content).
+7. Run `npm exec --no -- intent validate packages/ui-components/skills` and fix any errors.
+
+If a flow cannot be exercised with the keyboard or a screen reader in your test harness, report it
+as unverified rather than assuming it is accessible.
+
+## References
+
+- [semantic foundations](references/semantic-foundations.md) — read for landmark regions, heading
+ order, and wiring help/error text with `aria-describedby` beyond what a single component covers.
+- [announcing dynamic content](references/announcing-dynamic-content.md) — read before adding a
+ custom live region for app-driven updates that are not rendered by a Juno status component.
diff --git a/packages/ui-components/skills/accessibility/references/announcing-dynamic-content.md b/packages/ui-components/skills/accessibility/references/announcing-dynamic-content.md
new file mode 100644
index 0000000000..1b48aa8cb1
--- /dev/null
+++ b/packages/ui-components/skills/accessibility/references/announcing-dynamic-content.md
@@ -0,0 +1,84 @@
+# Announcing dynamic content
+
+Read this when application code produces an update that is **not** rendered by a Juno status
+component — a custom inline count that changes, a background sync message, a result banner you
+assemble yourself — and you need a screen reader to announce it. Sources:
+`docs/ux/accessibility.md` ("Dynamic Content"), `docs/ux/interaction-guidelines.md` ("Feedback").
+
+## Prefer a component that already announces
+
+Before writing a live region, check whether a Juno component covers the case — it will set the role
+for you:
+
+- **Status** sets `role="alert"` when `status="error"` and `role="status"` otherwise. Use it for
+ loading / empty / no-matches / error states.
+ (`packages/ui-components/src/components/Status/Status.component.tsx`.)
+- **Message** forwards extra props to its root `<div>`, so pass `role="status"` (non-urgent) or
+ `role="alert"` (urgent) when a Message appears dynamically.
+- For toast-style notifications that must announce without stealing focus, use the Juno
+ notification/toast components — see the feedback skill.
+
+```tsx
+import { Message } from "@cloudoperators/juno-ui-components"
+
+function SaveResult({ saved }: { saved: boolean }) {
+ if (!saved) return null
+ // appears after an action → announce politely
+ return <Message variant="success" role="status" text="Changes saved." />
+}
+```
+
+## Choosing the role for custom content
+
+| Situation | Use | Why |
+| --------------------------------------------- | ------------------------------------ | ---------------------------------- |
+| Error that needs immediate attention | `role="alert"` (implies assertive) | Interrupts and is read at once |
+| Non-urgent update (count, "saved", progress) | `role="status"` (implies polite) | Read after the current utterance |
+| A region you update repeatedly, finer control | `aria-live="polite"` / `"assertive"` | Explicit politeness on a container |
+
+Reserve `alert`/`assertive` for things the user must act on now — overusing it is as unhelpful as
+no announcement at all.
+
+## Worked example: a custom live region
+
+Render the live-region container **before** the content changes (empty is fine). Updating the text
+of an element that is already a live region is what gets announced; inserting a brand-new live
+region at the same time as its content is less reliable.
+
+```tsx
+import React, { useState } from "react"
+import { Button } from "@cloudoperators/juno-ui-components"
+
+declare function runSearch(): Promise<number>
+
+function SearchStatus() {
+ const [message, setMessage] = useState("")
+
+ async function onSearch() {
+ setMessage("Searching…")
+ const count = await runSearch()
+ setMessage(`${count} results found`)
+ }
+
+ return (
+ <div>
+ <Button label="Search" onClick={() => void onSearch()} />
+ {/* live region is always present; only its text changes */}
+ <p role="status" aria-live="polite">
+ {message}
+ </p>
+ </div>
+ )
+}
+```
+
+Every action that triggers a process must be acknowledged, loading included
+(`docs/ux/interaction-guidelines.md`, "Feedback"). Announcing the start ("Searching…") and the
+outcome ("12 results found") makes the process perceivable without sight of the screen.
+
+## Loading and progress specifically
+
+Juno's `Spinner` and `LoadingIndicator` render `role="progressbar"`. Wrapping a region that is being
+replaced with `aria-busy={true}` while it loads lets assistive tech know the content is in flux. Do
+not replace a whole page with a bare spinner — scope the busy/loading indication to the region that
+is actually changing (`docs/ux/interaction-guidelines.md`, "Feedback").
diff --git a/packages/ui-components/skills/accessibility/references/semantic-foundations.md b/packages/ui-components/skills/accessibility/references/semantic-foundations.md
new file mode 100644
index 0000000000..47b72e6dae
--- /dev/null
+++ b/packages/ui-components/skills/accessibility/references/semantic-foundations.md
@@ -0,0 +1,65 @@
+# Semantic foundations
+
+Read this when you need accessibility structure that spans more than a single component — page
+landmarks, heading order, labelling repeated regions, or linking help/error text to an input with
+`aria-describedby`. Source: `docs/ux/accessibility.md`.
+
+## Landmark regions and heading order
+
+Use the real landmark elements so assistive tech can jump between regions: `<nav>`, `<main>`,
+`<header>`, `<footer>`. Keep headings in order (`<h1>` → `<h2>` → `<h3>`, no skipped levels) — the
+heading outline is how screen-reader users scan a page. Juno layout components render the correct
+landmarks; in your own markup, use the semantic element, never a `<div>` styled to look like one
+(`docs/ux/accessibility.md`, "Semantic HTML as the Foundation").
+
+```
+<header>…</header>
+<nav aria-label="Primary">…</nav>
+<main>
+ <h1>Projects</h1>
+ <section aria-labelledby="recent-h">
+ <h2 id="recent-h">Recent</h2>
+ …
+ </section>
+</main>
+<footer>…</footer>
+```
+
+## Distinguish repeated regions
+
+When the same landmark appears more than once (e.g. two `<nav>` regions, or several `role="group"`
+containers), give each a distinct accessible name so they are not announced identically. Prefer
+`aria-labelledby` pointing at a visible heading over a separate `aria-label` — it keeps the visible
+and announced names in sync and avoids duplicated copy (`docs/ux/accessibility.md`, "Labels and
+Accessible Names").
+
+```
+<nav aria-label="Primary">…</nav>
+<nav aria-label="Pagination">…</nav>
+
+<section aria-labelledby="filters-h">
+ <h2 id="filters-h">Filters</h2>
+ …
+</section>
+```
+
+## Help and error text with aria-describedby
+
+For Juno form inputs, prefer the component's own `helptext`, `errortext`, and `successtext` props
+rather than rendering adjacent text yourself — they render the hint and keep the copy consistent
+with the field (`docs/ux/accessibility.md`, "Descriptive and Help Text"). The TextInput wires the
+visible `<label>` to the input automatically.
+
+When you render custom descriptive text next to a native input in application code (outside the
+Juno form components), link it explicitly with `aria-describedby` so screen readers announce it in
+context:
+
+```
+<label for="token">API token</label>
+<input id="token" type="password" aria-describedby="token-hint" />
+<p id="token-hint">Generated under Settings → Access tokens.</p>
+```
+
+Use `aria-describedby` for supplementary hints and error messages; use the `<label>`/`htmlFor`
+association (which Juno components do for you) for the input's name. Keep the two roles separate —
+the label is the name, the description is extra context.
diff --git a/packages/ui-components/skills/actions/SKILL.md b/packages/ui-components/skills/actions/SKILL.md
new file mode 100644
index 0000000000..e01e0c18ae
--- /dev/null
+++ b/packages/ui-components/skills/actions/SKILL.md
@@ -0,0 +1,248 @@
+---
+name: actions
+description: >
+ Use when adding actions to a Juno UI built with @cloudoperators/juno-ui-components: choosing a
+ Button variant (default, primary, primary-danger, subdued) and size, showing an in-progress
+ button during async work, grouping buttons with ButtonRow in dialogs and forms, wiring a
+ SortButton for a sortable column, and placing a ThemeToggle. Covers which action is primary vs
+ secondary vs destructive, button label wording (title case, infinitive verbs), and when to disable
+ vs hide an action. For page-level toolbar slot layout and the overflow menu, read the
+ page-level-actions reference; for actions scoped to a DataGrid, see the datagrid skill.
+metadata:
+ purpose: >
+ Teaches developers to pick the correct Juno Button variant and placement for an action, group
+ actions consistently with ButtonRow, give async actions in-progress feedback, and apply the
+ SortButton and ThemeToggle correctly — enforcing the UX rules (one primary action per page,
+ destructive = primary-danger, title-case infinitive labels, disable vs hide) that the
+ components do not enforce on their own.
+ type: core
+ library: "@cloudoperators/juno-ui-components"
+ library_version: "9.6.0"
+sources:
+ - cloudoperators/juno:packages/ui-components/src/components/Button/Button.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/Button/Button.stories.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/ButtonRow/ButtonRow.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/ButtonRow/ButtonRow.stories.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/SortButton/SortButton.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/SortButton/SortButton.stories.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/ThemeToggle/ThemeToggle.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/ThemeToggle/ThemeToggle.stories.tsx
+ - cloudoperators/juno:docs/ux/page-level-actions.md
+ - cloudoperators/juno:docs/ux/interaction-guidelines.md
+ - cloudoperators/juno:docs/ux/ux-writing-content-design.md
+---
+
+# Add actions with the Juno Button family
+
+An action in a Juno UI is almost always a `Button`. The hard part is not the markup — it is
+choosing the right **variant** so the button's visual weight matches its role (primary, secondary,
+or destructive), writing the **label** correctly, and placing it where the UX guidelines expect.
+This skill covers `Button`, grouping with `ButtonRow`, the `SortButton` for sortable columns, and
+the `ThemeToggle`.
+
+## Setup
+
+A `Button` renders a `<button>`, or an `<a role="button">` when you pass `href`. Pass the label
+as the `label` prop (or as `children`). The default variant is `default`.
+
+```tsx
+import { Button } from "@cloudoperators/juno-ui-components"
+
+function SaveButton({ onSave }: { onSave: () => void }) {
+ return <Button variant="primary" label="Save" onClick={onSave} />
+}
+```
+
+The four variants map directly onto the four UX roles:
+
+- `primary` — the one preferred action on the page or in the dialog. **At most one per context.**
+- `default` — a neutral secondary action; may appear several times.
+- `subdued` — a lower-emphasis secondary action, used to create contrast next to a primary button
+ or when several default buttons would be too heavy.
+- `primary-danger` — a destructive or irreversible action (delete, terminate, revoke). Use
+ sparingly. (`docs/ux/page-level-actions.md`, "The Primary Action"; `Button.stories.tsx`.)
+
+Sizes are `default`, `small`, and `xs` via the `size` prop. Use `small`/`xs` only inside dense
+contexts (toolbars, inline cells); keep the `default` size for standalone page actions.
+
+## Core patterns
+
+### Add an icon or make an icon-only button
+
+Pass a Juno icon name as `icon`. Omit `label` and `children` for an icon-only button — but then
+you **must** give it a `title` for accessibility, because the icon alone is not a label.
+
+```tsx
+import { Button } from "@cloudoperators/juno-ui-components"
+
+function RefreshButton({ onRefresh }: { onRefresh: () => void }) {
+ return <Button icon="cached" title="Refresh Page" onClick={onRefresh} />
+}
+```
+
+Every icon-only button must carry a native `title` (or an explicit tooltip) — no exceptions
+(`docs/ux/page-level-actions.md`, "Icon-Only Buttons").
+
+### Show progress during an async action
+
+Set `progress` while an action is running. The button swaps its icon for a spinner and disables
+its own click; pass `progressLabel` to replace the label text while running. This gives the
+required feedback for every state-changing action (`docs/ux/interaction-guidelines.md`,
+"Feedback").
+
+```tsx
+import { useState } from "react"
+import { Button } from "@cloudoperators/juno-ui-components"
+
+function CreateButton({ create }: { create: () => Promise<void> }) {
+ const [saving, setSaving] = useState(false)
+ const onClick = async () => {
+ setSaving(true)
+ try {
+ await create()
+ } finally {
+ setSaving(false)
+ }
+ }
+ return <Button variant="primary" label="Create" progress={saving} progressLabel="Creating…" onClick={onClick} />
+}
+```
+
+Note the ellipsis in `progressLabel`: a single `…` glyph is allowed and signals an ongoing step
+(`docs/ux/ux-writing-content-design.md`, "Button Labels").
+
+### Render a link that looks like a button
+
+Pass `href` to render an `<a role="button">` with identical styling. Use this for navigation that
+is a GET to another location, not for a JavaScript action.
+
+```tsx
+import { Button } from "@cloudoperators/juno-ui-components"
+
+function DocsLink() {
+ return <Button variant="subdued" label="Documentation" href="/docs" icon="openInNew" />
+}
+```
+
+### Group actions with ButtonRow
+
+In a dialog, form, or any place with more than one action, wrap the buttons in `ButtonRow`. It
+lays them out in a row with consistent spacing and aligns them to the **end** (right). Order them
+so the primary action is **last** (rightmost); secondary/cancel actions sit to its left.
+
+```tsx
+import { Button, ButtonRow } from "@cloudoperators/juno-ui-components"
+
+function FormActions({ onCancel, onSave }: { onCancel: () => void; onSave: () => void }) {
+ return (
+ <ButtonRow>
+ <Button label="Cancel" onClick={onCancel} />
+ <Button variant="primary" label="Save" onClick={onSave} />
+ </ButtonRow>
+ )
+}
+```
+
+`ButtonRow` takes only `children` and `className` — it is a layout container, not a place to
+configure the buttons (`ButtonRow.component.tsx`, `ButtonRow.stories.tsx`).
+
+### Wire a SortButton for a sortable column
+
+`SortButton` is a two-state toggle for ascending/descending order. It is **controlled**: pass the
+current `order` and update your state in `onChange`, which fires with the new order. It defaults
+to showing up/down sort icons, so you normally pass no `options`.
+
+```tsx
+import { useState } from "react"
+import { SortButton } from "@cloudoperators/juno-ui-components"
+
+type Order = "asc" | "desc"
+
+function CreatedAtHeader() {
+ const [order, setOrder] = useState<Order>("desc")
+ return (
+ <span>
+ Created
+ <SortButton order={order} onChange={(next) => setOrder(next)} />
+ </span>
+ )
+}
+```
+
+`SortButton` extends `ButtonProps` (minus `value`/`onChange`), so `disabled` works too. Prefer the
+default sort icons; custom `options` icons are supported but discouraged
+(`SortButton.stories.tsx`, "CustomOptions"). Do not confirm a sort — sorting is predictable and
+reversible (`docs/ux/interaction-guidelines.md`, "Confirmation of Consequential Actions").
+
+### Place a ThemeToggle
+
+`ThemeToggle` flips the app between light and dark themes. It reads and writes the `StyleProvider`
+context (provided automatically by the Juno `AppShell`), so it needs no `value` prop — it is
+self-wiring. Place it in the app header/shell, not inside page content.
+
+```tsx
+import { ThemeToggle } from "@cloudoperators/juno-ui-components"
+
+function HeaderThemeToggle() {
+ return <ThemeToggle onToggleTheme={(theme) => console.log("theme is now", theme)} />
+}
+```
+
+It accepts `className`, `disabled`, `id`, `name`, and `onToggleTheme` — nothing else. Without a
+`StyleProvider`/`AppShell` in the tree it logs a warning and does nothing
+(`ThemeToggle.component.tsx`).
+
+## Common mistakes
+
+- **CRITICAL — More than one `primary` button in a context.** Two primaries leave the user with no
+ clear preferred action. Keep exactly one `variant="primary"` per page or dialog; demote the rest
+ to `default`/`subdued`, or move secondary actions into an overflow menu.
+ (`docs/ux/page-level-actions.md`, "The Primary Action".)
+- **CRITICAL — Destructive action not styled as `primary-danger`.** A delete/terminate/revoke
+ rendered as a plain primary gives no visual warning. Use `variant="primary-danger"`, and confirm
+ irreversible actions before committing. (`Button.stories.tsx`, "PrimaryDanger";
+ `docs/ux/interaction-guidelines.md`, "Reversibility".)
+- **HIGH — Icon-only button with no `title`.** An icon alone is unreadable to screen readers and
+ ambiguous to sighted users. Always set `title` (or a tooltip) on an icon-only `Button`.
+ (`docs/ux/page-level-actions.md`, "Icon-Only Buttons".)
+- **HIGH — No feedback on an async action.** Firing a mutation with no progress indication leaves
+ users unsure it registered, and lets them double-submit. Set `progress` (and ideally
+ `progressLabel`) while the action runs. (`docs/ux/interaction-guidelines.md`, "Feedback".)
+- **HIGH — Wrong label wording.** Labels must be short, title-case, infinitive verbs ("Create",
+ "Delete", "Save"), never "Click to Create", never ALL-CAPS, and use "Sign in" not "Log in". Keep
+ the verb consistent with the surrounding copy and dialog title.
+ (`docs/ux/ux-writing-content-design.md`, "Button Labels", "Title Case", "Consistency".)
+- **MEDIUM — Hiding an action that is only temporarily blocked.** Disable (`disabled`) an action
+ that is generally available but blocked right now; only omit it when the user cannot or should
+ not get it (e.g. no permission). (`docs/ux/page-level-actions.md`, "Disabled vs. Hidden
+ Actions".)
+- **MEDIUM — Primary action not last in a `ButtonRow`.** `ButtonRow` aligns to the end; put the
+ primary action rightmost so placement matches emphasis. (`ButtonRow.stories.tsx`.)
+- **MEDIUM — Inventing a new action pattern.** Reusing one interaction style for the same action
+ type across the app matters more than a local tweak. Reuse the existing Juno pattern.
+ (`docs/ux/interaction-guidelines.md`, "Consistency".)
+
+## Completion
+
+Verify:
+
+1. Each page/dialog has at most one `variant="primary"`, and any destructive action is
+ `variant="primary-danger"`.
+2. Every icon-only `Button` has a `title`; async actions set `progress` while running.
+3. Labels are short, title-case, infinitive verbs with no trailing punctuation (an ellipsis is
+ allowed to signal a further step).
+4. Multi-action groups use `ButtonRow` with the primary action last.
+5. Any `SortButton` is controlled (`order` + `onChange`), and `ThemeToggle` sits inside an
+ `AppShell`/`StyleProvider`.
+6. Run `npm exec --no -- intent validate packages/ui-components/skills` and fix any errors.
+
+If an action's placement depends on page-level toolbar structure you cannot see, confirm it against
+the page-level-actions reference rather than guessing.
+
+## References
+
+- [page-level toolbar and overflow placement](references/page-level-actions.md) — read when
+ deciding whether an action is primary, goes in the overflow menu, or is the refresh button, and
+ where it sits relative to tabs and DataGrids.
+- [label wording rules](references/label-wording.md) — read when writing or reviewing button label
+ text, including title case, confirming-button wording in modals, and "Sign in".
diff --git a/packages/ui-components/skills/actions/references/label-wording.md b/packages/ui-components/skills/actions/references/label-wording.md
new file mode 100644
index 0000000000..157e364b34
--- /dev/null
+++ b/packages/ui-components/skills/actions/references/label-wording.md
@@ -0,0 +1,54 @@
+# Button label wording rules
+
+Read this when writing or reviewing the text on a button, including confirming buttons in modals.
+The rules come from `docs/ux/ux-writing-content-design.md`.
+
+## Core rules
+
+- Keep labels **short** and use the **infinitive form of a verb**: "Create", "Delete", "Save",
+ "Edit", "Stop", "Confirm".
+- Do **not** prefix with "Click to …". The button already implies the click.
+- **Title case** applies (see below). **Never use ALL-CAPS, ever.**
+- No trailing punctuation. An ellipsis ("…", a single glyph) is allowed to indicate another step
+ follows — e.g. a button that opens a modal with further options.
+- Use "OK" only when the click means acknowledgement, or when nothing else really fits.
+
+## Title case
+
+Capitalize the first and last word always, plus nouns, verbs, pronouns, adjectives, adverbs,
+numbers, and subordinating conjunctions (Although, Because, If, When). Do **not** capitalize (unless
+first or last word): articles (a, an, the), short prepositions (max 5 letters: at, by, for, in, of,
+on, to, up …), short coordinating conjunctions (and, but, or, nor, so, yet), and "to" in an
+infinitive.
+
+- Do: "Sign in", "How to Use This Guide", "Confirm to Terminate an Action".
+- Don't: "Sign In", "Confirm To Terminate An Action".
+
+## "Sign in", not "Log in"
+
+Always use "Sign in" (matching SAP Fiori guidance), consistently across the app.
+
+## Consistency with surrounding copy
+
+Use the same verb in the button, the dialog title, and the body copy. If "Terminate Instance" is
+the modal title, use "terminate" in the copy and the button. If the term would appear too many
+times, fall back to a generic "OK" or "Confirm". Never use different words for the same action
+("terminate" vs. "stop" vs. "kill" reads as three different operations).
+
+## Confirming buttons in modals
+
+For the primary confirming button in a modal, prefer appending the object type to the verb when the
+object type is a single short word — "Delete Image" communicates intent more clearly than a bare
+"Delete". If the object type is more than one word or has an unusually high syllable count, use the
+verb alone.
+
+- Do (short object): "Delete Image", "Revoke Key", "Stop Instance".
+- Fall back to the verb alone: "Delete" (not "Delete Kubernetes Node Pool"), "Stop" (not "Stop
+ Hyperscaler Infrastructure").
+
+Apply this consistently within one application — do not use "Delete Image" in one modal and bare
+"Delete" in another for the same action type.
+
+## Never use "Please" or "Thanks"
+
+An app is not an individual. Be polite by respecting the user's time, not with pleasantries.
diff --git a/packages/ui-components/skills/actions/references/page-level-actions.md b/packages/ui-components/skills/actions/references/page-level-actions.md
new file mode 100644
index 0000000000..a2d605a36a
--- /dev/null
+++ b/packages/ui-components/skills/actions/references/page-level-actions.md
@@ -0,0 +1,64 @@
+# Page-level toolbar and overflow placement
+
+Read this when you are deciding whether an action should be a visible button, which variant it
+takes, whether it belongs in the overflow menu, or how actions relate to tabs and DataGrids. The
+rules below come from `docs/ux/page-level-actions.md`.
+
+## The three toolbar slots
+
+The page-level toolbar has at most three slots, in fixed left-to-right order:
+
+```
+[↻ Refresh] [⋮ Overflow] [Primary Action]
+```
+
+Not every slot must be filled. Valid combinations are: overflow alone; primary alone; overflow +
+primary; refresh alone; refresh + overflow; refresh + primary; and all three. No other orderings
+or extra button variants are permitted in the page-level toolbar.
+
+## Deciding the role
+
+Placement is driven by the action's **role**, not by screen width or how many actions there are.
+The overflow menu is a semantic container for secondary/destructive actions, not a space saver.
+
+- **Primary** — at most one per page, always a visible button, never in the overflow. A page need
+ not have one; an overflow-only toolbar is valid. Which action is primary is a human judgment
+ (frequency, relevance, expected intent) — do not pick it with a quantitative metric. A primary
+ action is almost never destructive.
+- **Secondary** — goes into the overflow menu, regardless of count or available space. One
+ exception: when there is exactly one secondary action alongside a primary and discoverability is
+ a specific concern, it may appear as a secondary button: `[↻] [Secondary] [Primary Action]`.
+ There is **no standalone secondary button** — a lone action that cannot reasonably be primary
+ goes into a single-item overflow menu.
+- **Destructive** — lives in the overflow menu with the other secondary/destructive items (see
+ `popup-and-overflow-menus.md` for ordering and divider rules). Only a page whose sole purpose is
+ a destructive operation may make it the primary button.
+
+## The refresh button
+
+Always a directly visible button, never in the overflow, always leftmost. Its label and tooltip
+text is "Refresh Page". While refreshing it must be disabled and show visual feedback — in Juno,
+set `progress` on the `Button`. If a page is only a DataGrid, use the DataGrid's built-in refresh
+instead of adding a page-level one.
+
+## Icon-only toolbar buttons
+
+Refresh and the overflow toggle are inherently icon-only. Any other action may be icon-only only
+when it is the sole secondary action, there is no overflow menu, and the icon has a strong,
+universally understood meaning (e.g. a gear for settings). If several secondary actions exist, they
+all go into the overflow with text labels. Every icon-only button needs a `title` or tooltip.
+
+## Disabled vs. hidden
+
+- **Disable** an action that is generally available but temporarily blocked by a technical
+ circumstance. A disabled button does not require a tooltip, though an accurate one is welcome.
+- **Consider not rendering** an action the user is unlikely to gain access to soon, or lacks
+ permission for.
+
+## Scope rules: DataGrids and tabs
+
+- Action affects individual rows or the whole collection → DataGrid toolbar.
+- Action affects a selection of rows → DataGrid bulk-actions area.
+- Action affects the page context/scope as a whole → page-level toolbar.
+- With tabs: actions affecting the whole page go **above** the tab bar and are static (they do not
+ change with the active tab); actions scoped to one tab go **below** the tab bar.
diff --git a/packages/ui-components/skills/app-foundations/SKILL.md b/packages/ui-components/skills/app-foundations/SKILL.md
new file mode 100644
index 0000000000..7a40387a58
--- /dev/null
+++ b/packages/ui-components/skills/app-foundations/SKILL.md
@@ -0,0 +1,244 @@
+---
+name: app-foundations
+description: >
+ Use when bootstrapping a Juno app or plugin with @cloudoperators/juno-ui-components: wiring the
+ required provider so components render at all, loading the library CSS and your own styles,
+ choosing or switching the dark/light theme, encapsulating styles in a Shadow DOM, and running
+ the app embedded inside a host shell. Covers AppShellProvider (the recommended entry point) plus
+ the primitives it composes — StyleProvider, PortalProvider, and ShadowRoot — and when to drop
+ down to them. For the page layout container (header/nav/footer slots) see the AppShell layout
+ skill; this skill is about the providers that must wrap it.
+metadata:
+ purpose: >
+ Teaches developers to bootstrap a Juno application correctly: wrapping the app in a single
+ AppShellProvider (which composes StyleProvider + PortalProvider, optionally inside a ShadowRoot),
+ loading the component CSS where the chosen style/shadow mode requires it, selecting a theme, and
+ adjusting the setup for standalone vs. Shadow-DOM-encapsulated vs. host-embedded deployment —
+ the invisible plumbing that, if omitted, makes components silently fail to style or portal.
+ type: core
+ library: "@cloudoperators/juno-ui-components"
+ library_version: "9.6.0"
+sources:
+ - cloudoperators/juno:packages/ui-components/src/components/AppShellProvider/AppShellProvider.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/AppShellProvider/AppShellProvider.stories.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/StyleProvider/StyleProvider.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/StyleProvider/StyleProvider.stories.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/PortalProvider/PortalProvider.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/PortalProvider/PortalProvider.stories.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/ShadowRoot/ShadowRoot.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/ShadowRoot/ShadowRoot.stories.tsx
+ - cloudoperators/juno:docs/ux/the-appshell.md
+ - cloudoperators/juno:docs/ux/getting-started-with-juno-ui-components.md
+ - cloudoperators/juno:docs/ux/core-concepts.md
+ - cloudoperators/juno:docs/ux/foundations.md
+ - cloudoperators/juno:docs/ux/embedded-application-layout.md
+---
+
+# Bootstrap a Juno app: providers, theming, and embedding
+
+Every Juno component needs styling context, a theme class, and a portal root before it can render
+correctly. The library gives you one component that supplies all of this: **`AppShellProvider`**. It
+composes three primitives for you — `StyleProvider` (styles + theme), `PortalProvider` (portal root
+for `Modal`, `Select`, menus, etc.), and optionally a `ShadowRoot` (style encapsulation). You wrap
+your whole app in it exactly once, at the root.
+
+Starting without these building blocks is possible but costly: the UX guidance warns that an app
+built from scratch without them "may result in the application or individual components not working
+at all, or not rendering or working as expected" (`docs/ux/the-appshell.md`). Use `AppShellProvider`
+as the entry point and only drop down to the individual providers when you have a specific reason
+(documented under [standalone and advanced provider setups](references/providers-standalone.md)).
+
+## Setup
+
+Wrap the application once, at the root, and load your own styles as a child `<style>` element so
+they land in the same (shadow) scope as the component styles:
+
+```tsx
+import { AppShellProvider } from "@cloudoperators/juno-ui-components"
+import { createRoot } from "react-dom/client"
+
+declare const App: React.ComponentType
+declare const appStyles: string // your bundled CSS, imported as a string
+
+createRoot(document.getElementById("root")!).render(
+ <AppShellProvider>
+ {/* Load your app styles inside the same scope as the Juno styles */}
+ <style>{appStyles}</style>
+ <App />
+ </AppShellProvider>
+)
+```
+
+With no props, `AppShellProvider` renders the app inside a `ShadowRoot` (`shadowRoot` defaults to
+`true`), applies the default dark theme (`theme` defaults to `"theme-dark"`), and injects the
+component CSS **inline** inside that shadow root. This is the recommended default and the one used
+in the getting-started guide (`docs/ux/getting-started-with-juno-ui-components.md`).
+
+Do **not** nest a second `AppShellProvider`, `StyleProvider`, or `PortalProvider` inside this one —
+one provider at the root is the whole contract.
+
+## Core patterns
+
+### Choose a theme
+
+`AppShellProvider`'s `theme` prop is typed to exactly `"theme-dark" | "theme-light"`; dark is the
+default. Set it once at the root:
+
+```tsx
+import { AppShellProvider } from "@cloudoperators/juno-ui-components"
+
+declare const App: React.ComponentType
+
+function Root() {
+ return (
+ <AppShellProvider theme="theme-light">
+ <App />
+ </AppShellProvider>
+ )
+}
+```
+
+The theme is applied as a CSS class on the provider's container element; Juno theming currently
+works through CSS variables carried by that class (`docs/ux/core-concepts.md`, "Themeability").
+
+To let the user toggle the theme at runtime (rather than fixing it at the root), use the
+`StyleProvider.useStyles()` context hook, which exposes `currentTheme` and `setThemeClass`. That
+only works for descendants of a `StyleProvider` (which `AppShellProvider` renders for you). See
+[runtime theme switching](references/providers-standalone.md#runtime-theme-switching).
+
+### Decide where the styles live: Shadow DOM vs. document
+
+`AppShellProvider` has two props that together control style scoping. They interact, so set them as
+a pair:
+
+- `shadowRoot?: boolean` (default `true`) — render the app inside a `ShadowRoot` so Juno styles are
+ isolated from the host page and vice versa.
+- `stylesWrapper?: "head" | "inline"` (default `"inline"`) — where the component CSS is injected.
+ **This is only honored when `shadowRoot` is `false`.** Inside a shadow root the styles must be
+ inline (they cannot reach `document.head` through the shadow boundary), so the provider forces
+ `"inline"` regardless of what you pass.
+
+```tsx
+import { AppShellProvider } from "@cloudoperators/juno-ui-components"
+
+declare const App: React.ComponentType
+
+// Standalone app, no shadow DOM, Juno styles injected into <head>:
+function Root() {
+ return (
+ <AppShellProvider shadowRoot={false} stylesWrapper="head">
+ <App />
+ </AppShellProvider>
+ )
+}
+```
+
+Guidance:
+
+- **Embedded in a host shell, or any page you don't fully control → keep `shadowRoot` (default
+ `true`).** Encapsulation prevents the host's CSS from leaking into your components and vice versa,
+ which matters for the micro-frontend / embedded model Juno supports
+ (`docs/ux/core-concepts.md`, "Micro-Frontend Support").
+- **Standalone app that owns the whole document → `shadowRoot={false}`** is fine, and
+ `stylesWrapper="head"` keeps the DOM a little cleaner. `"inline"` also works standalone.
+
+### Run embedded inside a host shell
+
+A Juno app can run on its own or be mounted by a host ("Shell") app that embeds one or more child
+apps (`docs/ux/embedded-application-layout.md`). The provider setup is the same either way — wrap in
+`AppShellProvider` — but embedded apps should keep the Shadow DOM on so the host's styles stay out:
+
+```tsx
+import { AppShellProvider } from "@cloudoperators/juno-ui-components"
+
+declare const App: React.ComponentType
+
+// Mount point the host hands you; theme usually follows the host.
+export default function mount(container: HTMLElement, theme: "theme-dark" | "theme-light") {
+ return (
+ <AppShellProvider shadowRoot theme={theme}>
+ <App />
+ </AppShellProvider>
+ )
+}
+```
+
+Embedding also changes **layout** (the embedded app hides its own page header because the host
+renders one, per `docs/ux/embedded-application-layout.md`) — that is controlled by the `AppShell`
+layout component's `embedded` prop, not by `AppShellProvider`. See the AppShell layout skill for
+that. This skill only covers the provider wrapper.
+
+### Render overlays through the portal
+
+Because `AppShellProvider` includes `PortalProvider`, components that pop out of the normal flow —
+`Modal`, `Select`, menus, date pickers — already have a portal root to render into, with a high
+`z-index` so they stack above app content. You usually do nothing extra. When you build a _custom_
+component that must portal (a bespoke popover, a positioned picker), reach the root with the
+`usePortalRef` hook or the `PortalProvider.Portal` component:
+
+```tsx
+import { usePortalRef } from "@cloudoperators/juno-ui-components"
+import { createPortal } from "react-dom"
+
+function CustomPopover({ children }: { children: React.ReactNode }) {
+ const portalRef = usePortalRef()
+ if (!portalRef) return null
+ return createPortal(children, portalRef)
+}
+```
+
+`usePortalRef` returns `null` until the portal root exists, and warns to the console if it is called
+outside a `PortalProvider` — which is the symptom of a missing `AppShellProvider` at the root. Read
+[portals and the portal root](references/portals.md) when a portaled component renders in the wrong
+place, is clipped, or stacks incorrectly.
+
+## Common mistakes
+
+- **CRITICAL — No provider at the root.** Rendering Juno components without wrapping the app in
+ `AppShellProvider` (or the individual `StyleProvider` + `PortalProvider`) leaves components
+ unstyled and breaks every portaled component (`Modal`, `Select`, menus). The UX guidance is
+ explicit that skipping these building blocks can make components "not working at all, or not
+ rendering or working as expected" (`docs/ux/the-appshell.md`). Always wrap once at the root.
+- **CRITICAL — App styles loaded outside the provider's scope when using a Shadow DOM.** With the
+ default `shadowRoot`, a global stylesheet linked in `document.head` does **not** cross the shadow
+ boundary, so your own CSS silently does nothing. Load app styles as a `<style>` child _inside_
+ `AppShellProvider`, as in Setup (`docs/ux/getting-started-with-juno-ui-components.md`).
+- **HIGH — Expecting `stylesWrapper="head"` to work inside a Shadow DOM.** `stylesWrapper` is only
+ honored when `shadowRoot={false}`; inside a shadow root styles are forced inline. To put styles in
+ `<head>`, you must also set `shadowRoot={false}`.
+- **HIGH — Nesting multiple providers.** Wrapping an already-provided subtree in another
+ `AppShellProvider`/`StyleProvider`/`PortalProvider` creates duplicate theme containers and portal
+ roots, causing double styling scopes and misplaced overlays. Provide exactly once, at the root.
+- **MEDIUM — Invalid `theme` value.** `AppShellProvider` accepts only `"theme-dark"` or
+ `"theme-light"`. An arbitrary string (e.g. `"dark"`) applies a class that no CSS variables match,
+ leaving the app half-styled.
+- **MEDIUM — Dropping the Shadow DOM for an embedded app.** Running embedded with
+ `shadowRoot={false}` lets the host page's CSS bleed into your components. Keep encapsulation on
+ when a host controls the surrounding document (`docs/ux/core-concepts.md`, "Micro-Frontend
+ Support").
+
+## Completion
+
+Verify:
+
+1. The app is wrapped in exactly one `AppShellProvider` (or one `StyleProvider` + `PortalProvider`
+ pair) at the root — not nested, not duplicated.
+2. Your own CSS is loaded where the chosen scoping puts it: inside the provider as a `<style>` child
+ when a Shadow DOM is used; otherwise `<head>`/inline consistently.
+3. `theme` is `"theme-dark"` or `"theme-light"` (or driven by the host when embedded).
+4. A portaled component (`Modal` or `Select`) opens and renders above app content — proof the portal
+ root exists.
+5. Run `npm exec --no -- intent validate packages/ui-components/skills` and fix any errors.
+
+If a deployment mode (standalone vs. embedded, light vs. dark) cannot be exercised in your harness,
+report it as unverified rather than assuming it renders.
+
+## References
+
+- [standalone and advanced provider setups](references/providers-standalone.md) — read when you
+ need the individual providers directly (`StyleProvider`, `PortalProvider`, `ShadowRoot`) instead
+ of `AppShellProvider`, want runtime theme switching, or need the exact `stylesWrapper` /
+ `shadowRootMode` matrix.
+- [portals and the portal root](references/portals.md) — read when a portaled component (custom or
+ built-in) renders in the wrong container, is clipped, warns about `usePortalRef`, or stacks behind
+ other content.
diff --git a/packages/ui-components/skills/app-foundations/references/portals.md b/packages/ui-components/skills/app-foundations/references/portals.md
new file mode 100644
index 0000000000..092c8d5c9c
--- /dev/null
+++ b/packages/ui-components/skills/app-foundations/references/portals.md
@@ -0,0 +1,74 @@
+# Portals and the portal root
+
+Read this when a portaled component — a built-in `Modal`/`Select`/menu, or a custom one you wrote —
+renders in the wrong place, is clipped by an ancestor's `overflow`, stacks behind other content, or
+logs a `usePortalRef must be called inside a PortalProvider` warning. Source:
+`packages/ui-components/src/components/PortalProvider/PortalProvider.component.tsx`,
+`packages/ui-components/src/components/PortalProvider/PortalProvider.Portal.component.tsx`,
+`packages/ui-components/src/components/PortalProvider/PortalProvider.stories.tsx`.
+
+## What `PortalProvider` provides
+
+`PortalProvider` renders a single portal-root `<div>` (class `juno-portal-root`, id defaults to
+`"juno-portal-root"`) with a very high `z-index` (9999) and `position: absolute`. Everything that
+needs to escape normal flow — modals, select dropdowns, menus, date pickers — portals into this
+root so it stacks above app content regardless of ancestor `overflow`/`z-index`.
+
+`AppShellProvider` already includes `PortalProvider`, so in a correctly bootstrapped app you get
+this for free. You interact with it only when writing your own portaled component.
+
+Props:
+
+- `className?: string` — extra class on the portal-root container.
+- `id?: string` — id of the portal-root container (default `"juno-portal-root"`).
+- `children?: ReactNode`.
+
+## Two ways to portal custom content
+
+### `usePortalRef` hook
+
+`usePortalRef()` creates a dedicated portal container inside the portal root and returns its DOM
+node (or `null` until it is ready). Use it with React's `createPortal`, or hand it to components
+that take a positioning reference element (e.g. a Flatpickr/date picker):
+
+```tsx
+import { usePortalRef } from "@cloudoperators/juno-ui-components"
+import { createPortal } from "react-dom"
+
+function CustomMenu({ children }: { children: React.ReactNode }) {
+ const portalRef = usePortalRef()
+ if (!portalRef) return null // not ready, or no PortalProvider above
+ return createPortal(children, portalRef)
+}
+```
+
+If called outside a `PortalProvider`, `usePortalRef` warns to the console and returns `null` — the
+tell-tale sign that the app is missing its `AppShellProvider` (or `PortalProvider`) at the root.
+
+### `PortalProvider.Portal` component
+
+For a declarative wrapper, render children through `PortalProvider.Portal`; it portals them into the
+root for you:
+
+```tsx
+import { PortalProvider } from "@cloudoperators/juno-ui-components"
+
+function Overlay({ children }: { children: React.ReactNode }) {
+ return <PortalProvider.Portal>{children}</PortalProvider.Portal>
+}
+```
+
+Both approaches render into the same high-`z-index` root, so multiple portals coexist (see the
+`MultiplePortals` story).
+
+## Troubleshooting
+
+- **Component renders inline / clipped instead of on top** → it is not portaling, usually because
+ there is no `PortalProvider` ancestor. Confirm the app is wrapped in `AppShellProvider`.
+- **`usePortalRef` warning in the console** → same cause: the hook ran outside a `PortalProvider`.
+ Wrap the root; do not add a second `PortalProvider` deep in the tree.
+- **Overlay stacks behind other UI** → something in the app sets a `z-index` above 9999, or the
+ content was rendered without the portal. Portal it (hook or `PortalProvider.Portal`) rather than
+ bumping z-indexes.
+- **Returns `null` on first render** → expected. `usePortalRef` is `null` until the portal container
+ mounts; guard with `if (!portalRef) return null` as shown.
diff --git a/packages/ui-components/skills/app-foundations/references/providers-standalone.md b/packages/ui-components/skills/app-foundations/references/providers-standalone.md
new file mode 100644
index 0000000000..4d7aef8664
--- /dev/null
+++ b/packages/ui-components/skills/app-foundations/references/providers-standalone.md
@@ -0,0 +1,134 @@
+# Standalone and advanced provider setups
+
+Read this when you cannot use `AppShellProvider` as-is and need the individual providers it
+composes, when you want to switch themes at runtime, or when you need the exact `stylesWrapper` /
+`shadowRootMode` behavior. Sources:
+`packages/ui-components/src/components/StyleProvider/StyleProvider.component.tsx`,
+`packages/ui-components/src/components/ShadowRoot/ShadowRoot.component.tsx`,
+`packages/ui-components/src/components/PortalProvider/PortalProvider.component.tsx`,
+`docs/ux/foundations.md`, `docs/ux/core-concepts.md`.
+
+## What `AppShellProvider` actually renders
+
+`AppShellProvider` is a thin composition. With `shadowRoot` on it renders:
+
+```
+ShadowRoot(mode=shadowRootMode)
+ └─ StyleProvider(theme, stylesWrapper="inline")
+ └─ PortalProvider
+ └─ your children
+```
+
+With `shadowRoot={false}` the `ShadowRoot` wrapper is dropped and `StyleProvider` uses the
+`stylesWrapper` you passed (`"head"` or `"inline"`). This is why you only need the primitives
+directly in unusual cases — the default composition already covers standalone and embedded apps.
+
+## Assembling the providers by hand
+
+If you must build the stack yourself (e.g. you want a non-standard nesting, or to interleave your
+own context), replicate the same order — styles outside, portal inside:
+
+```tsx
+import { StyleProvider, PortalProvider } from "@cloudoperators/juno-ui-components"
+
+declare const App: React.ComponentType
+
+function Root() {
+ return (
+ <StyleProvider theme="theme-dark" stylesWrapper="head">
+ <PortalProvider>
+ <App />
+ </PortalProvider>
+ </StyleProvider>
+ )
+}
+```
+
+Keep `PortalProvider` **inside** `StyleProvider` so portaled content is still inside the themed
+container. This hand-rolled form is the "do it yourself" path the UX guidance warns is higher-cost
+than `AppShellProvider` (`docs/ux/the-appshell.md`); prefer the provider unless you have a concrete
+reason.
+
+## `StyleProvider` on its own
+
+`StyleProvider` manages styles and theming. Its props:
+
+- `theme?: string` — the theme class name. Defaults to `"theme-dark"` (`DEFAULT_THEME_NAME`).
+ Unlike `AppShellProvider`, this prop is a plain `string`, so pass a real theme class.
+- `stylesWrapper?: "head" | "inline" | "shadowRoot"` — where styles go. Default `"inline"`.
+ `"head"` injects into `document.head`; `"inline"` renders a `<style>` next to the content;
+ `"shadowRoot"` wraps the content in a `ShadowRoot` and inlines styles there (a backwards-compat
+ convenience — prefer composing `ShadowRoot` explicitly or using `AppShellProvider`).
+- `shadowRootMode?: "open" | "closed"` — only relevant when `stylesWrapper="shadowRoot"`.
+- `children?: ReactNode`.
+
+```tsx
+import { StyleProvider } from "@cloudoperators/juno-ui-components"
+
+function ThemedWidget({ children }: { children: React.ReactNode }) {
+ return (
+ <StyleProvider theme="theme-light" stylesWrapper="inline">
+ {children}
+ </StyleProvider>
+ )
+}
+```
+
+### Runtime theme switching
+
+`StyleProvider` exposes a context via the static `StyleProvider.useStyles()` hook. It returns
+`{ styles, currentTheme, setThemeClass, addCssClass, removeCssClass }`. Call `setThemeClass` with a
+theme class name to switch the theme live (it also persists to local storage under `"juno-theme"`):
+
+```tsx
+import { StyleProvider } from "@cloudoperators/juno-ui-components"
+
+function ThemeToggle() {
+ const { currentTheme, setThemeClass } = StyleProvider.useStyles()
+ return (
+ <button onClick={() => setThemeClass(currentTheme === "theme-dark" ? "theme-light" : "theme-dark")}>
+ Toggle theme (now {currentTheme})
+ </button>
+ )
+}
+```
+
+`useStyles()` only works for descendants of a `StyleProvider` (which `AppShellProvider` renders), so
+a theme toggle must live inside the provided subtree.
+
+## `ShadowRoot` on its own
+
+`ShadowRoot` attaches a shadow DOM to a host `<div>` and portals its children into it, isolating
+styles. Props:
+
+- `mode?: "open" | "closed"` — default `"open"`. Use `"closed"` to prevent styles being inherited
+ from the parent node.
+- `delegatesFocus?: boolean` — default `false`.
+- `children?: ReactNode`.
+
+```tsx
+import { ShadowRoot } from "@cloudoperators/juno-ui-components"
+
+function IsolatedBox() {
+ return (
+ <ShadowRoot mode="closed">
+ <h1>Welcome</h1>
+ </ShadowRoot>
+ )
+}
+```
+
+Note: `ShadowRoot` by itself does **not** inject Juno styles — put a `StyleProvider` (with
+`stylesWrapper="inline"`) inside it, or just use `AppShellProvider`, which wires both together.
+
+## The `stylesWrapper` / `shadowRoot` matrix
+
+| Goal | `AppShellProvider` props |
+| --------------------------------------- | ------------------------------------------- |
+| Default: isolated, inline styles | _(none)_ — `shadowRoot` true, inline forced |
+| Standalone, styles in `<head>` | `shadowRoot={false} stylesWrapper="head"` |
+| Standalone, inline styles, no isolation | `shadowRoot={false} stylesWrapper="inline"` |
+| Closed shadow root | `shadowRootMode="closed"` |
+
+`stylesWrapper` is ignored while `shadowRoot` is `true` (styles cannot cross the shadow boundary
+into `document.head`, so they are always inlined inside the shadow root).
diff --git a/packages/ui-components/skills/data-display/SKILL.md b/packages/ui-components/skills/data-display/SKILL.md
new file mode 100644
index 0000000000..61da6ddacc
--- /dev/null
+++ b/packages/ui-components/skills/data-display/SKILL.md
@@ -0,0 +1,322 @@
+---
+name: data-display
+description: >
+ Use when displaying non-tabular content in a Juno app built with @cloudoperators/juno-ui-components:
+ grouping information in a Card, rendering an item's properties as a term/definition DescriptionList,
+ showing inline code with Code or a copyable multi-line block with CodeBlock and CodeBlockFooter,
+ rendering structured JSON with the collapsible JsonViewer, styling rich HTML prose with
+ FormattedText, and placing an Icon as a glyph, link, or button. For tabular lists of items use the
+ datagrid skill; for status badges and the empty/error pattern see the feedback skill.
+metadata:
+ purpose: >
+ Teaches developers to pick and compose the Juno content-display primitives (Card, DescriptionList
+ with DescriptionTerm/DescriptionDefinition, Code, CodeBlock with CodeBlockFooter, JsonViewer,
+ FormattedText, Icon) with their real props, including the detail-view term/definition pattern,
+ the inline-vs-block code distinction, and the UX writing rules for titles, empty values, and
+ accessible interactive icons that the components do not enforce on their own.
+ type: core
+ library: "@cloudoperators/juno-ui-components"
+ library_version: "9.6.0"
+sources:
+ - cloudoperators/juno:packages/ui-components/src/components/Card/Card.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/Card/Card.stories.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/DescriptionList/DescriptionList.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/DescriptionList/DescriptionList.stories.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/DescriptionTerm/DescriptionTerm.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/DescriptionDefinition/DescriptionDefinition.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/Code/Code.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/Code/Code.stories.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/CodeBlock/CodeBlock.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/CodeBlock/CodeBlock.stories.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/CodeBlockFooter/CodeBlockFooter.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/CodeBlockFooter/CodeBlockFooter.stories.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/JsonViewer/JsonViewer.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/JsonViewer/JsonViewer.stories.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/FormattedText/FormattedText.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/FormattedText/FormattedText.stories.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/Icon/Icon.component.tsx
+ - cloudoperators/juno:docs/ux/datagrid.md
+ - cloudoperators/juno:docs/ux/ux-writing-content-design.md
+---
+
+# Display content and data with Juno
+
+For a _list of items_ that users scan, sort, and filter, reach for the DataGrid (see the datagrid
+skill). This skill covers everything else: a single item's properties, a container that groups
+content, code and JSON, rich prose, and glyphs. The UX guidelines explicitly point you here — a
+single item or entity belongs in a detail view, panel, or card, not a grid (`docs/ux/datagrid.md`,
+"Don't use a DataGrid and Consider an Alternative When").
+
+Pick the component by content shape:
+
+- **Card** — a container that groups related content; optionally the whole card is a link or button.
+- **DescriptionList** (+ **DescriptionTerm**, **DescriptionDefinition**) — term/definition pairs, i.e.
+ an item's properties in a detail view. Renders real `<dl>`/`<dt>`/`<dd>`.
+- **Code** — short inline `<code>` inside a sentence.
+- **CodeBlock** (+ **CodeBlockFooter**) — a multi-line, copyable code block; renders a `JsonViewer`
+ when `lang="json"`.
+- **JsonViewer** — a collapsible, searchable JSON tree on its own.
+- **FormattedText** — a wrapper that styles raw HTML prose (headings, lists, tables, links).
+- **Icon** — a named SVG glyph, optionally a link (`href`) or button (`onClick`).
+
+## Setup
+
+Everything imports from the package root. Components render unstyled unless the app is wrapped in
+`AppShellProvider` (see the fundamentals skill if styles are missing).
+
+```tsx
+import { Card, DescriptionList, DescriptionTerm, DescriptionDefinition } from "@cloudoperators/juno-ui-components"
+
+function PreviewCard() {
+ return (
+ <Card padding>
+ <DescriptionList>
+ <DescriptionTerm>Region</DescriptionTerm>
+ <DescriptionDefinition>eu-de-1</DescriptionDefinition>
+ </DescriptionList>
+ </Card>
+ )
+}
+```
+
+## Core patterns
+
+### Group content in a Card
+
+A `Card` is a `<div>` by default. Pass `padding` for internal spacing (default `false`). It accepts
+any `children`:
+
+```tsx
+import { Card } from "@cloudoperators/juno-ui-components"
+
+function InfoCard() {
+ return (
+ <Card padding className="jn:max-w-md">
+ <h3>Cluster health</h3>
+ <p>All control-plane nodes are reachable.</p>
+ </Card>
+ )
+}
+```
+
+Make a card interactive by passing `href` (renders an `<a>`) or `onClick` (renders a `<button>`).
+`href` takes precedence over `onClick`. `disabled` strips the `href`, adds `aria-disabled`, and
+shows a not-allowed cursor. Only make a card interactive when the whole card is one navigation
+target or action — mirror the DataGrid rule that a clickable surface should not also wrap its own
+nested buttons/links (`docs/ux/datagrid.md`, "Interacting with DataGrid Rows / Items").
+
+```tsx
+import { Card } from "@cloudoperators/juno-ui-components"
+declare function navigate(to: string): void
+
+function ClusterCard({ id, name }: { id: string; name: string }) {
+ return (
+ <Card padding onClick={() => navigate(`/clusters/${id}`)}>
+ <h3>{name}</h3>
+ </Card>
+ )
+}
+```
+
+### Show an item's properties in a DescriptionList
+
+`DescriptionList` renders a `<dl>` on a 4-column grid: each `DescriptionTerm` (`<dt>`) spans 1 column,
+each `DescriptionDefinition` (`<dd>`) spans 3. Stream `DescriptionTerm`/`DescriptionDefinition` pairs
+as children. `alignTerms` is `"right"` (default) or `"left"`. `DL`, `DT`, `DD` are exported aliases.
+
+```tsx
+import { DescriptionList, DescriptionTerm, DescriptionDefinition } from "@cloudoperators/juno-ui-components"
+
+type Instance = { name?: string; id: string; region: string; createdAt: string }
+
+function InstanceDetails({ instance }: { instance: Instance }) {
+ return (
+ <DescriptionList alignTerms="left">
+ <DescriptionTerm>Name</DescriptionTerm>
+ <DescriptionDefinition>{instance.name ?? "- -"}</DescriptionDefinition>
+ <DescriptionTerm>ID</DescriptionTerm>
+ <DescriptionDefinition>{instance.id}</DescriptionDefinition>
+ <DescriptionTerm>Region</DescriptionTerm>
+ <DescriptionDefinition>{instance.region}</DescriptionDefinition>
+ <DescriptionTerm>Created</DescriptionTerm>
+ <DescriptionDefinition>{instance.createdAt}</DescriptionDefinition>
+ </DescriptionList>
+ )
+}
+```
+
+A `DescriptionList` is a verbatim metadata display: when a value is missing render the `- -`
+placeholder (two hyphens separated by a space), and here do **not** substitute the ID for a missing
+name — that would misrepresent what is stored (`docs/ux/ux-writing-content-design.md`, "Rendering
+Empty or Unknown Values" / "Exception: verbatim metadata display"). Override the grid via `className`
+(e.g. `className="jn:grid-cols-2"` plus matching `col-span` classes on children) only when the 1:3
+layout does not fit. See [description-list layout](references/description-list-layout.md) for the
+custom-grid recipe.
+
+### Inline code vs. a code block
+
+Use `Code` for a short token inside running text — a flag, an env var, a field name. It renders an
+inline `<code>`. Content comes from `children` or the `content` prop (`content` overrides
+`children`):
+
+```tsx
+import { Code } from "@cloudoperators/juno-ui-components"
+
+function Hint() {
+ return (
+ <p>
+ Set <Code>LOG_LEVEL=debug</Code> to see verbose output.
+ </p>
+ )
+}
+```
+
+Use `CodeBlock` for multi-line snippets, certificates, or payloads the user may copy. It renders a
+`<pre><code>` with a copy button by default (`copy={true}`). Pass the body as `children` (or `content`
+for a string); `wrap` (default `true`) toggles line wrapping; `size` (`"auto" | "small" | "medium"
+| "large"`) caps height with a scrollbar; `heading` renders a tab-styled caption.
+
+```tsx
+import { CodeBlock } from "@cloudoperators/juno-ui-components"
+
+function CertBlock({ pem }: { pem: string }) {
+ return (
+ <CodeBlock heading="server.crt" size="small" wrap={false}>
+ {pem}
+ </CodeBlock>
+ )
+}
+```
+
+### Render JSON
+
+Set `lang="json"` on `CodeBlock` and pass an object/string to `content` — it renders a `JsonViewer`
+internally and the copy button serializes the JSON. For a standalone, interactive tree use
+`JsonViewer` directly: `data` is required; `toolbar` adds expand-all/collapse-all and search;
+`expanded` (default `1`) sets how many levels start open; `showRoot`, `truncate`, `indentWidth`, and
+`theme` (`"dark"`/`"light"` or a color map) tune the display.
+
+```tsx
+import { CodeBlock, JsonViewer } from "@cloudoperators/juno-ui-components"
+
+type Payload = { name: string; labels: Record<string, string> }
+
+function PayloadView({ payload }: { payload: Payload }) {
+ return (
+ <>
+ <CodeBlock lang="json" heading="payload.json" content={payload} />
+ <JsonViewer data={payload} toolbar expanded={2} theme="dark" />
+ </>
+ )
+}
+```
+
+### Add a custom action to a CodeBlock footer
+
+Pass a node to `codeBlockFooter` to inject a control to the **left of** the Copy button; the footer
+wrapper always renders. Keep `copy` at its default `true` to show both, or set `copy={false}` to
+show only your action. This replaced the old "pass an element to replace the whole footer" behavior —
+read [codeblock footer actions](references/codeblock-footer.md) before migrating older code.
+
+```tsx
+import { CodeBlock, Icon } from "@cloudoperators/juno-ui-components"
+declare function handleDownload(): void
+
+function DownloadableBlock({ code }: { code: string }) {
+ return <CodeBlock content={code} codeBlockFooter={<Icon icon="download" onClick={handleDownload} />} />
+}
+```
+
+### Style rich prose with FormattedText
+
+`FormattedText` is a wrapper that applies consistent typography to raw HTML children — headings,
+paragraphs, lists, tables, links, and inline `<code>`. Use it for long-form content (docs, release
+notes, markdown rendered to HTML), not for individual labels.
+
+```tsx
+import { FormattedText } from "@cloudoperators/juno-ui-components"
+
+function ReleaseNotes() {
+ return (
+ <FormattedText>
+ <h2>Release 9.6.0</h2>
+ <p>Highlights of this release:</p>
+ <ul>
+ <li>New data-display components</li>
+ </ul>
+ </FormattedText>
+ )
+}
+```
+
+### Render an Icon as glyph, link, or button
+
+`Icon` takes a named `icon` (a `KnownIcons` value such as `"info"`, `"download"`, `"contentCopy"`,
+`"checkCircle"`), plus `size` (number or string, default `24`), `color`, and `title`. With no `href`
+or `onClick` it renders a plain inline glyph; `href` makes it an `<a>`; `onClick` makes it a
+`<button>`. Set `title` so the control is labeled for screen readers — it drives `aria-label` on the
+link/button and the SVG `title`.
+
+```tsx
+import { Icon } from "@cloudoperators/juno-ui-components"
+declare function refresh(): void
+
+function RefreshButton() {
+ return <Icon icon="cached" title="Refresh" onClick={refresh} />
+}
+```
+
+Only known icon names type-check; an unknown or omitted name falls back to the help glyph. For the
+full list of names and the deprecated aliases (`success` → `checkCircle`, `schedule` → `accessTime`)
+read [icon names and accessibility](references/icon-names.md).
+
+## Common mistakes
+
+- **CRITICAL — Interactive icon with no `title`.** An `Icon` used as `onClick` button or `href` link
+ with no `title` gives screen-reader users only the raw icon name (or nothing) as its label. Always
+ pass a human-readable `title`; it becomes the `aria-label`. (Icon source: `title` drives
+ `aria-label`.)
+- **HIGH — Substituting the ID for a missing name inside a `DescriptionList`.** A `<dl>` is verbatim
+ metadata; show `- -` for an unset name here. The "fall back to the ID" rule is for Name columns,
+ detail-view titles, and breadcrumbs — not for a property list. (`docs/ux/ux-writing-content-design.md`,
+ "Exception: verbatim metadata display".)
+- **HIGH — Nesting buttons/links inside an interactive Card.** A `Card` with `onClick`/`href` is one
+ click target; inner buttons or links create ambiguous, conflicting targets. Use a non-interactive
+ Card with in-content actions, or an interactive Card with no nested targets. (`docs/ux/datagrid.md`,
+ "Interacting with DataGrid Rows / Items" — same affordance rule.)
+- **HIGH — `CodeBlock` for a single inline token.** A full copyable block around one word breaks the
+ reading flow of a sentence. Use `Code` inline; reserve `CodeBlock` for multi-line, copyable content.
+- **MEDIUM — All-caps or punctuated titles in Cards and lists.** Titles and `DescriptionTerm` labels
+ follow title case, never all-caps, and carry no trailing punctuation. (`docs/ux/ux-writing-content-design.md`,
+ "Title Case", "Errors and Error Messages".)
+- **MEDIUM — Em/en dash instead of `- -` for empty values.** Render missing values as `- -` (two
+ hyphens, a space between), not `–`, `—`, `--`, or `N/A`. (`docs/ux/ux-writing-content-design.md`,
+ "Rendering Empty or Unknown Values".)
+- **MEDIUM — Non-`DescriptionTerm`/`Definition` children in a `DescriptionList`.** The grid alignment
+ depends on `<dt>`/`<dd>` and their `col-span` classes; arbitrary children break the layout and the
+ `<dl>` semantics.
+
+## Completion
+
+Verify:
+
+1. Each component uses only real props (e.g. `Card` has no `variant`; `DescriptionTerm`/`Definition`
+ take `children`, not a `label`/`value` pair).
+2. Every interactive `Icon` and interactive `Card` has an accessible label (`title` / discernible
+ text).
+3. Missing values render `- -`, except Name columns / detail-view titles / breadcrumbs (ID) — and a
+ `DescriptionList` stays verbatim (`- -`, never the ID).
+4. Titles and term labels follow title case with no all-caps and no trailing punctuation.
+5. Run `npm exec --no -- intent validate packages/ui-components/skills` and fix any errors.
+
+If a rendered state (e.g. the copy confirmation or JSON search) cannot be exercised in your harness,
+report it as unverified rather than assuming it renders.
+
+## References
+
+- [description-list layout](references/description-list-layout.md) — read when the default 1:3,
+ 4-column grid does not fit and you need a custom `grid-cols`/`col-span` template.
+- [codeblock footer actions](references/codeblock-footer.md) — read before adding footer actions or
+ migrating code that passed a full replacement element to `codeBlockFooter`.
+- [icon names and accessibility](references/icon-names.md) — read for the full `KnownIcons` list, the
+ deprecated aliases, and the link-vs-button rendering rules.
diff --git a/packages/ui-components/skills/data-display/references/codeblock-footer.md b/packages/ui-components/skills/data-display/references/codeblock-footer.md
new file mode 100644
index 0000000000..0b2f1e0fb9
--- /dev/null
+++ b/packages/ui-components/skills/data-display/references/codeblock-footer.md
@@ -0,0 +1,54 @@
+# CodeBlock footer actions
+
+`CodeBlock` always renders a `CodeBlockFooter` when either `copy` is truthy (the default) or
+`codeBlockFooter` is provided. The `codeBlockFooter` prop injects content **into** the footer bar, to
+the left of the Copy button.
+
+## Breaking change (do not reintroduce the old pattern)
+
+Previously `codeBlockFooter` accepted a full replacement element that replaced the entire footer.
+It now injects content _into_ the always-rendered footer wrapper. If you are migrating older code
+that passed a complete footer element expecting it to replace the bar, drop the wrapper and pass only
+the action node; use `copy={false}` when you want to hide the built-in Copy button
+(`CodeBlock.component.tsx`, `codeBlockFooter` JSDoc).
+
+## Combinations
+
+- `copy` default `true`, no `codeBlockFooter` → Copy button only.
+- `copy` default `true` + `codeBlockFooter={node}` → your action **and** the Copy button, in one bar.
+- `copy={false}` + `codeBlockFooter={node}` → only your action, no Copy button.
+- `copy={false}`, no `codeBlockFooter` → no footer rendered at all.
+
+```
+<CodeBlock
+ content={code}
+ copy={false}
+ codeBlockFooter={<Icon icon="download" onClick={handleDownload} />}
+/>
+```
+
+## CodeBlockFooter standalone
+
+`CodeBlockFooter` can be used directly (`CodeBlockFooter.component.tsx`). Its props:
+
+- `onCopy: () => void` — required; invoked when the Copy button is clicked. (React's `onCopy`
+ clipboard handler is deliberately omitted from the inherited HTML attributes to avoid a type
+ clash.)
+- `isCopied: boolean` — drives the "Copied!" tooltip above the Copy button.
+- `copy: boolean` — whether to render the Copy button.
+- `children` — rendered to the left of the Copy button.
+
+A fully wired example toggles `isCopied` for one second (`CodeBlockFooter.stories.tsx`, "Interactive"):
+
+```
+const [isCopied, setIsCopied] = useState(false)
+const handleCopy = () => {
+ setIsCopied(true)
+ setTimeout(() => setIsCopied(false), 1000)
+}
+
+<CodeBlockFooter onCopy={handleCopy} isCopied={isCopied} copy={true} />
+```
+
+When `CodeBlock` manages the footer for you it wires `onCopy`/`isCopied` itself; you rarely construct
+`CodeBlockFooter` by hand unless you are composing a custom block.
diff --git a/packages/ui-components/skills/data-display/references/description-list-layout.md b/packages/ui-components/skills/data-display/references/description-list-layout.md
new file mode 100644
index 0000000000..d8cde45100
--- /dev/null
+++ b/packages/ui-components/skills/data-display/references/description-list-layout.md
@@ -0,0 +1,45 @@
+# DescriptionList custom layout
+
+By default `DescriptionList` renders a `<dl>` with `jn:grid jn:grid-cols-4`: every `DescriptionTerm`
+(`<dt>`) carries `jn:col-span-1` and every `DescriptionDefinition` (`<dd>`) carries `jn:col-span-3`,
+so terms occupy one quarter and definitions three quarters of the row. `alignTerms` toggles the
+term's text alignment: `"right"` (default) adds the `align-right` group class, `"left"` adds
+`align-left`. The exported aliases `DL`, `DT`, and `DD` are identical to the full names.
+
+## When the 1:3 ratio does not fit
+
+Pass Tailwind grid classes through `className` on the `DescriptionList` to change the column count,
+then set matching `col-span` classes on the children. This mirrors the component's own documented
+example (`DescriptionList.stories.tsx` docs block):
+
+```
+<DL className="grid-cols-2">
+ <DT className="col-span-1">Shipping Method</DT>
+ <DD className="col-span-1">Standard shipping: 5-7 business days.</DD>
+</DL>
+```
+
+In a real Juno app the utility classes are prefixed with `jn:`:
+
+```
+<DescriptionList className="jn:grid-cols-2">
+ <DescriptionTerm className="jn:col-span-1">Shipping Method</DescriptionTerm>
+ <DescriptionDefinition className="jn:col-span-1">Standard shipping: 5-7 business days.</DescriptionDefinition>
+</DescriptionList>
+```
+
+Keep the per-row `col-span` values summing to the grid's column count so rows stay aligned. Only
+`DescriptionTerm`, `DescriptionDefinition`, or a single `<div>` wrapper are valid children — the
+`DescriptionListProps.children` type enforces this to preserve the `<dl>` semantics.
+
+## Content rules inside the list
+
+A `DescriptionList` is a **verbatim metadata display**: it reflects what is stored. When a value is
+missing render the `- -` placeholder (two hyphens separated by a single space). Do **not** substitute
+an item's ID for a missing name here — that is the rule for Name columns, detail-view page titles,
+and breadcrumb segments, where the name is the primary identifier. In a property list, substituting
+the ID would imply a name exists when it does not (`docs/ux/ux-writing-content-design.md`, "Rendering
+Empty or Unknown Values", "Exception: verbatim metadata display").
+
+Term labels are headings: apply title case, no all-caps, no trailing punctuation
+(`docs/ux/ux-writing-content-design.md`, "Title Case").
diff --git a/packages/ui-components/skills/data-display/references/icon-names.md b/packages/ui-components/skills/data-display/references/icon-names.md
new file mode 100644
index 0000000000..4d4d3b8a8b
--- /dev/null
+++ b/packages/ui-components/skills/data-display/references/icon-names.md
@@ -0,0 +1,49 @@
+# Icon names and accessibility
+
+`Icon` renders a named SVG. The `icon` prop is typed as `KnownIcons` (the keys of `KnownIconsEnum` in
+`Icon.component.tsx`); passing an unknown name or omitting it falls back to the `help` glyph rather
+than throwing.
+
+## Known icon names
+
+```
+accessTime, accountCircle, addCircle, autoAwesomeMosaic, autoAwesomeMotion, bolt, cached,
+calendarToday, cancel, check, checkCircle, chevronLeft, chevronRight, close, comment, contentCopy,
+danger, dangerous, default, deleteForever, description, dns, download, edit, error, errorOutline,
+exitToApp, expandLess, expandMore, filterAlt, forum, help, home, info, language, manageAccounts,
+monitorHeart, moreVert, nightsStay, notificationsOff, openInBrowser, openInNew, place, schedule,
+search, severityLow, severityMedium, severityHigh, severityVeryHigh, severityCritical,
+severityUnknown, sortShortWideArrowUp, sortShortWideArrowDown, sortWideShortArrowUp,
+sortWideShortArrowDown, success, upload, warning, wbSunny, widgets
+```
+
+### Deprecated aliases (kept working)
+
+- `success` → renders the `checkCircle` SVG (the old `check_box` glyph was deprecated to avoid visual
+ inconsistency; the `success` name still works).
+- `schedule` → alias for `accessTime` (same SVG).
+
+## Rendering modes
+
+- No `href` and no `onClick` → a plain inline glyph wrapped in a `<span>`.
+- `href` set → an `<a>` (anchor styles applied). `href` takes precedence if both are passed.
+- `onClick` set (no `href`) → a `<button type="button">` (button styles applied).
+
+When `href` or `onClick` is present, extra `className`/props are applied to the anchor/button
+wrapper; otherwise they are applied to the SVG itself.
+
+## Accessibility
+
+`title` is the single accessibility lever. For interactive icons it is set as the `aria-label` on the
+`<a>`/`<button>` (falling back to the icon name if `title` is empty), and it also sets the SVG
+`<title>` and the per-icon default. Always pass a human-readable `title` on interactive icons so the
+control is announced meaningfully — relying on the raw icon name as the fallback label is a defect.
+
+```
+<Icon icon="cached" title="Refresh" onClick={refresh} />
+<Icon icon="openInNew" title="Open in New Tab" href="https://example.com" />
+```
+
+`size` accepts a number or a string (pixels/rem); the default is `24`. `color` sets the glyph color;
+`disabled` applies only to the button rendering. Follow title case for `title` text
+(`docs/ux/ux-writing-content-design.md`, "Title Case").
diff --git a/packages/ui-components/skills/datagrid/SKILL.md b/packages/ui-components/skills/datagrid/SKILL.md
new file mode 100644
index 0000000000..e1fba76b3d
--- /dev/null
+++ b/packages/ui-components/skills/datagrid/SKILL.md
@@ -0,0 +1,251 @@
+---
+name: datagrid
+description: >
+ Use when building data tables with the Juno DataGrid in @cloudoperators/juno-ui-components:
+ rendering rows and columns, controlling column widths, adding a toolbar for filtering and
+ search, row click and bulk selection, and rendering empty, loading, and error states inside
+ the grid. For form inputs used inside filters, see the forms skill; for the Status component's
+ other uses, see the feedback skill.
+metadata:
+ purpose: >
+ Teaches developers to compose the Juno DataGrid primitives (DataGrid, DataGridRow,
+ DataGridCell, DataGridHeadCell, DataGridToolbar) into an accessible, UX-compliant data
+ table, including the required Status-based empty/loading/error pattern and the tri-state
+ bulk-selection model that the component library does not enforce on its own.
+ type: core
+ library: "@cloudoperators/juno-ui-components"
+ library_version: "9.6.0"
+sources:
+ - cloudoperators/juno:packages/ui-components/src/components/DataGrid/DataGrid.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/DataGrid/DataGrid.stories.tsx
+ - cloudoperators/juno:docs/ux/datagrid.md
+---
+
+# Build a data table with the Juno DataGrid
+
+The DataGrid is a CSS-grid layout, not an HTML `<table>`. You declare how many `columns` there
+are on the `DataGrid` and then render a flat stream of `DataGridRow` → `DataGridCell` children.
+There is no `<thead>`/`<tbody>`; a header row is just a `DataGridRow` whose children are
+`DataGridHeadCell` instead of `DataGridCell`.
+
+## Setup
+
+```tsx
+import { DataGrid, DataGridRow, DataGridHeadCell, DataGridCell } from "@cloudoperators/juno-ui-components"
+
+type ImageItem = { id: string; name: string; status: string; createdAt: string }
+
+function ImagesTable({ images }: { images: ImageItem[] }) {
+ return (
+ <DataGrid columns={3}>
+ <DataGridRow>
+ <DataGridHeadCell>Name</DataGridHeadCell>
+ <DataGridHeadCell>Status</DataGridHeadCell>
+ <DataGridHeadCell>Created</DataGridHeadCell>
+ </DataGridRow>
+ {images.map((image) => (
+ <DataGridRow key={image.id}>
+ <DataGridCell>{image.name}</DataGridCell>
+ <DataGridCell>{image.status}</DataGridCell>
+ <DataGridCell>{image.createdAt}</DataGridCell>
+ </DataGridRow>
+ ))}
+ </DataGrid>
+ )
+}
+```
+
+The number of `DataGridCell`/`DataGridHeadCell` children in each row must equal `columns`. The one
+exception is `colSpan` (see below). `DataGrid` requires the app to be wrapped in
+`AppShellProvider` for styling to apply — see the fundamentals skill if styles are missing.
+
+## Core patterns
+
+### Control column widths
+
+By default every column is `minmax(min-content, auto)`. Four props on `DataGrid` adjust this; they
+map directly onto CSS `grid-template-columns`:
+
+- `columnMinSize` / `columnMaxSize` — strings used as `minmax(columnMinSize, columnMaxSize)` for
+ every column, e.g. `columnMaxSize="1fr"` makes all columns equal width regardless of content.
+- `minContentColumns={[0, 3]}` — zero-based indices of columns that should be only as wide as their
+ content. Use this for a column holding a single checkbox or icon button.
+- `gridColumnTemplate="200px 1fr min-content"` — a full custom template. **When set, every other
+ width prop is ignored.**
+
+```
+// Checkbox column stays tight; the rest share remaining space
+<DataGrid columns={4} minContentColumns={[0]} columnMaxSize="1fr">
+```
+
+### Make rows clickable or hoverable
+
+Pass `onClick` to `DataGridRow` to make the whole row an interactive, hoverable target (used for
+"open detail view"):
+
+```
+<DataGridRow onClick={() => navigate(`/images/${image.id}`)}>
+```
+
+Only make a row clickable when the primary action is "navigate to this item's detail". Do not put a
+row `onClick` on a grid whose cells already contain their own buttons or links — the nested click
+targets conflict (`docs/ux/datagrid.md`, "Interacting with DataGrid Rows / Items").
+
+### Span a cell across all columns
+
+Use `colSpan` on a `DataGridCell` for rows that are not part of the tabular data — most importantly
+the empty/loading/error state (next section):
+
+```
+<DataGridRow>
+ <DataGridCell colSpan={3}>…</DataGridCell>
+</DataGridRow>
+```
+
+### Add a toolbar for filters, search, and bulk actions
+
+Controls that modify the view (search, filters, sorting, bulk actions, item count, refresh) live
+**above** the grid in a `DataGridToolbar`, not inside the `DataGrid` itself:
+
+```
+<DataGridToolbar>
+ <Select name="status" label="Status" onChange={setStatus}>
+ <SelectOption value="active">Active</SelectOption>
+ <SelectOption value="deleted">Deleted</SelectOption>
+ </Select>
+ <SearchInput onChange={(e) => setSearch(e.target.value)} />
+</DataGridToolbar>
+<DataGrid columns={3}>…</DataGrid>
+```
+
+The toolbar is a composable container, not a single pre-built control. The UX guidelines define
+three zones — Zone 1 (predefined filter tabs, sorting, primary action), Zone 2 (filter inputs,
+search, active filter pills), Zone 3 (bulk actions, item count, refresh). Read
+[toolbar zones and persistence](references/toolbar-zones.md) when you need the full zone layout or
+have to decide whether filters persist across navigation.
+
+## Empty, loading, and error states (required)
+
+The DataGrid renders nothing meaningful for an empty, loading, or failed dataset on its own. You
+**must** render these states explicitly, scoped to the grid (never a full-page spinner), using the
+`Status` component inside a `DataGridRow`/`DataGridCell` that spans all columns. `Status` adapts its
+styling automatically when it detects the DataGrid context (`docs/ux/datagrid.md`, "DataGrid Empty,
+Loading, and Error States").
+
+```tsx
+import { DataGrid, DataGridRow, DataGridHeadCell, DataGridCell, Status } from "@cloudoperators/juno-ui-components"
+
+type ImageItem = { id: string; name: string; status: string; createdAt: string }
+
+type Props = {
+ images: ImageItem[]
+ isLoading: boolean
+ error?: Error
+ hasActiveFilters: boolean
+}
+
+const COLUMNS = 3
+
+function ImagesTable({ images, isLoading, error, hasActiveFilters }: Props) {
+ return (
+ <DataGrid columns={COLUMNS}>
+ <DataGridRow>
+ <DataGridHeadCell>Name</DataGridHeadCell>
+ <DataGridHeadCell>Status</DataGridHeadCell>
+ <DataGridHeadCell>Created</DataGridHeadCell>
+ </DataGridRow>
+
+ {isLoading && (
+ <DataGridRow>
+ <DataGridCell colSpan={COLUMNS}>
+ <Status status="progress" title="Loading images…" />
+ </DataGridCell>
+ </DataGridRow>
+ )}
+
+ {error && (
+ <DataGridRow>
+ <DataGridCell colSpan={COLUMNS}>
+ <Status status="error" title="Could not load images" body={error.message} />
+ </DataGridCell>
+ </DataGridRow>
+ )}
+
+ {!isLoading && !error && images.length === 0 && (
+ <DataGridRow>
+ <DataGridCell colSpan={COLUMNS}>
+ <Status
+ status={hasActiveFilters ? "no-matches" : "empty"}
+ title={hasActiveFilters ? "No matching images" : "No images yet"}
+ body={hasActiveFilters ? "No images match your current filters." : "Create one to get started."}
+ />
+ </DataGridCell>
+ </DataGridRow>
+ )}
+
+ {!isLoading &&
+ !error &&
+ images.map((image) => (
+ <DataGridRow key={image.id}>
+ <DataGridCell>{image.name}</DataGridCell>
+ <DataGridCell>{image.status}</DataGridCell>
+ <DataGridCell>{image.createdAt}</DataGridCell>
+ </DataGridRow>
+ ))}
+ </DataGrid>
+ )
+}
+```
+
+Distinguish "no data exists" from "no data matches your filters" — they lead the user to different
+actions. Keep the empty/filtered message copy source-backed per the UX doc.
+
+## Bulk selection
+
+When users act on multiple rows at once, add a leading checkbox column and a select-all checkbox in
+the toolbar's Zone 3. The library gives you `Checkbox` but does **not** implement the selection
+model — you own it, and it must follow the UX rules (`docs/ux/datagrid.md`, Zone 3):
+
+- The select-all checkbox is **tri-state**: unchecked (none selected), `indeterminate` (some), checked (all).
+- Clicking it while unchecked or indeterminate selects all; clicking while checked deselects all.
+- Bulk-action controls stay **disabled until at least one row is selected**.
+- The selection/checkbox column goes **first (leftmost)**; status columns go near the left too.
+
+Read [bulk selection model](references/bulk-selection.md) for the complete tri-state wiring and a
+worked `useState`-based example before implementing it.
+
+## Common mistakes
+
+- **CRITICAL — No empty/error state.** Rendering only the mapped rows means a failed fetch shows a
+ blank grid with no explanation and no retry. Always render the `Status`-based states above.
+ (`docs/ux/datagrid.md`, "DataGrid Empty, Loading, and Error States".)
+- **HIGH — Page-level spinner instead of grid-scoped.** A full-page spinner hides the toolbar and
+ surrounding context. Scope loading to the grid with `Status` in a spanning cell.
+- **HIGH — Cell count ≠ `columns`.** If a row has fewer/more cells than `columns` (and no `colSpan`),
+ the CSS grid misaligns silently. Keep the counts equal; use `colSpan={columns}` for full-width rows.
+- **HIGH — Row `onClick` plus in-cell buttons.** Nested interactive targets inside a clickable row
+ produce ambiguous click behavior. Choose one: a clickable row for navigation, or in-cell actions.
+- **MEDIUM — Bulk actions enabled with nothing selected.** Disable bulk-action buttons until at
+ least one row is selected; otherwise users trigger no-op or accidental actions.
+- **MEDIUM — Misusing predefined filter tabs as navigation.** Filter tabs must operate on the same
+ entity set, just filtered. For unrelated data sets use page-level tabs, each with its own DataGrid.
+
+## Completion
+
+Verify:
+
+1. The grid renders header + body rows with cell counts matching `columns`.
+2. Loading, error, and both empty variants each render a grid-scoped `Status` and are reachable.
+3. If bulk selection exists, the select-all checkbox is tri-state and bulk actions are disabled with
+ nothing selected.
+4. Run `npm exec --no -- intent validate packages/ui-components/skills` and fix any errors.
+
+If a dataset state cannot be exercised in your test harness, report it as unverified rather than
+assuming it renders.
+
+## References
+
+- [toolbar zones and persistence](references/toolbar-zones.md) — read for the full three-zone
+ toolbar layout and the filter/sort persistence decision.
+- [bulk selection model](references/bulk-selection.md) — read before wiring tri-state select-all and
+ per-row selection.
diff --git a/packages/ui-components/skills/datagrid/references/bulk-selection.md b/packages/ui-components/skills/datagrid/references/bulk-selection.md
new file mode 100644
index 0000000000..4151158ca3
--- /dev/null
+++ b/packages/ui-components/skills/datagrid/references/bulk-selection.md
@@ -0,0 +1,102 @@
+# DataGrid bulk selection model
+
+Read this before wiring row selection and a tri-state select-all checkbox. The component library
+provides `Checkbox` but does not implement the selection state machine — you own it. Source:
+`docs/ux/datagrid.md` ("Zone 3: DataGrid View/State, Bulk Actions, Refresh"; "Column Order,
+Structure, and Layout"; "Selecting Rows / Items").
+
+## Rules
+
+- The selection checkbox column is **first (leftmost)**.
+- The select-all checkbox is **tri-state**:
+ - unchecked when no rows are selected,
+ - `indeterminate` when some are selected,
+ - checked when all are selected.
+- Clicking select-all while unchecked **or** indeterminate selects all rows; clicking while checked
+ deselects all.
+- Bulk-action controls are **disabled until at least one row is selected**.
+
+## Worked example
+
+```tsx
+import { useState } from "react"
+import {
+ DataGrid,
+ DataGridRow,
+ DataGridHeadCell,
+ DataGridCell,
+ DataGridToolbar,
+ Checkbox,
+ Button,
+} from "@cloudoperators/juno-ui-components"
+
+type ImageItem = { id: string; name: string; status: string }
+declare function deleteImages(ids: string[]): void
+
+function SelectableImagesTable({ images }: { images: ImageItem[] }) {
+ const [selected, setSelected] = useState<Set<string>>(new Set())
+
+ const allSelected = images.length > 0 && selected.size === images.length
+ const someSelected = selected.size > 0 && !allSelected
+
+ const toggleAll = () => {
+ setSelected(allSelected ? new Set() : new Set(images.map((i) => i.id)))
+ }
+
+ const toggleOne = (id: string) => {
+ setSelected((prev) => {
+ const next = new Set(prev)
+ next.has(id) ? next.delete(id) : next.add(id)
+ return next
+ })
+ }
+
+ const COLUMNS = 3
+
+ return (
+ <>
+ <DataGridToolbar>
+ <Checkbox
+ checked={allSelected}
+ indeterminate={someSelected}
+ onChange={toggleAll}
+ aria-label="Select all images"
+ />
+ <Button disabled={selected.size === 0} onClick={() => deleteImages([...selected])}>
+ Delete selected
+ </Button>
+ </DataGridToolbar>
+
+ <DataGrid columns={COLUMNS} minContentColumns={[0]}>
+ <DataGridRow>
+ <DataGridHeadCell>{/* checkbox column */}</DataGridHeadCell>
+ <DataGridHeadCell>Name</DataGridHeadCell>
+ <DataGridHeadCell>Status</DataGridHeadCell>
+ </DataGridRow>
+ {images.map((image) => (
+ <DataGridRow key={image.id}>
+ <DataGridCell>
+ <Checkbox
+ checked={selected.has(image.id)}
+ onChange={() => toggleOne(image.id)}
+ aria-label={`Select ${image.name}`}
+ />
+ </DataGridCell>
+ <DataGridCell>{image.name}</DataGridCell>
+ <DataGridCell>{image.status}</DataGridCell>
+ </DataGridRow>
+ ))}
+ </DataGrid>
+ </>
+ )
+}
+```
+
+## Notes
+
+- `indeterminate` is a visual state only; it never submits as a value. Derive it from counts as
+ shown (`someSelected`), do not store it.
+- Give every checkbox an `aria-label` — the checkbox column header is intentionally empty, so the
+ per-row checkboxes have no visible label to associate with.
+- Keep the selection source of truth (`Set` of ids here) separate from the row data so sorting and
+ filtering the rows does not drop the selection.
diff --git a/packages/ui-components/skills/datagrid/references/toolbar-zones.md b/packages/ui-components/skills/datagrid/references/toolbar-zones.md
new file mode 100644
index 0000000000..19e5984984
--- /dev/null
+++ b/packages/ui-components/skills/datagrid/references/toolbar-zones.md
@@ -0,0 +1,47 @@
+# DataGrid toolbar zones and filter/sort persistence
+
+Read this when laying out a full DataGrid toolbar or deciding whether filters and sorting should
+survive navigation. Source: `docs/ux/datagrid.md` ("DataGrid Header / Toolbar", "Filter and Sort
+Persistence on Navigation").
+
+## The three zones
+
+The `DataGridToolbar` is a composable container. The UX guidelines split its contents into three
+zones with distinct visual treatment:
+
+- **Zone 1 — predefined filter tabs, sorting, primary action.** No distinct background; a plain row
+ sitting above the framed toolbar area.
+ - Predefined filter tabs on the far left apply a fixed, meaningful subset of the data (e.g.
+ "All" / "Deleted", "Active" / "Archived"). Add them only when the subsets are genuinely useful.
+ - Sorting: a `Select` to choose the sort key plus a button to toggle direction.
+ - Primary action (e.g. "Create") on the far right.
+- **Zone 2 — filters and search.** Has its own background and padding.
+ - Filter inputs: a `Select`, or a `Select`/`ComboBox` combined with a `TextInput`, depending on data.
+ - Active filter pills: one `Pill` per configured filter, plus a trailing "clear all" button.
+ - `SearchInput` for free-text search.
+- **Zone 3 — grid state, bulk actions, refresh.** Its own background and padding.
+ - Bulk actions on the left (select-all `Checkbox` + bulk-action menu).
+ - Item count in the center (matching items / total when filters are active).
+ - Last-updated text and a refresh button on the right.
+
+Zones 2 and 3 are visually separate blocks — do not merge them into one band.
+
+## Do not misuse predefined filter tabs as navigation
+
+Filter tabs must always operate on the **same set of entities**, just filtered differently. If tabs
+would show entirely different, unrelated data sets or entity types, use page-level tabs instead,
+with each tab containing its own independent DataGrid.
+
+## Filter and sort persistence on navigation
+
+There is no single default. Decide based on the user's goal and the navigation model:
+
+- Default expectation: users do **not** expect filter/sort state configured in one session to still
+ be active when they return. Stale filters hide data and cause confusion that is hard to diagnose.
+- Persist when the grid is part of a continuous task or navigation flow — e.g. drilling through a
+ folder/file hierarchy, or returning via browser back/forward.
+- When the DataGrid itself is the **navigation mechanism** (browsing a folder structure), persisting
+ is appropriate; clearing on each step would be disruptive.
+
+If you persist state, always keep the active state visible — active filter pills and the sort
+indicator must show — so users are never left wondering why data appears missing or reordered.
diff --git a/packages/ui-components/skills/feedback/SKILL.md b/packages/ui-components/skills/feedback/SKILL.md
new file mode 100644
index 0000000000..e27fe8f507
--- /dev/null
+++ b/packages/ui-components/skills/feedback/SKILL.md
@@ -0,0 +1,329 @@
+---
+name: feedback
+description: >
+ Use when surfacing feedback in a Juno app with @cloudoperators/juno-ui-components: a static
+ inline Message vs a transient Toast notification fired through NotificationManager and the
+ toast() API, the Status component for page/section empty, loading, error and no-matches states,
+ Spinner / LoadingIndicator / ProgressBar for progress, and Badge / Pill for inline status labels
+ and filter chips. Covers which component to reach for, the semantic variant to pick, and the
+ message copy and dismissal rules the library does not enforce. For Status inside a DataGrid, see
+ the datagrid skill; for form field validation, see the forms skill.
+metadata:
+ purpose: >
+ Teaches developers to choose and compose the Juno feedback primitives — Message, Toast +
+ NotificationManager, Status, Spinner, LoadingIndicator, ProgressBar, Badge, and Pill — into
+ UX-compliant feedback, including the Message-vs-Notification decision, the semantic-variant
+ rules, the required non-blocking scoping of loading/error states, and the copy and dismissal
+ conventions the components leave to the consumer.
+ type: core
+ library: "@cloudoperators/juno-ui-components"
+ library_version: "9.6.0"
+sources:
+ - cloudoperators/juno:packages/ui-components/src/components/Message/Message.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/Message/Message.stories.ts
+ - cloudoperators/juno:packages/ui-components/src/components/Toast/Toast.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/Toast/Toast.stories.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/NotificationManager/NotificationManager.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/NotificationManager/NotificationManager.types.ts
+ - cloudoperators/juno:packages/ui-components/src/components/NotificationManager/NotificationManager.stories.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/Status/Status.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/Status/Status.stories.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/Spinner/Spinner.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/LoadingIndicator/LoadingIndicator.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/ProgressBar/ProgressBar.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/Badge/Badge.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/Pill/Pill.component.tsx
+ - cloudoperators/juno:docs/ux/messages-and-notifications.md
+ - cloudoperators/juno:docs/ux/error-handling-loading-empty-states.md
+ - cloudoperators/juno:docs/ux/transient-states-and-progress.md
+ - cloudoperators/juno:docs/ux/semantic-variants.md
+---
+
+# Surface feedback in a Juno app
+
+Feedback in Juno splits into three jobs, each with its own component. Pick by what you are telling
+the user, not by appearance:
+
+- **A condition the user needs to see in place** → `Message` (static, anchored in the layout).
+- **A transient confirmation of a background/async result** → a notification via `toast()`, rendered
+ by `NotificationManager`. Never use `Toast` directly.
+- **A whole view/section/container has no data, is loading, or failed** → `Status`.
+- **Something small is busy** → `Spinner`; **a whole view/panel is busy** → `LoadingIndicator`;
+ **a quantifiable batch is progressing** → `ProgressBar`.
+- **An inline label for an entity's property or state** → `Badge`; **a selected filter chip** → `Pill`.
+
+Message and Notification are distinct mechanisms and must not be used interchangeably
+(`docs/ux/messages-and-notifications.md`). All of these except Status/Spinner/LoadingIndicator/
+ProgressBar/Pill take a **semantic `variant`** — choose it by meaning (see
+[semantic variants](references/semantic-variants.md)).
+
+## Setup
+
+Notifications need a single `NotificationManager` mounted once near the app root. Everything else
+imports from the package and renders inline:
+
+```tsx
+import { NotificationManager } from "@cloudoperators/juno-ui-components"
+
+function App() {
+ return (
+ <>
+ {/* your routes/content */}
+ <NotificationManager position="bottom-right" />
+ </>
+ )
+}
+```
+
+`NotificationManager` wraps the Sonner toaster and owns all timers, auto-dismiss, queueing, and
+positioning. The `Message`, `Status`, `Badge`, etc. components only need the app wrapped in
+`AppShellProvider` for theming — see the fundamentals skill if styles are missing.
+
+## Core patterns
+
+### Show an inline Message for a condition in the view
+
+Use a `Message` for operation results, persistent warnings, or contextual guidance that belongs in
+the layout. Pass short text via `text`; pass formatted content or links as `children` (children win
+over `text`). Add a `title` only when the message needs a heading to stand apart — not by default
+(`docs/ux/messages-and-notifications.md`, "Title"/"Content").
+
+```tsx
+import { Message } from "@cloudoperators/juno-ui-components"
+
+function ReadOnlyBanner() {
+ return (
+ <Message variant="warning" title="Read-only access">
+ You can view these resources but not modify them. Contact an admin to request write access.
+ </Message>
+ )
+}
+```
+
+Place a Message as close as possible to what it relates to: form-level feedback at the top of the
+form, page-level feedback below the page header (`docs/ux/messages-and-notifications.md`,
+"Placement").
+
+Make it `dismissible` only for one-off feedback after a user action. Keep it persistent
+(non-dismissible, the default) for ongoing conditions like a permission limit or degraded state.
+
+```tsx
+import { Message } from "@cloudoperators/juno-ui-components"
+
+function SavedConfirmation({ onClose }: { onClose: () => void }) {
+ return <Message variant="success" text="Settings saved." dismissible onDismiss={onClose} />
+}
+```
+
+`autoDismiss` (default `autoDismissTimeout` 10000 ms) is available but is only for low-stakes `info`
+or `success` feedback — **never** for `error` or `warning`, and be aware it causes a layout shift
+when it disappears (`docs/ux/messages-and-notifications.md`, "Dismissible Messages").
+
+### Fire a transient notification with toast()
+
+Trigger notifications through the `toast()` API; `NotificationManager` renders them. Use notifications
+to confirm background/async results and low-interruption events outside the user's current focus — not
+for errors or warnings that require action (use a `Message` for those).
+
+```tsx
+import { toast } from "@cloudoperators/juno-ui-components"
+
+declare function deleteImage(id: string): Promise<void>
+
+async function onDelete(id: string) {
+ try {
+ await deleteImage(id)
+ toast.success("Image deleted", { description: "The image was removed." })
+ } catch (err) {
+ toast.error("Could not delete image", { description: (err as Error).message })
+ }
+}
+```
+
+The semantic helpers are `toast.info`, `toast.success`, `toast.warning`, `toast.error`, and
+`toast.danger`; calling `toast(...)` bare renders as `info`. Options include `description`,
+`duration` (ms; pass `Infinity` to persist until dismissed), `dismissible`, `toasterId` (to target a
+specific manager instance), `id` (to update/dedupe), and the `onDismiss` / `onAutoClose` / `onClick`
+callbacks. Read [notifications in depth](references/notifications.md) before using multiple managers,
+updating a toast by id, non-dismissible toasts, or notification history.
+
+### Render page/section empty, loading, and error states with Status
+
+`Status` is the required default for any error, loading, empty, or no-matches state without a
+dedicated local solution — at application, page, and section scope
+(`docs/ux/error-handling-loading-empty-states.md`, note). It renders a centered `<div>`; outside a
+DataGrid it applies its own top margin.
+
+```tsx
+import { Status, Button } from "@cloudoperators/juno-ui-components"
+
+type Props = { isLoading: boolean; error?: Error; retry: () => void }
+
+function ServicesView({ isLoading, error, retry }: Props) {
+ if (isLoading) return <Status status="progress" title="Loading services…" />
+ if (error) {
+ return (
+ <Status
+ status="error"
+ title="Could not load services"
+ body={error.message}
+ action={
+ <Button variant="primary" onClick={retry}>
+ Retry
+ </Button>
+ }
+ />
+ )
+ }
+ return <div>{/* data */}</div>
+}
+```
+
+`status` is one of `"progress" | "error" | "empty" | "no-matches"` (default `"error"`); each ships
+sensible default `title`/`body` copy you can override. For "BIG" server/routing errors, pass a `code`
+(e.g. `404`, `500`) to render the large HTTP code with its standard title/body
+(`docs/ux/error-handling-loading-empty-states.md`, "HTTP Error Code Reference"). Pass a stack trace or
+server response via `details` to render a scrollable `<pre>`, and an `action` (typically a `Button`)
+for retry/next-step. Distinguish `empty` ("no data exists") from `no-matches` ("nothing matches the
+current filters") — they lead to different user actions. For `Status` **inside a DataGrid**, wrap it in
+a spanning `DataGridRow`/`DataGridCell`; see the datagrid skill.
+
+### Indicate busy state at the right scale
+
+Match the indicator to the scope of what is busy (`docs/ux/transient-states-and-progress.md`):
+
+- **Atomic element** (Button, Select) — use its built-in busy state; don't drop a Spinner next to it.
+- **Small element / entity** (e.g. one row transitioning) — `Spinner`.
+- **Whole view, panel, or large section** — `LoadingIndicator`.
+- **Quantifiable batch** — `ProgressBar`.
+
+```tsx
+import { Spinner, LoadingIndicator } from "@cloudoperators/juno-ui-components"
+
+function InlineBusy() {
+ return <Spinner variant="primary" size="small" aria-label="Starting instance" />
+}
+
+function PanelBusy() {
+ return <LoadingIndicator />
+}
+```
+
+`Spinner` variants are `primary | danger | success | warning | default`; `size` accepts
+`"small"`, `"large"`, or any CSS length. `LoadingIndicator` takes `size` (number/px, default 96) and a
+`color` text-color class. Use **one** indicator at the tightest scope that covers everything busy —
+don't stack a page spinner and per-item spinners for the same load
+(`docs/ux/error-handling-loading-empty-states.md`, "Don't overdo it").
+
+### Show quantifiable progress with ProgressBar
+
+Use `ProgressBar` only when progress is a batch over multiple entities and can be expressed as a
+percentage or current/target value (`docs/ux/transient-states-and-progress.md`, "Progress Bar"). For a
+single transition or unquantifiable wait, use a `Spinner` instead.
+
+```tsx
+import { ProgressBar } from "@cloudoperators/juno-ui-components"
+
+function Migration({ done, total }: { done: number; total: number }) {
+ return <ProgressBar value={(done / total) * 100} aria-label={`Migrating ${done} of ${total} volumes`} />
+}
+```
+
+`value` (0–100, clamped automatically) applies in the default `determinate` mode. Set `mode="busy"`
+for an indeterminate animated bar when the operation affects multiple entities but the total is not
+yet known. Always pass a meaningful `aria-label` (defaults to `"Progress"`).
+
+### Label entity state with Badge, and filter chips with Pill
+
+Use a `Badge` to label a property or state of an entity inline (e.g. a resource's status). Variants
+are `default | info | success | warning | danger | error`. Pass `icon={true}` for the variant's
+matching icon, or an icon name string for a specific one.
+
+```tsx
+import { Badge } from "@cloudoperators/juno-ui-components"
+
+function HealthBadge({ healthy }: { healthy: boolean }) {
+ return healthy ? <Badge variant="success" icon text="Healthy" /> : <Badge variant="error" icon text="Unhealthy" />
+}
+```
+
+A `Badge` renders as a `<span>` by default; pass `onClick` to render a `<button>` or `href` to render
+an `<a>` (href wins), with `disabled` support. Use `Pill` for a key/value chip, typically a selected
+filter value, with an optional close button:
+
+```tsx
+import { Pill } from "@cloudoperators/juno-ui-components"
+
+declare function removeFilter(id: string): void
+
+function RegionFilterPill() {
+ return (
+ <Pill
+ uid="region:eu-de-1"
+ pillKey="region"
+ pillKeyLabel="Region"
+ pillValue="eu-de-1"
+ pillValueLabel="EU-DE-1"
+ closeable
+ onClose={(_event, id) => removeFilter(id)}
+ />
+ )
+}
+```
+
+`pillValue` is required. `onClose` and `onClick` receive `(event, id)` where `id` is `uid` → falling
+back to `pillKey` → `pillValue`.
+
+## Common mistakes
+
+- **CRITICAL — Transient toast for an error that needs action.** A `toast.error` auto-dismisses and
+ leaves no trace; a user who looks away misses it. For errors or warnings the user must act on, render
+ an anchored `Message` (or a `Status` with a retry `action`) instead
+ (`docs/ux/messages-and-notifications.md`, "Notifications" / "Auto-Dismiss").
+- **CRITICAL — Rendering `Toast` directly.** `Toast` is purely presentational and has no lifecycle;
+ mounting it yourself gets no timers, queueing, or positioning. Always trigger via `toast()` with a
+ mounted `NotificationManager` (`docs/ux/messages-and-notifications.md`, "Toast and NotificationManager").
+- **HIGH — No empty/loading/error state (blank screen).** Rendering nothing while loading or on
+ failure looks broken. Use `Status` for every such state that lacks a dedicated solution; never leave
+ a silent non-responding UI (`docs/ux/error-handling-loading-empty-states.md`, note & "Communicate
+ Clearly").
+- **HIGH — `autoDismiss` on an `error`/`warning` Message.** These must stay until the condition
+ resolves. Reserve `autoDismiss` for low-stakes `info`/`success`
+ (`docs/ux/messages-and-notifications.md`, "Dismissible Messages").
+- **HIGH — Page-level busy state for a scoped load.** A full-view `LoadingIndicator` while only a
+ DataGrid is fetching blocks navigation and context. Scope the busy state to the tightest boundary
+ that covers what is busy (`docs/ux/error-handling-loading-empty-states.md`, "Use Sensible Boundaries").
+- **MEDIUM — Picking a variant for color, not meaning.** Using `danger` for emphasis or `success` for a
+ neutral confirmation degrades the signal. Match the variant to intent; `error` = something failed,
+ `danger` = destructive/irreversible action (`docs/ux/semantic-variants.md`).
+- **MEDIUM — `ProgressBar` for an unquantifiable wait.** If you can't express progress as a
+ number/percentage, use a `Spinner` (or `mode="busy"` when the total is merely not-yet-known)
+ (`docs/ux/transient-states-and-progress.md`, "Spinner" / "Progress Bar").
+- **MEDIUM — Confusing `empty` with `no-matches`.** "No data exists" and "nothing matches your filters"
+ need different copy and next actions; hint at loosening filters for `no-matches`
+ (`docs/ux/error-handling-loading-empty-states.md`, "Empty State").
+
+## Completion
+
+Verify:
+
+1. Each feedback surface uses the right component: static condition → `Message`; async confirmation →
+ `toast()`; absent/loading/failed container → `Status`; busy → `Spinner`/`LoadingIndicator`;
+ quantifiable batch → `ProgressBar`; inline label → `Badge`/`Pill`.
+2. Exactly one `NotificationManager` is mounted near the app root, and no `Toast` is rendered directly.
+3. Every `variant` is chosen by meaning, and no `error`/`warning` feedback relies on auto-dismiss.
+4. Loading/error/empty states are scoped to the tightest boundary, not the whole app, and empty vs
+ no-matches copy is distinct.
+5. `ProgressBar` and `Spinner`/`LoadingIndicator` carry a meaningful `aria-label`.
+6. Run `npm exec --no -- intent validate packages/ui-components/skills` and fix any errors.
+
+If a state (error, empty, loading) cannot be exercised in your harness, report it as unverified rather
+than assuming it renders.
+
+## References
+
+- [semantic variants](references/semantic-variants.md) — read before choosing a `variant`, especially
+ for the `error` vs `danger` and `warning` vs `error` distinctions.
+- [notifications in depth](references/notifications.md) — read before scoping toasts with `toasterId`,
+ updating/dismissing a toast by id, non-dismissible or infinite toasts, lifecycle callbacks, or
+ notification history and persistence.
diff --git a/packages/ui-components/skills/feedback/references/notifications.md b/packages/ui-components/skills/feedback/references/notifications.md
new file mode 100644
index 0000000000..fd906b3b49
--- /dev/null
+++ b/packages/ui-components/skills/feedback/references/notifications.md
@@ -0,0 +1,110 @@
+# Notifications in depth
+
+Read this when you go beyond a single fire-and-forget `toast()` call: scoping toasts to a specific
+manager, updating or dismissing a toast programmatically, non-dismissible or infinite toasts,
+lifecycle callbacks, or notification history and persistence.
+
+`NotificationManager` wraps the Sonner toast library and owns all lifecycle — timers, auto-dismiss,
+queueing, screen position. The `Toast` component is purely presentational and is rendered _by_ the
+manager; never mount it yourself. Trigger everything through the `toast()` API
+(`docs/ux/messages-and-notifications.md`, "Toast and NotificationManager").
+
+## Manager props
+
+Mount one `NotificationManager` near the app root. Props and defaults:
+
+- `id` — optional Sonner toaster id. Scope `toast()` calls to this instance by passing a matching
+ `toasterId` in the options.
+- `dismissible` (default `true`) — whether toasts show a close button. Overridable per toast.
+- `duration` (default `4000` ms) — default visible time before auto-dismiss. Overridable per toast.
+ Pass `Infinity` to keep toasts until manually dismissed.
+- `visibleToasts` (default `3`) — max shown at once; the rest queue and appear as others close.
+- `position` (default `"bottom-right"`) — one of `top-left | top-right | bottom-left | bottom-right |
+top-center | bottom-center`.
+
+## The toast() options
+
+Each `toast()` / `toast.<variant>()` call takes `(message, options?)`. Options
+(`NotificationOptions`): `id`, `toasterId`, `duration`, `dismissible`, `description` (string or
+`() => ReactNode`), `onDismiss`, `onAutoClose`, `onClick`, `style`, `className`, `descriptionClassName`,
+`position`. The call returns the toast id.
+
+## Scope toasts to a specific manager
+
+```tsx
+import { NotificationManager, toast } from "@cloudoperators/juno-ui-components"
+
+const TOASTER_ID = "uploads"
+
+function UploadsPanel() {
+ return (
+ <>
+ <button onClick={() => toast.success("Upload complete", { toasterId: TOASTER_ID })}>Finish</button>
+ <NotificationManager id={TOASTER_ID} position="top-right" />
+ </>
+ )
+}
+```
+
+## Update or dismiss a toast by id
+
+Capture the returned id to replace a toast's content in place (e.g. pending → resolved) or dismiss it:
+
+```tsx
+import { toast } from "@cloudoperators/juno-ui-components"
+
+declare function sync(): Promise<void>
+
+async function run() {
+ const id = toast.info("Syncing…", { duration: Infinity })
+ try {
+ await sync()
+ toast.success("Synced", { id })
+ } catch {
+ toast.error("Sync failed", { id })
+ }
+}
+```
+
+Passing the same `id` reuses that toast instead of stacking a new one. `toast.dismiss(id)` closes it
+programmatically.
+
+## Non-dismissible and infinite toasts
+
+Set `dismissible: false` (manager-wide, or per toast) to drop the close button so a toast disappears
+only on timeout or programmatic dismissal. A per-toast `dismissible` overrides the manager default.
+Combine with `duration: Infinity` for a critical alert that stays until explicit action — but prefer a
+`Message` when the user genuinely must act (`docs/ux/messages-and-notifications.md`, "Notifications").
+
+```tsx
+import { toast } from "@cloudoperators/juno-ui-components"
+
+toast.warning("Background sync running", { dismissible: false })
+toast.info("Important", { duration: Infinity })
+```
+
+## Lifecycle callbacks
+
+`onDismiss` fires on manual close; `onAutoClose` fires when the duration expires; `onClick` fires on
+click. Use them to react to a notification's resolution — e.g. undo flows or analytics.
+
+```tsx
+import { toast } from "@cloudoperators/juno-ui-components"
+
+toast.success("Item archived", {
+ onDismiss: () => console.log("dismissed"),
+ onAutoClose: () => console.log("auto-closed"),
+})
+```
+
+## History and persistence
+
+`toast.getToasts()` returns currently active notifications; `toast.getHistory()` returns everything
+created during the current runtime, including dismissed/expired ones. History is **in-memory only** —
+if you need notifications to survive reloads, navigation, or app restarts you must persist them
+yourself (application state, backend, or `localStorage`). Long-term retention is intentionally the
+consumer's responsibility.
+
+> Note: `toast.loading`, `toast.promise`, and `toast.custom` are passed through from Sonner and
+> bypass Juno's `Toast` renderer, so they use Sonner's default styling rather than Juno's semantics.
+> Prefer the semantic helpers (`info`/`success`/`warning`/`error`/`danger`) for consistent appearance.
diff --git a/packages/ui-components/skills/feedback/references/semantic-variants.md b/packages/ui-components/skills/feedback/references/semantic-variants.md
new file mode 100644
index 0000000000..02b823547e
--- /dev/null
+++ b/packages/ui-components/skills/feedback/references/semantic-variants.md
@@ -0,0 +1,43 @@
+# Semantic variants
+
+Read this when choosing a `variant` for `Message`, `Toast` / `toast()`, or `Badge` — and whenever you
+are unsure between `error`/`danger` or `warning`/`error`.
+
+Several Juno feedback components accept a semantic `variant` prop. The variant is **not styling** — it
+carries meaning and must be chosen by the nature of the information, never for aesthetic effect
+(`docs/ux/semantic-variants.md`). Misusing a variant (e.g. `danger` for emphasis, `success` for a
+neutral confirmation) degrades the signal value and breaks product consistency.
+
+## The variants
+
+| Variant | Meaning | Typical use |
+| --------- | ------------------------ | --------------------------------------------------------- |
+| `info` | Neutral, informational | General guidance, hints, status with no urgency |
+| `success` | Positive outcome | Confirmation that an operation completed successfully |
+| `warning` | Caution required | Non-blocking issue the user should be aware of or act on |
+| `error` | Something went wrong | A failure the user should be informed about |
+| `danger` | High-risk or destructive | Destructive actions, data loss, irreversible consequences |
+
+## `error` vs. `danger`
+
+Use `error` for system or operation failures — something that already went wrong. Use `danger` for
+situations where the user is about to take a destructive or irreversible action. A failed API call is
+an `error`; a delete confirmation is `danger`.
+
+## `warning` vs. `error`
+
+A `warning` does not mean something has failed — it signals that something _might_ go wrong, or that
+the user should proceed carefully. An `error` means something already has gone wrong.
+
+## Which components take which variants
+
+- **`Message`** (`MessageVariantType`) and **`Toast`** / the `toast()` helpers: `info | success |
+warning | error | danger`. `Message` and bare `toast()` default to `info`. Note the semantic
+ `info` variant maps internally to the library's neutral/default icon.
+- **`Badge`** (`BadgeVariantType`): `default | info | success | warning | danger | error`. The extra
+ `default` is the neutral, un-semantic chip; use it for labels that carry no status meaning.
+- **`Spinner`** uses a `variant` for color only (`primary | danger | success | warning | default`) —
+ this is purely a tint, not the semantic-variant contract above. Pick `primary` for ordinary loading.
+
+Match the variant to intent in every case. The same word (`danger`, `error`) means the same thing
+across all of these components, which is exactly why consistent use matters.
diff --git a/packages/ui-components/skills/forms/SKILL.md b/packages/ui-components/skills/forms/SKILL.md
new file mode 100644
index 0000000000..e6aaf8e10a
--- /dev/null
+++ b/packages/ui-components/skills/forms/SKILL.md
@@ -0,0 +1,449 @@
+---
+name: forms
+description: >
+ Use when building forms with Juno inputs in @cloudoperators/juno-ui-components: text fields,
+ textareas, selects, native selects, combo boxes, checkboxes, radios, switches, toggle buttons,
+ secret/date fields, grouping with Form/FormRow/FormSection, labels and hints, validation state
+ and timing (helptext/errortext/successtext, invalid/valid), and the dedicated SignInForm. For a
+ data table and its filter toolbar, see the datagrid skill; for Status-based page states, see the
+ feedback skill.
+metadata:
+ purpose: >
+ Teaches developers to compose the Juno form primitives into accessible, UX-compliant forms:
+ picking the right input for the data, labelling and hinting fields the Juno way (the `label`
+ prop, not a standalone Label), driving validation state through invalid/valid plus
+ errortext/successtext, choosing when to validate, and the sign-in form's deliberately
+ different (no-validation) rules the library does not enforce for you.
+ type: core
+ library: "@cloudoperators/juno-ui-components"
+ library_version: "9.6.0"
+sources:
+ - cloudoperators/juno:packages/ui-components/src/components/Form/Form.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/FormRow/FormRow.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/FormSection/FormSection.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/FormHint/FormHint.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/Label/Label.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/TextInput/TextInput.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/TextInput/TextInput.stories.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/Textarea/Textarea.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/SearchInput/SearchInput.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/SecretText/SecretText.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/Checkbox/Checkbox.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/CheckboxGroup/CheckboxGroup.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/Radio/Radio.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/RadioGroup/RadioGroup.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/RadioGroup/RadioGroup.stories.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/Switch/Switch.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/ToggleButton/ToggleButton.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/Select/Select.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/Select/Select.stories.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/SelectOption/SelectOption.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/SelectDivider/SelectDivider.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/NativeSelect/NativeSelect.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/NativeSelectOption/NativeSelectOption.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/NativeSelectOptionGroup/NativeSelectOptionGroup.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/ComboBox/ComboBox.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/ComboBoxOption/ComboBoxOption.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/InputGroup/InputGroup.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/InputGroup/InputGroup.stories.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/DateTimePicker/DateTimePicker.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/SignInForm/SignInForm.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/SignInForm/SignInForm.stories.tsx
+ - cloudoperators/juno:docs/ux/forms.md
+ - cloudoperators/juno:docs/ux/sign-in.md
+ - cloudoperators/juno:docs/ux/authentication-and-access.md
+ - cloudoperators/juno:docs/ux/semantic-variants.md
+---
+
+# Build a form with Juno inputs
+
+Juno form controls are mostly self-contained: each input renders its own label, help/error/success
+text, and validation styling from props — you rarely assemble those pieces by hand. The structural
+components (`Form`, `FormSection`, `FormRow`) only add spacing and headings; the inputs do the
+labelling and validation display. The two patterns that trip people up are **labelling** (use the
+`label` prop, not a standalone `Label`) and **validation state** (drive it with `invalid`/`valid`
+plus `errortext`/`successtext`), both covered below.
+
+## Setup
+
+```tsx
+import { Form, FormSection, FormRow, TextInput, Select, SelectOption, Button } from "@cloudoperators/juno-ui-components"
+
+declare function createProject(data: { name: string; region: string }): void
+
+function CreateProjectForm() {
+ return (
+ <Form title="Create project">
+ <FormSection title="Details">
+ <FormRow>
+ <TextInput name="name" label="Project name" required />
+ </FormRow>
+ <FormRow>
+ <Select name="region" label="Region" required>
+ <SelectOption value="eu-de-1">EU (Germany)</SelectOption>
+ <SelectOption value="us-east-1">US (East)</SelectOption>
+ </Select>
+ </FormRow>
+ </FormSection>
+ <Button variant="primary" type="submit">
+ Create
+ </Button>
+ </Form>
+ )
+}
+```
+
+`Form` renders a `<form>` with an optional `title` heading; `FormSection` groups related fields
+under a `title`; `FormRow` wraps one field (or a tightly-related pair) and supplies vertical
+spacing. One field per `FormRow` is the single-column default the UX guide recommends
+(`docs/ux/forms.md`, "Single-Column vs. Two-Column Layouts"). Styling requires the app to be wrapped
+in `AppShellProvider` — see the fundamentals skill if styles are missing.
+
+## Core patterns
+
+### Label every field with the `label` prop
+
+Most Juno controls accept a `label` prop that renders a visible, correctly-associated label and
+auto-generates an `id` when you pass none. Prefer it over placing a standalone `Label` next to the
+input (`docs/ux/forms.md`, "Labels and IDs"):
+
+```tsx
+import { TextInput } from "@cloudoperators/juno-ui-components"
+
+function EmailField() {
+ return <TextInput name="email" type="email" label="Email address" autoComplete="email" required />
+}
+```
+
+`SearchInput` and `NativeSelect` are the exceptions — they have no `label` prop and do **not**
+auto-generate an `id`. If you need a visible label there, pass an explicit `id` and associate a
+standalone `Label` via `htmlFor`:
+
+```tsx
+import { Label, NativeSelect, NativeSelectOption } from "@cloudoperators/juno-ui-components"
+
+function RegionField() {
+ return (
+ <>
+ <Label text="Region" htmlFor="region" />
+ <NativeSelect id="region" name="region">
+ <NativeSelectOption value="eu-de-1" label="EU (Germany)" />
+ <NativeSelectOption value="us-east-1" label="US (East)" />
+ </NativeSelect>
+ </>
+ )
+}
+```
+
+### Pick the right input type
+
+Set the `type` on `TextInput` so the browser enables the right keyboard, spellcheck, and format
+hints (`docs/ux/forms.md`, "Input Types"). `TextInput` disables autocomplete by default
+(`autoComplete="off"`); turn it back on explicitly for email/name/address/password fields:
+
+```tsx
+import { FormRow, TextInput } from "@cloudoperators/juno-ui-components"
+
+function ContactFields() {
+ return (
+ <>
+ <FormRow>
+ <TextInput name="email" type="email" label="Email" autoComplete="email" />
+ </FormRow>
+ <FormRow>
+ <TextInput name="phone" type="tel" label="Phone" />
+ </FormRow>
+ <FormRow>
+ <TextInput name="website" type="url" label="Website" placeholder="https://example.com" />
+ </FormRow>
+ </>
+ )
+}
+```
+
+Which component for which data: single line → `TextInput`; multi-line → `Textarea`; a secret the
+user reveals/copies (SSH key, token) → `SecretText`; one of a known list → `Select` (styled,
+searchable-feeling, multi-select capable) or `NativeSelect` (native `<select>`, best on mobile); a
+list where the user also types to filter → `ComboBox`; a date/time → `DateTimePicker`. See
+[choosing selects](references/selects.md) for the full `Select` vs `NativeSelect` vs `ComboBox`
+decision and multi-select wiring.
+
+### Communicate expectations with `helptext`
+
+Describe constraints before the user hits an error. Every major input takes a `helptext` prop; list
+multi-part requirements (e.g. password rules) upfront rather than revealing them one failure at a
+time (`docs/ux/forms.md`, "Communicating Expectations"):
+
+```tsx
+import { TextInput } from "@cloudoperators/juno-ui-components"
+
+function PasswordField() {
+ return (
+ <TextInput
+ name="password"
+ type="password"
+ label="Password"
+ autoComplete="new-password"
+ helptext="At least 12 characters, including a number and a symbol."
+ />
+ )
+}
+```
+
+The `helptext` prop is typed `ReactNode`, so richer content such as a link goes straight into it —
+no separate hint element needed:
+
+```tsx
+import { TextInput } from "@cloudoperators/juno-ui-components"
+
+function FilterField() {
+ return (
+ <TextInput
+ name="filter"
+ label="Filter"
+ placeholder="prod-*"
+ helptext={
+ <>
+ Supports wildcards — see the <a href="/docs/filtering">filtering guide</a>.
+ </>
+ }
+ />
+ )
+}
+```
+
+Drive validation text the same way through the input's own `errortext`/`successtext` (also
+`ReactNode`); don't reach for a standalone hint component — hint rendering is an internal detail of
+each input, not part of the public API.
+
+### Show validation state
+
+Validation is driven by two paired props on each input: a boolean state (`invalid` / `valid`) and
+the matching message (`errortext` / `successtext`). Passing `errortext` renders the message in the
+error style; also set `invalid` so the field border and the control's state reflect the error:
+
+```tsx
+import { useState } from "react"
+import { Form, FormRow, TextInput, Button } from "@cloudoperators/juno-ui-components"
+
+function NameForm() {
+ const [name, setName] = useState("")
+ const [error, setError] = useState<string>()
+
+ const validate = () => setError(name.trim() === "" ? "Name is required." : undefined)
+
+ return (
+ <Form title="Rename">
+ <FormRow>
+ <TextInput
+ name="name"
+ label="Name"
+ value={name}
+ onChange={(e) => setName(e.target.value)}
+ onBlur={validate}
+ invalid={Boolean(error)}
+ errortext={error}
+ />
+ </FormRow>
+ <Button variant="primary" type="submit">
+ Save
+ </Button>
+ </Form>
+ )
+}
+```
+
+Validate **on blur** as the safe default, and always re-validate **on submit**; reserve as-you-type
+for strict formats, and never flag a required-but-untouched field before interaction or submit
+(`docs/ux/forms.md`, "When to Validate"). For cross-field rules (e.g. password confirmation) put the
+error on the dependent field. See [validation timing and errors](references/validation.md) for
+inline-vs-summary errors, submit-time handling, and server-error placement.
+
+### Group radios and checkboxes
+
+Wrap related radios in `RadioGroup` and related checkboxes in `CheckboxGroup`. The group owns the
+shared `name`, selection state, and group-level `label`/`helptext`/`errortext`/`successtext`; the
+children only carry `value` and `label`. `RadioGroup.onChange` and `CheckboxGroup.onChange` receive
+the selected value, not a DOM event. Pass a `label` **and** an `aria-label` so the group has an
+accessible name (`docs/ux/forms.md`, "Grouped Inputs"):
+
+```tsx
+import { RadioGroup, Radio } from "@cloudoperators/juno-ui-components"
+
+function VisibilityField() {
+ return (
+ <RadioGroup
+ label="Visibility"
+ aria-label="Visibility"
+ name="visibility"
+ required
+ helptext="Who can see this project."
+ >
+ <Radio value="private" label="Private" />
+ <Radio value="internal" label="Internal" />
+ <Radio value="public" label="Public" />
+ </RadioGroup>
+ )
+}
+```
+
+```tsx
+import { CheckboxGroup, Checkbox } from "@cloudoperators/juno-ui-components"
+
+function NotificationsField() {
+ return (
+ <CheckboxGroup label="Notifications" aria-label="Notifications" name="notify" selected={["email"]}>
+ <Checkbox value="email" label="Email" />
+ <Checkbox value="sms" label="SMS" />
+ <Checkbox value="push" label="Push" />
+ </CheckboxGroup>
+ )
+}
+```
+
+### Switch vs. Checkbox
+
+Use `Switch` only for a setting that takes effect **immediately** without a submit step; use
+`Checkbox`/`CheckboxGroup` for choices that are submitted with the form. Do not put a `Switch` in a
+form that has its own submit button (`docs/ux/forms.md`, "Switches and Checkboxes"):
+
+```tsx
+import { Switch } from "@cloudoperators/juno-ui-components"
+
+declare function setMaintenanceMode(on: boolean): void
+
+function MaintenanceToggle({ enabled }: { enabled: boolean }) {
+ return <Switch label="Maintenance mode" on={enabled} onChange={() => setMaintenanceMode(!enabled)} />
+}
+```
+
+`Switch` renders a `<button role="switch">`, so its `onChange` fires with a
+`ChangeEvent<HTMLButtonElement>` on each toggle — there is no `event.target.checked` to read.
+Track the on/off state yourself (here from the `enabled` prop) and flip it when the change fires.
+
+For cycling through a small fixed set of modes (not a form value), `ToggleButton` takes an `options`
+array and reports the picked value through `onChange(value)`:
+
+```tsx
+import { useState } from "react"
+import { ToggleButton } from "@cloudoperators/juno-ui-components"
+
+function DensityToggle() {
+ const [density, setDensity] = useState("comfortable")
+ return <ToggleButton options={["comfortable", "compact"]} value={density} onChange={(v) => setDensity(v)} />
+}
+```
+
+### Join an input and a button with InputGroup
+
+`InputGroup` visually joins adjacent controls (e.g. an input and its submit button, or a
+`Select` + `TextInput`) and propagates a shared `variant`/`disabled` to its children:
+
+```tsx
+import { InputGroup, TextInput, Button } from "@cloudoperators/juno-ui-components"
+
+function AddTagRow() {
+ return (
+ <InputGroup>
+ <TextInput placeholder="New tag…" />
+ <Button label="Add" />
+ </InputGroup>
+ )
+}
+```
+
+### Submit, cancel, and submission feedback
+
+Place actions at the bottom of the form; the primary action is the rightmost button, with cancel to
+its left. Show a busy state on the submit button while the request is in flight and disable both
+buttons to prevent double submits (`docs/ux/forms.md`, "Submit and Cancel Actions" / "In-Progress
+State"). For destructive submits use the `primary-danger` button variant. See
+[validation timing and errors](references/validation.md) for the full submit lifecycle (success
+navigation, server-error placement).
+
+### Sign-in forms are different — use SignInForm
+
+Build sign-in on a dedicated page (never a modal) with the `SignInForm` component. It renders the
+heading, an optional error `Message`, auto-spaced children, and an optional reset-password link.
+Deliberately, sign-in fields are **not** marked required, submit is **not** disabled, and no inline
+validation runs — the server returns a generic error instead (`docs/ux/sign-in.md`):
+
+```tsx
+import { SignInForm, TextInput, Button } from "@cloudoperators/juno-ui-components"
+
+function LoginPage({ failed }: { failed: boolean }) {
+ return (
+ <SignInForm title="Sign in" error={failed} resetPwUrl="/reset-password">
+ <TextInput key="user" label="Username" id="user" />
+ <TextInput key="pw" label="Password" id="pw" type="password" />
+ <Button key="submit" variant="primary" type="submit" className="jn:w-full">
+ Sign In
+ </Button>
+ </SignInForm>
+ )
+}
+```
+
+`error` accepts `true` (default generic message), a custom string, or `false`/omitted (hidden). The
+message must never reveal whether an account exists for the entered identifier — the same rule
+applies to password-reset responses (`docs/ux/sign-in.md`, "Failed Sign-In";
+`docs/ux/authentication-and-access.md`). See [the sign-in form](references/sign-in.md) for the
+full prop set and security-safe error copy.
+
+## Common mistakes
+
+- **CRITICAL — Leaking account existence on failed sign-in.** A message like "No account for that
+ email" tells an attacker the address is (not) registered. Use `SignInForm`'s generic `error`
+ (`true`) or an equally non-committal custom string, and apply the same rule to password-reset
+ responses. (`docs/ux/sign-in.md`, "Failed Sign-In".)
+- **HIGH — `errortext` without `invalid` (or `successtext` without `valid`).** The message renders
+ but the field's border/state does not change, so the error is easy to miss. Always set the paired
+ boolean. (`docs/ux/forms.md`, "Validation".)
+- **HIGH — Validating required fields before interaction.** Showing "required" on untouched fields
+ on first render punishes the user before they start. Validate on blur / on submit instead.
+ (`docs/ux/forms.md`, "When to Validate".)
+- **HIGH — Standalone `Label` where a `label` prop exists.** Hand-wiring a `Label` next to a
+ `TextInput`/`Select` duplicates associations the `label` prop handles correctly. Use the prop;
+ reserve standalone `Label` for `SearchInput`/`NativeSelect`. (`docs/ux/forms.md`, "Labels and
+ IDs".)
+- **HIGH — `Switch` inside a form with a submit button.** `Switch` means "takes effect now". For a
+ value submitted with the form use `Checkbox`/`CheckboxGroup`. (`docs/ux/forms.md`, "Switches and
+ Checkboxes".)
+- **MEDIUM — Marking sign-in fields required / disabling the Sign In button.** Juno intentionally
+ does neither; let the user submit and show a generic server error. (`docs/ux/sign-in.md`,
+ "Sign-In Form Validation".)
+- **MEDIUM — Instruction only in `placeholder`.** Placeholder text disappears on first keystroke.
+ Put requirements in `helptext`; use `placeholder` only for example values alongside a
+ visible label. (`docs/ux/forms.md`, "Communicating Expectations".)
+- **MEDIUM — Both an inline field error and a form summary for the same problem.** Pick the one
+ closer to where the user acts. (`docs/ux/forms.md`, "Inline Field Errors vs. Summary Errors".)
+- **MEDIUM — Misusing the `error` prop for validation on Select/NativeSelect/ComboBox.** `error`
+ signals an operational problem (e.g. options failed to load); negative validation is `invalid`
+ with `errortext`. (`Select.component.tsx`, `error` vs `invalid` prop docs.)
+
+## Completion
+
+Verify:
+
+1. Every field has an accessible label (the `label` prop, or an `id` + `Label htmlFor` for
+ `SearchInput`/`NativeSelect`); grouped radios/checkboxes have a `label` and `aria-label`.
+2. Validation state uses the paired props (`invalid`+`errortext`, `valid`+`successtext`) and fires
+ on blur and on submit, never on untouched required fields.
+3. `Switch` is used only for immediate-effect settings, not form values.
+4. Sign-in uses `SignInForm` with a generic, non-leaking error and no required markers / disabled
+ submit.
+5. Run `npm exec --no -- intent validate packages/ui-components/skills` and fix any errors.
+
+If a validation or submission path cannot be exercised in your test harness, report it as
+unverified rather than assuming it renders.
+
+## References
+
+- [choosing selects](references/selects.md) — read when deciding between `Select`, `NativeSelect`,
+ and `ComboBox`, or wiring multi-select, option groups, dividers, or loading/error states.
+- [validation timing and errors](references/validation.md) — read when deciding when to validate,
+ inline vs. summary errors, cross-field rules, or submit/success/server-error handling.
+- [the sign-in form](references/sign-in.md) — read before building any sign-in or password-reset
+ flow, for the full `SignInForm` props and security-safe error copy.
+- [secret and date fields](references/secret-and-date.md) — read when adding a `SecretText`
+ (reveal/copy/paste) or a `DateTimePicker` (date, time, range, min/max).
diff --git a/packages/ui-components/skills/forms/references/secret-and-date.md b/packages/ui-components/skills/forms/references/secret-and-date.md
new file mode 100644
index 0000000000..4ff5399736
--- /dev/null
+++ b/packages/ui-components/skills/forms/references/secret-and-date.md
@@ -0,0 +1,98 @@
+# Secret and date fields
+
+Read this when adding a `SecretText` (reveal/copy/paste a secret such as an SSH key or token) or a
+`DateTimePicker` (date, time, range, or min/max constraints). Grounded in
+`SecretText.component.tsx` and `DateTimePicker.component.tsx`.
+
+## SecretText
+
+`SecretText` holds a secret in a textarea that can be concealed, revealed, copied, pasted, and
+cleared. Each affordance is toggled by a boolean (`toggle`, `copy`, `paste`, `clear`) and can be
+individually disabled (`disableToggle`, `disableCopy`, `disablePaste`, `disableClear`). It carries
+the same validation props as other inputs (`invalid`/`valid`, `errortext`/`successtext`,
+`helptext`, `required`, `label`).
+
+```tsx
+import { useState } from "react"
+import { SecretText } from "@cloudoperators/juno-ui-components"
+
+function SshKeyField() {
+ const [key, setKey] = useState("")
+ return (
+ <SecretText
+ name="ssh_key"
+ label="SSH public key"
+ value={key}
+ onChange={(e) => setKey(e.target.value)}
+ toggle
+ copy
+ paste
+ clear
+ helptext="Paste your public key. It stays hidden until you reveal it."
+ />
+ )
+}
+```
+
+Key handlers (all optional): `onChange`, `onReveal`, `onHide`, `onToggle`, `onCopy(value)`,
+`onPaste(value)`, `onClear`, `onBlur`, `onFocus`. Use `reveal` to control visibility and
+`copyConfirmtext` to customise the brief "copied" confirmation.
+
+## DateTimePicker
+
+`DateTimePicker` wraps Flatpickr. By default it is a date picker; opt into time with `enableTime`,
+drop the calendar for a pure time picker with `noCalendar`, and switch selection mode with
+`mode="single" | "multiple" | "range"`. `onChange` is a Flatpickr-style handler receiving the
+selected dates and the formatted string, not a DOM change event. It shares the validation props
+(`invalid`/`valid`, `errortext`/`successtext`, `helptext`, `required`, `label`).
+
+### Date only
+
+```tsx
+import { DateTimePicker } from "@cloudoperators/juno-ui-components"
+
+function StartDateField() {
+ return <DateTimePicker name="start" label="Start date" onChange={(dates, dateStr) => console.log(dateStr, dates)} />
+}
+```
+
+### Date and time, with min/max bounds
+
+```tsx
+import { DateTimePicker } from "@cloudoperators/juno-ui-components"
+
+function WindowStartField() {
+ return (
+ <DateTimePicker
+ name="window_start"
+ label="Maintenance window start"
+ enableTime
+ time_24hr
+ minDate="today"
+ helptext="Must be today or later."
+ />
+ )
+}
+```
+
+### Date range
+
+```tsx
+import { DateTimePicker } from "@cloudoperators/juno-ui-components"
+
+function BookingRangeField() {
+ return <DateTimePicker name="booking" label="Booking range" mode="range" />
+}
+```
+
+## Notes
+
+- `DateTimePicker` accepts flexible value inputs — `Date` objects, timestamps, ISO strings,
+ `YYYY-MM-DD HH:MM` strings (matching the current `dateFormat`), and the shortcut `"today"` — via
+ `value` / `defaultValue` / `defaultDate`. If both `value` and `defaultDate` are passed, `value`
+ wins.
+- Set `allowInput` to let users type a date directly; leave it off (default) for calendar-only
+ selection.
+- `enableSeconds`, `hourIncrement`, and `minuteIncrement` only take effect when `enableTime` is on.
+- `dateFormat` uses Flatpickr tokens (https://flatpickr.js.org/formatting/); when omitted the
+ component picks a sensible default based on whether time/seconds/calendar are enabled.
diff --git a/packages/ui-components/skills/forms/references/selects.md b/packages/ui-components/skills/forms/references/selects.md
new file mode 100644
index 0000000000..23f907a4c8
--- /dev/null
+++ b/packages/ui-components/skills/forms/references/selects.md
@@ -0,0 +1,144 @@
+# Choosing and wiring Juno selects
+
+Read this when deciding between `Select`, `NativeSelect`, and `ComboBox`, or when you need
+multi-select, option groups, dividers, or loading/error states. Grounded in `Select.component.tsx`,
+`NativeSelect.component.tsx`, `ComboBox.component.tsx`, and their option children.
+
+## Which one
+
+- **`Select`** — Juno-styled dropdown. Use for most desktop forms. Supports `multiple`, semantic
+ `variant`s, a `loading` spinner, truncation, and an `error` state for failed option loading.
+ Options are `SelectOption` children; group them visually with `SelectDivider`.
+- **`NativeSelect`** — a real `<select>`. Best when native behaviour matters (mobile, long lists,
+ minimal JS). No `label` prop and no auto `id` — label it with a standalone `Label htmlFor`.
+ Children are `NativeSelectOption`, grouped with `NativeSelectOptionGroup`.
+- **`ComboBox`** — dropdown the user can type into to filter. Use when the option list is long and
+ type-ahead filtering helps. Children are `ComboBoxOption`.
+
+## Select — single and multiple
+
+`Select.onChange` receives the selected value(s), not a DOM event. For `multiple`, pass an array as
+`value`/`defaultValue` and expect an array back.
+
+```tsx
+import { useState } from "react"
+import { Select, SelectOption, SelectDivider } from "@cloudoperators/juno-ui-components"
+
+function RegionSelect() {
+ const [region, setRegion] = useState<string>()
+ return (
+ <Select name="region" label="Region" value={region} onChange={(v) => setRegion(v as string)} required>
+ <SelectOption value="eu-de-1">EU (Germany)</SelectOption>
+ <SelectOption value="eu-nl-1">EU (Netherlands)</SelectOption>
+ <SelectDivider />
+ <SelectOption value="us-east-1">US (East)</SelectOption>
+ </Select>
+ )
+}
+```
+
+```tsx
+import { useState } from "react"
+import { Select, SelectOption } from "@cloudoperators/juno-ui-components"
+
+function TagsSelect() {
+ const [tags, setTags] = useState<string[]>([])
+ return (
+ <Select name="tags" label="Tags" multiple value={tags} onChange={(v) => setTags((v as string[]) ?? [])}>
+ <SelectOption value="prod">Production</SelectOption>
+ <SelectOption value="staging">Staging</SelectOption>
+ <SelectOption value="dev">Development</SelectOption>
+ </Select>
+ )
+}
+```
+
+### Loading and operational errors
+
+Use `loading` while fetching options and `error` (not `invalid`) when the fetch failed — `invalid`
+is reserved for negative validation of the chosen value:
+
+```tsx
+import { Select, SelectOption } from "@cloudoperators/juno-ui-components"
+
+type Props = { regions: string[]; isLoading: boolean; failed: boolean }
+
+function RemoteRegionSelect({ regions, isLoading, failed }: Props) {
+ return (
+ <Select
+ name="region"
+ label="Region"
+ loading={isLoading}
+ error={failed}
+ errortext={failed ? "Could not load regions." : undefined}
+ >
+ {regions.map((r) => (
+ <SelectOption key={r} value={r}>
+ {r}
+ </SelectOption>
+ ))}
+ </Select>
+ )
+}
+```
+
+## NativeSelect with option groups
+
+```tsx
+import { Label, NativeSelect, NativeSelectOption, NativeSelectOptionGroup } from "@cloudoperators/juno-ui-components"
+
+function ZoneSelect() {
+ return (
+ <>
+ <Label text="Zone" htmlFor="zone" />
+ <NativeSelect id="zone" name="zone">
+ <NativeSelectOptionGroup label="Europe">
+ <NativeSelectOption value="eu-de-1" label="EU (Germany)" />
+ <NativeSelectOption value="eu-nl-1" label="EU (Netherlands)" />
+ </NativeSelectOptionGroup>
+ <NativeSelectOptionGroup label="Americas">
+ <NativeSelectOption value="us-east-1" label="US (East)" />
+ </NativeSelectOptionGroup>
+ </NativeSelect>
+ </>
+ )
+}
+```
+
+`NativeSelectOption` takes `label` and `value` (both `string | number`); it has no boolean children
+API — pass the display text via `label`.
+
+## ComboBox — type to filter
+
+`ComboBox.onChange` reports the selected value as a string; `onInputChange` fires on each keystroke
+in the text field. Children are `ComboBoxOption` with a `value` and display `children`/`label`.
+
+```tsx
+import { useState } from "react"
+import { ComboBox, ComboBoxOption } from "@cloudoperators/juno-ui-components"
+
+const VEGETABLES = ["Rhubarb", "Carrots", "Spinach", "Tomatoes", "Cucumbers", "Eggplant"]
+
+function VegetablePicker() {
+ const [value, setValue] = useState<string>()
+ return (
+ <ComboBox name="vegetable" label="Vegetable" value={value} onChange={(v) => setValue(v)}>
+ {VEGETABLES.map((name) => (
+ <ComboBoxOption key={name} value={name}>
+ {name}
+ </ComboBoxOption>
+ ))}
+ </ComboBox>
+ )
+}
+```
+
+Like `Select`, `ComboBox` supports `loading`, `error`+`errortext` for operational failures, and
+`invalid`+`errortext` for negative validation of the chosen value.
+
+## Notes
+
+- `Select`, `NativeSelect`, and `ComboBox` all auto-generate an `id` except `NativeSelect`, which
+ does not — give it an explicit `id` when labelling.
+- In controlled mode, if your options use human-readable labels distinct from their submitted
+ `value`, also pass `valueLabel` to `Select`/`ComboBox` so the toggle renders the right text.
diff --git a/packages/ui-components/skills/forms/references/sign-in.md b/packages/ui-components/skills/forms/references/sign-in.md
new file mode 100644
index 0000000000..20923e8945
--- /dev/null
+++ b/packages/ui-components/skills/forms/references/sign-in.md
@@ -0,0 +1,80 @@
+# The sign-in form
+
+Read this before building any sign-in or password-reset flow. Grounded in
+`SignInForm.component.tsx`, `SignInForm.stories.tsx`, `docs/ux/sign-in.md`, and
+`docs/ux/authentication-and-access.md`.
+
+Sign-in deliberately breaks the normal form rules: fields are **not** marked required, the submit
+button is **not** disabled, and there is **no** inline validation. Users may submit empty and get a
+generic server error. This is intentional — the context makes the requirement obvious, and the
+error must not leak account information (`docs/ux/sign-in.md`, "Sign-In Form Validation"). Always
+use a dedicated page, never a modal.
+
+## Props
+
+`SignInForm` extends the native `<form>` attributes (minus `title`) and adds:
+
+- `title?: string | false` — heading text. Omit for the default `"Sign In"`; pass `false` to hide
+ the heading entirely.
+- `error?: string | boolean` — pass `true` for the built-in generic message
+ ("Authentication failed. Verify your credentials and try again."), a custom non-leaking string,
+ or `false`/omit to hide.
+- `resetPwUrl?: string | null` — a URL renders a "Reset password" link; `null` (default) or empty
+ hides it.
+- `children` — your inputs and submit button; `SignInForm` auto-spaces them in a vertical stack.
+
+## Typical form
+
+Mirrors the Storybook example: username/email, password, remember-me checkbox, full-width submit,
+and a reset link. Note the absence of `required` on the fields and of `disabled` on the button.
+
+```tsx
+import { SignInForm, TextInput, Checkbox, Button } from "@cloudoperators/juno-ui-components"
+
+function LoginPage({ failed }: { failed: boolean }) {
+ return (
+ <SignInForm title="Sign in" error={failed} resetPwUrl="/reset-password">
+ <TextInput key="email" label="Email address" id="email" />
+ <TextInput key="password" label="Password" id="password" type="password" />
+ <Checkbox key="remember" label="Remember me" id="remember" />
+ <Button key="submit" variant="primary" type="submit" className="jn:mt-4 jn:w-full">
+ Sign In
+ </Button>
+ </SignInForm>
+ )
+}
+```
+
+Additional fields (e.g. a region `Select`) can be passed as children too; follow the same
+no-validation, no-disabled practice as long as it is sensible (`docs/ux/sign-in.md`).
+
+## Security-safe error copy
+
+The failure message must never reveal whether an account exists for the entered identifier
+(`docs/ux/sign-in.md`, "Failed Sign-In"). The same applies to password-reset responses — confirm
+"If an account exists, we've sent reset instructions" rather than stating whether the address is
+registered.
+
+Safe:
+
+```tsx
+import { SignInForm, TextInput, Button } from "@cloudoperators/juno-ui-components"
+
+function LoginForm({ failed }: { failed: boolean }) {
+ return (
+ <SignInForm error={failed ? "Authentication failed. Verify your credentials and try again." : false}>
+ <TextInput label="Username" id="user" />
+ <TextInput label="Password" id="pw" type="password" />
+ <Button variant="primary" type="submit">
+ Sign In
+ </Button>
+ </SignInForm>
+ )
+}
+```
+
+Unsafe (do not do this): `error="No account found for that email"` or
+`error="Wrong password for this account"` — both confirm the identifier exists.
+
+For broader guidance on rendering UI that unauthorized users may not use, see
+`docs/ux/authentication-and-access.md` and its "UI for Unauthorized Users" link.
diff --git a/packages/ui-components/skills/forms/references/validation.md b/packages/ui-components/skills/forms/references/validation.md
new file mode 100644
index 0000000000..8f54962a84
--- /dev/null
+++ b/packages/ui-components/skills/forms/references/validation.md
@@ -0,0 +1,137 @@
+# Validation timing, errors, and submission
+
+Read this when deciding when to validate, how to place errors (inline vs. summary), handling
+cross-field rules, or wiring the submit → success/failure lifecycle. Grounded in
+`docs/ux/forms.md` ("Validation", "Submit and Cancel Actions", "Submission Feedback") and the
+input `invalid`/`valid`/`errortext`/`successtext` props.
+
+## When to validate
+
+- **On blur** — the safe default. Validate when the field loses focus, so you don't flag errors
+ mid-typing but still give early feedback.
+- **On submit** — always validate everything on submit, even if blur validation already ran.
+- **As-you-type** — only for strict formats (slug, API-key pattern) where immediate feedback helps.
+ Avoid it for fields that are temporarily invalid while being typed (e.g. a number field).
+
+Never show a validation error on a required-but-untouched field before interaction or a submit
+attempt.
+
+## Inline vs. summary errors
+
+- **Inline** (field's own `errortext` + `invalid`) — whenever the error belongs to one field. It
+ sits next to the control the user must fix.
+- **Summary** (one message at the top of the form or section) — for errors that cannot be pinned to
+ a single field (a cross-field business rule), or when a submit flags several fields at once. Make
+ it specific: say what went wrong and what to do.
+
+Do not use both inline and summary for the **same** problem.
+
+## Cross-field rules
+
+Put the error on the **dependent** field — the one whose value is the problem — not the field filled
+in first. Password confirmation is the canonical case:
+
+```tsx
+import { useState } from "react"
+import { Form, FormRow, TextInput, Button } from "@cloudoperators/juno-ui-components"
+
+function SetPasswordForm() {
+ const [pw, setPw] = useState("")
+ const [confirm, setConfirm] = useState("")
+ const mismatch = confirm !== "" && confirm !== pw
+
+ return (
+ <Form title="Set password">
+ <FormRow>
+ <TextInput
+ name="password"
+ type="password"
+ label="Password"
+ value={pw}
+ onChange={(e) => setPw(e.target.value)}
+ />
+ </FormRow>
+ <FormRow>
+ <TextInput
+ name="confirm"
+ type="password"
+ label="Confirm password"
+ value={confirm}
+ onChange={(e) => setConfirm(e.target.value)}
+ invalid={mismatch}
+ errortext={mismatch ? "Passwords do not match." : undefined}
+ />
+ </FormRow>
+ <Button variant="primary" type="submit">
+ Save
+ </Button>
+ </Form>
+ )
+}
+```
+
+If the relationship is ambiguous, show the error at section level instead.
+
+## Submit lifecycle
+
+Show a busy state on the submit button the moment the user submits, and disable both the submit and
+cancel buttons for the duration to prevent duplicate submissions. On success do one of: navigate to
+the created/edited entity's detail view; close a modal and show a confirming toast; or replace the
+form area with an inline confirmation. Never pair a toast with an in-page confirmation for the same
+action.
+
+```tsx
+import { useState } from "react"
+import { Form, FormRow, TextInput, Message, Button } from "@cloudoperators/juno-ui-components"
+
+declare function saveProject(name: string): Promise<void>
+declare function navigate(to: string): void
+
+function SaveProjectForm() {
+ const [name, setName] = useState("")
+ const [submitting, setSubmitting] = useState(false)
+ const [serverError, setServerError] = useState<string>()
+
+ const onSubmit = async (e: React.FormEvent) => {
+ e.preventDefault()
+ setSubmitting(true)
+ setServerError(undefined)
+ try {
+ await saveProject(name)
+ navigate("/projects")
+ } catch {
+ setServerError("Could not save the project. Please try again.")
+ } finally {
+ setSubmitting(false)
+ }
+ }
+
+ return (
+ <Form title="New project" onSubmit={onSubmit}>
+ {serverError && <Message variant="error" text={serverError} className="jn:mb-4" />}
+ <FormRow>
+ <TextInput name="name" label="Name" value={name} onChange={(e) => setName(e.target.value)} />
+ </FormRow>
+ <Button variant="primary" type="submit" disabled={submitting} progress={submitting}>
+ {submitting ? "Saving…" : "Save"}
+ </Button>
+ </Form>
+ )
+}
+```
+
+## Validation errors vs. server errors
+
+- **Validation errors** (bad input) — surface inline per the rules above; do not navigate away or
+ close the form.
+- **Server-side errors** (network/conflict/fault, outside the user's input) — show a `Message` at
+ the top of the form (or inside the modal), explaining what happened and whether retrying helps.
+ Use the `error` semantic variant for a failure; reserve `danger` for destructive-action
+ confirmations (`docs/ux/semantic-variants.md`, "`error` vs. `danger`").
+
+## Disabling submit until valid
+
+Only disable the submit button when the invalid state is always obvious to the user (short forms),
+or when paired with real-time inline validation. For longer forms, keep submit enabled and surface
+all errors on submit. Modal forms are the exception: disable the primary action while required
+fields are missing/invalid.
diff --git a/packages/ui-components/skills/interaction-patterns/SKILL.md b/packages/ui-components/skills/interaction-patterns/SKILL.md
new file mode 100644
index 0000000000..1631a1f8f6
--- /dev/null
+++ b/packages/ui-components/skills/interaction-patterns/SKILL.md
@@ -0,0 +1,360 @@
+---
+name: interaction-patterns
+description: >
+ Use when designing interaction flows in a Juno app built with @cloudoperators/juno-ui-components:
+ confirming consequential or destructive actions with a Modal, deciding whether to disable, hide,
+ or always-render a control the user may not be authorized for, adding/editing/deleting items
+ inline in a list, breaking a long task into a multi-step wizard, and laying out the overall
+ sign-in → home → scope → list → detail page flow. This is a UX-guidelines skill: it tells you
+ which pattern to reach for and wires real Juno components (Button, Modal, Tooltip, Icon,
+ TextInput, Message) into each. For the Modal API itself see the overlays skill; for form
+ validation see the forms skill; for the DataGrid list view see the datagrid skill.
+metadata:
+ purpose: >
+ Teaches developers to choose and implement Juno's interaction patterns correctly — confirmation
+ of destructive actions, the disable/hide/error decision for unauthorized controls, inline
+ add/edit/delete, multi-step wizards, and the standard page-and-user flow — grounded in the UX
+ guidelines so apps stay predictable and consistent instead of each screen inventing its own
+ affordances.
+ type: core
+ library: "@cloudoperators/juno-ui-components"
+ library_version: "9.6.0"
+sources:
+ - cloudoperators/juno:packages/ui-components/src/components/Button/Button.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/Button/Button.stories.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/Modal/Modal.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/Modal/Modal.stories.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/ModalFooter/ModalFooter.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/Tooltip/Tooltip.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/TextInput/TextInput.component.tsx
+ - cloudoperators/juno:docs/ux/interaction-guidelines.md
+ - cloudoperators/juno:docs/ux/inline-adding-editing-and-deleting.md
+ - cloudoperators/juno:docs/ux/wizard.md
+ - cloudoperators/juno:docs/ux/ui-for-unauthorized-users.md
+ - cloudoperators/juno:docs/ux/page-and-user-flow.md
+---
+
+# Design interaction flows in a Juno app
+
+Interactions in Juno apps should feel predictable: buttons look like buttons, every action gets
+feedback, and the same action uses the same pattern everywhere in the app
+(`docs/ux/interaction-guidelines.md`, "Clarity and Predictability" / "Consistency"). This skill
+covers the five flow-level decisions the component library does **not** make for you: when to
+confirm, whether to disable/hide/error an unauthorized control, how to add/edit/delete inline, when
+to reach for a wizard, and how pages connect. It uses real Juno components in every example but is
+primarily about _which_ pattern to choose.
+
+## Setup
+
+The patterns below compose existing components; there is nothing to install beyond the library and
+its `AppShellProvider` wrapper (see the fundamentals skill if styles are missing). The one piece of
+machinery that recurs is the controlled `Modal`: its `open` prop is driven by your state, and it
+does **not** close itself on confirm — your `onConfirm` must flip the state.
+
+```tsx
+import { useState } from "react"
+import { Button, Modal } from "@cloudoperators/juno-ui-components"
+
+function DangerExample() {
+ const [open, setOpen] = useState(false)
+ return (
+ <>
+ <Button variant="primary-danger" label="Delete" onClick={() => setOpen(true)} />
+ <Modal
+ open={open}
+ title="Delete project?"
+ confirmButtonLabel="Delete"
+ confirmButtonVariant="primary-danger"
+ onConfirm={() => setOpen(false)}
+ onCancel={() => setOpen(false)}
+ >
+ This permanently deletes the project and all its resources. This cannot be undone.
+ </Modal>
+ </>
+ )
+}
+```
+
+## Core patterns
+
+### Confirm consequential and destructive actions — and only those
+
+Reserve confirmation for destructive/irreversible actions (delete, terminate, revoke) and for
+actions whose consequences the user may not have anticipated. Do **not** confirm routine, obvious
+actions like navigating, filtering, sorting, or selecting — unnecessary dialogs are friction with no
+benefit (`docs/ux/interaction-guidelines.md`, "Confirmation of Consequential Actions").
+
+Make irreversibility explicit in the copy **before** the user commits, and label the confirm button
+with the verb, not "OK". Use `confirmButtonVariant="primary-danger"` for destructive confirms so the
+button reads as dangerous.
+
+```tsx
+import { useState } from "react"
+import { Button, Modal } from "@cloudoperators/juno-ui-components"
+
+declare function revokeToken(id: string): Promise<void>
+
+function RevokeTokenButton({ id }: { id: string }) {
+ const [open, setOpen] = useState(false)
+ const [busy, setBusy] = useState(false)
+
+ const confirm = async () => {
+ setBusy(true)
+ await revokeToken(id)
+ setBusy(false)
+ setOpen(false)
+ }
+
+ return (
+ <>
+ <Button variant="primary-danger" label="Revoke" onClick={() => setOpen(true)} />
+ <Modal
+ open={open}
+ title="Revoke this token?"
+ confirmButtonLabel="Revoke token"
+ confirmButtonVariant="primary-danger"
+ disableConfirmButton={busy}
+ disableCancelButton={busy}
+ onConfirm={confirm}
+ onCancel={() => setOpen(false)}
+ >
+ Any client using this token will stop working immediately. This action is irreversible.
+ </Modal>
+ </>
+ )
+}
+```
+
+Prefer reversible workflows where you can; only fall back to confirmation when the action truly
+cannot be undone (`docs/ux/interaction-guidelines.md`, "Reversibility"). For severity levels of
+destructive confirmation (e.g. type-to-confirm), see the overlays skill and `docs/ux/modals.md`.
+
+### Give every action feedback
+
+Every action that starts a process or changes state must be acknowledged by the UI — never leave the
+user guessing (`docs/ux/interaction-guidelines.md`, "Feedback"). The Juno `Button` has this built
+in: pass `progress` to show a spinner, and `progressLabel` to swap the label while in flight. Keep
+the button disabled while busy so it cannot be double-submitted.
+
+```tsx
+import { useState } from "react"
+import { Button } from "@cloudoperators/juno-ui-components"
+
+declare function save(): Promise<void>
+
+function SaveButton() {
+ const [busy, setBusy] = useState(false)
+ const onClick = async () => {
+ setBusy(true)
+ await save()
+ setBusy(false)
+ }
+ return (
+ <Button variant="primary" label="Save" progress={busy} progressLabel="Saving…" disabled={busy} onClick={onClick} />
+ )
+}
+```
+
+On success reflect the new state immediately; if the result is not visible in the current view, use
+a toast (see the feedback skill). On failure surface an actionable error (see below and the forms
+skill).
+
+### Decide disabled vs hidden vs always-functional for unauthorized controls
+
+When a control is gated by permissions, pick one of three options from the context — do not default
+to disabling everything (`docs/ux/ui-for-unauthorized-users.md`):
+
+1. **Render disabled** when the feature is available to most users and _this_ user just does not meet
+ a requirement, **and you know** their authorization up front. Explain _why_ it is disabled with a
+ tooltip or nearby message — a bare disabled button is a dead end
+ (`docs/ux/interaction-guidelines.md`, "Disabled States").
+2. **Do not render** when the feature is only for a privileged few or touches very sensitive data —
+ the current user will almost never be able to use it.
+3. **Render fully functional, handle the API error** only when you **cannot know** the user's
+ authorization beforehand; rely on the system response and show a "not authorized" message. This
+ is the least desirable option — use it only when option 1 or 2 is impossible.
+
+The disabled-with-reason case is the one developers most often get wrong. A disabled Juno `Button`
+cannot itself fire hover events, so wrap the trigger (not the button) and use `asChild`:
+
+```tsx
+import { Button, Tooltip, TooltipTrigger, TooltipContent } from "@cloudoperators/juno-ui-components"
+
+function CreateButton({ canCreate }: { canCreate: boolean }) {
+ if (!canCreate) {
+ return (
+ <Tooltip triggerEvent="hover">
+ <TooltipTrigger asChild>
+ <span>
+ <Button variant="primary" label="Create project" disabled />
+ </span>
+ </TooltipTrigger>
+ <TooltipContent>You need the project-admin role to create projects.</TooltipContent>
+ </Tooltip>
+ )
+ }
+ return <Button variant="primary" label="Create project" />
+}
+```
+
+For option 3, show the server's refusal with a `Message` of `variant="error"` near the control:
+
+```tsx
+import { Message } from "@cloudoperators/juno-ui-components"
+
+function NotAuthorized({ error }: { error?: string }) {
+ if (!error) return null
+ return <Message variant="error" title="Not authorized" text={error} />
+}
+```
+
+Read [choosing disable / hide / error](references/authorization-ui.md) for the full decision tree,
+including how to pick when permissions are only partially known.
+
+### Add, edit, and delete items inline in a list
+
+For simple, low-stakes items a few fields wide, let users edit **in place** rather than opening a
+Modal (`docs/ux/inline-adding-editing-and-deleting.md`). On edit, the item's display values are
+replaced by editable fields while the rest of the list stays visible; always offer **Save** and
+**Cancel**, and Cancel must restore the previous values without saving.
+
+```tsx
+import { useState } from "react"
+import { Button, ButtonRow, TextInput } from "@cloudoperators/juno-ui-components"
+
+type Tag = { id: string; name: string }
+declare function persist(tag: Tag): void
+
+function TagRow({ tag }: { tag: Tag }) {
+ const [editing, setEditing] = useState(false)
+ const [draft, setDraft] = useState(tag.name)
+
+ if (!editing) {
+ return (
+ <ButtonRow>
+ <span>{tag.name}</span>
+ <Button size="small" icon="edit" label="Edit" onClick={() => setEditing(true)} />
+ </ButtonRow>
+ )
+ }
+ return (
+ <ButtonRow>
+ <TextInput value={draft} onChange={(e) => setDraft(e.target.value)} aria-label="Tag name" />
+ <Button
+ size="small"
+ variant="primary"
+ label="Save"
+ onClick={() => {
+ persist({ ...tag, name: draft })
+ setEditing(false)
+ }}
+ />
+ <Button
+ size="small"
+ variant="subdued"
+ label="Cancel"
+ onClick={() => {
+ setDraft(tag.name) // restore previous state, discard the edit
+ setEditing(false)
+ }}
+ />
+ </ButtonRow>
+ )
+}
+```
+
+Inline **delete** is typically an icon button per item. While the request is in flight, disable the
+action; remove the item only after it succeeds, and keep it (showing an error) if it fails. Use
+inline delete only for low-criticality deletions — add a confirmation step (the Modal above) for
+higher-criticality ones. New items are added at the **bottom** in their editable state and scrolled
+into view; do not require more fields to create an item than the list already shows.
+
+Read [inline add/edit/delete details](references/inline-crud.md) for the add-at-bottom flow, the
+in-flight delete states, and when to escalate to a Modal instead.
+
+### Break long, sequential tasks into a wizard
+
+Use a wizard only when a task has multiple ordered steps, is too long for a single form, or has
+early decisions that change later steps (`docs/ux/wizard.md`). If the task is short and
+self-contained, a single Modal with a form is the better fit — do not wrap a two-field form in a
+wizard.
+
+> The step-indicator component and the Modal wizard variant are still in design/development
+> (`docs/ux/wizard.md`, note). Until they ship, compose the behavior yourself from `Modal`/`Button`:
+> a **Back** button on every step except the first, a **Next** button disabled while the current
+> step is invalid, and a final step whose **Next** becomes **Submit** ("Create"/"Finish"). Input
+> must be preserved across Back/Next, and always offer Cancel.
+
+Read [wizard composition](references/wizard.md) for a worked multi-step example and the step
+validation / revisiting rules before building one.
+
+### Lay out the overall page flow
+
+Follow the standard Juno flow so navigation is predictable across apps
+(`docs/ux/page-and-user-flow.md`): Sign In → Home (overview of what the user owns/can access) →
+navigate into a scope (via Side Navigation) → **list view** (a DataGrid, see the datagrid skill) →
+**detail view**. Every detail view must be deep-linkable with a stable URL, and must offer an
+explicit way back to the list — a breadcrumb **and** a back button — never relying on the browser
+back button alone. Give every page a heading describing its contents ("Servers", "Images"); omit it
+only when genuinely redundant (e.g. an obvious Dashboard).
+
+## Common mistakes
+
+- **CRITICAL — No feedback on a state-changing action.** A button that fires a request but shows no
+ spinner, no disabled state, and no success/error leaves users re-clicking and unsure. Use
+ `progress`/`progressLabel` + `disabled`, then a toast or inline result.
+ (`docs/ux/interaction-guidelines.md`, "Feedback".)
+- **CRITICAL — Irreversible action with no confirmation or an unclear one.** Destructive/irreversible
+ actions must be confirmed with the consequence stated up front and a verb-labeled
+ `primary-danger` confirm button — not a generic "OK".
+ (`docs/ux/interaction-guidelines.md`, "Confirmation of Consequential Actions" / "Reversibility".)
+- **HIGH — Confirming routine actions.** Dialogs on navigate/filter/sort/select are pure friction.
+ Reserve confirmation for destructive or non-obvious actions only.
+ (`docs/ux/interaction-guidelines.md`, "Confirmation of Consequential Actions".)
+- **HIGH — Bare disabled control with no reason.** A disabled button the user cannot explain is a
+ dead end; attach a tooltip or nearby message saying why (and remember a disabled button cannot
+ fire its own hover — wrap it). (`docs/ux/ui-for-unauthorized-users.md`, "Render Disabled
+ Elements"; `docs/ux/interaction-guidelines.md`, "Disabled States".)
+- **HIGH — Modal assumed to self-close.** `Modal` does not close on confirm; your `onConfirm` must
+ flip the `open` state, or the dialog hangs after the action completes.
+ (`Modal.component.tsx`, `onConfirm` doc: "we do not close the modal automatically".)
+- **HIGH — Inline delete removes the row before the request succeeds.** Disable the action in flight
+ and only remove on success; keep the item and show an error on failure.
+ (`docs/ux/inline-adding-editing-and-deleting.md`, "Inline Deleting".)
+- **MEDIUM — Wizard for a short task.** Multi-step chrome for a two-field form is overkill; use a
+ single Modal form. Reserve the wizard for genuinely long, ordered, branching tasks.
+ (`docs/ux/wizard.md`, "When to Use a Wizard".)
+- **MEDIUM — Inconsistent pattern for the same action.** If creating a resource uses a Modal in one
+ place, use a Modal for it everywhere in the app; do not optimize one screen in isolation.
+ (`docs/ux/interaction-guidelines.md`, "Consistency".)
+- **MEDIUM — Detail view with no stable URL or no in-page back.** Detail pages must be
+ deep-linkable and reachable back to the list via breadcrumb + back button.
+ (`docs/ux/page-and-user-flow.md`, "Detail Views".)
+
+## Completion
+
+Verify:
+
+1. Every state-changing action shows in-flight feedback (`progress`/`disabled`) and a success or
+ error result.
+2. Destructive/irreversible actions are confirmed with the consequence stated up front and a
+ `primary-danger` confirm button; routine actions are **not** confirmed.
+3. Each Modal's `onConfirm`/`onCancel` actually flips its `open` state.
+4. Unauthorized controls follow one deliberate choice (disable-with-reason / hide / functional +
+ error), consistent with the rest of the app.
+5. Inline edit offers Save + Cancel (Cancel restores previous values); inline delete disables while
+ in flight and removes only on success.
+6. The same action uses the same pattern everywhere in the app.
+7. Run `npm exec --no -- intent validate packages/ui-components/skills` and fix any errors.
+
+If a flow state (e.g. the server-side authorization error, or a failed inline delete) cannot be
+exercised in your harness, report it as unverified rather than assuming it renders.
+
+## References
+
+- [choosing disable / hide / error](references/authorization-ui.md) — read when gating a control by
+ permissions and deciding how to render it for users who may not be authorized.
+- [inline add/edit/delete details](references/inline-crud.md) — read before building inline list
+ editing, including add-at-bottom and the in-flight delete states.
+- [wizard composition](references/wizard.md) — read before composing a multi-step wizard flow (step
+ validation, Back/Next/Submit, revisiting steps).
diff --git a/packages/ui-components/skills/interaction-patterns/references/authorization-ui.md b/packages/ui-components/skills/interaction-patterns/references/authorization-ui.md
new file mode 100644
index 0000000000..2be520480c
--- /dev/null
+++ b/packages/ui-components/skills/interaction-patterns/references/authorization-ui.md
@@ -0,0 +1,88 @@
+# Choosing disable / hide / error for unauthorized controls
+
+Read this when a control is gated by permissions and you must decide how to render it for a user who
+may not be authorized. Source: `docs/ux/ui-for-unauthorized-users.md` and
+`docs/ux/interaction-guidelines.md` ("Disabled States").
+
+The decision depends on three things: the sensitivity/criticality of the action, how broadly the
+feature is available, and whether you can know the user's authorization _before_ they act.
+
+## Decision tree
+
+1. **Do you know the user's authorization up front?**
+ - **No** → there is no good UI-side choice. Render the control **fully functional** and rely on
+ the API/system response, then show a "not authorized" error message. This is the least
+ desirable option — only build it when it is impossible to learn authorization beforehand.
+ - **Yes** → continue.
+2. **Is the feature available to all/most/many users, with this user just not (yet) meeting a
+ requirement?**
+ - **Yes** → **render it disabled**, and communicate _why_ (tooltip on the button, or a message /
+ info block next to it). A disabled element the user cannot explain is a dead end.
+3. **Is the feature only for a privileged few, or does it touch very sensitive, business-critical
+ data?**
+ - **Yes** → **do not render it at all**. The probability this user will ever use it is very low,
+ so showing it only adds noise.
+
+## Disabled-with-reason: wrap the trigger
+
+A disabled Juno `Button` sets the native `disabled` attribute (`Button.component.tsx`), which
+suppresses pointer events — so a tooltip bound directly to the button never opens. Wrap the button
+in a focusable/hoverable element and point `TooltipTrigger asChild` at that wrapper.
+
+```tsx
+import { Button, Tooltip, TooltipTrigger, TooltipContent } from "@cloudoperators/juno-ui-components"
+
+function GatedAction({ allowed, reason }: { allowed: boolean; reason: string }) {
+ if (allowed) {
+ return <Button variant="primary" label="Terminate instance" />
+ }
+ return (
+ <Tooltip triggerEvent="hover">
+ <TooltipTrigger asChild>
+ <span tabIndex={0}>
+ <Button variant="primary" label="Terminate instance" disabled />
+ </span>
+ </TooltipTrigger>
+ <TooltipContent>{reason}</TooltipContent>
+ </Tooltip>
+ )
+}
+```
+
+## Functional + error (option 3)
+
+When you cannot know authorization, let the action run and surface the server's refusal in place with
+a `Message`. Keep the user's input intact so they are not forced to redo work.
+
+```tsx
+import { useState } from "react"
+import { Button, Message } from "@cloudoperators/juno-ui-components"
+
+declare function doAction(): Promise<void>
+
+function OptimisticAction() {
+ const [error, setError] = useState<string | null>(null)
+ const run = async () => {
+ setError(null)
+ try {
+ await doAction()
+ } catch {
+ setError("You are not authorized to perform this action.")
+ }
+ }
+ return (
+ <>
+ <Button variant="primary" label="Run" onClick={run} />
+ {error && <Message variant="error" title="Not authorized" text={error} />}
+ </>
+ )
+}
+```
+
+## Notes
+
+- Whatever you choose, be **consistent across the app**: do not disable the create button on one
+ page and hide it on another (`docs/ux/interaction-guidelines.md`, "Consistency").
+- "Partially known" permissions (you know some scopes, not others) usually resolve to option 1 for
+ the known-denied cases and option 3 only for the genuinely unknown ones — do not blanket-apply
+ option 3 just because one scope is uncertain.
diff --git a/packages/ui-components/skills/interaction-patterns/references/inline-crud.md b/packages/ui-components/skills/interaction-patterns/references/inline-crud.md
new file mode 100644
index 0000000000..7e8ecefa44
--- /dev/null
+++ b/packages/ui-components/skills/interaction-patterns/references/inline-crud.md
@@ -0,0 +1,116 @@
+# Inline add / edit / delete details
+
+Read this before building inline list editing. Source:
+`docs/ux/inline-adding-editing-and-deleting.md` and
+`docs/ux/interaction-guidelines.md` ("Efficiency").
+
+Use the inline pattern only for **simple, low-stakes** items a few fields wide, where in-place
+interaction is faster than a Modal. For complex items with many fields, or high-criticality actions,
+use a Modal or a dedicated page instead. Inline is primarily for standalone lists; DataGrids
+typically add items via a Modal (patterns can be combined where it makes sense).
+
+## When to use it
+
+- Items are simple enough to edit with a small number of fields.
+- The task is low-stakes and does not need focused attention away from the list.
+- Adding/editing inline feels natural for the content structure.
+
+## Inline adding — add at the bottom
+
+Provide a clearly visible add action, typically a button at or near the top of the list. The new
+item is appended at the **bottom** in its editable state, ready for input, and scrolled into view if
+it is off-screen. Do not require more (or different) information to create an item than the list
+already displays for existing items.
+
+```tsx
+import { useState } from "react"
+import { Button, TextInput } from "@cloudoperators/juno-ui-components"
+
+type Tag = { id: string; name: string; draft?: boolean }
+declare function createTag(name: string): Promise<Tag>
+
+function TagList({ initial }: { initial: Tag[] }) {
+ const [tags, setTags] = useState<Tag[]>(initial)
+
+ const addDraft = () => setTags((prev) => [...prev, { id: `draft-${Date.now()}`, name: "", draft: true }])
+
+ const commit = async (id: string, name: string) => {
+ const saved = await createTag(name)
+ setTags((prev) => prev.map((t) => (t.id === id ? saved : t)))
+ }
+
+ return (
+ <div>
+ <Button icon="addCircle" label="Add tag" onClick={addDraft} />
+ {tags.map((tag) =>
+ tag.draft ? (
+ <TextInput
+ key={tag.id}
+ autoFocus
+ placeholder="Tag name"
+ onBlur={(e) => commit(tag.id, e.target.value)}
+ aria-label="New tag name"
+ />
+ ) : (
+ <div key={tag.id}>{tag.name}</div>
+ )
+ )}
+ </div>
+ )
+}
+```
+
+## Inline editing — Save and Cancel
+
+On edit, the item's display values are replaced by editable fields; the rest of the list stays
+visible and unchanged. Always provide Save and Cancel. **Cancel must restore the item to its
+previous state without saving** — snapshot the original value and write it back on cancel (see the
+`TagRow` example in the main skill).
+
+## Inline deleting — guard the in-flight state
+
+Place a delete action (usually an icon button) on each item where the user has permission. The order
+of operations matters:
+
+1. On activation, **disable the action** while deletion is in progress (prevents double-submit).
+2. Remove the item from the list **only after the request succeeds**.
+3. If it fails, **retain the item** and surface an error.
+
+```tsx
+import { useState } from "react"
+import { Icon, Message } from "@cloudoperators/juno-ui-components"
+
+declare function deleteTag(id: string): Promise<void>
+
+function DeletableTag({ id, name, onRemoved }: { id: string; name: string; onRemoved: () => void }) {
+ const [busy, setBusy] = useState(false)
+ const [error, setError] = useState<string | null>(null)
+
+ const remove = async () => {
+ setBusy(true)
+ setError(null)
+ try {
+ await deleteTag(id)
+ onRemoved() // remove from the list only after success
+ } catch {
+ setError("Could not delete tag.") // keep the item, show the error
+ setBusy(false)
+ }
+ }
+
+ return (
+ <div>
+ <span>{name}</span>
+ <Icon icon="deleteForever" title={`Delete ${name}`} disabled={busy} onClick={remove} />
+ {error && <Message variant="error" text={error} />}
+ </div>
+ )
+}
+```
+
+## Escalate to a Modal
+
+Use inline delete only for **low-criticality** deletions where accidental deletion is cheap. For
+higher criticality, add a confirmation step — a Modal with the consequence stated up front and a
+`primary-danger` confirm button (see the main skill's "Confirm consequential actions" and
+`docs/ux/modals.md`).
diff --git a/packages/ui-components/skills/interaction-patterns/references/wizard.md b/packages/ui-components/skills/interaction-patterns/references/wizard.md
new file mode 100644
index 0000000000..d6215ede0b
--- /dev/null
+++ b/packages/ui-components/skills/interaction-patterns/references/wizard.md
@@ -0,0 +1,127 @@
+# Wizard composition
+
+Read this before composing a multi-step wizard. Source: `docs/ux/wizard.md` and, for validation and
+submission feedback, `docs/ux/forms.md`.
+
+> The dedicated step-indicator component and the Modal wizard variant are still in
+> design/development (`docs/ux/wizard.md`, note). Until they ship, compose the behavior from `Modal`
+> and `Button` as shown here. When the official components land, migrate to them.
+
+## When a wizard is the right choice
+
+Use a wizard only when the task:
+
+- consists of multiple distinct steps that must be completed in order,
+- is too complex or long for a single Modal or form,
+- has decisions in earlier steps that affect what later steps show.
+
+If the task is short and self-contained, use a single Modal with a form instead
+(`docs/ux/wizard.md`, "When to Use a Wizard").
+
+## Contexts
+
+- **In a Modal** — focused, self-contained tasks that do not warrant leaving the page. Keep the step
+ count low.
+- **On a standalone page** — significant tasks with many steps or long/complex step content.
+
+## Anatomy and navigation rules
+
+- A **step indicator** showing position, with completed / current / upcoming steps differentiated.
+- A **content area** for the current step's fields.
+- **Navigation actions**: a **Back** button on every step except the first (returns without losing
+ input), a **Next** button **disabled while required fields in the current step are missing or
+ invalid**, and on the last step a **Submit** button labeled to reflect the final action
+ ("Create" / "Finish").
+- Always provide **Cancel**; cancelling must not persist partial state unless the wizard explicitly
+ supports saving progress.
+- **Validate each step before advancing**; never validate a future step before the user reaches it.
+- **Preserve input** when moving Back and Next. Completed steps in the indicator may be made directly
+ clickable **only when steps are independent** — if later steps depend on earlier ones, require
+ sequential navigation.
+- Each step has a single clear purpose; do not bundle unrelated fields. Indicator labels are short
+ (one to three words).
+
+## Worked example (Modal-hosted, three steps)
+
+```tsx
+import { useState } from "react"
+import { Button, ButtonRow, Modal, ModalFooter, TextInput } from "@cloudoperators/juno-ui-components"
+
+type Draft = { name: string; region: string; confirmed: boolean }
+declare function createCluster(draft: Draft): Promise<void>
+
+const STEP_LABELS = ["Name", "Region", "Review"]
+
+function CreateClusterWizard({ open, onClose }: { open: boolean; onClose: () => void }) {
+ const [step, setStep] = useState(0)
+ const [draft, setDraft] = useState<Draft>({ name: "", region: "", confirmed: false })
+ const [busy, setBusy] = useState(false)
+
+ // Validate only the current step; never a step the user has not reached.
+ const stepValid = step === 0 ? draft.name.trim() !== "" : step === 1 ? draft.region !== "" : true
+ const isLast = step === STEP_LABELS.length - 1
+
+ const submit = async () => {
+ setBusy(true)
+ await createCluster(draft)
+ setBusy(false)
+ onClose()
+ }
+
+ const footer = (
+ <ModalFooter>
+ <ButtonRow>
+ <Button variant="subdued" label="Cancel" disabled={busy} onClick={onClose} />
+ {step > 0 && <Button label="Back" disabled={busy} onClick={() => setStep((s) => s - 1)} />}
+ {isLast ? (
+ <Button
+ variant="primary"
+ label="Create"
+ progress={busy}
+ progressLabel="Creating…"
+ disabled={busy}
+ onClick={submit}
+ />
+ ) : (
+ <Button variant="primary" label="Next" disabled={!stepValid} onClick={() => setStep((s) => s + 1)} />
+ )}
+ </ButtonRow>
+ </ModalFooter>
+ )
+
+ return (
+ <Modal open={open} title={`Create cluster — ${STEP_LABELS[step]}`} modalFooter={footer} onCancel={onClose}>
+ {step === 0 && (
+ <TextInput
+ label="Cluster name"
+ value={draft.name}
+ onChange={(e) => setDraft((d) => ({ ...d, name: e.target.value }))}
+ />
+ )}
+ {step === 1 && (
+ <TextInput
+ label="Region"
+ value={draft.region}
+ onChange={(e) => setDraft((d) => ({ ...d, region: e.target.value }))}
+ />
+ )}
+ {step === 2 && (
+ <div>
+ Create cluster <strong>{draft.name}</strong> in <strong>{draft.region}</strong>?
+ </div>
+ )}
+ </Modal>
+ )
+}
+```
+
+## Notes
+
+- The `draft` state lives above the step index, so moving Back and Next never loses input — this is
+ what satisfies the "preserve input" rule.
+- `Next` is gated on `stepValid` for the current step only; the Review step is always valid because
+ its inputs were validated earlier.
+- Passing a custom `modalFooter` replaces the Modal's default Confirm/Cancel buttons, which is how
+ you get Back / Next / Submit in one row.
+- For submission feedback (success toast, inline error on failure) follow the forms skill and
+ `docs/ux/forms.md` ("Submission Feedback").
diff --git a/packages/ui-components/skills/layout/SKILL.md b/packages/ui-components/skills/layout/SKILL.md
new file mode 100644
index 0000000000..4a3ca04f0e
--- /dev/null
+++ b/packages/ui-components/skills/layout/SKILL.md
@@ -0,0 +1,385 @@
+---
+name: layout
+description: >
+ Use when building the overall page structure of a Juno app with
+ @cloudoperators/juno-ui-components: wrapping the app in AppShellProvider, scaffolding the shell
+ with AppShell (page header, side/top navigation, content area, page footer), running in embedded
+ mode for micro-frontends, and arranging content inside the content area with ContentHeading,
+ ContentAreaToolbar, Grid/GridRow/GridColumn, Stack, Container, Box, IntroBox, and Divider. For
+ the data table that usually fills a list page, see the datagrid skill; for the navigation items
+ themselves, see the navigation skill.
+metadata:
+ purpose: >
+ Teaches developers to assemble a UX-compliant Juno page: the mandatory AppShellProvider wrapper
+ plus the AppShell page frame (header, content area, footer) that the UX guidelines require on
+ every page, when to drop to the manual AppBody/MainContainer primitives, how embedded mode
+ changes the frame for micro-frontends, and how to lay out the content area with the Grid, Stack,
+ Container, Box, IntroBox, and Divider primitives.
+ type: core
+ library: "@cloudoperators/juno-ui-components"
+ library_version: "9.6.0"
+sources:
+ - cloudoperators/juno:packages/ui-components/src/components/AppShellProvider/AppShellProvider.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/AppShell/AppShell.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/AppShell/AppShell.stories.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/AppBody/AppBody.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/Container/Container.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/ContentContainer/ContentContainer.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/MainContainer/MainContainer.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/MainContainerInner/MainContainerInner.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/HeaderContainer/HeaderContainer.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/PageHeader/PageHeader.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/PageFooter/PageFooter.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/PageFooter/PageFooter.stories.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/ContentHeading/ContentHeading.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/ContentAreaToolbar/ContentAreaToolbar.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/Grid/Grid.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/GridRow/GridRow.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/GridColumn/GridColumn.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/Stack/Stack.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/Box/Box.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/IntroBox/IntroBox.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/Divider/Divider.component.tsx
+ - cloudoperators/juno:docs/ux/juno-layout.md
+ - cloudoperators/juno:docs/ux/the-appshell.md
+ - cloudoperators/juno:docs/ux/layout-fundamentals.md
+ - cloudoperators/juno:docs/ux/page-header.md
+ - cloudoperators/juno:docs/ux/page-content-area.md
+ - cloudoperators/juno:docs/ux/page-footer.md
+ - cloudoperators/juno:docs/ux/page-layout-elements.md
+ - cloudoperators/juno:docs/ux/embedded-application-layout.md
+ - cloudoperators/juno:docs/ux/box.md
+---
+
+# Build the page layout and app shell of a Juno app
+
+Every Juno application has the same stable frame: a **Page Header** at the top, a **Page Content
+Area** in the middle, and a **Page Footer** at the bottom (`docs/ux/page-layout-elements.md`). You
+almost never assemble that frame by hand — two components give it to you:
+
+- `AppShellProvider` — the outermost wrapper. It supplies theming, CSS variables, the shadow root,
+ and the portal context that every other component depends on. Without it, styles do not apply.
+- `AppShell` — the page frame itself. It renders the header, a main content area (with optional
+ side/top navigation), and the footer in the correct markup positions, each via a named slot.
+
+Reach for the lower-level primitives (`AppBody`, `MainContainer`, `ContentContainer`, …) only when
+you deliberately opt out of `AppShell`; the UX guidance calls that "significantly more effort" and
+warns the app may not render correctly (`docs/ux/the-appshell.md`).
+
+## Setup
+
+Wrap the whole app in `AppShellProvider`, then scaffold the frame with `AppShell`. Pass the page
+title either as a string (rendered as the application name in the default header) or as your own
+`PageHeader`. Content goes in `children`.
+
+```tsx
+import { AppShellProvider, AppShell, Container, ContentHeading } from "@cloudoperators/juno-ui-components"
+
+function App() {
+ return (
+ <AppShellProvider theme="theme-dark">
+ <AppShell pageHeader="My App">
+ <Container py>
+ <ContentHeading>Dashboard</ContentHeading>
+ <p>Content goes here.</p>
+ </Container>
+ </AppShell>
+ </AppShellProvider>
+ )
+}
+```
+
+`AppShell` already renders a default `PageHeader` and `PageFooter` when you pass neither, so the
+mandatory three-part frame (`docs/ux/layout-fundamentals.md`) is present out of the box. Wrap your
+own content in a `Container` to get the standard horizontal padding (`px` defaults to `true`); add
+`py` for vertical padding too.
+
+## Core patterns
+
+### Add side and/or top navigation
+
+Primary navigation belongs in the `sideNavigation` slot, left of the content — "New applications
+should always use a Side Navigation adjacent to the left of the actual content"
+(`docs/ux/juno-layout.md`, "Main Content Area"). `topNavigation` is an additional slot rendered in
+the header area. Both are plain `ReactNode` slots; pass the navigation components from the
+navigation skill.
+
+```tsx
+import { AppShell, SideNavigation, SideNavigationItem } from "@cloudoperators/juno-ui-components"
+
+declare function navigate(to: string): void
+
+function Shell({ children }: { children: React.ReactNode }) {
+ return (
+ <AppShell
+ pageHeader="My App"
+ sideNavigation={
+ <SideNavigation>
+ <SideNavigationItem label="Overview" onClick={() => navigate("/")} />
+ <SideNavigationItem label="Settings" onClick={() => navigate("/settings")} />
+ </SideNavigation>
+ }
+ >
+ {children}
+ </AppShell>
+ )
+}
+```
+
+### Customize the Page Header
+
+The header's left side identifies the app (logo + application name); its right side holds global
+options that must not change as the user navigates (`docs/ux/page-header.md`). Pass children for the
+right-side options area, and make the logo/name interactive with `href` or `onClick` so it links
+home.
+
+```tsx
+import { AppShell, PageHeader, Button } from "@cloudoperators/juno-ui-components"
+
+function Shell({ children }: { children: React.ReactNode }) {
+ return (
+ <AppShell
+ pageHeader={
+ <PageHeader applicationName="My App" href="/">
+ <Button variant="subdued" icon="autoAwesomeMotion" />
+ <Button label="Sign out" />
+ </PageHeader>
+ }
+ >
+ {children}
+ </AppShell>
+ )
+}
+```
+
+Keep both logo and application name visible — hiding both leaves users without orientation
+(`docs/ux/page-header.md`). `logo` defaults to the Juno logo; pass a React element for a custom one
+or `logo={false}` to hide just the logo. The deprecated `heading` prop is superseded by
+`applicationName`.
+
+### Fill in the Page Footer
+
+The footer carries secondary, site-wide links and legal info — never primary navigation or actions
+(`docs/ux/page-footer.md`). Use inline links for a few items, or two/three columns for more, plus an
+optional `copyright`. The footer ships CSS classes for this structure.
+
+```tsx
+import { AppShell, PageFooter } from "@cloudoperators/juno-ui-components"
+
+function Shell({ children }: { children: React.ReactNode }) {
+ return (
+ <AppShell
+ pageHeader="My App"
+ pageFooter={
+ <PageFooter copyright="© 2026 ACME">
+ <ul className="juno-pagefooter-items-inline">
+ <li>
+ <a className="juno-pagefooter-item" href="/imprint">
+ Imprint
+ </a>
+ </li>
+ <li>
+ <a className="juno-pagefooter-item" href="/terms">
+ Terms of Use
+ </a>
+ </li>
+ </ul>
+ </PageFooter>
+ }
+ >
+ {children}
+ </AppShell>
+ )
+}
+```
+
+See [page-footer structure](references/page-footer.md) for the two/three-column markup and the full
+list of `juno-pagefooter-*` classes.
+
+### Structure the content area
+
+Inside `children`, the UX guidance orders the content area as: breadcrumb → page heading → toolbar →
+main content (`docs/ux/page-content-area.md`). Use `ContentHeading` for the page title and
+`ContentAreaToolbar` for page-level actions (it is right-aligned by default).
+
+```tsx
+import { Container, ContentHeading, ContentAreaToolbar, Button } from "@cloudoperators/juno-ui-components"
+
+declare function openCreate(): void
+
+function ListPage() {
+ return (
+ <Container py>
+ <ContentHeading>Instances</ContentHeading>
+ <ContentAreaToolbar>
+ <Button variant="primary" label="Create instance" onClick={openCreate} />
+ </ContentAreaToolbar>
+ {/* main content: a DataGrid, detail panel, etc. */}
+ </Container>
+ )
+}
+```
+
+`ContentAreaToolbar` holds page-context actions (create, view details). Do not confuse it with the
+`DataGridToolbar` that lives inside a grid for search/filter/bulk actions — see the datagrid skill.
+
+### Arrange blocks with Stack
+
+`Stack` is the go-to flexbox primitive for laying out a handful of elements in a row or column with
+a consistent `gap`. `direction` is `"horizontal"` (default) or `"vertical"`; `alignment` controls
+the cross axis, `distribution` the main axis. `gap` accepts a fixed set of Tailwind spacing tokens
+(e.g. `"2"`, `"4"`, `"8"`).
+
+```tsx
+import { Stack, Button } from "@cloudoperators/juno-ui-components"
+
+function FormActions() {
+ return (
+ <Stack direction="horizontal" gap="2" distribution="end" alignment="center">
+ <Button variant="subdued" label="Cancel" />
+ <Button variant="primary" label="Save" />
+ </Stack>
+ )
+}
+```
+
+### Lay out a responsive grid
+
+`Grid` is Juno's 12-column fluid grid. Put `GridRow`s inside it and `GridColumn`s inside those. A
+column spans `cols={n}` (1–12) of the twelve columns, or an exact `width={n}` percentage (which
+overrides `cols`). Pass `auto` on the `Grid` to make every column share space equally instead.
+
+```tsx
+import { Grid, GridRow, GridColumn } from "@cloudoperators/juno-ui-components"
+
+function TwoThirdsLayout() {
+ return (
+ <Grid>
+ <GridRow>
+ <GridColumn cols={8}>Main</GridColumn>
+ <GridColumn cols={4}>Sidebar</GridColumn>
+ </GridRow>
+ </Grid>
+ )
+}
+```
+
+Use `Grid` for a true multi-column page layout; use `Stack` for a single row/column of items. See
+[grid vs stack](references/grid-and-stack.md) for the `auto`, `width`, and nesting rules.
+
+### Set content apart with Box, IntroBox, and Divider
+
+- `Box` — a lightweight bordered container for annotations and supplementary notes. Optional `title`
+ and a semantic `variant` (`info` | `success` | `warning` | `error` | `danger`). It is **not** for
+ system feedback — use `Message` for operation results and errors (`docs/ux/box.md`).
+- `IntroBox` — a prominent block introducing the purpose or state of a page; `variant="hero"` for a
+ larger treatment, with an optional `heroImage` CSS background string.
+- `Divider` — a 1px horizontal separator with adjustable `spacing`.
+
+```tsx
+import { IntroBox, Box, Divider } from "@cloudoperators/juno-ui-components"
+
+function Intro() {
+ return (
+ <>
+ <IntroBox title="Welcome" text="Manage your cloud instances from here." />
+ <Box variant="warning" title="Maintenance">
+ A scheduled maintenance window starts at 22:00 UTC.
+ </Box>
+ <Divider spacing="4" />
+ </>
+ )
+}
+```
+
+For the Inline Action Box pattern (a `Box` with a `Divider` and right-aligned actions), see
+[box patterns](references/box-patterns.md).
+
+## Embedded mode (micro-frontends)
+
+When your app runs inside a host shell, pass `embedded` to `AppShell`. In embedded mode the host
+renders the chrome, so **the embedded app's own Page Header and Page Footer are not rendered** —
+only the content and the app's own navigations (`docs/ux/embedded-application-layout.md`). Content
+also defaults to full width in embedded mode.
+
+```tsx
+import { AppShell, TopNavigation, TopNavigationItem } from "@cloudoperators/juno-ui-components"
+
+function EmbeddedApp({ children }: { children: React.ReactNode }) {
+ return (
+ <AppShell
+ embedded
+ topNavigation={
+ <TopNavigation>
+ <TopNavigationItem icon="home" label="Home" />
+ <TopNavigationItem active label="Instances" />
+ </TopNavigation>
+ }
+ >
+ {children}
+ </AppShell>
+ )
+}
+```
+
+`fullWidthContent` controls the width constraint: it defaults to full width when `embedded`, and to
+constrained (centered at the 2xl breakpoint) otherwise. Pass it explicitly to override the default.
+
+## Manual layout without AppShell
+
+Only when you cannot use `AppShell` (e.g. a bespoke frame), assemble the primitives yourself:
+`AppBody` → `HeaderContainer` → `MainContainer` → `MainContainerInner` → `ContentContainer`. You are
+then responsible for wiring the slots `AppShell` would have wired. Read
+[manual layout primitives](references/manual-layout.md) before doing this — and remember the parent
+`AppShellProvider` is still mandatory.
+
+## Common mistakes
+
+- **CRITICAL — No `AppShellProvider` at the root.** Rendering `AppShell`, `DataGrid`, or any
+ component without an enclosing `AppShellProvider` means no theme, CSS variables, portals, or
+ shadow root, so styles do not apply and components may not work at all (`docs/ux/the-appshell.md`,
+ warning box). Wrap the app once at the top.
+- **CRITICAL — Hiding both logo and application name in the header.** This leaves users with no
+ orientation and is strongly discouraged. Keep at least the application name visible
+ (`docs/ux/page-header.md`, "Left side").
+- **HIGH — Hand-rolling the header/footer frame instead of using `AppShell`.** The manual primitives
+ exist, but skipping `AppShell` and forgetting a provider or container is the documented failure
+ mode (`docs/ux/page-layout-elements.md`, "Using AppShell"). Prefer `AppShell`.
+- **HIGH — Putting navigation or primary actions in the Page Footer.** The footer is for secondary,
+ site-wide links and legal info only, and must not change as users navigate
+ (`docs/ux/page-footer.md`, "What Goes in the Footer").
+- **HIGH — Rendering a Page Header/Footer in embedded mode.** The host already renders the chrome;
+ the embedded app must not duplicate it. Use `embedded` so `AppShell` drops them
+ (`docs/ux/embedded-application-layout.md`).
+- **MEDIUM — Using `Box` for system feedback.** Operation results, errors, and status changes belong
+ in `Message`, not `Box`; `Box` is for annotations and supplementary notes (`docs/ux/box.md`,
+ "When to Use Box").
+- **MEDIUM — Options in the header that change during navigation.** Right-side header options are
+ global and must stay stable across the app so users always find them (`docs/ux/page-header.md`,
+ "Right side").
+
+## Completion
+
+Verify:
+
+1. The app is wrapped once in `AppShellProvider`, and the page frame comes from `AppShell` (or, if
+ manual, every container plus the provider is present).
+2. In a standard (non-embedded) app the Page Header and Page Footer are both present; in embedded
+ mode neither is rendered.
+3. The header keeps the application name (and ideally logo) visible, and right-side options are
+ global and stable.
+4. The content area follows heading → toolbar → main content, with page-level actions in
+ `ContentAreaToolbar`.
+5. `Box` is used only for annotations (not system feedback); the footer holds only secondary links.
+6. Run `npm exec --no -- intent validate packages/ui-components/skills` and fix any errors.
+
+## References
+
+- [page-footer structure](references/page-footer.md) — read for the inline / two / three-column
+ markup and the full `juno-pagefooter-*` class list.
+- [grid vs stack](references/grid-and-stack.md) — read when choosing between `Grid` and `Stack` or
+ wiring `cols`/`width`/`auto` and nested rows.
+- [box patterns](references/box-patterns.md) — read before building an Inline Action Box or picking
+ a `Box` / `IntroBox` variant.
+- [manual layout primitives](references/manual-layout.md) — read only if you must assemble the frame
+ without `AppShell`.
diff --git a/packages/ui-components/skills/layout/references/box-patterns.md b/packages/ui-components/skills/layout/references/box-patterns.md
new file mode 100644
index 0000000000..8f1ddb4191
--- /dev/null
+++ b/packages/ui-components/skills/layout/references/box-patterns.md
@@ -0,0 +1,113 @@
+# Box patterns
+
+`Box`, `IntroBox`, and the Inline Action Box pattern set content apart from the surrounding layout.
+
+## Box
+
+A lightweight bordered container for annotations, supplementary explanations, and contextual
+remarks — not for system feedback (`docs/ux/box.md`, "When to Use Box"). For operation results,
+errors, and status changes use `Message` instead.
+
+Props:
+
+- `title?: string` — optional bold label above the content. Do not add one by default; most Boxes
+ are self-explanatory in context (`docs/ux/box.md`, "Title").
+- `variant?: "info" | "success" | "warning" | "error" | "danger"` — a semantic variant that adjusts
+ border and background color. Choose it by the **meaning** of the content, never for visual effect.
+ Omit it for a neutral Box.
+- `unpad?: boolean` — remove the default padding (`default false`).
+
+```tsx
+import { Box } from "@cloudoperators/juno-ui-components"
+
+function Notes() {
+ return (
+ <>
+ <Box>Instances are billed hourly.</Box>
+ <Box title="Note" variant="info">
+ Changes take a few minutes to propagate.
+ </Box>
+ </>
+ )
+}
+```
+
+## IntroBox
+
+A more prominent block that introduces the contents, purpose, or state of a page or view.
+
+Props:
+
+- `title?: string` and `text?: string` — the heading and body text. `children` take precedence over
+ `text`.
+- `variant?: "default" | "hero"` — `"hero"` renders a larger font and more padding.
+- `heroImage?: string` — a CSS background-image string for the hero variant (import svg images with
+ the `?url` query param, per `IntroBox.stories.tsx`).
+
+```tsx
+import { IntroBox } from "@cloudoperators/juno-ui-components"
+
+function PageIntro() {
+ return (
+ <IntroBox
+ variant="hero"
+ title="Welcome to the Console"
+ text="Manage instances, networks, and storage from one place."
+ />
+ )
+}
+```
+
+## Inline Action Box
+
+A pattern built on `Box` for a contextual notice that also offers one or two follow-up actions,
+without the focus-lock of a Modal (`docs/ux/box.md`, "Inline Action Box"). Compose it from a `Box`
+(with a matching semantic `variant`), a `Divider`, and a right-aligned `Stack` of actions.
+
+Rules from the UX doc:
+
+- Keep the content area brief — one or two sentences.
+- Prefer a single primary action; at most two buttons, the second a secondary/tertiary option.
+- Align actions to the right.
+- Do **not** use it for destructive actions that require confirmation — use a Modal.
+- Do not nest Inline Action Boxes.
+
+```tsx
+import { Box, Divider, Stack, Button } from "@cloudoperators/juno-ui-components"
+
+declare function dismiss(): void
+declare function openDocs(): void
+
+function QuotaNotice() {
+ return (
+ <Box variant="info" title="Approaching quota">
+ <p>You have used 85% of your instance quota.</p>
+ <Divider spacing="2" />
+ <Stack direction="horizontal" gap="2" distribution="end">
+ <Button variant="subdued" label="Dismiss" onClick={dismiss} />
+ <Button variant="primary" label="Learn more" onClick={openDocs} />
+ </Stack>
+ </Box>
+ )
+}
+```
+
+## Divider
+
+A 1px horizontal separator. `spacing` adjusts the vertical space around it (same Tailwind token set
+as `Stack`'s `gap`, default `"1"`); `color` overrides the line color with a Tailwind `border-color`
+class (e.g. `jn:border-juno-blue-3`).
+
+```tsx
+import { Divider } from "@cloudoperators/juno-ui-components"
+
+function Separated() {
+ return (
+ <>
+ <p>Section one</p>
+ <Divider spacing="6" />
+ <p>Section two</p>
+ </>
+ )
+}
+```
diff --git a/packages/ui-components/skills/layout/references/grid-and-stack.md b/packages/ui-components/skills/layout/references/grid-and-stack.md
new file mode 100644
index 0000000000..447ef0df63
--- /dev/null
+++ b/packages/ui-components/skills/layout/references/grid-and-stack.md
@@ -0,0 +1,92 @@
+# Grid vs Stack
+
+Both arrange children, but they solve different problems.
+
+- **`Stack`** — a flexbox row or column of a handful of items with a uniform `gap`. Reach for it
+ for toolbars, button groups, form field rows, and any single-axis arrangement.
+- **`Grid` / `GridRow` / `GridColumn`** — Juno's responsive **12-column fluid grid** for true page
+ layouts where columns span fractions of the width and wrap responsively.
+
+## Stack details
+
+`Stack` props (all optional):
+
+- `direction`: `"horizontal"` (default) | `"vertical"`.
+- `gap`: one of a fixed set of Tailwind spacing tokens — `"0"`, `"px"`, `"0.5"`, `"1"`, `"1.5"`,
+ `"2"` … up to `"96"`. Arbitrary values are not allowed; pick from the token list.
+- `alignment` (cross axis): `"start"` | `"end"` | `"center"` | `"baseline"` | `"stretch"` (default).
+- `distribution` (main axis): `"start"` (default) | `"end"` | `"center"` | `"between"` | `"around"`
+ | `"evenly"`.
+- `wrap`: `boolean` — allow children to wrap.
+
+```tsx
+import { Stack, Button } from "@cloudoperators/juno-ui-components"
+
+function Toolbar() {
+ return (
+ <Stack direction="horizontal" gap="2" distribution="between" alignment="center" wrap>
+ <span>5 items</span>
+ <Stack gap="2">
+ <Button variant="subdued" label="Refresh" />
+ <Button variant="primary" label="Create" />
+ </Stack>
+ </Stack>
+ )
+}
+```
+
+A vertical `Stack` swaps the axes: `alignment` then controls horizontal alignment and `distribution`
+the vertical distribution.
+
+## Grid details
+
+- `Grid` wraps `GridRow`s; each `GridRow` wraps `GridColumn`s.
+- `GridColumn` width:
+ - `cols={n}` — span `n` of 12 columns (valid 1–12; out-of-range falls back to the default width).
+ - `width={n}` — an exact percentage width. **`width` overrides `cols`.**
+ - `auto` — size to share remaining space equally.
+- `Grid auto` — makes every contained column auto-size equally, overriding the 12-column default;
+ columns with `cols={n}` switch to auto-sizing too (`Grid.stories.tsx`).
+
+```tsx
+import { Grid, GridRow, GridColumn } from "@cloudoperators/juno-ui-components"
+
+function PageLayout() {
+ return (
+ <Grid>
+ <GridRow>
+ <GridColumn cols={3}>Nav</GridColumn>
+ <GridColumn cols={9}>Content</GridColumn>
+ </GridRow>
+ <GridRow>
+ <GridColumn width={50}>Half</GridColumn>
+ <GridColumn width={50}>Half</GridColumn>
+ </GridRow>
+ </Grid>
+ )
+}
+```
+
+### Equal columns with `auto`
+
+```tsx
+import { Grid, GridRow, GridColumn } from "@cloudoperators/juno-ui-components"
+
+function EqualColumns() {
+ return (
+ <Grid auto>
+ <GridRow>
+ <GridColumn>A</GridColumn>
+ <GridColumn>B</GridColumn>
+ <GridColumn>C</GridColumn>
+ </GridRow>
+ </Grid>
+ )
+}
+```
+
+## Choosing
+
+- One row or one column of items, uniform gap → `Stack`.
+- A page split into proportional, responsive columns → `Grid`.
+- Do not nest a `Grid` just to place two buttons side by side — that is a `Stack`.
diff --git a/packages/ui-components/skills/layout/references/manual-layout.md b/packages/ui-components/skills/layout/references/manual-layout.md
new file mode 100644
index 0000000000..63e95452b6
--- /dev/null
+++ b/packages/ui-components/skills/layout/references/manual-layout.md
@@ -0,0 +1,82 @@
+# Manual layout primitives (without AppShell)
+
+> Use `AppShell` whenever you can. Assembling the frame by hand is "significantly more effort" and
+> the documented way to end up with an app that does not render correctly
+> (`docs/ux/page-layout-elements.md`, "Using AppShell"; `docs/ux/the-appshell.md` warning). This
+> page is for the rare case where you genuinely cannot use `AppShell`.
+
+Even in manual mode, the outermost `AppShellProvider` is still **mandatory** — it supplies theme,
+CSS variables, portals, and the shadow root. Only the frame changes.
+
+## The nesting order
+
+`AppShell` internally composes these primitives. If you replicate it by hand, use the same order:
+
+```
+AppBody // flex column, full height; the <div class="juno-body">
+ HeaderContainer // sticky top bar — holds PageHeader (+ TopNavigation)
+ MainContainer // <main>, grows to fill
+ MainContainerInner // width constraint (or fullWidth) wrapper
+ <SideNavigation/> // optional, left of content
+ ContentContainer // the content-area background wrapper
+ {your content}
+ PageFooter // sticky bottom footer
+```
+
+## What each primitive does
+
+- `AppBody` — top-level body container (`className` + standard HTML div attrs).
+- `HeaderContainer` — sticky, shadowed top container. `fullWidth?: boolean` (default `false`)
+ toggles between a constrained (centered at the 2xl breakpoint) and full-width header.
+- `MainContainer` — the `<main>` element that grows to fill remaining height.
+- `MainContainerInner` — inner wrapper; `fullWidth?: boolean` (default `false`) applies the same
+ width constraint vs. full-width choice as `HeaderContainer`.
+- `ContentContainer` — the content-area background/wrapper the page content sits in.
+
+All five take `className` and `children` only (plus standard HTML attributes); none of them render a
+header or footer for you — that is why `AppShell` is preferred.
+
+## Example
+
+```tsx
+import {
+ AppShellProvider,
+ AppBody,
+ HeaderContainer,
+ PageHeader,
+ MainContainer,
+ MainContainerInner,
+ ContentContainer,
+ PageFooter,
+ Container,
+ ContentHeading,
+} from "@cloudoperators/juno-ui-components"
+
+function ManualApp() {
+ return (
+ <AppShellProvider>
+ <AppBody>
+ <HeaderContainer>
+ <PageHeader applicationName="My App" href="/" />
+ </HeaderContainer>
+ <MainContainer>
+ <MainContainerInner>
+ <ContentContainer>
+ <Container py>
+ <ContentHeading>Dashboard</ContentHeading>
+ <p>Content goes here.</p>
+ </Container>
+ </ContentContainer>
+ </MainContainerInner>
+ </MainContainer>
+ <PageFooter copyright="© 2026 ACME" />
+ </AppBody>
+ </AppShellProvider>
+ )
+}
+```
+
+This reproduces, by hand, exactly what `<AppShell pageHeader="My App">…</AppShell>` would have given
+you. Keep the Page Header and Page Footer present (both are mandatory in a standard app per
+`docs/ux/layout-fundamentals.md`), and set `fullWidth` consistently on `HeaderContainer` and
+`MainContainerInner` so the header and content align.
diff --git a/packages/ui-components/skills/layout/references/page-footer.md b/packages/ui-components/skills/layout/references/page-footer.md
new file mode 100644
index 0000000000..8716dcc27b
--- /dev/null
+++ b/packages/ui-components/skills/layout/references/page-footer.md
@@ -0,0 +1,101 @@
+# Page Footer structure
+
+The `PageFooter` is a thin wrapper (`role="contentinfo"`). You structure its content with a set of
+`juno-pagefooter-*` CSS classes that the component ships. The `copyright` prop renders a copyright
+notice below the children; the children carry the links.
+
+Per `docs/ux/page-footer.md`, use **inline links** for a few items, or **columns** (two or three)
+for more structured content. Do not put primary navigation or actions here, and keep the content
+stable across navigation.
+
+## Available classes
+
+From `PageFooter.component.tsx` JSDoc:
+
+- `.juno-pagefooter-title` — a column title.
+- `.juno-pagefooter-items` — a list of items (column layout).
+- `.juno-pagefooter-items-inline` — a single-line list with pipe separators.
+- `.juno-pagefooter-item` — an individual link/item.
+
+## Inline links
+
+```tsx
+import { PageFooter } from "@cloudoperators/juno-ui-components"
+
+function Footer() {
+ return (
+ <PageFooter copyright="© 2026 ACME Corporation. All rights reserved.">
+ <ul className="juno-pagefooter-items-inline">
+ <li>
+ <a className="juno-pagefooter-item" href="/about">
+ About
+ </a>
+ </li>
+ <li>
+ <a className="juno-pagefooter-item" href="/imprint">
+ Imprint
+ </a>
+ </li>
+ <li>
+ <a className="juno-pagefooter-item" href="/terms">
+ Terms of Use
+ </a>
+ </li>
+ </ul>
+ </PageFooter>
+ )
+}
+```
+
+## Columns
+
+Group each column in a `<div role="group" aria-labelledby="...">` with a `.juno-pagefooter-title`
+and a `.juno-pagefooter-items` list. Use two or three columns.
+
+```tsx
+import { PageFooter } from "@cloudoperators/juno-ui-components"
+
+function Footer() {
+ return (
+ <PageFooter copyright="© 2026 ACME Corporation. All rights reserved.">
+ <div role="group" aria-labelledby="footer-col1-title">
+ <p className="juno-pagefooter-title" id="footer-col1-title">
+ Company
+ </p>
+ <ul className="juno-pagefooter-items">
+ <li>
+ <a className="juno-pagefooter-item" href="/about">
+ About
+ </a>
+ </li>
+ <li>
+ <a className="juno-pagefooter-item" href="/imprint">
+ Imprint
+ </a>
+ </li>
+ </ul>
+ </div>
+ <div role="group" aria-labelledby="footer-col2-title">
+ <p className="juno-pagefooter-title" id="footer-col2-title">
+ Legal
+ </p>
+ <ul className="juno-pagefooter-items">
+ <li>
+ <a className="juno-pagefooter-item" href="/privacy">
+ Privacy Policy
+ </a>
+ </li>
+ <li>
+ <a className="juno-pagefooter-item" href="/contact">
+ Contact
+ </a>
+ </li>
+ </ul>
+ </div>
+ </PageFooter>
+ )
+}
+```
+
+The `aria-labelledby` on each group, pointing at the title's `id`, keeps the columns accessible as
+labeled groups (as shown in `PageFooter.stories.tsx`).
diff --git a/packages/ui-components/skills/navigation/SKILL.md b/packages/ui-components/skills/navigation/SKILL.md
new file mode 100644
index 0000000000..290497afa7
--- /dev/null
+++ b/packages/ui-components/skills/navigation/SKILL.md
@@ -0,0 +1,319 @@
+---
+name: navigation
+description: >
+ Use when building navigation in a Juno app with @cloudoperators/juno-ui-components: the primary
+ left SideNavigation (flat items, groups, nested children up to three levels, active + controlled
+ expansion), a horizontal TopNavigation or TabBar as a second-level navigation above content,
+ a Breadcrumb trail back to list views, in-page tabbed content (deprecated Tabs/TabList/TabPanel
+ and MainTabs), and Pagination for paged lists. For the DataGrid that fills a list view, see the
+ datagrid skill; for the AppShell that frames the whole layout, see the fundamentals skill.
+metadata:
+ purpose: >
+ Teaches developers to pick the right Juno navigation primitive for each level of an app —
+ SideNavigation for top-level, TopNavigation/TabBar for second-level, Breadcrumb for the path
+ back, Tabs for in-page content, Pagination for paged lists — and to wire the active-item and
+ controlled-expansion state the components leave to the app, following the UX rules on depth,
+ icon placement, and the "navigation vs. filtering" distinction.
+ type: core
+ library: "@cloudoperators/juno-ui-components"
+ library_version: "9.6.0"
+sources:
+ - cloudoperators/juno:packages/ui-components/src/components/SideNavigation/SideNavigation.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/SideNavigation/SideNavigation.stories.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/SideNavigationGroup/SideNavigationGroup.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/SideNavigationItem/SideNavigationItem.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/SideNavigationList/SideNavigationList.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/TopNavigation/TopNavigation.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/TopNavigationItem/TopNavigationItem.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/Navigation/Navigation.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/NavigationItem/NavigationItem.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/Breadcrumb/Breadcrumb.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/BreadcrumbItem/BreadcrumbItem.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/TabBar/TabBar.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/TabBarItem/TabBarItem.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/Tabs/Tabs.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/Pagination/Pagination.component.tsx
+ - cloudoperators/juno:docs/ux/navigation-fundamentals.md
+ - cloudoperators/juno:docs/ux/navigation-side-navigation.md
+ - cloudoperators/juno:docs/ux/navigation.md
+ - cloudoperators/juno:docs/ux/page-and-user-flow.md
+---
+
+# Build navigation in a Juno app
+
+Juno layers navigation by scope. The **SideNavigation** is the primary top-level navigation — a
+fixed left column present in every view (`docs/ux/navigation-side-navigation.md`, "When to Use the
+Side Navigation"). When a second level will not fit as nested items, a horizontal **TopNavigation**
+or **TabBar** sits above the content as a child of the active top-level entry. A **Breadcrumb**
+gives the user the path back from a detail view to its list. **Tabs** switch content _inside_ a
+single view, and **Pagination** steps through a paged list.
+
+Pick the component by what the user is doing, not by how it looks:
+
+- Moving between app sections/views → `SideNavigation` (top level), `TopNavigation`/`TabBar` (second level).
+- Returning up the hierarchy from a detail page → `Breadcrumb`.
+- Swapping content panels within one view → `Tabs`/`MainTabs` (deprecated — see note below) or a `TabBar` wired to your own router.
+- Filtering the same entity set → **not** navigation; use a DataGrid toolbar (see the datagrid skill).
+
+## Setup: the SideNavigation
+
+A `SideNavigation` wraps a single `SideNavigationList`, which contains `SideNavigationItem`s and
+optional `SideNavigationGroup`s. An item becomes a link when given `href`, or a button when given
+`onClick`. Mark the current view with `selected`.
+
+```tsx
+import { SideNavigation, SideNavigationList, SideNavigationItem } from "@cloudoperators/juno-ui-components"
+
+function AppNav({ path }: { path: string }) {
+ return (
+ <SideNavigation ariaLabel="Main">
+ <SideNavigationList>
+ <SideNavigationItem icon="home" label="Home" href="/" selected={path === "/"} />
+ <SideNavigationItem icon="dns" label="Servers" href="/servers" selected={path === "/servers"} />
+ <SideNavigationItem icon="place" label="Networks" href="/networks" selected={path === "/networks"} />
+ </SideNavigationList>
+ </SideNavigation>
+ )
+}
+```
+
+Prefer a flat list unless the content genuinely needs hierarchy. `icon` (a Juno `KnownIcons` name)
+is honored **only at the first level** — nested children never render an icon
+(`docs/ux/navigation-side-navigation.md`, "Item Labels and Icons").
+
+## Core patterns
+
+### Group related top-level items
+
+A `SideNavigationGroup` renders a non-navigable section header that expands/collapses its children.
+Use it to organize a large top-level set — never a single group wrapping everything.
+
+```tsx
+import {
+ SideNavigation,
+ SideNavigationList,
+ SideNavigationGroup,
+ SideNavigationItem,
+} from "@cloudoperators/juno-ui-components"
+
+function GroupedNav() {
+ return (
+ <SideNavigation ariaLabel="Main">
+ <SideNavigationList>
+ <SideNavigationGroup label="Compute" open>
+ <SideNavigationItem label="Servers" href="/servers" />
+ <SideNavigationItem label="Images" href="/images" />
+ </SideNavigationGroup>
+ <SideNavigationGroup label="Network">
+ <SideNavigationItem label="Networks" href="/networks" />
+ <SideNavigationItem label="Subnets" href="/subnets" />
+ </SideNavigationGroup>
+ </SideNavigationList>
+ </SideNavigation>
+ )
+}
+```
+
+### Nest items up to three levels
+
+A `SideNavigationItem` with `SideNavigationItem` children renders an expand chevron. The chevron is
+a **separate control** from the item's navigation action — clicking the label navigates, clicking
+the chevron toggles the sub-list. Do not exceed three levels
+(`docs/ux/navigation-side-navigation.md`, "Structure and Depth").
+
+```tsx
+import { SideNavigationItem } from "@cloudoperators/juno-ui-components"
+
+function Nested() {
+ return (
+ <SideNavigationItem label="Messages">
+ <SideNavigationItem label="Inbox" href="/inbox" />
+ <SideNavigationItem label="Sent Items" href="/sent" />
+ </SideNavigationItem>
+ )
+}
+```
+
+### Expand the group containing the active route (controlled)
+
+`open` on a group/item is both the initial value _and_ a controlled value — the component re-syncs
+to it whenever the parent updates. `onToggle` receives the next open state. On page load, open the
+branch holding the active route so the active child stays visible
+(`docs/ux/navigation-side-navigation.md`, "Active and Disabled States", "Controlled vs. Uncontrolled
+Expansion").
+
+```tsx
+import { useState } from "react"
+import { SideNavigationGroup, SideNavigationItem } from "@cloudoperators/juno-ui-components"
+
+function ControlledGroup({ path }: { path: string }) {
+ const [open, setOpen] = useState(path.startsWith("/compute"))
+ return (
+ <SideNavigationGroup label="Compute" open={open} onToggle={setOpen}>
+ <SideNavigationItem label="Servers" href="/compute/servers" selected={path === "/compute/servers"} />
+ <SideNavigationItem label="Images" href="/compute/images" selected={path === "/compute/images"} />
+ </SideNavigationGroup>
+ )
+}
+```
+
+### Add a second-level navigation above the content
+
+When a second level will not fit as nested side-nav items, place a horizontal bar above the content
+that visibly belongs to the active top-level entry (`docs/ux/navigation-fundamentals.md`,
+"Alternative Second-Level Navigations"; `docs/ux/navigation-side-navigation.md`, "Alternative
+Second-Level Navigation"). Two components do this; both track the active item by `value` (falling
+back to `label` or the child string) via `activeItem` on the parent.
+
+`TabBar` is the current, non-deprecated choice. Use `appearance="main"` for the first bar in an
+AppShell, `appearance="content"` for a bar inside page content.
+
+```tsx
+import { useState } from "react"
+import { TabBar, TabBarItem } from "@cloudoperators/juno-ui-components"
+
+declare function navigate(to: string): void
+
+function ServerTabs() {
+ const [active, setActive] = useState("overview")
+ return (
+ <TabBar
+ appearance="content"
+ activeItem={active}
+ onActiveItemChange={(item) => {
+ setActive(String(item))
+ navigate(`/servers/${item}`)
+ }}
+ >
+ <TabBarItem label="Overview" value="overview" />
+ <TabBarItem label="Metrics" value="metrics" />
+ <TabBarItem label="Logs" value="logs" />
+ </TabBar>
+ )
+}
+```
+
+`TopNavigation`/`TopNavigationItem` is the equivalent horizontal bar with the same `activeItem` /
+`value` / `onActiveItemChange` model and an optional `icon` per item. Read
+[second-level bars: TopNavigation vs TabBar](references/second-level-bars.md) to choose between them
+and to see the active-item resolution rules (value → children → label).
+
+### Give the user a path back with a Breadcrumb
+
+Every detail page must let the user return to its list view — provide a breadcrumb reflecting the
+navigational path (and a back button), not just the browser back button
+(`docs/ux/page-and-user-flow.md`, "Detail Views"). `Breadcrumb` auto-inserts chevron separators
+between its `BreadcrumbItem` children. An item is a link with `href`, a button with `onClick`, and a
+non-interactive current-page marker with `active`.
+
+```tsx
+import { Breadcrumb, BreadcrumbItem } from "@cloudoperators/juno-ui-components"
+
+function ServerCrumb({ id }: { id: string }) {
+ return (
+ <Breadcrumb>
+ <BreadcrumbItem icon="home" label="Home" href="/" />
+ <BreadcrumbItem label="Servers" href="/servers" />
+ <BreadcrumbItem label={id} active />
+ </Breadcrumb>
+ )
+}
+```
+
+Mark exactly the last (current) item `active`; it renders as a `<span aria-current="page">`, not a
+link.
+
+### Page through a list with Pagination
+
+`Pagination` renders previous/next buttons plus an optional page indicator chosen by `variant`:
+`"default"` (buttons only), `"number"` (shows the current page), `"select"` (a page dropdown), or
+`"input"` (a page entry field). It is controlled — pass `currentPage` and `totalPages`, and update
+them from the callbacks (`onPressPrevious`, `onPressNext`, `onSelectChange`, `onInputChange`).
+
+```tsx
+import { useState } from "react"
+import { Pagination } from "@cloudoperators/juno-ui-components"
+
+function PagedList({ totalPages }: { totalPages: number }) {
+ const [page, setPage] = useState(1)
+ return (
+ <Pagination
+ variant="select"
+ currentPage={page}
+ totalPages={totalPages}
+ onPressPrevious={() => setPage((p) => Math.max(1, p - 1))}
+ onPressNext={() => setPage((p) => Math.min(totalPages, p + 1))}
+ onSelectChange={(selected) => setPage(selected)}
+ />
+ )
+}
+```
+
+The buttons disable themselves at the bounds (page 1 / last page) and whenever `disabled` or
+`progress` is set; `progress` also swaps the indicator for a spinner. Read
+[Pagination variants and callbacks](references/pagination.md) for the per-variant callback wiring
+(the `input` variant's `onKeyPress`/`onBlur`, the legacy `pages` alias).
+
+## In-page tabbed content (Tabs is deprecated)
+
+The `Tabs` / `TabList` / `Tab` / `TabPanel` set and `MainTabs` are **deprecated** and may be removed
+in a future major release (see each component's `@deprecated` JSDoc). They wrap `react-tabs`. For
+new work, use `react-tabs` directly, or a `TabBar` wired to your router/state for the tab headers.
+If you must maintain existing `Tabs` code, read
+[legacy Tabs/TabList/TabPanel/MainTabs](references/legacy-tabs.md) for the controlled
+`selectedIndex`/`onSelect` pattern and the index-correspondence rule.
+
+## Common mistakes
+
+- **CRITICAL — Using the SideNavigation for filtering or in-page sections.** The side nav is for
+ distinct app views only; do not drive secondary filtering or content organization within one view
+ from it. Filter the same entity set in a DataGrid toolbar; switch content panels with Tabs/TabBar.
+ (`docs/ux/navigation-side-navigation.md`, "When to Use the Side Navigation".)
+- **CRITICAL — No way back from a detail page.** Shipping a detail view without a breadcrumb (and
+ back button) strands users who did not arrive via an in-app link. Always render a `Breadcrumb`
+ reflecting the path. (`docs/ux/page-and-user-flow.md`, "Detail Views".)
+- **HIGH — More than three navigation levels.** Deeper hierarchies are unscannable and signal an
+ information-architecture problem. Keep the side nav at three levels max; prefer flat.
+ (`docs/ux/navigation-side-navigation.md`, "Structure and Depth".)
+- **HIGH — `activeItem` not matching any item's identifier.** `TabBar`/`TopNavigation` resolve the
+ active item by `value`, then child string, then `label`. If you set `activeItem` to a value no
+ item carries, nothing is highlighted. Use each item's `value` (or its exact `label`). (TabBar/
+ TopNavigation source; `docs/ux/navigation-side-navigation.md`, "Active and Disabled States".)
+- **HIGH — Collapsing the branch that holds the active route.** When a parent/group contains the
+ active child, keep it expanded (control `open`) so the current location stays visible.
+ (`docs/ux/navigation-side-navigation.md`, "Active and Disabled States".)
+- **MEDIUM — Icons on nested items or icons without labels.** Icons render only at the first side-nav
+ level and must never replace the text label. (`docs/ux/navigation-side-navigation.md`, "Item Labels
+ and Icons".)
+- **MEDIUM — More than one item marked active, or none.** Exactly one item represents the user's
+ current location. (`docs/ux/navigation-side-navigation.md`, "Anatomy", "Active and Disabled
+ States".)
+- **MEDIUM — Reaching for deprecated `Tabs`/`MainTabs` in new code.** They are slated for removal; use
+ `react-tabs` directly or a `TabBar`. (Tabs/MainTabs `@deprecated` JSDoc.)
+- **MEDIUM — Missing `ariaLabel` with multiple nav landmarks.** `SideNavigation`/`TopNavigation`/
+ `TabBar` render a `role="navigation"` landmark; when a view has more than one, give each a distinct
+ `ariaLabel`. (`docs/ux/navigation-side-navigation.md`, "Accessibility".)
+
+## Completion
+
+Verify:
+
+1. Exactly one `SideNavigationItem` is `selected`, matching the current route.
+2. If groups/nested items exist, the branch containing the active route is expanded on load.
+3. Any `TabBar`/`TopNavigation` `activeItem` equals a real item `value`/`label`, so one tab is highlighted.
+4. Every detail view renders a `Breadcrumb` whose last item is `active` and whose earlier items link back.
+5. `Pagination` is controlled (`currentPage`/`totalPages` wired to callbacks) and new code avoids deprecated `Tabs`/`MainTabs`.
+6. Each `role="navigation"` landmark on a view has a distinct `ariaLabel` when more than one is present.
+7. Run `npm exec --no -- intent validate packages/ui-components/skills` and fix any errors.
+
+If a navigation state (active route, controlled expansion) cannot be exercised in your harness,
+report it as unverified rather than assuming it renders.
+
+## References
+
+- [second-level bars: TopNavigation vs TabBar](references/second-level-bars.md) — read when choosing a
+ horizontal second-level bar and wiring its active item.
+- [Pagination variants and callbacks](references/pagination.md) — read when wiring a specific
+ Pagination variant or the backward-compatible `pages` prop.
+- [legacy Tabs/TabList/TabPanel/MainTabs](references/legacy-tabs.md) — read only when maintaining
+ existing deprecated Tabs code.
diff --git a/packages/ui-components/skills/navigation/references/legacy-tabs.md b/packages/ui-components/skills/navigation/references/legacy-tabs.md
new file mode 100644
index 0000000000..81e0bf5b20
--- /dev/null
+++ b/packages/ui-components/skills/navigation/references/legacy-tabs.md
@@ -0,0 +1,77 @@
+# Legacy Tabs / TabList / TabPanel / MainTabs (deprecated)
+
+Read this only when maintaining existing code that uses `Tabs`, `TabList`, `Tab`, `TabPanel`, or
+`MainTabs`. **All of these are deprecated** and may be removed in a future major release — see the
+`@deprecated` JSDoc on each component. For new in-page tabbed content, use `react-tabs` directly, or
+a `TabBar` wired to your own router/state for the headers. Sources: `Tabs.component.tsx`,
+`Tab.component.tsx`, `TabList.component.tsx`, `TabPanel.component.tsx`, `MainTabs.component.tsx`.
+
+## Structure
+
+A `Tabs` wraps exactly one `TabList` (holding the `Tab` headers) followed by one `TabPanel` per tab,
+in the same order. The Nth `Tab` corresponds to the Nth `TabPanel` by position — there is no id
+linking them, so the counts and order must match.
+
+```tsx
+import { Tabs, TabList, Tab, TabPanel } from "@cloudoperators/juno-ui-components"
+
+function Deprecated() {
+ return (
+ <Tabs>
+ <TabList>
+ <Tab>Overview</Tab>
+ <Tab icon="warning">Alerts</Tab>
+ </TabList>
+ <TabPanel>Overview content</TabPanel>
+ <TabPanel>Alerts content</TabPanel>
+ </Tabs>
+ )
+}
+```
+
+## Variant
+
+`Tabs` takes `variant`: `"content"` (default, tabs inside a content area), `"main"` (main-level tab
+styling), or `"codeblocks"`. `MainTabs` is simply `Tabs` with `variant="main"` preset — it exposes
+`children`, `defaultIndex`, `selectedIndex`, `onSelect`, and `className`, and is likewise deprecated.
+
+## Uncontrolled vs. controlled
+
+- **Uncontrolled (default):** pass `defaultIndex` for the initially selected tab and let `Tabs`
+ manage selection internally. Do not also pass `selectedIndex`.
+- **Controlled:** pass `selectedIndex` _and_ `onSelect`. `onSelect` receives the newly selected index
+ as a `number`; store it and feed it back as `selectedIndex`.
+
+```tsx
+import { useState } from "react"
+import { Tabs, TabList, Tab, TabPanel } from "@cloudoperators/juno-ui-components"
+
+function Controlled() {
+ const [index, setIndex] = useState(0)
+ return (
+ <Tabs selectedIndex={index} onSelect={(i) => setIndex(i)}>
+ <TabList>
+ <Tab>One</Tab>
+ <Tab>Two</Tab>
+ </TabList>
+ <TabPanel>First panel</TabPanel>
+ <TabPanel>Second panel</TabPanel>
+ </Tabs>
+ )
+}
+```
+
+## Tab props
+
+A `Tab` renders its `children`, or its `label` string if no children are given, plus an optional
+`icon` (a Juno `KnownIcons` name). `disabled` greys it out and makes it non-selectable. A `TabList`
+also accepts its own `variant`, but inside a `Tabs` the parent's variant (via context) takes
+precedence.
+
+## Migration note
+
+Because these wrap `react-tabs`, the cleanest migration is to use `react-tabs` directly (same
+`Tabs`/`TabList`/`Tab`/`TabPanel` roles) and style it yourself, or — when you only need tab-shaped
+navigation headers that run handlers or hrefs rather than toggling local panels — switch to
+`TabBar` + `TabBarItem` (see the second-level-bars reference) and render the panel content yourself
+based on the active item.
diff --git a/packages/ui-components/skills/navigation/references/pagination.md b/packages/ui-components/skills/navigation/references/pagination.md
new file mode 100644
index 0000000000..6bcba5c48b
--- /dev/null
+++ b/packages/ui-components/skills/navigation/references/pagination.md
@@ -0,0 +1,113 @@
+# Pagination variants and callbacks
+
+Read this when wiring a specific `Pagination` variant or dealing with its backward-compatible
+`pages` prop. Source: `Pagination.component.tsx`;
+`docs/ux/page-and-user-flow.md` ("List Views") for where paged lists appear.
+
+`Pagination` is a controlled component. You own `currentPage` and `totalPages` and update them from
+the callbacks. It always renders a previous and a next `Button`; what sits between them depends on
+`variant`.
+
+## Common props
+
+- `currentPage?: number` — the active page.
+- `totalPages?: number` — total page count. (`pages?: number` is a backward-compatible alias; if
+ both are set, `pages` wins. Prefer `totalPages` in new code.)
+- `disabled?: boolean` — disables the whole control.
+- `progress?: boolean` — shows a spinner in place of the indicator and disables the buttons.
+- `isFirstPage?` / `isLastPage?: boolean` — force the previous/next button disabled regardless of
+ `currentPage`.
+
+The previous button auto-disables when `currentPage === 1`; the next button auto-disables when
+`currentPage === totalPages`. `disabled` and `progress` disable both.
+
+## variant="default" — buttons only
+
+```tsx
+import { useState } from "react"
+import { Pagination } from "@cloudoperators/juno-ui-components"
+
+function Pager({ totalPages }: { totalPages: number }) {
+ const [page, setPage] = useState(1)
+ return (
+ <Pagination
+ currentPage={page}
+ totalPages={totalPages}
+ onPressPrevious={() => setPage((p) => Math.max(1, p - 1))}
+ onPressNext={() => setPage((p) => Math.min(totalPages, p + 1))}
+ />
+ )
+}
+```
+
+`onPressPrevious`/`onPressNext` also receive the computed next page as their argument
+(`(newPage?: number) => void`), so you can use that instead of recomputing.
+
+## variant="number" — shows the current page
+
+Same callbacks as `default`; the current page number renders between the buttons. No extra wiring.
+
+## variant="select" — page dropdown
+
+Renders a `Select` listing every page `1..totalPages`. Handle `onSelectChange`, which receives the
+chosen page as a `number`.
+
+```tsx
+import { useState } from "react"
+import { Pagination } from "@cloudoperators/juno-ui-components"
+
+function SelectPager({ totalPages }: { totalPages: number }) {
+ const [page, setPage] = useState(1)
+ return (
+ <Pagination
+ variant="select"
+ currentPage={page}
+ totalPages={totalPages}
+ onPressPrevious={() => setPage((p) => Math.max(1, p - 1))}
+ onPressNext={() => setPage((p) => Math.min(totalPages, p + 1))}
+ onSelectChange={(selected) => setPage(selected)}
+ />
+ )
+}
+```
+
+## variant="input" — manual page entry
+
+Renders a `TextInput` plus an "of N" label. The component clamps the entered value to
+`1..totalPages` internally. Three callbacks apply:
+
+- `onInputChange?: (inputValue?: number) => void` — fires on every keystroke (already clamped).
+- `onKeyPress?: (controlCurrentPage?: number) => void` — fires on Enter, with the current value.
+- `onBlur?: (controlCurrentPage?: number) => void` — fires when the field loses focus.
+
+Commit the page on Enter or blur rather than on every keystroke:
+
+```tsx
+import { useState } from "react"
+import { Pagination } from "@cloudoperators/juno-ui-components"
+
+function InputPager({ totalPages }: { totalPages: number }) {
+ const [page, setPage] = useState(1)
+ const [draft, setDraft] = useState<number | undefined>(1)
+ const commit = (value?: number) => {
+ if (value !== undefined) setPage(value)
+ }
+ return (
+ <Pagination
+ variant="input"
+ currentPage={page}
+ totalPages={totalPages}
+ onInputChange={(value) => setDraft(value)}
+ onKeyPress={() => commit(draft)}
+ onBlur={() => commit(draft)}
+ onPressPrevious={() => setPage((p) => Math.max(1, p - 1))}
+ onPressNext={() => setPage((p) => Math.min(totalPages, p + 1))}
+ />
+ )
+}
+```
+
+## Loading state
+
+While a page is being fetched, set `progress`. The indicator is replaced by a spinner and both
+buttons are disabled, preventing rapid double-steps during the request.
diff --git a/packages/ui-components/skills/navigation/references/second-level-bars.md b/packages/ui-components/skills/navigation/references/second-level-bars.md
new file mode 100644
index 0000000000..76ce695abd
--- /dev/null
+++ b/packages/ui-components/skills/navigation/references/second-level-bars.md
@@ -0,0 +1,106 @@
+# Second-level bars: TopNavigation vs TabBar
+
+Read this when you need a horizontal navigation bar above the content as a second-level navigation,
+and have to choose between `TopNavigation` and `TabBar` and wire the active item correctly. Both
+wrap the internal `Navigation` component and share its active-item model. Sources:
+`TopNavigation.component.tsx`, `TopNavigationItem.component.tsx`, `TabBar.component.tsx`,
+`TabBarItem.component.tsx`, `Navigation.component.tsx`;
+`docs/ux/navigation-fundamentals.md` ("Alternative Second-Level Navigations"),
+`docs/ux/navigation-side-navigation.md` ("Alternative Second-Level Navigation").
+
+## When to use a second-level bar at all
+
+Only when a second navigation level will not fit as nested `SideNavigationItem` children — for
+example, the second level has many entries or needs a distinct visual treatment. The bar must
+visually read as a child of the currently selected top-level side-nav entry.
+
+## Which component
+
+- `TabBar` + `TabBarItem` — the current, non-deprecated choice. Prefer this for new work. It takes an
+ `appearance` prop: `"main"` for the first bar in an AppShell, `"content"` for a bar inside page
+ content (which adds a darkened bottom border on inactive tabs). Defaults to `"main"`.
+- `TopNavigation` + `TopNavigationItem` — a horizontal top-level bar placed below the app header but
+ above content. Same active-item model; items also accept an `icon`.
+
+Both are thin wrappers over `Navigation`, so they expose the same props: `activeItem`,
+`onActiveItemChange`, `disabled`, `ariaLabel`, and children items with `label`, `value`, `href`,
+`onClick`, `disabled`, `icon`.
+
+## How the active item resolves
+
+`activeItem` on the parent is matched against each child in this priority order (from
+`Navigation.component.tsx`, `findItemIdByKeyValue` + `NavigationItem` `theKey = value || children || label`):
+
+1. `value` prop of the item, if present
+2. the item's child string
+3. the item's `label`
+
+So if an item has a `value`, you **must** set `activeItem` to that `value` — not its label. If an
+item has no `value`, use its exact label (or child string). An `activeItem` matching nothing leaves
+every item unhighlighted. The `activeItem` on the parent overrides any `active` prop on an
+individual child.
+
+## Controlled example (TabBar)
+
+```tsx
+import { useState } from "react"
+import { TabBar, TabBarItem } from "@cloudoperators/juno-ui-components"
+
+declare function navigate(to: string): void
+
+type View = "overview" | "metrics" | "logs"
+
+function ServerDetailTabs({ initial }: { initial: View }) {
+ const [active, setActive] = useState<View>(initial)
+ return (
+ <TabBar
+ appearance="content"
+ ariaLabel="Server detail sections"
+ activeItem={active}
+ onActiveItemChange={(item) => {
+ const next = String(item) as View
+ setActive(next)
+ navigate(`/servers/${next}`)
+ }}
+ >
+ <TabBarItem label="Overview" value="overview" />
+ <TabBarItem label="Metrics" value="metrics" />
+ <TabBarItem label="Logs" value="logs" />
+ </TabBar>
+ )
+}
+```
+
+## Controlled example (TopNavigation)
+
+```tsx
+import { useState } from "react"
+import { TopNavigation, TopNavigationItem } from "@cloudoperators/juno-ui-components"
+
+function AppSections() {
+ const [active, setActive] = useState("servers")
+ return (
+ <TopNavigation ariaLabel="Sections" activeItem={active} onActiveItemChange={(item) => setActive(String(item))}>
+ <TopNavigationItem label="Servers" value="servers" icon="dns" />
+ <TopNavigationItem label="Networks" value="networks" icon="place" />
+ <TopNavigationItem label="Images" value="images" icon="autoAwesomeMotion" />
+ </TopNavigation>
+ )
+}
+```
+
+## Disabling
+
+Set `disabled` on the parent (`TabBar`/`TopNavigation`) to disable every child at once, or on an
+individual item to disable just that one. A disabled item does not fire `onActiveItemChange`.
+
+## Links vs. handlers
+
+Give an item `href` to render it as an `<a>` (hard navigation), or `onClick` to render it as a
+`<button>` and run your own router. Either way, keep `activeItem` in sync so the correct tab shows
+as active after navigation.
+
+## Accessibility
+
+Both render a `role="navigation"` landmark. When a view has more than one navigation landmark (e.g.
+the side nav plus a second-level bar), give each a distinct `ariaLabel`.
diff --git a/packages/ui-components/skills/overlays/SKILL.md b/packages/ui-components/skills/overlays/SKILL.md
new file mode 100644
index 0000000000..03e4f67371
--- /dev/null
+++ b/packages/ui-components/skills/overlays/SKILL.md
@@ -0,0 +1,312 @@
+---
+name: overlays
+description: >
+ Use when building overlay UI in a Juno app with @cloudoperators/juno-ui-components: Modal dialogs
+ with built-in or custom ModalFooter actions and destructive-action confirmation (checkbox / typed
+ phrase), slide-in Panels with PanelBody and PanelFooter, Tooltips (TooltipTrigger + TooltipContent,
+ hover vs. click, semantic variants), and PopupMenu overflow menus with sections and dividers. Also
+ covers the PortalProvider these overlays render into. For the Button variants used in footers see
+ the forms/actions material; for Status-based empty states inside tables see the datagrid skill.
+metadata:
+ purpose: >
+ Teaches developers to build Juno overlays — Modal/ModalFooter, Panel/PanelBody/PanelFooter,
+ Tooltip/TooltipTrigger/TooltipContent, and PopupMenu — so they are triggered by user action,
+ render into the PortalProvider, confirm destructive actions at the correct severity, and order
+ menu items by the UX rules the components do not enforce on their own.
+ type: core
+ library: "@cloudoperators/juno-ui-components"
+ library_version: "9.6.0"
+sources:
+ - cloudoperators/juno:packages/ui-components/src/components/Modal/Modal.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/Modal/Modal.stories.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/ModalFooter/ModalFooter.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/Panel/Panel.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/Panel/Panel.stories.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/PanelBody/PanelBody.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/PanelFooter/PanelFooter.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/Tooltip/Tooltip.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/Tooltip/Tooltip.stories.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/TooltipTrigger/TooltipTrigger.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/TooltipContent/TooltipContent.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/PopupMenu/PopupMenu.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/PopupMenu/PopupMenu.stories.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/PortalProvider/PortalProvider.component.tsx
+ - cloudoperators/juno:docs/ux/modals.md
+ - cloudoperators/juno:docs/ux/popup-and-overflow-menus.md
+ - cloudoperators/juno:docs/ux/interaction-guidelines.md
+---
+
+# Build overlays with Juno: Modal, Panel, Tooltip, PopupMenu
+
+All four overlays render through a portal, so the app must be wrapped in `PortalProvider` (included
+automatically by `AppShellProvider` — see the fundamentals material). `Modal` and `Panel` call
+`usePortalRef()` and fall back to `document.body` if no provider is found, logging a console warning;
+`PopupMenu` renders into `PortalProvider.Portal` and will not position correctly without it.
+
+Every overlay must be opened by a prior user action — a button click, a menu choice, a hover. Never
+auto-open a Modal on page load (`docs/ux/modals.md`, "No Modals Without Previous Interaction";
+`docs/ux/interaction-guidelines.md`, "Clarity and Predictability").
+
+## Setup
+
+`Modal` is controlled by `open`; you own the state and the handlers. The built-in footer renders a
+Cancel + Confirm pair as soon as you pass `confirmButtonLabel` or `onConfirm`. Note the component
+does **not** close itself on confirm — `onConfirm` fires and you decide when to flip `open`.
+
+```tsx
+import { useState } from "react"
+import { Modal, Button } from "@cloudoperators/juno-ui-components"
+
+function AssignRoleButton() {
+ const [open, setOpen] = useState(false)
+ return (
+ <>
+ <Button label="Assign Role" variant="primary" onClick={() => setOpen(true)} />
+ <Modal
+ title="Assign Role"
+ open={open}
+ confirmButtonLabel="Assign Role"
+ cancelButtonLabel="Cancel"
+ onConfirm={() => setOpen(false)}
+ onCancel={() => setOpen(false)}
+ >
+ Assign the role Operator to user@example.com? This grants access to all project resources.
+ </Modal>
+ </>
+ )
+}
+```
+
+State the action in the `title` and reference the affected object by name in the body — object names
+are often long and get truncated in a title (`docs/ux/modals.md`, "Modal Content and Title").
+
+## Core patterns
+
+### Confirm a destructive action at the right severity
+
+For destructive actions, set `confirmButtonVariant="primary-danger"` (red) and name the item in the
+body. The UX doc defines a severity ladder — the component does not enforce it, you wire it with
+`disableConfirmButton` (`docs/ux/modals.md`, "Destructive Actions"):
+
+- **Low** — confirm button always enabled.
+- **Mid** — a `Checkbox` gates the confirm button.
+- **High** — the user must type a matching phrase.
+
+```tsx
+import { useState } from "react"
+import { Modal, TextInput } from "@cloudoperators/juno-ui-components"
+
+function DeleteProjectModal({ open, onClose }: { open: boolean; onClose: () => void }) {
+ const [phrase, setPhrase] = useState("")
+ return (
+ <Modal
+ title="Delete Project"
+ open={open}
+ confirmButtonLabel="Delete Project"
+ confirmButtonVariant="primary-danger"
+ disableConfirmButton={phrase !== "DELETE"}
+ onConfirm={onClose}
+ onCancel={() => {
+ setPhrase("")
+ onClose()
+ }}
+ >
+ <p>Project 'production-eu' and all its resources will be permanently deleted.</p>
+ <p>Type DELETE to confirm:</p>
+ <TextInput value={phrase} onChange={(e) => setPhrase(e.target.value)} />
+ </Modal>
+ )
+}
+```
+
+Do **not** add a danger `Message` to a destructive Modal body — the red confirm button already
+carries the semantics, and mixed semantic colors confuse users (`docs/ux/modals.md`, "Messages in
+Modals"). For the full severity table and the acknowledgement-only ("Close"-button) pattern, read
+[modal patterns](references/modal-patterns.md).
+
+### Replace the footer with a custom ModalFooter
+
+When one Confirm + Cancel pair is not enough, pass a `modalFooter` element. `ModalFooter` with
+children renders them verbatim (no default buttons), so you lay out the buttons and keep the
+rightmost one `primary` as the single primary action (`docs/ux/modals.md`, "One Primary Action"):
+
+```tsx
+import { Modal, ModalFooter, ButtonRow, Button } from "@cloudoperators/juno-ui-components"
+
+function CustomFooterModal({ open, onClose }: { open: boolean; onClose: () => void }) {
+ return (
+ <Modal
+ title="Review Changes"
+ size="large"
+ open={open}
+ onCancel={onClose}
+ modalFooter={
+ <ModalFooter>
+ <ButtonRow>
+ <Button variant="subdued" label="Cancel" onClick={onClose} />
+ <Button variant="primary-danger" label="Discard" onClick={onClose} />
+ <Button variant="primary" label="Save" onClick={onClose} />
+ </ButtonRow>
+ </ModalFooter>
+ }
+ >
+ Review and choose how to proceed.
+ </Modal>
+ )
+}
+```
+
+With a custom footer the built-in sync between the Cancel button and the top-right close-X no longer
+applies. If you need to disable dismissal, pass `disableCloseButton` to the `Modal` **and** disable
+your custom buttons together — disabling one and leaving the other lets users bypass the restriction
+(`docs/ux/modals.md`, "Redundant Cancel/Close").
+
+### Slide in a Panel for a form or detail drawer
+
+`Panel` slides in from the right and is a better fit than a Modal for longer content or a create/edit
+form on the current view. It is controlled by `opened`. Compose `PanelBody` for content and pass a
+`PanelFooter` to `PanelBody`'s `footer` prop so the footer pins below the scrolling body:
+
+```tsx
+import { useState } from "react"
+import { Panel, PanelBody, PanelFooter, Button, TextInput } from "@cloudoperators/juno-ui-components"
+
+function NewPeeringPanel() {
+ const [opened, setOpened] = useState(false)
+ return (
+ <>
+ <Button label="New Peering" variant="primary" onClick={() => setOpened(true)} />
+ <Panel heading="New Peering" opened={opened} onClose={() => setOpened(false)}>
+ <PanelBody
+ footer={
+ <PanelFooter>
+ <Button label="Cancel" variant="subdued" onClick={() => setOpened(false)} />
+ <Button label="Create" variant="primary" onClick={() => setOpened(false)} />
+ </PanelFooter>
+ }
+ >
+ <TextInput label="Name" />
+ </PanelBody>
+ </Panel>
+ </>
+ )
+}
+```
+
+`Panel` always gives a heading region; always set `heading` so the drawer is labelled
+(`docs/ux/modals.md` — Modal/Panel/Page is a task-complexity choice; the Panel story notes "Panels
+should have a heading"). `PanelFooter` right-aligns its buttons automatically.
+
+### Add a Tooltip
+
+A Tooltip is composed of three parts: a `Tooltip` wrapper holding the shared state, a
+`TooltipTrigger`, and a `TooltipContent`. Uncontrolled, pick `triggerEvent="hover"` for a passive
+hint or `"click"` (the default) for one the user opts into. Use `asChild` to make an existing
+element (Icon, Button) the trigger instead of wrapping it in the default `<button>`:
+
+```tsx
+import { Tooltip, TooltipTrigger, TooltipContent, Icon } from "@cloudoperators/juno-ui-components"
+
+function HelpHint() {
+ return (
+ <Tooltip triggerEvent="hover">
+ <TooltipTrigger asChild>
+ <Icon icon="help" />
+ </TooltipTrigger>
+ <TooltipContent>Peerings connect two networks across accounts.</TooltipContent>
+ </Tooltip>
+ )
+}
+```
+
+Pass a `variant` (`info`, `warning`, `danger`, `error`, `success`) to add a semantic icon and color.
+To drive it yourself, pass `open` to make the Tooltip controlled — `triggerEvent` is then ignored and
+you manage opening and closing. See [tooltip modes](references/tooltip-modes.md) for the controlled
+pattern and variant guidance.
+
+### Build an overflow menu with PopupMenu
+
+`PopupMenu` renders a `moreVert` (three-dot) toggle by default and holds its items in
+`PopupMenuOptions`. Order items by importance, **not** alphabetically: put any View/Details action
+first and the destructive action last, separated by a `PopupMenuSectionSeparator`
+(`docs/ux/popup-and-overflow-menus.md`, "Menu Item Order and Grouping"):
+
+```tsx
+import {
+ PopupMenu,
+ PopupMenuOptions,
+ PopupMenuItem,
+ PopupMenuSectionSeparator,
+} from "@cloudoperators/juno-ui-components"
+
+declare function navigate(to: string): void
+
+function ItemActions({ id }: { id: string }) {
+ return (
+ <PopupMenu>
+ <PopupMenuOptions>
+ <PopupMenuItem label="View Item Details" onClick={() => navigate(`/items/${id}`)} />
+ <PopupMenuItem label="Copy Item" />
+ <PopupMenuItem label="Download Item" icon="download" />
+ <PopupMenuSectionSeparator />
+ <PopupMenuItem label="Delete Item" icon="deleteForever" />
+ </PopupMenuOptions>
+ </PopupMenu>
+ )
+}
+```
+
+For a menu spanning multiple entity types, wrap each group in a `PopupMenuSection` and separate
+groups with `PopupMenuSectionSeparator` — within a group, do not add an extra divider before the
+destructive item (`docs/ux/popup-and-overflow-menus.md`, "Grouping"). For custom toggles via `as`,
+`PopupMenuSectionHeading`, link items, and closing from custom content, read
+[popup menu composition](references/popup-menu-composition.md).
+
+## Common mistakes
+
+- **CRITICAL — Modal does not close on confirm by itself.** `onConfirm` fires but the Modal stays
+ open; set `open={false}` in your handler once the action succeeds, or the dialog lingers over a
+ completed task (Modal source: "we do not close the modal automatically").
+- **CRITICAL — Custom footer bypasses dismissal lock.** With `modalFooter`, disabling only your
+ Cancel button leaves the close-X live. Pass `disableCloseButton` to `Modal` and disable both
+ together (`docs/ux/modals.md`, "Redundant Cancel/Close").
+- **HIGH — Destructive confirm without `primary-danger` + named item.** A blue confirm button and a
+ vague "Are you sure?" title fail to signal irreversibility. Use `confirmButtonVariant="primary-danger"`
+ and name the item in the body (`docs/ux/modals.md`, "Destructive Actions", "Don't").
+- **HIGH — Alphabetically sorted or View-last menu.** Order by frequency; View first, destructive
+ last with a divider (`docs/ux/popup-and-overflow-menus.md`, "Item Order").
+- **HIGH — PopupMenu or Modal without a PortalProvider.** The menu mispositions and Modal/Panel warn
+ and fall back to `document.body`. Wrap the app in `AppShellProvider`/`PortalProvider`
+ (PopupMenu source: "using Juno's PortalProvider … is mandatory").
+- **MEDIUM — Non-closeable Modal / locking the user in.** `closeable={false}` removes every exit and
+ is an antipattern; prefer a `Message`. A user must always be able to close a Modal
+ (`docs/ux/modals.md`, "Never Lock Users in Modals").
+- **MEDIUM — Confirming routine actions.** Do not wrap navigating, filtering, or sorting in a
+ confirmation Modal; reserve confirmation for destructive or surprising actions
+ (`docs/ux/interaction-guidelines.md`, "Confirmation of Consequential Actions").
+- **MEDIUM — Stacking Modals or confusing Modal vs. Panel.** Never open a Modal from inside a Modal;
+ use a Panel for longer forms on the current view (`docs/ux/modals.md`, "When Not to Use a Modal").
+
+## Completion
+
+Verify:
+
+1. Every overlay is opened by a user action, and the app is wrapped in `PortalProvider` /
+ `AppShellProvider` (no `usePortalRef` console warning).
+2. Modals close in their own `onConfirm`/`onCancel`; a user can always dismiss (close-X or Cancel).
+3. Destructive Modals use `primary-danger`, name the item in the body, and gate the confirm button at
+ the correct severity (always-on / checkbox / typed phrase).
+4. PopupMenu items are frequency-ordered: View first, destructive last behind a divider.
+5. Run `npm exec --no -- intent validate packages/ui-components/skills` and fix any errors.
+
+If an overlay state (e.g. the failure path of a confirm handler) cannot be exercised in your test
+harness, report it as unverified rather than assuming it renders.
+
+## References
+
+- [modal patterns](references/modal-patterns.md) — read for the destructive-action severity table,
+ acknowledgement-only Modals, form-validation gating, and accessibility/focus-trap notes.
+- [tooltip modes](references/tooltip-modes.md) — read before using a controlled Tooltip or choosing a
+ semantic variant and placement.
+- [popup menu composition](references/popup-menu-composition.md) — read for custom toggles (`as`),
+ section headings, link items, menu sizing, and closing the menu from custom content.
diff --git a/packages/ui-components/skills/overlays/references/modal-patterns.md b/packages/ui-components/skills/overlays/references/modal-patterns.md
new file mode 100644
index 0000000000..dea1b83600
--- /dev/null
+++ b/packages/ui-components/skills/overlays/references/modal-patterns.md
@@ -0,0 +1,117 @@
+# Modal patterns
+
+Read this when confirming a destructive action, building an acknowledgement-only Modal, gating a
+Modal that contains a form, or wiring Modal accessibility. Source: `docs/ux/modals.md` and
+`packages/ui-components/src/components/Modal/Modal.component.tsx`.
+
+## Destructive-action severity ladder
+
+The `Modal` component gives you the hooks (`confirmButtonVariant`, `disableConfirmButton`,
+`onConfirm`) but does not enforce a severity. Choose the level from the risk of the action
+(`docs/ux/modals.md`, "Destructive Actions and Confirmation of Destructive Actions"):
+
+| Severity | Means of confirmation | How to wire it |
+| -------- | ------------------------------------ | --------------------------------------------------------------- |
+| Very Low | none — no Modal; maybe a toast | skip the Modal entirely |
+| Low | one click on the confirm button | `confirmButtonVariant="primary-danger"`, confirm always enabled |
+| Mid | tick a checkbox, then confirm | `disableConfirmButton={!checked}` |
+| High | type a required phrase, then confirm | `disableConfirmButton={phrase !== "DELETE"}` |
+
+For all but very-low-risk actions, follow up with a toast confirming the entity was actually deleted,
+unless it is obvious from context or many identical actions would flood the user with notifications.
+
+The medium-risk (checkbox-gated) pattern:
+
+```tsx
+import { useState } from "react"
+import { Modal, Checkbox } from "@cloudoperators/juno-ui-components"
+
+function RemoveUserModal({ open, onClose }: { open: boolean; onClose: () => void }) {
+ const [confirmed, setConfirmed] = useState(false)
+ return (
+ <Modal
+ title="Remove User"
+ open={open}
+ confirmButtonLabel="Remove User"
+ confirmButtonVariant="primary-danger"
+ disableConfirmButton={!confirmed}
+ onConfirm={onClose}
+ onCancel={() => {
+ setConfirmed(false)
+ onClose()
+ }}
+ >
+ <p>Removing user 'jsmith' immediately revokes all project access.</p>
+ <Checkbox
+ label="Check the box to confirm removing user 'jsmith'"
+ checked={confirmed}
+ onChange={(e) => setConfirmed(e.target.checked)}
+ />
+ </Modal>
+ )
+}
+```
+
+Note the UX distinction: **Delete** and **Wipe** are destructive and warrant this ladder; **Remove**,
+**Revoke**, and **Disable** are reversible and usually need less friction
+(`docs/ux/popup-and-overflow-menus.md`, "Destructive Actions").
+
+## Acknowledgement-only Modal
+
+A Modal that only confirms acknowledgement of a fact should have a **single** button labelled
+"Close" / "OK". With the built-in footer, render exactly one button by passing neither
+`confirmButtonLabel` nor `onConfirm` — `ModalFooter` then renders a lone Close button
+(`ModalFooter.component.tsx`). Do not add a `Message` to the body of such a Modal
+(`docs/ux/modals.md`, "General Confirmation Modals").
+
+```tsx
+import { Modal } from "@cloudoperators/juno-ui-components"
+
+function MaintenanceNotice({ open, onClose }: { open: boolean; onClose: () => void }) {
+ return (
+ <Modal title="Maintenance Mode Enabled" open={open} onCancel={onClose}>
+ Automated alerts for cluster 'prod-eu-west-1' are suspended until you turn off maintenance mode.
+ </Modal>
+ )
+}
+```
+
+## Form validation inside a Modal
+
+When a Modal hosts a form, keep the confirm/primary button disabled until every required field has a
+value and all validations pass; re-evaluate on `onChange` for a responsive feel
+(`docs/ux/modals.md`, "Form Validation Specifics in Modals"). Use `initialFocus` with a selector or
+`id` to focus the first field when the Modal opens:
+
+```tsx
+import { useState } from "react"
+import { Modal, TextInput } from "@cloudoperators/juno-ui-components"
+
+function CreateKeyModal({ open, onClose }: { open: boolean; onClose: () => void }) {
+ const [name, setName] = useState("")
+ return (
+ <Modal
+ title="Create API Key"
+ open={open}
+ initialFocus="#key-name"
+ confirmButtonLabel="Create"
+ disableConfirmButton={name.trim() === ""}
+ onConfirm={onClose}
+ onCancel={onClose}
+ >
+ <TextInput id="key-name" label="Key name" value={name} onChange={(e) => setName(e.target.value)} required />
+ </Modal>
+ )
+}
+```
+
+## Accessibility and dismissal
+
+- The Modal sets `role="dialog"` and wraps content in a focus trap, so focus cycles inside and never
+ leaves until it closes (`docs/ux/modals.md`, "Modal Accessibility").
+- Give the Modal an accessible name: pass `title` or `heading` (the component wires
+ `aria-labelledby`), or `ariaLabel` when there is no visible title.
+- `closeOnEsc` (default `true`) and the close-X both call `onCancel`. `closeOnBackdropClick` is off by
+ default; enabling it makes the Modal feel lighter but effectively "un-modals" it.
+- Never set `closeable={false}` to trap a user — there must always be a way out
+ (`docs/ux/modals.md`, "Never Lock Users in Modals").
diff --git a/packages/ui-components/skills/overlays/references/popup-menu-composition.md b/packages/ui-components/skills/overlays/references/popup-menu-composition.md
new file mode 100644
index 0000000000..5fd2fbd8a1
--- /dev/null
+++ b/packages/ui-components/skills/overlays/references/popup-menu-composition.md
@@ -0,0 +1,158 @@
+# PopupMenu composition
+
+Read this for custom toggles, section headings, link items, menu sizing, and closing the menu from
+custom content. Source: `packages/ui-components/src/components/PopupMenu/PopupMenu.component.tsx` and
+`PopupMenu.stories.tsx`.
+
+`PopupMenu` wraps Headless UI's `Menu` and renders its options into `PortalProvider.Portal`, so a
+`PortalProvider` (via `AppShellProvider`) is mandatory. It tracks the open state internally; there is
+no `open` prop. Use the `onOpen` / `onClose` handlers to react to state changes.
+
+## Default toggle, icon, and sizing
+
+With no `PopupMenuToggle` child, `PopupMenu` renders a default `moreVert` three-dot toggle. Change it
+with `icon`, and set `menuSize="small"` for a denser menu:
+
+```tsx
+import { PopupMenu, PopupMenuOptions, PopupMenuItem } from "@cloudoperators/juno-ui-components"
+
+function CompactMenu() {
+ return (
+ <PopupMenu icon="edit" menuSize="small">
+ <PopupMenuOptions>
+ <PopupMenuItem label="Rename" />
+ <PopupMenuItem label="Duplicate" />
+ </PopupMenuOptions>
+ </PopupMenu>
+ )
+}
+```
+
+## Custom toggle via `as` or a child
+
+Pass `as` on `PopupMenuToggle` to render a custom component as the toggle. The component **must**
+forward its ref. If your component already renders its own button-like element, set
+`as={React.Fragment}` to avoid a button-inside-a-button:
+
+```tsx
+import React, { forwardRef } from "react"
+import {
+ PopupMenu,
+ PopupMenuToggle,
+ PopupMenuOptions,
+ PopupMenuItem,
+ Button,
+ ButtonProps,
+} from "@cloudoperators/juno-ui-components"
+
+const IconToggle = forwardRef<HTMLButtonElement, ButtonProps>((props, ref) => (
+ <Button ref={ref} icon="moreVert" {...props} />
+))
+IconToggle.displayName = "IconToggle"
+
+function RowActions() {
+ return (
+ <PopupMenu>
+ <PopupMenuToggle as={IconToggle} title="More actions" />
+ <PopupMenuOptions>
+ <PopupMenuItem label="View Details" />
+ <PopupMenuItem label="Edit" />
+ </PopupMenuOptions>
+ </PopupMenu>
+ )
+}
+```
+
+A custom toggle receives the forwarded `ref` and the toggle props (including click handling and ARIA
+attributes), so it renders and behaves as the menu's trigger. The hook that exposes the live `isOpen`
+state and a programmatic `close` is internal to the package and not part of the public API, so style
+the toggle from the props it is given rather than reading menu state directly.
+
+## Sections, headings, and dividers
+
+Group items with `PopupMenuSection`, label a group with `PopupMenuSectionHeading`, and separate
+groups with `PopupMenuSectionSeparator`. Use grouping only when it aids scanning — for short menus
+(4–5 items) dividers add noise (`docs/ux/popup-and-overflow-menus.md`, "Grouping"). For a
+multi-entity menu, group by entity type; within a group the destructive item is last with **no**
+extra divider before it (the group dividers already separate it):
+
+```tsx
+import {
+ PopupMenu,
+ PopupMenuOptions,
+ PopupMenuSection,
+ PopupMenuSectionHeading,
+ PopupMenuSectionSeparator,
+ PopupMenuItem,
+} from "@cloudoperators/juno-ui-components"
+
+function BucketMenu() {
+ return (
+ <PopupMenu>
+ <PopupMenuOptions>
+ <PopupMenuSection>
+ <PopupMenuSectionHeading label="Bucket" />
+ <PopupMenuItem label="View Bucket" />
+ <PopupMenuItem label="Edit Bucket" />
+ <PopupMenuItem label="Delete Bucket" icon="deleteForever" />
+ </PopupMenuSection>
+ <PopupMenuSectionSeparator />
+ <PopupMenuSection>
+ <PopupMenuSectionHeading label="Policy" />
+ <PopupMenuItem label="View Policy" />
+ <PopupMenuItem label="Delete Policy" icon="deleteForever" />
+ </PopupMenuSection>
+ </PopupMenuOptions>
+ </PopupMenu>
+ )
+}
+```
+
+## Link items
+
+Render an item as an anchor with `as="a"` plus `href` (and optional `target`, `rel`):
+
+```tsx
+import { PopupMenu, PopupMenuOptions, PopupMenuItem } from "@cloudoperators/juno-ui-components"
+
+function LinkMenu() {
+ return (
+ <PopupMenu>
+ <PopupMenuOptions>
+ <PopupMenuItem as="a" href="https://github.com/cloudoperators/juno" label="Open on GitHub" />
+ <PopupMenuItem as="a" href="https://www.sap.com" target="_blank" icon="openInNew" label="sap.com" />
+ </PopupMenuOptions>
+ </PopupMenu>
+ )
+}
+```
+
+## Closing from custom content
+
+Non-`PopupMenuItem` content inside the menu does not auto-close it, and the context hook that exposes
+`close` is internal to the package — it is not part of the public API. For an action that must close
+the menu, use a `PopupMenuItem`: selecting one closes the menu automatically, and its `onClick`
+handler runs your logic. Wrap any extra non-interactive content around it:
+
+```tsx
+import { PopupMenu, PopupMenuOptions, PopupMenuItem } from "@cloudoperators/juno-ui-components"
+
+function MenuWithCustomContent() {
+ const applyFilter = () => {
+ // run your logic here; the menu closes automatically on select
+ }
+
+ return (
+ <PopupMenu>
+ <PopupMenuOptions>
+ <p>Apply the current filter?</p>
+ <PopupMenuItem label="Apply" onClick={applyFilter} />
+ </PopupMenuOptions>
+ </PopupMenu>
+ )
+}
+```
+
+Label items so the action is unambiguous and the referenced entity is clear — prefer "Edit Item XYZ"
+over "Edit" when context is not obvious (`docs/ux/popup-and-overflow-menus.md`, "When using a
+PopupMenu, always make sure").
diff --git a/packages/ui-components/skills/overlays/references/tooltip-modes.md b/packages/ui-components/skills/overlays/references/tooltip-modes.md
new file mode 100644
index 0000000000..d3daba08df
--- /dev/null
+++ b/packages/ui-components/skills/overlays/references/tooltip-modes.md
@@ -0,0 +1,103 @@
+# Tooltip modes and variants
+
+Read this before using a controlled Tooltip or picking a semantic variant/placement. Source:
+`packages/ui-components/src/components/Tooltip/Tooltip.component.tsx`,
+`TooltipTrigger.component.tsx`, `TooltipContent.component.tsx`, and `Tooltip.stories.tsx`.
+
+A Tooltip is always three nested components under one `Tooltip` wrapper that owns the shared state:
+`TooltipTrigger` (the anchor) and `TooltipContent` (the floating bubble). `TooltipContent` renders
+nothing while closed or when the Tooltip is `disabled`.
+
+## Uncontrolled: hover vs. click
+
+Uncontrolled is the common case — the Tooltip manages its own open state. Pick the trigger event:
+
+- `triggerEvent="hover"` — passive hint, opens on pointer hover. Use for help text and labels.
+- `triggerEvent="click"` (default) — opens on click, for content the user deliberately reveals.
+
+```tsx
+import { Tooltip, TooltipTrigger, TooltipContent } from "@cloudoperators/juno-ui-components"
+
+function Hint() {
+ return (
+ <Tooltip triggerEvent="hover" placement="right">
+ <TooltipTrigger>
+ <span>Peering status</span>
+ </TooltipTrigger>
+ <TooltipContent>Shows whether both ends of the peering are active.</TooltipContent>
+ </Tooltip>
+ )
+}
+```
+
+Pass `initialOpen` to render it open on first mount (uncontrolled only). `placement` accepts the
+twelve floating-ui values (`top`, `top-start`, `right`, `bottom-end`, `left`, …); the default is
+`top`.
+
+## `asChild`: use an existing element as the trigger
+
+By default `TooltipTrigger` renders its own `<button>`. Pass `asChild` to project the trigger
+behavior onto the single child element instead — use this for an `Icon` or `Button` so you do not nest
+a button inside a button:
+
+```tsx
+import { Tooltip, TooltipTrigger, TooltipContent, Icon } from "@cloudoperators/juno-ui-components"
+
+function IconHint() {
+ return (
+ <Tooltip triggerEvent="hover">
+ <TooltipTrigger asChild>
+ <Icon icon="info" />
+ </TooltipTrigger>
+ <TooltipContent>Read-only field, managed by the controller.</TooltipContent>
+ </Tooltip>
+ )
+}
+```
+
+## Semantic variants
+
+Pass `variant` to add a leading icon and themed color to the content bubble. Allowed values:
+`info`, `warning`, `danger`, `error`, `success` (`ToolTip.types.ts`). `error` renders the
+`dangerous` icon; the others render the icon of the same name.
+
+```tsx
+import { Tooltip, TooltipTrigger, TooltipContent, Icon } from "@cloudoperators/juno-ui-components"
+
+function WarningHint() {
+ return (
+ <Tooltip variant="warning" triggerEvent="hover">
+ <TooltipTrigger asChild>
+ <Icon icon="warning" />
+ </TooltipTrigger>
+ <TooltipContent>This resource is scheduled for decommissioning.</TooltipContent>
+ </Tooltip>
+ )
+}
+```
+
+## Controlled mode
+
+Pass `open` to take control. The Tooltip then ignores `triggerEvent` and you drive opening/closing
+yourself — e.g. to show a tooltip in response to validation state rather than hover. Provide an
+accessible way to toggle it.
+
+```tsx
+import { useState } from "react"
+import { Tooltip, TooltipTrigger, TooltipContent, Button } from "@cloudoperators/juno-ui-components"
+
+function ControlledTooltip() {
+ const [open, setOpen] = useState(false)
+ return (
+ <Tooltip open={open}>
+ <TooltipTrigger asChild>
+ <Button label="Toggle hint" onClick={() => setOpen((v) => !v)} />
+ </TooltipTrigger>
+ <TooltipContent>Shown while the controlled state is open.</TooltipContent>
+ </Tooltip>
+ )
+}
+```
+
+`disabled` short-circuits everything: an uncontrolled Tooltip can no longer open, the trigger shows
+the default cursor instead of a pointer, and `TooltipContent` returns `null`.
diff --git a/packages/ui-components/skills/ux-writing/SKILL.md b/packages/ui-components/skills/ux-writing/SKILL.md
new file mode 100644
index 0000000000..951d610314
--- /dev/null
+++ b/packages/ui-components/skills/ux-writing/SKILL.md
@@ -0,0 +1,273 @@
+---
+name: ux-writing
+description: >
+ Use when writing any user-facing text in a Juno UI built with @cloudoperators/juno-ui-components:
+ button and confirm-action labels, Modal titles and copy, Status/Message titles and bodies,
+ headings and DataGrid column headers, error and empty-state wording, and rendering missing or
+ unknown field values. Covers active-voice phrasing, title-case rules, the "no please/thanks",
+ "no exclamation marks", "Sign in not Log in" rules, and the "- -" / fall-back-to-ID conventions,
+ so copy stays consistent across the app. For the DataGrid empty/loading/error structure itself
+ see the datagrid skill; this skill governs the words that go in it.
+metadata:
+ purpose: >
+ Teaches developers to write and label Juno UI text that follows the project's UX Writing and
+ Content Design guidelines — active impersonal voice, title case, concise verb-based button
+ labels, professional non-alarmist error copy, and the project-specific empty-value conventions
+ (render "- -", fall back to the ID for name-like fields) — grounded in the real Button, Status,
+ Message, Modal, and DescriptionList component props so the examples type-check.
+ type: core
+ library: "@cloudoperators/juno-ui-components"
+ library_version: "9.6.0"
+sources:
+ - cloudoperators/juno:packages/ui-components/src/components/Button/Button.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/Button/Button.stories.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/Status/Status.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/Message/Message.component.tsx
+ - cloudoperators/juno:packages/ui-components/src/components/Modal/Modal.component.tsx
+ - cloudoperators/juno:docs/ux/ux-writing-content-design.md
+ - cloudoperators/juno:docs/ux/application-design-guidelines.md
+---
+
+# Write user-facing text for a Juno UI
+
+The Juno component library gives you the containers for text — a `Button`'s `label`, a `Status`'s
+`title`/`body`, a `Modal`'s `title`, a `Message`'s `text` — but it does **not** enforce what the
+text says. The wording is yours, and it has to follow the project's UX Writing rules so copy reads
+consistently across every app. These rules exist because Juno apps are built for technical,
+professional users working with SAP ConvergedCloud: respect their time and expertise, be precise,
+and never sound like a chatty consumer app (`docs/ux/ux-writing-content-design.md`, "Scope,
+Intended Audience and Tone").
+
+This is a content skill, not a component API. Every example below targets a real component so it
+type-checks, but the point is the string, not the markup.
+
+## Setup
+
+There is nothing to install beyond the component library. You write text as plain props:
+
+```tsx
+import { Button, Status } from "@cloudoperators/juno-ui-components"
+
+function Example() {
+ return (
+ <>
+ <Button variant="primary" label="Create Image" onClick={() => {}} />
+ <Status status="error" title="Could Not Load Images" body="An error occurred. Try again." />
+ </>
+ )
+}
+```
+
+Note the capitalization and the full stop only on the body sentence. The rest of this skill is the
+set of rules that produce strings like these.
+
+## Core patterns
+
+### Use active, impersonal voice
+
+Prefer active voice, but avoid "We"/"Us" — the system is not a person. If staying active forces a
+"we", rephrase impersonally rather than slipping into passive (`docs/ux/ux-writing-content-design.md`,
+"Active or Passive Voice?").
+
+```tsx
+import { Status } from "@cloudoperators/juno-ui-components"
+
+// Do: active, impersonal
+const ok = <Status status="error" title="There Was an Error" body="An error occurred while processing your request." />
+
+// Don't: personal "we" — avoid
+const bad = <Status status="error" title="There Was an Error" body="We encountered an error processing your request." />
+```
+
+Avoid nominalizations (substantiations): "Creating an instance may take up to a minute." reads
+better than "The creation of an instance may take up to a minute." Use a verb
+(`docs/ux/ux-writing-content-design.md`, "Avoid Substantiations").
+
+### Apply title case to titles, headings, and labels
+
+Capitalize titles and headings everywhere they appear — body copy, Modals, Panels, DataGrid headers,
+lists, buttons, and Message/Notification titles. Capitalize the first and last word, plus nouns,
+verbs, pronouns, adjectives, adverbs, numbers, and subordinating conjunctions. Do **not** capitalize
+articles (a/an/the), prepositions of five letters or fewer, short coordinating conjunctions
+(and/but/or/nor/so/yet), or the "to" of an infinitive — unless it is the first or last word
+(`docs/ux/ux-writing-content-design.md`, "Title Case").
+
+```tsx
+import { DataGrid, DataGridRow, DataGridHeadCell, ContentHeading } from "@cloudoperators/juno-ui-components"
+
+function Headings() {
+ return (
+ <>
+ {/* Do: "How to Use This Guide" — "to"/"This" cased per the rules */}
+ <ContentHeading heading="How to Use This Guide" />
+ <DataGrid columns={2}>
+ <DataGridRow>
+ {/* Do: nouns capitalized, article lowercased mid-title */}
+ <DataGridHeadCell>Name of the Instance</DataGridHeadCell>
+ <DataGridHeadCell>Created At</DataGridHeadCell>
+ </DataGridRow>
+ </DataGrid>
+ </>
+ )
+}
+```
+
+**Never use ALL-CAPS.** Do not add punctuation to titles unless it carries meaning — no trailing
+full stop, no exclamation mark. An ellipsis ("…") counts as a single glyph and is allowed where it
+signals a follow-up step.
+
+### Write button labels as short verbs
+
+Button labels use the infinitive form of a verb, kept short, with title case. Do not prefix
+"Click to …". Pass the text as `label` (or as `children`) on `Button`
+(`docs/ux/ux-writing-content-design.md`, "Button Labels").
+
+```tsx
+import { Button } from "@cloudoperators/juno-ui-components"
+
+function Actions() {
+ return (
+ <>
+ <Button label="Save" onClick={() => {}} />
+ <Button label="Delete" variant="primary-danger" onClick={() => {}} />
+ {/* Ellipsis signals a further step (e.g. a Modal opens) */}
+ <Button label="Export…" onClick={() => {}} />
+ </>
+ )
+}
+```
+
+For a Modal's **primary confirming** button, append the object type to the verb when the object is a
+single short word — "Delete Image" is clearer than a bare "Delete". If the object type is long or
+multi-word, fall back to the verb alone ("Delete", not "Delete Kubernetes Node Pool"). Be
+consistent within an app (`docs/ux/ux-writing-content-design.md`, "Confirming Buttons in Modals").
+
+```tsx
+import { Modal } from "@cloudoperators/juno-ui-components"
+
+function DeleteModal({ open }: { open: boolean }) {
+ return (
+ <Modal
+ open={open}
+ title="Delete Image"
+ confirmButtonLabel="Delete Image"
+ cancelButtonLabel="Cancel"
+ onConfirm={() => {}}
+ >
+ Select an image and click "Delete Image" to delete the selected image.
+ </Modal>
+ )
+}
+```
+
+### Keep terminology consistent
+
+Use one verb for one action across title, copy, and button. If "Terminate Instance" is the Modal
+title, use "terminate" in the body and on the button — or fall back to a generic "Confirm"/"OK" if
+the exact term would repeat too often. Never swap in a synonym ("stop", "kill", "pause") that
+changes or blurs the meaning (`docs/ux/ux-writing-content-design.md`, "Consistency").
+
+Use **"Sign in"**, never "Log in", and apply it consistently
+(`docs/ux/ux-writing-content-design.md`, 'Use "Sign in" over "Log in"').
+
+### Write professional, non-alarmist error copy
+
+Address the user as "You"; label UI chrome without possessives ("User Account", not "My Account" or
+"Your Account"). Keep error copy calm and factual — the shipped `Status` and `Message` defaults
+model the tone ("Something Went Wrong", "An error occurred. Try again.")
+(`docs/ux/ux-writing-content-design.md`, "Errors and Error Messages").
+
+```tsx
+import { Message } from "@cloudoperators/juno-ui-components"
+
+const errorMessage = (
+ <Message
+ variant="error"
+ title="Access Denied"
+ text="You do not have the required permissions to access this resource."
+ />
+)
+```
+
+**No exclamation marks** and never double/triple punctuation. **Never write "Please" or "Thanks"** —
+the system is polite by respecting the user's time, not by imitating a person
+(`docs/ux/ux-writing-content-design.md`, 'Never Use "Please" or "Thanks"').
+
+### Render missing values as "- -" (with the ID fall-back)
+
+When a field has no value, render **two hyphens separated by a space: `- -`**. The space stops
+editors from "smart"-substituting `--` into an en dash. Do not use `–`, `—`, `--`, or `N/A`
+(`docs/ux/ux-writing-content-design.md`, "Rendering Empty or Unknown Values").
+
+```tsx
+import { DescriptionList, DescriptionTerm, DescriptionDefinition } from "@cloudoperators/juno-ui-components"
+
+const EMPTY_VALUE = "- -"
+
+function Metadata({ region }: { region?: string }) {
+ return (
+ <DescriptionList>
+ <DescriptionTerm>Region</DescriptionTerm>
+ {/* Verbatim metadata: show "- -", never substitute an ID here */}
+ <DescriptionDefinition>{region ?? EMPTY_VALUE}</DescriptionDefinition>
+ </DescriptionList>
+ )
+}
+```
+
+There is one important exception: for a **name-like identifier** — the Name column of a DataGrid, a
+detail-page title, a breadcrumb segment — fall back to the item's **ID** instead of `- -`, so the
+item stays identifiable and linkable. Read
+[empty values and the ID fall-back](references/empty-values.md) before implementing name columns,
+detail titles, or breadcrumbs — it has the full decision (including when a visible ID column flips
+the rule back to `- -`, and the verbatim-metadata exception).
+
+## Common mistakes
+
+- **CRITICAL — "Please"/"Thanks" or exclamation marks in copy.** `<Status title="Error!" body="Please try again." />`
+ violates two rules at once. Drop the courtesy words and the "!": "An error occurred. Try again."
+ (`docs/ux/ux-writing-content-design.md`, 'Never Use "Please" or "Thanks"' and "Errors and Error Messages".)
+- **CRITICAL — Rendering `- -` for a missing name in a Name column, detail title, or breadcrumb.**
+ This makes items indistinguishable and unlinkable. Fall back to the ID in those positions; use
+ `- -` only for ordinary fields. (`docs/ux/ux-writing-content-design.md`, "Names as Identifiers".)
+- **HIGH — ALL-CAPS or Title-Casing Every Word.** "SIGN IN" and "There Was An Error" are both wrong.
+ Never all-caps; lowercase articles/short prepositions/short conjunctions mid-title: "There was an
+ Error", "Sign in". (`docs/ux/ux-writing-content-design.md`, "Title Case".)
+- **HIGH — En/em dash or `N/A` for empty values.** `–`, `—`, bare `--`, and `N/A` are all rejected.
+ Render exactly `- -`. (`docs/ux/ux-writing-content-design.md`, "Rendering Empty or Unknown Values".)
+- **HIGH — "Log in" / inconsistent sign-in wording.** Use "Sign in" everywhere.
+ (`docs/ux/ux-writing-content-design.md`, 'Use "Sign in" over "Log in"'.)
+- **MEDIUM — Personal "we" or passive voice in messages.** "We hit an error" / "Your request could
+ not be processed" → "An error occurred while processing your request." (active, impersonal).
+ (`docs/ux/ux-writing-content-design.md`, "Active or Passive Voice?".)
+- **MEDIUM — Synonym drift for one action.** Title says "Terminate Instance" but the button says
+ "Kill Instance". Keep one verb, or fall back to "Confirm". (`docs/ux/ux-writing-content-design.md`,
+ "Consistency".)
+- **MEDIUM — "Click to …" / overlong button labels.** Use the bare infinitive verb ("Delete",
+ "Save", "Export…"). (`docs/ux/ux-writing-content-design.md`, "Button Labels".)
+
+## Completion
+
+Verify, for every user-facing string you added or changed:
+
+1. Titles, headings, DataGrid headers, and button labels use title case (no ALL-CAPS, no
+ over-capitalized articles/prepositions), with no trailing punctuation unless meaningful.
+2. No "Please", no "Thanks", no exclamation marks, no doubled punctuation anywhere.
+3. Error/info copy is active and impersonal (no "we"); the user is addressed as "You"; UI labels
+ avoid "My"/"Your".
+4. Button labels are short infinitive verbs; a Modal's primary confirm button follows the
+ verb-or-verb+object rule consistently across the app.
+5. Sign-in wording is "Sign in" everywhere.
+6. Missing values render exactly `- -`, except name-column/detail-title/breadcrumb positions, which
+ fall back to the ID per [empty values and the ID fall-back](references/empty-values.md).
+7. Run `npm exec --no -- intent validate packages/ui-components/skills` and fix any errors.
+
+If a string is produced by server defaults or a shared util you cannot see, flag it as unverified
+rather than assuming it complies.
+
+## References
+
+- [title case rules and examples](references/title-case.md) — read when you are unsure whether a
+ specific word in a heading or label should be capitalized.
+- [empty values and the ID fall-back](references/empty-values.md) — read before rendering missing
+ values in Name columns, detail-view titles, breadcrumbs, or verbatim metadata lists.
diff --git a/packages/ui-components/skills/ux-writing/references/empty-values.md b/packages/ui-components/skills/ux-writing/references/empty-values.md
new file mode 100644
index 0000000000..767faae177
--- /dev/null
+++ b/packages/ui-components/skills/ux-writing/references/empty-values.md
@@ -0,0 +1,111 @@
+# Empty values and the ID fall-back
+
+Source: `docs/ux/ux-writing-content-design.md`, "Rendering Empty or Unknown Values" and "Names as
+Identifiers: Fall Back to the ID". Read this before rendering a missing value in a Name column, a
+detail-view title, a breadcrumb, or a verbatim metadata list.
+
+## The base rule: render "- -"
+
+When a field has no value — not set, not available, or unknown — render **two hyphens separated by
+a space: `- -`**.
+
+The space matters: many editors apply "smart" typography and silently turn `--` into an en dash as
+you type. The space between the two hyphens prevents that substitution.
+
+Do **not** use:
+
+- `–` (en dash) or `—` (em dash) — visually similar but semantically wrong, and often introduced
+ automatically by tooling.
+- `--` (adjacent hyphens) — may be transformed by formatters.
+- `N/A` or `n/a` — avoid unless it is a firmly established convention in that specific context.
+
+```tsx
+import { DescriptionList, DescriptionTerm, DescriptionDefinition } from "@cloudoperators/juno-ui-components"
+
+const EMPTY_VALUE = "- -"
+
+function Field({ label, value }: { label: string; value?: string | null }) {
+ return (
+ <DescriptionList>
+ <DescriptionTerm>{label}</DescriptionTerm>
+ <DescriptionDefinition>{value || EMPTY_VALUE}</DescriptionDefinition>
+ </DescriptionList>
+ )
+}
+```
+
+## The exception: name-like identifiers fall back to the ID
+
+For a field that serves as a human-readable, human-assigned **name** for an item, do not render
+`- -` when the name is missing — display the item's **ID** instead. The ID stays unique, stable, and
+linkable, so the user can still identify, reference, and share the item. Rendering `- -` here would
+make items indistinguishable.
+
+Apply this in these positions:
+
+- **Name column in a DataGrid** — show the ID in place of the missing name.
+- **Detail-view page title** — use the ID as the title.
+- **Breadcrumb segment** — use the ID as the segment label.
+
+```tsx
+import { DataGrid, DataGridRow, DataGridCell, DataGridHeadCell } from "@cloudoperators/juno-ui-components"
+
+type Item = { id: string; name?: string | null }
+
+function NameColumn({ items }: { items: Item[] }) {
+ return (
+ <DataGrid columns={1}>
+ <DataGridRow>
+ <DataGridHeadCell>Name</DataGridHeadCell>
+ </DataGridRow>
+ {items.map((item) => (
+ <DataGridRow key={item.id}>
+ {/* Missing name -> fall back to the ID, not "- -" */}
+ <DataGridCell>{item.name || item.id}</DataGridCell>
+ </DataGridRow>
+ ))}
+ </DataGrid>
+ )
+}
+```
+
+### Sub-exception: a visible ID column flips it back to "- -"
+
+If the DataGrid **already has a dedicated, visible ID column**, do not repeat the ID in the Name
+column — the item is already identifiable, and duplicating the ID is redundant and confusing. In
+that case use `- -` in the Name column.
+
+```tsx
+import { DataGrid, DataGridRow, DataGridCell, DataGridHeadCell } from "@cloudoperators/juno-ui-components"
+
+type Row = { id: string; name?: string | null }
+
+const EMPTY_VALUE = "- -"
+
+function WithIdColumn({ rows }: { rows: Row[] }) {
+ return (
+ <DataGrid columns={2}>
+ <DataGridRow>
+ <DataGridHeadCell>ID</DataGridHeadCell>
+ <DataGridHeadCell>Name</DataGridHeadCell>
+ </DataGridRow>
+ {rows.map((row) => (
+ <DataGridRow key={row.id}>
+ <DataGridCell>{row.id}</DataGridCell>
+ {/* ID is already visible, so a missing name shows "- -" */}
+ <DataGridCell>{row.name || EMPTY_VALUE}</DataGridCell>
+ </DataGridRow>
+ ))}
+ </DataGrid>
+ )
+}
+```
+
+## Verbatim metadata display: always "- -"
+
+When rendering an item's **raw metadata as-is** — e.g. a `<dl>` that shows every stored property —
+do **not** substitute the ID for a missing name. Use `- -`. The purpose of verbatim display is to
+reflect what is actually stored; substituting the ID would imply a name exists when it does not.
+
+Display the fallback value with no extra decoration beyond what a normal value in that position
+would receive.
diff --git a/packages/ui-components/skills/ux-writing/references/title-case.md b/packages/ui-components/skills/ux-writing/references/title-case.md
new file mode 100644
index 0000000000..d3c65d3ab6
--- /dev/null
+++ b/packages/ui-components/skills/ux-writing/references/title-case.md
@@ -0,0 +1,58 @@
+# Title case rules and examples
+
+Source: `docs/ux/ux-writing-content-design.md`, "Title Case". Read this when you are unsure whether
+a specific word in a heading, Modal title, DataGrid header, or button label should be capitalized.
+
+Title case applies to titles and headings in: body copy, Modals, Panels, DataGrid, Lists, Buttons,
+and Message/Notification titles.
+
+## Always capitalize
+
+- The **first and last word** of the title or heading, regardless of what part of speech it is.
+- Nouns
+- Verbs
+- Pronouns
+- Adjectives
+- Adverbs
+- Numbers
+- Subordinating conjunctions: _Although, Because, If, When_
+
+Written numerals are capitalized ("One", "Nine", "Thousands"). For compound numerals, capitalize
+only the first part: "Twenty-one".
+
+## Do not capitalize (unless first or last word)
+
+- Articles: _a, an, the_
+- Short prepositions, five letters or fewer: _at, by, for, in, of, off, on, out, over, to, under, up_
+- Short coordinating conjunctions: _and, but, for, or, nor, so, yet_
+- "to" when it is part of an infinitive ("How to Use…")
+
+## Punctuation and caps
+
+- **Never use ALL-CAPS, ever.**
+- Do not add punctuation unless it conveys actual meaning — no trailing full stop or exclamation
+ mark on a title.
+- An ellipsis "…" is a single glyph and may be used (e.g. a button label that opens a further step).
+- Never double or triple punctuation.
+
+## Worked examples
+
+Correct:
+
+- "There was an Error" — "was"/"an" lowercased (short verb "was" is actually capitalized as a verb;
+ note the doc's own example keeps "was" lowercase as the common-usage form — follow the doc's
+ rendering: _"There was an Error"_).
+- "Sign in" — "in" is a short preposition and not the first word.
+- "How to Use This Guide" — "to" is an infinitive marker (lowercase), "Use"/"This"/"Guide" capitalized.
+- "Confirm to Terminate an Action" — "to" infinitive and "an" article lowercased.
+
+Incorrect:
+
+- "There Was An Error" — over-capitalized "Was"/"An".
+- "Sign In" — "In" wrongly capitalized.
+- "Confirm To Terminate An Action" — "To"/"An" wrongly capitalized.
+- "There was an Error." — trailing full stop on a title.
+- "There was an Error!" / "There was an Error!!!" — exclamation / repeated punctuation.
+
+When in doubt, keep the title short enough that the only ambiguous words are the obvious
+articles/prepositions, and lowercase those.
diff --git a/packages/ui-components/src/components/DataGrid/DataGrid.component.tsx b/packages/ui-components/src/components/DataGrid/DataGrid.component.tsx
index da5d2db935..407f16a39a 100644
--- a/packages/ui-components/src/components/DataGrid/DataGrid.component.tsx
+++ b/packages/ui-components/src/components/DataGrid/DataGrid.component.tsx
@@ -61,7 +61,7 @@ export const useDataGridContext = () => useContext(DataGridContext)
* @see {@link DataGridProps}
*/
export const DataGrid = ({
- columns = 1,
+ columnCount = 1,
columnMaxSize = "auto",
columnMinSize = "0px",
minContentColumns,
@@ -83,7 +83,7 @@ export const DataGrid = ({
<DataGridContext.Provider value={dataGridConf}>
<div
className={`juno-datagrid ${dataGridStyles} ${className}`}
- style={gridTemplate(columns, columnMaxSize, columnMinSize, minContentColumns, gridColumnTemplate)}
+ style={gridTemplate(columnCount, columnMaxSize, columnMinSize, minContentColumns, gridColumnTemplate)}
role="grid"
{...props}
>
@@ -100,7 +100,7 @@ export interface DataGridProps extends HTMLAttributes<HTMLDivElement> {
* Specifies the number of columns in the grid.
* @default 1
*/
- columns?: number
+ columnCount?: number
/**
* Defines maximum column sizing.
diff --git a/packages/ui-components/src/components/DataGrid/DataGrid.stories.tsx b/packages/ui-components/src/components/DataGrid/DataGrid.stories.tsx
index 1c006b6fa8..ea0a8cb03d 100644
--- a/packages/ui-components/src/components/DataGrid/DataGrid.stories.tsx
+++ b/packages/ui-components/src/components/DataGrid/DataGrid.stories.tsx
@@ -38,7 +38,7 @@ const meta: Meta<typeof DataGrid> = {
export default meta
const Template = (args: TemplateProps) => {
- const { hideHead, includeColSpanRow, columns = defaultColumns } = args
+ const { hideHead, includeColSpanRow, columnCount: columns = defaultColumns } = args
return (
<DataGrid {...args}>
@@ -73,7 +73,7 @@ const Template = (args: TemplateProps) => {
export const Default: StoryObj<TemplateProps> = {
render: Template,
args: {
- columns: 5,
+ columnCount: 5,
},
parameters: {
docs: {
@@ -87,7 +87,7 @@ export const Default: StoryObj<TemplateProps> = {
export const EqualColumnSize: StoryObj<TemplateProps> = {
render: Template,
args: {
- columns: 5,
+ columnCount: 5,
columnMaxSize: "1fr",
},
parameters: {
@@ -103,7 +103,7 @@ export const EqualColumnSize: StoryObj<TemplateProps> = {
export const ColumnMinSize: StoryObj<TemplateProps> = {
render: Template,
args: {
- columns: 5,
+ columnCount: 5,
columnMinSize: "300px",
},
parameters: {
@@ -119,7 +119,7 @@ export const ColumnMinSize: StoryObj<TemplateProps> = {
export const MinimumSizedColumns: StoryObj<TemplateProps> = {
render: Template,
args: {
- columns: 5,
+ columnCount: 5,
minContentColumns: [0, 4],
},
parameters: {
@@ -136,7 +136,7 @@ export const CustomGridTemplate: StoryObj<TemplateProps> = {
render: Template,
args: {
gridColumnTemplate: `20% repeat(${defaultColumns - 1}, auto)`,
- columns: defaultColumns,
+ columnCount: defaultColumns,
},
parameters: {
docs: {
@@ -151,7 +151,7 @@ export const CustomGridTemplate: StoryObj<TemplateProps> = {
export const NoHead: StoryObj<TemplateProps> = {
render: Template,
args: {
- columns: 5,
+ columnCount: 5,
hideHead: true,
},
parameters: {
@@ -166,7 +166,7 @@ export const NoHead: StoryObj<TemplateProps> = {
export const ColSpanCell: StoryObj<TemplateProps> = {
render: Template,
args: {
- columns: 5,
+ columnCount: 5,
includeColSpanRow: true,
},
parameters: {
@@ -180,7 +180,7 @@ export const ColSpanCell: StoryObj<TemplateProps> = {
export const HoverableRow: StoryObj<DataGridRowStoryProps> = {
render: (args) => (
- <DataGrid columns={defaultColumns}>
+ <DataGrid columnCount={defaultColumns}>
<DataGridRow>
<DataGridHeadCell>ID</DataGridHeadCell>
<DataGridHeadCell>Name</DataGridHeadCell>
@@ -210,7 +210,7 @@ export const HoverableRow: StoryObj<DataGridRowStoryProps> = {
export const HoverableRowWithInteractableElements: StoryObj<DataGridRowStoryProps> = {
render: (args) => (
- <DataGrid columns={defaultColumns + 1}>
+ <DataGrid columnCount={defaultColumns + 1}>
<DataGridRow>
<DataGridHeadCell>ID</DataGridHeadCell>
<DataGridHeadCell>Name</DataGridHeadCell>
diff --git a/packages/ui-components/src/components/DataGrid/DataGridHeader.stories.tsx b/packages/ui-components/src/components/DataGrid/DataGridHeader.stories.tsx
index be4f01bf17..526fe63cb5 100644
--- a/packages/ui-components/src/components/DataGrid/DataGridHeader.stories.tsx
+++ b/packages/ui-components/src/components/DataGrid/DataGridHeader.stories.tsx
@@ -246,7 +246,7 @@ export const FullyFeatured: Story = {
</DataGridToolbar>
</Stack>
- <DataGrid columns={6} minContentColumns={[0, 5]}>
+ <DataGrid columnCount={6} minContentColumns={[0, 5]}>
<DataGridRow>
<DataGridHeadCell />
<DataGridHeadCell>Name</DataGridHeadCell>
@@ -370,7 +370,7 @@ export const FullyFeatured: Story = {
</DataGridToolbar>
</Stack>
- <DataGrid columns={6} minContentColumns={[0, 5]}>
+ <DataGrid columnCount={6} minContentColumns={[0, 5]}>
<DataGridRow>
<DataGridHeadCell />
<DataGridHeadCell>Name</DataGridHeadCell>
diff --git a/packages/ui-components/src/components/DataGridCell/DataGridCell.stories.tsx b/packages/ui-components/src/components/DataGridCell/DataGridCell.stories.tsx
index 67fcb36b9b..5f7d8b2c07 100644
--- a/packages/ui-components/src/components/DataGridCell/DataGridCell.stories.tsx
+++ b/packages/ui-components/src/components/DataGridCell/DataGridCell.stories.tsx
@@ -64,7 +64,7 @@ export const Default: Story = {
},
},
render: () => (
- <DataGrid columns={3}>
+ <DataGrid columnCount={3}>
<DataGridRow>
<DataGridHeadCell>Name</DataGridHeadCell>
<DataGridHeadCell>Status</DataGridHeadCell>
@@ -91,7 +91,7 @@ export const NoWrap: Story = {
},
},
render: () => (
- <DataGrid columns={3}>
+ <DataGrid columnCount={3}>
<DataGridRow>
<DataGridHeadCell>Name</DataGridHeadCell>
<DataGridHeadCell>Status</DataGridHeadCell>
@@ -119,7 +119,7 @@ export const ColSpan: Story = {
},
},
render: () => (
- <DataGrid columns={3}>
+ <DataGrid columnCount={3}>
<DataGridRow>
<DataGridHeadCell>Name</DataGridHeadCell>
<DataGridHeadCell>Status</DataGridHeadCell>
@@ -145,7 +145,7 @@ export const VerticalAlignmentOverride: Story = {
},
},
render: () => (
- <DataGrid columns={2} cellVerticalAlignment="center">
+ <DataGrid columnCount={2} cellVerticalAlignment="center">
<DataGridRow>
<DataGridHeadCell>Name</DataGridHeadCell>
<DataGridHeadCell>Description</DataGridHeadCell>
diff --git a/packages/ui-components/src/components/DataGridCell/DataGridCell.test.tsx b/packages/ui-components/src/components/DataGridCell/DataGridCell.test.tsx
index c3a04e58d9..79aa7fae0c 100644
--- a/packages/ui-components/src/components/DataGridCell/DataGridCell.test.tsx
+++ b/packages/ui-components/src/components/DataGridCell/DataGridCell.test.tsx
@@ -27,7 +27,7 @@ describe("DataGridCell", () => {
test("inherits cellVerticalAlignment from parent DataGrid context", () => {
render(
- <DataGrid columns={1} cellVerticalAlignment="center">
+ <DataGrid columnCount={1} cellVerticalAlignment="center">
<DataGridCell />
</DataGrid>
)
@@ -38,7 +38,7 @@ describe("DataGridCell", () => {
test("verticalAlignment prop overrides parent DataGrid context", () => {
render(
- <DataGrid columns={1} cellVerticalAlignment="center">
+ <DataGrid columnCount={1} cellVerticalAlignment="center">
<DataGridCell verticalAlignment="top" />
</DataGrid>
)
@@ -49,7 +49,7 @@ describe("DataGridCell", () => {
test("verticalAlignment='center' overrides parent DataGrid cellVerticalAlignment='top'", () => {
render(
- <DataGrid columns={1} cellVerticalAlignment="top">
+ <DataGrid columnCount={1} cellVerticalAlignment="top">
<DataGridCell verticalAlignment="center" />
</DataGrid>
)
diff --git a/packages/ui-components/src/components/DataGridHeadCell/DataGridHeadCell.stories.tsx b/packages/ui-components/src/components/DataGridHeadCell/DataGridHeadCell.stories.tsx
index b8ac52ff0d..45c904f26e 100644
--- a/packages/ui-components/src/components/DataGridHeadCell/DataGridHeadCell.stories.tsx
+++ b/packages/ui-components/src/components/DataGridHeadCell/DataGridHeadCell.stories.tsx
@@ -22,7 +22,7 @@ const meta: Meta<typeof DataGridHeadCell> = {
},
decorators: [
(Story) => (
- <DataGrid columns={3}>
+ <DataGrid columnCount={3}>
<DataGridRow>
<Story />
</DataGridRow>
diff --git a/packages/ui-components/src/components/DataGridRow/DataGridRow.stories.tsx b/packages/ui-components/src/components/DataGridRow/DataGridRow.stories.tsx
index b118da4a8d..69f4ca0a10 100644
--- a/packages/ui-components/src/components/DataGridRow/DataGridRow.stories.tsx
+++ b/packages/ui-components/src/components/DataGridRow/DataGridRow.stories.tsx
@@ -36,7 +36,7 @@ const meta: Meta<DataGridRowStoryProps> = {
},
decorators: [
(Story) => (
- <DataGrid columns={columns}>
+ <DataGrid columnCount={columns}>
<Story />
</DataGrid>
),
@@ -77,7 +77,7 @@ export const Default: StoryObj<DataGridRowStoryProps> = {
// If making changes, update in DataGrid story too
export const HoverableRow: StoryObj<DataGridRowStoryProps> = {
render: (args) => (
- <DataGrid columns={3} gridColumnTemplate="270px 270px 270px">
+ <DataGrid columnCount={3} gridColumnTemplate="270px 270px 270px">
<DataGridRow>
<DataGridHeadCell>ID</DataGridHeadCell>
<DataGridHeadCell>Name</DataGridHeadCell>
@@ -113,7 +113,7 @@ export const HoverableRow: StoryObj<DataGridRowStoryProps> = {
// If making changes, update in DataGrid story too
export const HoverableRowWithInteractableElements: StoryObj<DataGridRowStoryProps> = {
render: (args) => (
- <DataGrid columns={4} gridColumnTemplate="210px 210px 210px 210px">
+ <DataGrid columnCount={4} gridColumnTemplate="210px 210px 210px 210px">
<DataGridRow>
<DataGridHeadCell>ID</DataGridHeadCell>
<DataGridHeadCell>Name</DataGridHeadCell>
diff --git a/packages/ui-components/src/components/Status/Status.stories.tsx b/packages/ui-components/src/components/Status/Status.stories.tsx
index cbb69e2638..073e15a68e 100644
--- a/packages/ui-components/src/components/Status/Status.stories.tsx
+++ b/packages/ui-components/src/components/Status/Status.stories.tsx
@@ -181,7 +181,7 @@ export const DataGridLoading: Story = {
<SearchInput placeholder="Search Servers …" />
</Stack>
</DataGridToolbar>
- <DataGrid columns={4}>
+ <DataGrid columnCount={4}>
<DataGridRow>
<DataGridHeadCell>Name</DataGridHeadCell>
<DataGridHeadCell>Region</DataGridHeadCell>
@@ -215,7 +215,7 @@ export const DataGridError: Story = {
<SearchInput placeholder="Search Servers …" />
</Stack>
</DataGridToolbar>
- <DataGrid columns={4}>
+ <DataGrid columnCount={4}>
<DataGridRow>
<DataGridHeadCell>Name</DataGridHeadCell>
<DataGridHeadCell>Region</DataGridHeadCell>
@@ -249,7 +249,7 @@ export const DataGridEmpty: Story = {
<SearchInput placeholder="Search Servers …" />
</Stack>
</DataGridToolbar>
- <DataGrid columns={4}>
+ <DataGrid columnCount={4}>
<DataGridRow>
<DataGridHeadCell>Name</DataGridHeadCell>
<DataGridHeadCell>Region</DataGridHeadCell>
@@ -283,7 +283,7 @@ export const DataGridNoMatches: Story = {
<SearchInput placeholder="Search Servers …" />
</Stack>
</DataGridToolbar>
- <DataGrid columns={4}>
+ <DataGrid columnCount={4}>
<DataGridRow>
<DataGridHeadCell>Name</DataGridHeadCell>
<DataGridHeadCell>Region</DataGridHeadCell>
@@ -320,7 +320,7 @@ export const DataGridErrorWithDetails: Story = {
<SearchInput placeholder="Search Servers …" />
</Stack>
</DataGridToolbar>
- <DataGrid columns={4}>
+ <DataGrid columnCount={4}>
<DataGridRow>
<DataGridHeadCell>Name</DataGridHeadCell>
<DataGridHeadCell>Region</DataGridHeadCell>
diff --git a/packages/ui-components/src/components/Status/Status.test.tsx b/packages/ui-components/src/components/Status/Status.test.tsx
index 1367adcc92..45f34d244f 100644
--- a/packages/ui-components/src/components/Status/Status.test.tsx
+++ b/packages/ui-components/src/components/Status/Status.test.tsx
@@ -118,7 +118,7 @@ describe("Status", () => {
it("does not render a code inside a DataGrid", () => {
render(
- <DataGrid columns={1}>
+ <DataGrid columnCount={1}>
<DataGridRow>
<DataGridCell>
<Status status="error" code={404} />
@@ -131,7 +131,7 @@ describe("Status", () => {
it("adds a datagrid identifier class when rendered inside a DataGrid", () => {
render(
- <DataGrid columns={1}>
+ <DataGrid columnCount={1}>
<DataGridRow>
<DataGridCell>
<Status />
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 07066a46a8..aa62cd3342 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -891,6 +891,9 @@ importers:
'@tailwindcss/vite':
specifier: 4.3.3
version: 4.3.3(vite@8.3.2(@types/node@24.19.1)(esbuild@0.28.2)(jiti@2.7.0)(yaml@2.9.1))
+ '@tanstack/intent':
+ specifier: 0.5.5
+ version: 0.5.5
'@testing-library/jest-dom':
specifier: 7.0.1
version: 7.0.1(@testing-library/dom@10.4.2)(vitest@5.0.3(@types/node@24.19.1)(jsdom@30.1.2)(vite@8.3.2(@types/node@24.19.1)(esbuild@0.28.2)(jiti@2.7.0)(yaml@2.9.1)))
@@ -2852,6 +2855,11 @@ packages:
resolution: {integrity: sha512-utTS5L2OkeYUzXGohL1Z8sefu1GLNOJcxe8Hd6iIdc/Xo1K1nDB2JEp4iSFhvYh33xKC9V91TxrS8qfrpoKobQ==}
engines: {node: '>=20.19'}
+ '@tanstack/intent@0.5.5':
+ resolution: {integrity: sha512-Ei5RqUWgV96HrezTEyDbScy0wZN+17dNo59Am8/3ncv0YIaIxApkiX5LkM488wxe4a1Imdi09nhjFxblxwLMSQ==}
+ engines: {node: '>=20.12.0'}
+ hasBin: true
+
'@tanstack/query-core@5.104.1':
resolution: {integrity: sha512-TiRghcrGkUTE+M4JBxvpPSpBhxvIzQairw+cksrHYGr+2uwC77yW1SY9nYxnYRYOppvucf8rEg6b5byoz4rTpw==}
@@ -8157,6 +8165,8 @@ snapshots:
'@tanstack/history@1.162.4': {}
+ '@tanstack/intent@0.5.5': {}
+
'@tanstack/query-core@5.104.1': {}
'@tanstack/react-query@5.104.1(react@19.3.0)':
diff --git a/tarball/cloudoperators-juno-ui-components-9.5.1-taimoor.tgz b/tarball/cloudoperators-juno-ui-components-9.5.1-taimoor.tgz
new file mode 100644
index 0000000000..36d6fc02b8
Binary files /dev/null and b/tarball/cloudoperators-juno-ui-components-9.5.1-taimoor.tgz differ
diff --git a/tarball/cloudoperators-juno-ui-components-9.6.0.tgz b/tarball/cloudoperators-juno-ui-components-9.6.0.tgz
new file mode 100644
index 0000000000..3fb5823283
Binary files /dev/null and b/tarball/cloudoperators-juno-ui-components-9.6.0.tgz differ