tirify-ui-kit

Shared design system for the Tirify frontends. npm-workspaces monorepo,

published to the GitLab Package Registry under the `@tirify` scope.

Consumers:

• **tirify-admin** — Next.js 16, Tailwind v4 (canonical origin of the tokens)
• **tirify-frontend-common-panel** — Vite, Tailwind v4

Packages

Commands

npm install            # link workspaces

npm run build          # build all packages

npm run check          # verify generated output is not stale (CI gate)

Docs

• **[AGENTS.md](AGENTS.md)** — rules & conventions for changing this repo (read first).

Per-package: [design-tokens](packages/design-tokens/AGENTS.md), [ui-kit](packages/ui-kit/AGENTS.md).

• **[DESIGN.md](DESIGN.md)** — the visual design language (colours, type, motion, component vocabulary).
• [docs/PLAN.md](docs/PLAN.md) — approved design + phased rollout + migration notes
• [docs/GITLAB_REGISTRY.md](docs/GITLAB_REGISTRY.md) — how to publish/consume via GitLab

CI/CD и ArgoCD деплой

Текущий production-like технический деплой UI kit — это статический snapshot документации и build-артефактов пакетов, обслуживаемый nginx в k3s.

URL

• `https://tirify-ui-kit-prod-apps-k3s.tirify.com`
• Healthcheck: `https://tirify-ui-kit-prod-apps-k3s.tirify.com/healthz`

Pipeline

GitLab CI запускается на `main` и выполняет:

1. `validate`:

- `npm ci --no-audit --no-fund`

- `npm run build`

- `npm run check`

- `npm run typecheck`

- `npm run build:static`

2. `build_image`:

- собирает Docker image через Kaniko;

- пушит в Harbor:

- `harbor-ecosys.tirify.com/tirify-frontend/tirify-ui-kit:<branch>-latest`

- `harbor-ecosys.tirify.com/tirify-frontend/tirify-ui-kit:<branch>-<sha>`

3. `deploy_gitops`:

- обновляет image tag в `tirify-gitops/deployment`;

- ArgoCD синхронизирует `tirify-ui-kit-prod`.

GitOps

• GitOps repo: `tirify-gitops/deployment`
• ArgoCD app: `tirify-ui-kit-prod`
• Manifests path: `apps/tirify-ui-kit/prod`
• Namespace: `prod`
• Ingress host: `tirify-ui-kit-prod-apps-k3s.tirify.com`

Package Registry

Публикация npm-пакетов выполняется только на git tag job `publish_packages`:

• `@tirify/design-tokens`
• `@tirify/ui-kit`

Обычный push в `main` только валидирует пакеты и деплоит статический snapshot в k3s.

GitLab Package Registry

Publishing & consuming via GitLab Package Registry

How it differs from a plain git repo

A **git repo** stores source code; you `git clone` it and get files. A **package

registry** stores *published, versioned build artifacts* (npm tarballs) addressed by

`name@version`. Consumers never clone `tirify-ui-kit` — they run

`npm install @tirify/design-tokens@^0.1.0` and npm downloads the tarball you published.

So there are two separate things:

• the **git project** `tirify-ui-kit` (source, CI) — lives in GitLab like any repo;
• the **npm registry** attached to that same GitLab project — where `npm publish`

uploads tarballs and where `npm install` resolves the `@tirify` scope.

Each published version is **immutable** — you can't overwrite `0.1.0`; you bump to

`0.1.1`. That's the whole point: consumers pin a version and it never changes under them.

Endpoints

**You always publish to a _project_ endpoint.** For install, the group endpoint is

nicest (one line resolves every `@tirify` package). `<PROJECT_ID>` / `<GROUP_ID>` are

shown on the project/group overview page in GitLab. Self-hosted: swap `gitlab.com`

for your host.

Auth tokens

`.npmrc` auth reads an env var — never commit a real token.

**Cross-project CI gotcha:** when the `tirify-admin` pipeline installs `@tirify/*`

using its own `CI_JOB_TOKEN`, `tirify-ui-kit` must allow it: tirify-ui-kit → Settings →

CI/CD → **Job token permissions** → add the consuming projects to the allowlist.

Simpler alternative for consumers: a **group Deploy Token** with `read_package_registry`.

Publishing (this repo)

1. Add `publishConfig` to each publishable package's `package.json`:

```json

"publishConfig": {

"registry": "https://gitlab.com/api/v4/projects/<PROJECT_ID>/packages/npm/"

}

```

2. Root `.npmrc` already has the scope + auth template — fill in `<PROJECT_ID>` and

export `GITLAB_NPM_TOKEN` (or rely on CI_JOB_TOKEN in CI).

3. Bump the version, build, publish:

```bash

npm run build -w @tirify/design-tokens

npm version patch -w @tirify/design-tokens

npm publish -w @tirify/design-tokens

```

CI publish job (`.gitlab-ci.yml`)

publish:tokens:

  stage: publish

  image: node:22

  rules:

    - if: '$CI_COMMIT_TAG'          # publish only on a git tag

  before_script:

    - |

      cat > .npmrc <<EOF

      @tirify:registry=https://gitlab.com/api/v4/projects/${CI_PROJECT_ID}/packages/npm/

      //gitlab.com/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN}

      EOF

  script:

    - npm ci

    - npm run build

    - npm publish -w @tirify/design-tokens

Consuming (in tirify-admin / common-panel)

Add an `.npmrc` at each consumer repo root:

@tirify:registry=https://gitlab.com/api/v4/groups/<GROUP_ID>/-/packages/npm/

//gitlab.com/api/v4/groups/<GROUP_ID>/-/packages/npm/:_authToken=${GITLAB_NPM_TOKEN}

Then it's an ordinary dependency:

npm install @tirify/design-tokens

// package.json

"dependencies": { "@tirify/design-tokens": "^0.1.0" }

In CI, replace the auth line's token with `${CI_JOB_TOKEN}` (after allowlisting) or

a group deploy token, generated the same way as in the publish job above.

Local development without publishing

While iterating you don't want to publish on every change. Use `npm link` or a

`file:` dependency to point a consumer at your local checkout:

# from a consumer repo:

npm install file:../tirify-ui-kit/packages/design-tokens

# or:  npm link @tirify/design-tokens   (after `npm link` inside the package)

Switch back to the `^0.1.0` registry version before committing the consumer.