@powered-by-array/ui

ArrayHQ design-system UI package for React web consumers.

License: This package is published as UNLICENSED (proprietary). It is not open source and not free for unrestricted use by third parties. Use is limited to scenarios covered by your agreement with Powered By Array; contact your Array representative if you are unsure whether your use is permitted.

Current scope

This package ships ESM + type declarations, token helper exports, and UI primitives that are source-aligned with pba-webapp src/components/ui/*: cva + Tailwind class strings + cn (clsx + tailwind-merge).

Consumers must use Tailwind CSS v4 with the same @theme / :root / .dark theme as PBA Web (globals.css), so utilities like bg-primary match the app (purple primary, etc.). The optional @powered-by-array/tokens/tokens.css is for JSON-driven tooling, not required for these components.

It intentionally does not require styled-components.

Logos: React vs hosted static files

• React: import { ArrayLogo } from "@powered-by-array/ui/logos" for inline, resizable SVGs.
• Hosted (Storybook / design site): yarn storybook:build also writes versioned files under storybook-static/logos/{version}/ (for example array-logo.svg), using the same markup as src/logos/index.tsx. Public URLs look like https://design.arrayhq.com/logos/<version>/array-logo.svg where <version> matches this package’s version (or DESIGN_SYSTEM_SITE_VERSION / release tag in CI).

Keeping Storybook aligned with PBA Web

In this monorepo, .storybook/webapp-parity.css mirrors pba-webapp src/styles/globals.css (Tailwind imports, @theme primitives, shadcn semantic tokens, :root / .dark). Any change to the web app’s global theme should be reflected here so Storybook and package consumers stay visually consistent. Do not drop Storybook-specific directives (for example @source paths for packages/ui and stories/) when porting updates.

.storybook/array-font-scale.css mirrors pba-webapp src/styles/array-font-scale.css and is imported from webapp-parity.css. Update both mirrors when the font scale or typography tokens change in the web app.

See also docs/TOKEN_GAP_MATRIX.md for how tokens.css, Tailwind, and these mirrors relate.

CI quality gate parity

Workflow: .github/workflows/ci-quality-gate.yml (on pull_request and push to main). It uses Node.js 24, enables Corepack, activates Yarn 4.6.0, caches Berry artifacts, then runs:

| Step | Command | |------|---------| | Install | yarn install --immutable | | Lint | yarn lint | | Typecheck | yarn typecheck | | Tests | yarn test (Vitest) | | Build tokens | yarn workspace @powered-by-array/tokens build | | Build UI | yarn tsc -p packages/ui/tsconfig.json | | Storybook | yarn storybook:build | | Axe | yarn axe:storybook |

Run the same commands locally (UI build can use yarn workspace @powered-by-array/ui build instead of yarn tsc -p …; both invoke tsc for the UI package):

corepack enable
corepack prepare [email protected] --activate
yarn install --immutable
yarn lint
yarn typecheck
yarn test
yarn workspace @powered-by-array/tokens build
yarn workspace @powered-by-array/ui build
yarn storybook:build
yarn axe:storybook

Root yarn build runs tokens + UI builds in order and matches what yarn prestorybook runs before Storybook.

Axe threshold

yarn axe:storybook scans a small allowlist of Storybook story URLs from storybook-static and fails CI on serious or critical violations. Lower-severity findings (moderate, minor) are reported by Storybook a11y addon and should be triaged, but they do not fail the gate.

Installing @powered-by-array/ui from npm

This monorepo publishes @powered-by-array/ui and @powered-by-array/tokens to the public npm registry (npmjs.org) under the @powered-by-array scope (packages are listed publicly for install convenience only—see the license notice above). No .npmrc scope routing or NODE_AUTH_TOKEN is required for installation.

yarn add @powered-by-array/ui @powered-by-array/tokens react react-dom

react and react-dom are peer dependencies of @powered-by-array/ui.

For npm releases and Trusted Publishing (OIDC) from GitHub Actions, see npm’s publish documentation and this repo’s .github/workflows/publish-packages.yml.

Chart visualization (recharts)

Chart primitives (ChartContainer, ChartTooltip, ChartLegend, etc.) are built on Recharts. recharts is a peer dependency of @powered-by-array/ui (see peerDependencies in packages/ui/package.json, currently ^3.2.1). Install it in any app that uses those exports:

yarn add recharts

If your product does not use charts, you can skip recharts; tree-shaking and omitting the dependency only matter once you import chart components from @powered-by-array/ui.

For GitHub guidance on npm releases and Trusted Publishing, see: https://docs.npmjs.com/trusted-publishers

Release and versioning policy (semantic-release on main)

This repo uses semantic-release. On each push to main:

• semantic-release analyzes commit messages (Conventional Commits) to determine the next semver version.
• packages/tokens and packages/ui are both version-bumped to that release version.
• Packages are published to npmjs.org in dependency order (@powered-by-array/tokens first, then @powered-by-array/ui).
• A release tag (vX.Y.Z) and changelog update are produced automatically.

Conventional commit guidance

• feat: → minor release
• fix: → patch release
• feat!: or BREAKING CHANGE: in commit body/footer → major release
• chore:, docs:, refactor: without breaking change → no release

First publish checklist

If no release has happened yet, verify before the first main merge:

• GitHub Actions workflow publish-packages.yml is enabled and targets the npm-publish environment.
• Workflow permissions include contents: write, pull-requests: write, issues: write, and id-token: write (for npm Trusted Publishing).
• npmjs.org: scope @powered-by-array is ready; an initial manual publish (or token-based CI run) exists so each package can bind Trusted Publishers → GitHub Actions → this repo → workflow publish-packages.yml → environment npm-publish.
• Commits merged to main use Conventional Commit prefixes so semantic-release can compute versions.

Older versions may still appear on GitHub Packages; new releases use npm only.

Next.js consumption

@powered-by-array/ui is published as ESM and is tree-shakeable ("sideEffects": false).

Use named imports so bundlers can remove unused exports:

import { countLeafTokens, getTokenTree } from "@powered-by-array/ui";

To expose token CSS variables in your app, import tokens CSS once in your app entry (app/layout.tsx for App Router or pages/_app.tsx for Pages Router):

import "@powered-by-array/tokens/tokens.css";

Styling and primitive direction (pba-webapp aligned)

Planned web primitives in this package should follow the same stack as pba-webapp:

• Tailwind CSS utility classes for styling
• class-variance-authority + clsx + tailwind-merge for variants/class composition
• Radix UI primitives for behavior and accessibility where needed
• CSS variables from @powered-by-array/tokens for design-token values
• next-themes for app-level light/dark mode integration

This package should avoid introducing a parallel styled-components layer unless that decision is made explicitly at the program level.