Cobre Design System V3 (@cobre-npm/ds-v3)

Vue 3 + TypeScript component library for the Cobre platform, documented and developed through Storybook.

Heads up: this project uses pnpm, not npm. Running npm install will generate a stray package-lock.json and can produce a broken node_modules. Always use pnpm.

Prerequisites

• Node.js ≥ 20 (CI uses Node 24).
• pnpm ≥ 10. The exact version is pinned via the packageManager field in package.json, so the simplest setup is to let corepack match it:

  corepack enable
  

  To install manually instead: npm install -g pnpm.

Project Setup

pnpm install

On a fresh checkout, pnpm may prompt you to approve build scripts for native dependencies (esbuild, @swc/core, @parcel/watcher, unrs-resolver, vue-demi). If it does, approve them:

pnpm approve-builds

Then re-run pnpm install if needed.

postinstall downloads the headless Chromium the render lane tests against (~95 MB, once per machine, idempotent). It lives in postinstall rather than in the test script because the browser is a dependency of the suite, and because more than one command runs that suite — putting it in test left every other entry point without a browser. SKIP_TEST_BROWSER=1 skips it, for any image that installs dependencies and never runs the suite — the Dockerfile that builds the Storybook showcase sets it. On Alpine it skips itself, because Playwright publishes glibc builds only. --ignore-scripts skips it too, and pnpm test:browsers gets it back.

Develop with Storybook (primary workflow)

This is a component library — day-to-day development happens in Storybook, which renders every component with its variants and docs:

pnpm storybook

Opens at http://localhost:6006.

pnpm dev (plain vite) only serves the minimal src/main.ts / App.vue harness. It is not the component gallery — use pnpm storybook for normal development.

Common Commands

Testing

The suite is split in two lanes because the two numbers would not mean the same thing (ADR-0008):

• Render lane (test:stories) — every story mounts without error, in headless Chromium via @storybook/addon-vitest. It is binary: no percentage is attached to it. Storybook marks a line covered when a story renders it while asserting nothing, so a percentage built that way measures exercised, not verified.
• Logic lane (test:unit) — the non-component sources (src/**/*.ts minus stories, tests, type-only modules, barrels and the dev entry), with coverage thresholds enforced.

The coverage floor ratchets

coverage-floor.json holds the thresholds, and it is a floor, not a target. It was set to what the repo measured the day the gate was switched on — there is no retroactive 95% and no backfill of the existing components as a precondition. It may only rise:

• scripts/check-invariants.mjs fails the build when any number in the file drops below the base ref. It is a change-level check, so it runs in CI, or locally with pnpm test:invariants -- --base origin/trunk.
• src/utils/repo-invariants.test.ts fails when vitest.config.mts stops reading its thresholds from that file, which would otherwise be a silent way to lower the gate to nothing.

To raise the floor: improve coverage, run pnpm test:unit, and copy the reported totals into coverage-floor.json.

Adding tests

Component behaviour belongs in a story — it is the lane that already exists and the one consuming apps read as documentation. Reach for the logic lane when the subject is a composable, a pure function or shared state.

Recommended IDE Setup

VSCode + Vue - Official (Volar) (disable Vetur).

Type Support for .vue Imports in TS

TypeScript can't type .vue imports on its own, so we use vue-tsc for type checking and the Vue (Volar) extension to make the editor's TS language service aware of .vue types.

Project Structure & Conventions

See CLAUDE.md for the full architecture overview: Atomic Design layout (atoms/molecules/organisms), the Cobre* / co- naming conventions, the SCSS token system, and how to add a new component (each lives in its own folder with a .vue, a .stories.ts, and an index.ts, and must be exported from src/components/index.ts and src/index.ts).

Troubleshooting

• npm run dev / npm install fails or behaves oddly — you're using the wrong package manager. Delete any package-lock.json, then use pnpm install.
• pnpm asks to approve build scripts — run pnpm approve-builds, then re-run pnpm install if needed.
• Stale or broken node_modules — rm -rf node_modules && pnpm install.