# Core Principles

## Naming Conventions

| Concept | Convention                                       | Example                                                         |
|---|--------------------------------------------------|-----------------------------------------------------------------|
| HTML tag | Lowercase, kebab-case, `r-` prefix               | `<r-button>`, `<r-input>`                                       |
| Props in HTML | Kebab-case attributes                            | `icon-position`, `r-aria-label`                                 |
| Props in JSX/frameworks | camelCase                                        | `iconPosition`, `rAriaLabel`                                    |
| Custom events | Camel-case | `rClick`, `rChange`, `rValidate`, `focusPopover` , `hidePopover` |
| Event listeners | `addEventListener('rChange', handler)` (DOM), `@rChange=${handler}` (lit-html), `onRChange={handler}` (JSX/TS) | — |
| Boolean attributes | Presence toggles the prop                        | `?disabled=${true}` (lit-html), `disabled` (HTML)               |

## Shadow DOM Encapsulation

All components use Shadow DOM (`shadow: true`). This means:
- **Internal styles are isolated**: external CSS cannot reach inside the shadow root.
- **Styling customization** is done exclusively via CSS Custom Properties (`var(--r-*)`) or CSS parts exposed by the component.
- **Slots** are the only mechanism to project content into a component's shadow tree. Unknown slot names are silently ignored — always use slot names documented in the component API.
- **`document.querySelector`** cannot select elements inside a shadow root — use `element.shadowRoot.querySelector` in scripts.

## Theme Context

CSS Custom Properties inherit through light DOM and shadow DOM. Components therefore consume the
mode, UI, and brand context set by an ancestor:

- `data-theme` sets mode (`light`, `dark`, or `auto`); omit it for light default.
- `data-r-ui="alta"` remaps semantic tokens; omit it for default UI.
- `data-r-ui-brand="<brand>"` applies an application-owned brand overlay.
- `data-theme="inverse"` swaps semantic colour values within a small nested surface.

Do not add mode, UI, or brand attributes to a component merely to restyle it. Put application
context on an ancestor and style components only through documented custom properties or
`::part()` selectors. This preserves inherited `color-scheme`, `light-dark()` token resolution,
and brand precedence.