# AdiaUI — Design System Guidelines

> Drop this `guidelines/` folder into your Figma Make kit. Figma Make
> reads `Guidelines.md` first, then follows the links below. Pin `@0.8`
> (latest 0.8.x) or an exact version — check `npm view @adia-ai/web-components version` for current.

## What AdiaUI is

AdiaUI is a library of **framework-agnostic Light-DOM web components** —
custom HTML tags like `<button-ui>`, `<card-ui>`, `<admin-shell>`. They
register themselves and style themselves with CSS `@scope`. There is no
React/Vue wrapper to install and no build step required.

**Build all UI with AdiaUI tags. Do not hand-build buttons, cards,
inputs, tables, dialogs, navigation, or app shells from `<div>`s +
utility CSS when an AdiaUI tag exists.** Reach for a tag first; fall
back to plain HTML only for content with no matching primitive.

## Setup (do this first)

Add to the document `<head>`, before the app renders:

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@adia-ai/web-components@0.8/dist/web-components.min.css">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@adia-ai/web-modules@0.8/dist/shell/admin-shell.min.css">
<script type="module" src="https://cdn.jsdelivr.net/npm/@adia-ai/web-modules@0.8/dist/everything.min.js"></script>
```

- The first stylesheet (the **CDN rollup CSS**) carries every primitive's
  styles + design tokens + themes in one file. Always load it.
- Add a shell stylesheet only for the shell tier you render (`admin-shell`
  shown; swap for `chat/chat-shell`, `editor/editor-shell`,
  `simple/simple-shell`). Skip it if you use no shell.
- `everything.min.js` registers every primitive + all 4 shells + the icon
  set in one module. **Load exactly one JS path** — do not also load
  `web-components.min.js`, or `customElements.define` throws a duplicate-
  registration error.

If your kit has the npm packages installed, you may instead
`import '@adia-ai/web-components'` (JS) — but still load the **rollup CSS**
(`@adia-ai/web-components/css/bundled` or the CDN link above) rather than
127 individual component stylesheets. See `styles.md`.

## Naming rule

Every primitive is **`<name>-ui`**: `<button-ui>`, `<card-ui>`,
`<input-ui>`, `<table-ui>`, `<nav-ui>`. App shells are unsuffixed:
`<admin-shell>`, `<chat-shell>`, `<editor-shell>`, `<simple-shell>`.

## Reading order

1. **`components.md`** — the tag vocabulary, when to use each, correct vs
   wrong markup. Read before composing any screen.
2. **`styles.md`** — loading the CSS, theming (`theme` palette +
   `data-scheme` mode), layout primitives, the explicit-CSS rule.
3. **`tokens.md`** — the `--a-*` design tokens, parametric density, how to
   restyle without writing utility CSS.

## Critical rules (the common mistakes — follow exactly)

1. **`<button-ui>` and `<badge-ui>` take their label from `text=`, not
   children.** `<button-ui text="Save" variant="primary"></button-ui>`.
   Children are ignored on these two.
2. **`<card-ui>` body goes in a `<section>`:**
   `<card-ui><header><h3>Title</h3></header><section>…body…</section></card-ui>`.
   A direct child loses padding.
3. **Booleans are presence-based:** `<switch-ui checked>`,
   `<input-ui required>`. Never `checked="false"`.
4. **In JSX, write `class`, not `className`,** on AdiaUI tags (they are
   real DOM elements). Render boolean attrs conditionally:
   `{isOn && <switch-ui checked></switch-ui>}`.
5. **Sidebar nav is `<nav-ui>` + `<nav-item-ui>`** — not `<menu-ui>`
   (that is popover dropdowns only).
6. **`<stack-ui>` layers children on the z-axis** (overlap in one cell —
   e.g. a badge over an avatar). For vertical layout use
   `<col-ui gap="…">`, never `<stack-ui>`.
7. **Restyle via attributes first** (`variant` / `color` / `size` /
   `gap`), then `--a-*` tokens in a scoped CSS rule. **Never** inline
   `style="--token: …"` per instance, and never Tailwind/utility classes
   on AdiaUI internals — e.g. a primary danger button is
   `<button-ui variant="primary" color="danger">`, not a `--button-bg`
   override. See `tokens.md`.

## Where to find more

- Live demos + full catalog: https://ui-kit.exe.xyz/site/
- Component reference pages: https://ui-kit.exe.xyz/site/components/<name>