trustvid-ui-library

TrustVid shared React UI library: components, tokens, and styles. Published to npm as @trustvid/design-system.

Why this package exists

This repo is the source of truth for TrustVid UI primitives (Tv*), theme tokens, and bundled styles. It was extracted from trustvid-ai-platform/packages/design-system so the design system can be versioned and published independently (same pattern as trustvid-remotion-compositions).

Primary consumer today: trustvid-ai-platform ("@trustvid/design-system": "^0.1.3" from npm after publish).

Package name

@trustvid/design-system

Entry points

| Import | Purpose | |--------|---------| | @trustvid/design-system | Components, tokens, DesignSystemProvider, reactstrap re-exports | | @trustvid/design-system/styles.css | Bundled design-system CSS (import once in the host app entry) |

Published artifacts live under dist/ only (package.json files).

Local development

npm ci
npm run lint:ci
npm run build
npm run test

Watch TypeScript:

npm run build:watch

Theming (host app)

1. Import styles once before app components:

import "@trustvid/design-system/styles.css";

2. Wrap the tree with DesignSystemProvider (optional token overrides).

3. Use buildCssVariablesFromColors + apply variables on :root for account branding.

See docs/DEVELOPER_README.md for the full guide.

Versioning and release flow

Required Bitbucket repository variables

Add under Repository settings → Pipelines → Repository variables (mark NPM_AUTH_TOKEN as Secured):

| Variable | Required | Notes | |----------|----------|--------| | NPM_AUTH_TOKEN | Yes | npm Automation token with publish access for @trustvid/design-system | | NPM_REGISTRY_URL | No | Defaults to https://registry.npmjs.org/ | | NPM_REGISTRY_HOST | No | Defaults to registry.npmjs.org |

scripts/npm-registry-env.sh only sets registry URL/host defaults; it does not replace NPM_AUTH_TOKEN when Bitbucket already provides it.

Pipeline behavior

• main branch: validate (lint:ci, build, test:unit, test:integration, package:check) → auto bump + publish
• Custom pipelines: publish-current-version, release-patch, release-minor, release-major

Release runs scripts/release.sh (includes test:workflow before publish). Duplicate published versions fail fast. Before npm ci, release.sh runs npm whoami; if the npm token is expired or invalid, the log shows npm registry authentication failed instead of the misleading 404 from npm publish.

Auto bump rules on main

When BUMP_TYPE is not set, bump is derived from the latest commit message:

• #major or BREAKING CHANGE → major
• #minor or feat(...) / feature → minor
• default → patch

Git push for release commits

Bitbucket clones over HTTPS; release.sh rewrites origin to [email protected]:<workspace>/<repo>.git in Pipelines.

1. Repository settings → Pipelines → SSH keys — generate/add key (required for bump-and-publish push).
2. HTTPS fallback: set secured BITBUCKET_API_TOKEN if you do not use SSH keys.
3. Emergency: RELEASE_SKIP_GIT_PUSH=true publishes without pushing the version bump commit back to main (currently enabled — main branch restrictions rejected pipeline pushes).

After each release, ensure package.json version in git matches npm, or allow the pipeline identity to push to main (Branch permissions / merge checks).

Optional: RELEASE_GIT_NAME, RELEASE_GIT_EMAIL.

Install in consumers (after first publish)

npm install @trustvid/design-system

Configure .npmrc for your private registry if not using the public npm registry.

Tests

npm run test:unit
npm run test:integration
npm run test:workflow

Tests live under tests/unit/, tests/integration/, and tests/workflow/ (mirroring src/). See tests/README.md.

Extended documentation

• docs/DEVELOPER_README.md — tokens, components, branding, troubleshooting