uikit

Imported from acronis/uikit (AGENTS.md). Install upstream with npx skills add acronis/uikit. Copyright stays with the author.

AGENTS.md

Single source of truth for AI agents working in acronis/uikit.

This file is the root index. It is intentionally short (~120 lines) so it fits in any context window. Specifics live in:

• ./context/*.md — cross-cutting topics shared across workspaces
• <workspace>/AGENTS.md — quirks specific to one workspace

Each workspace also has a sibling CLAUDE.md containing only @AGENTS.md so Claude Code's nested auto-load (it walks up from CWD) picks the workspace's context when you work inside that subtree.

Repository overview

acronis/uikit is a pnpm monorepo containing a React component library, a documentation site, two design-data packages (assets and tokens), and a build-tooling tier. The library and the two design-data packages are published; the docs app and the tools are private.

The repo is organized into four top-level directories, each with a distinct role:

• context/ — Markdown instructions read by both LLMs and humans (cross-workspace conventions; each workspace also has its own).
• apps/ — applications that get deployed (the docs site). Private.
• packages/ — packages published to the npm registry.
• tools/ — scripts that automate, translate, or execute operations (e.g. token→CSS builds). Private; never published.

Workspaces

packages/ holds the published workspaces:

• packages/ui-react/ houses the published Base UI library (@base-ui/react as a direct dep), themed by @acronis-platform/tokens-pd. All component work goes here.
• packages/icons-react/ — published React icon components, generated from @acronis-platform/design-assets (24px masters + scale/stroke rules baked into a size prop). Per-pack subpath exports, tree-shakeable.
• packages/design-tokens/ and packages/design-assets/ — the published design-data packages. These ship JSON (and, for assets, bundled binaries) only: no build step, no runtime API. Their one real script is validate (ajv); build/dev/clean/lint/typecheck are no-ops and test aliases validate.
• packages/tokens-pd ships the consumable token artifacts (per-brand CSS, per-component CSS, DTCG). It has no build logic of its own — its build delegates to tools/style-dictionary, which writes the generated (and committed) output into the package.

tools/ holds private (unpublished) build tooling:

• tools/style-dictionary/ — a Style Dictionary v5 translation pipeline that builds @acronis-platform/design-tokens into per-brand CSS custom properties. Its real script is build; output lands in a gitignored dist/.
• tools/figma-design-assets-sync/ — exports _assetsource/* icon SVGs from a Figma frame, SVGO-optimizes them, and regenerates the matching packages/design-assets pack (packs/<pack>/*.svg + packs/<pack>.json). Run via tsx (no build step) from the consumer package: pnpm --filter @acronis-platform/design-assets sync. The write is diff-gated — it prints added/modified/deleted and reverts unless approved (--dry-run, --yes).

Design tokens are refreshed from Figma by a standalone project outside this monorepo (acronis-tokens-updater), which writes packages/design-tokens/tiers/*.json directly; this repo only validates them and rebuilds tokens-pd.

Scripts vocabulary

Every workspace exposes the same script names. Run any of them as:

• pnpm -r <name> — all workspaces, topological order
• pnpm --filter <package> <name> — single workspace

Names: dev · build · test · test:watch · lint · lint:fix · typecheck · clean

Root-only scripts (from the repo root):

• format, format:check — Prettier across the tree
• changeset, version, release — Changesets CLI passthroughs
• husky — runs lint-staged + typecheck (used by the pre-commit hook)

Tools follow the same vocabulary: tools/style-dictionary's real work is build (with test/test:watch running vitest); only dev is a no-op.

How agents should navigate this repo

1. Always read this file first — it tells you which workspace owns your task.
2. Read the workspace's AGENTS.md for the area you're editing. The workspace owns its own conventions, testing, theming, etc. in a workspace-local context/ directory.
3. Pull from this repo's root ./context/<topic>.md when relevant — it holds only the truly cross-workspace topics.

Cross-workspace context is intentionally minimal. Anything specific to how a particular workspace is built, tested, or styled lives inside that workspace, never here.

Always-loaded cross-cutting context

@context/conventions.md @context/commits.md

Cross-cutting context (read on demand)

• context/releasing.md — Changesets workflow that applies to any published workspace in the monorepo.
• context/roadmap.md — product roadmap (epics, phases, v1 scope/timeline); tracked on GitHub Project #3 as issues #102–108. Companion task breakdowns: context/backlog-p2-primitives.md, context/backlog-p3-p4.md.
• context/e1-theme-delivery.md — E1 (#102) theme-delivery implementation proposal: how the open theme sub-issues (#172/#173/#175/#101/#177) get built on the shipped tokens-pd pipeline, and what's reused from the legacy stack.
• context/project-board.md — how we run Project #3: epic/task model, status lifecycle + gates, fields, views, and automation.
• context/next-gen-components-migration.md — migrating the component token tier to Figma's next-gen brand.components (Option A naming, emitter rework, tokens-pd impact, ui-react per-component re-theme). §9 tracks execution status, the remaining ui-react backlog, and the Radio/Search/Select token gap.
• packages/ui-spec/context/component-specs-proposal.md — Proposed (not yet adopted): framework-agnostic component specs + a machine-readable design grammar, to support future non-React implementations and agent tooling.
• context/kit-consistency-audit-proposal.md — Proposed (not yet adopted): cross-component consistency rules (grammar), a common-inconsistency checklist, a complete-screen consistency audit (render real screens → structural + AI detectors), reference-implementation diffing, and a self-improving feedback loop + new AI skills. Extends the component-specs proposal above.

Tooling preconditions

• Package manager: pnpm 10.27.0 (declared in root packageManager). Enable via corepack enable or npm install -g pnpm@10.27.0.
• Node: 22.x (CI uses Node 22).
• TypeScript for all new source code.
• The catalog block in pnpm-workspace.yaml is the single source of truth for shared dependency versions — bump there, not per workspace. Respect intentional drift noted in catalog comments.
• Use pnpm --filter <package> <script> over cd <workspace> && pnpm <script>.
• Never use --no-verify to bypass commit hooks; fix the underlying issue. The pre-commit hook runs lint-staged + typecheck.

What this repo does NOT have

To prevent agents inventing things from outdated knowledge:

• No Vue. The repo is React-only. Any .vue reference is stale.
• No VitePress. Docs are Next.js + Fumadocs at apps/docs/.
• No packages/documentation/ or packages/examples/. Those paths never existed in this repo.