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.

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

| Command | What it does | |---|---| | pnpm install | Install dependencies | | pnpm storybook | Run Storybook dev server on port 6006 (main dev workflow) | | pnpm dev | Bare Vite dev harness (src/main.ts) — rarely needed | | pnpm build | Type-check + build the publishable library into dist/ | | pnpm build-storybook | Build the static Storybook site | | pnpm test:unit | Run unit tests with Vitest | | pnpm test | Run Storybook interaction tests (test-runner) | | pnpm lint | Lint & auto-fix with ESLint |

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.