# AI adoption guide

Use this when connecting the Bark brand system to another codebase.

Versioning is SemVer (`CHANGELOG.md`): major = ломающие визуальные/контрактные
изменения, minor = новые компоненты, patch = правки значений. Каждый продукт
показывает свою версию бренда в мета сайдбара: `Bark UI v2.0.0` — так отставшие
продукты видны с одного взгляда.

## Option A (preferred): npm package from the GitLab registry

`.npmrc` in the product repo:

```ini
@bark:registry=https://gitlab.toolsfs.synology.me/api/v4/projects/63/packages/npm/
//gitlab.toolsfs.synology.me/api/v4/projects/63/packages/npm/:_authToken=${BARK_NPM_TOKEN}
```

```bash
npm install @bark/brand-system@^2
```

Import:

```css
@import "@bark/brand-system/tokens/brand.css";
```

```js
module.exports = { presets: [require("@bark/brand-system/tokens/tailwind.preset.cjs")] };
```

Docs for agents live in `node_modules/@bark/brand-system/` (AGENTS.md, docs/…).
Lockfile pins the exact version; `npm outdated` shows drift; `npx bark-check`
lints conformance.

## Option B: versioned static URLs (no-build products: PHP, plain HTML)

Every release is archived under `dist/` and served at **https://static.bybark.net**
(auto-deployed by CI from `main`; the whole brand site lives there too —
`/registry.html`, `/index.html`):

```html
<link rel="stylesheet" href="https://static.bybark.net/dist/v2.0.0/brand.css">
<script type="module" src="https://static.bybark.net/dist/v2.0.0/toast.snippet.js"></script>
```

Pinned URLs never change content (`dist/vX.Y.Z/` is append-only); upgrading =
changing one version number. `dist/latest/` and `dist/version.json` exist for
tooling, not for production pins.

## Option C: vendor copy / submodule (legacy, still supported)

```bash
git submodule add <gitlab-url>/bark-brand-system.git vendor/bark-brand-system
```

Then add this line to the target repo's `AGENTS.md`:

```md
For brand/UI work, read `vendor/bark-brand-system/AGENTS.md` first.
```

## CI conformance job (all options)

Include the ready-made job in the product's `.gitlab-ci.yml` — every MR gets a
`bark:check` gate (naming, favicon acceptance, forbidden SSO photo transports,
`transition: all`, brand version freshness):

```yaml
include:
  - project: v.shurygin/bark-brand-system
    ref: main
    file: ci/bark-brand.gitlab-ci.yml
```

Optional variables: `BARK_MIN_VERSION: "2.0.0"`, `BARK_DIST_URL` (for option B).

## Deploy job (all options)

Deployment follows one contract — `docs/DEPLOY.md`: GitLab CI on the
`runner-dev` runner only, push to the default branch = deploy, manual
rsync/scp is forbidden. Products include the ready-made job and set the
`DEPLOY_*` variables:

```yaml
include:
  - project: v.shurygin/bark-brand-system
    ref: main
    file: ci/bark-deploy.gitlab-ci.yml
```

To migrate an existing product, run the agent prompt from
`templates/DEPLOY.prompt.md`.

## AI checklist for a product repo

The target app is the source of truth for **what exists**. Bark is the source of
truth for **how existing UI is styled and behaves**. Brand examples are visual
references, not a backlog: never add a card, chart, metric, page, button, or
business flow only because it appears in the brand kit.

When an AI agent applies Bark branding, it should check:

- sidebar and mobile header logo
- the sidebar-footer identity block `.bark-sidebar__user` — SSO photo (initials
  fallback via `initialsFromName()`), name + email with ellipsis, icon-only
  `Выйти` (Lucide `LogOut`) at its right end — the shell's single identity
  point; no avatar/name in the page header (`barkone` = documented exception)
- pinned page density: `.bark-main` `24px 32px 40px`, sections 24px apart,
  grids 16px, panel body 20px (`--dense` `12px 16px`), table rows 44/36px —
  no airier screens
- favicon wired via the generated `favicon.head.html` (SVG + PNG + apple-touch
  + manifest + theme-color = product colour; stale icons removed)
- PWA manifest
- document title and meta tags
- Onest on every interface heading including H1/H2; Red Hat Display only on logo/wordmark
- route progress on every page transition
- immediate spinner and action label on every async/long-running button
- existing SSO login button stays busy with `Входим…` until redirect or error
- local loading/empty/error states that do not block unrelated interface areas
- list toolbars (32px controls, accent filter chips, «Сбросить») and pagination
  (25/50/100, mono range counter, no infinite scroll)
- ONE toast system (`templates/toast.snippet.js`) for async results; inline
  `.bark-alert` for persistent region state; validation stays at the field
- ONE data formatter (`templates/format.snippet.js` / `docs/DATA_FORMATS.md`):
  МСК everywhere, `ДД.ММ.ГГГГ`, 24h, comma decimals, `₽` with kopecks, Russian
  compact units, pinned relative-time and duration ladders
- employee photo from current SSO `picture` in the existing Avatar, with initials fallback
- active navigation color
- chart and metric color usage; new charts = Apache ECharts + bark theme
  (self-hosted, ≤4 series), legacy charts keep their library on the same tokens
- table sorting (single active sort, aria-sort) and row actions (≤2 inline,
  kebab + .bark-menu, destructive only in the menu with confirmation)
- old product names in copy
- hard-coded colors that should become tokens
- spaced/camel/snake product wordmarks that should become no-space `bark<module>`

Loading markup and behavior come from `templates/loader.html` and
`templates/loader.snippet.js`; placement and timing are mandatory rules in
`docs/COMPONENT_RULES.md`.

## Durable prompt for a target repo

Use `templates/AGENTS.brand-snippet.md` as the durable prompt. Keep it in the
target repository so future sessions inherit the brand rules automatically.

For shared AI memory across multiple projects, use
`templates/PROJECT_MEMORY.prompt.md`. It only covers adding or updating the
project card in the shared employee catalog.

Short task launcher after the durable prompt is installed:

```text
Адаптируй существующий проект по AGENTS.md и подключённому Bark Brand System.
Не проектируй новый интерфейс и не добавляй отсутствующие элементы. Сначала
изучи текущее состояние, затем выполни минимальную адаптацию и проверь результат
на desktop/mobile и light/dark.
```