@etus/seven

CLI that distributes Seven Design System components as source into your React project — you own the code, no @etus/ui runtime dependency. Seven-native, shadcn-style, with per-component token slicing so a page ships only the tokens it uses.

npx @etus/seven init                 # foundation (tokens + @theme + base layer + cn) + seven.json
npx @etus/seven add button kbd       # copy components + their sliced tokens into your src

Commands

• seven init — installs the curated foundation (semantic tokens, @theme mappings, base layer, scrollbar, the cn helper), detects your import alias from tsconfig/jsconfig paths (falls back to @/), and writes seven.json.
• seven add <component...> — resolves the component's registryDependencies, writes the source into your project (rewriting imports to your alias), and reports the npm packages to install.

Flags

• --registry <path|url> — registry manifest (default: the registry bundled in this package).
• --cwd <dir> — target project (default: current directory).
• --overwrite / --force — replace files that already exist (default: keep your customized files).
• --dry-run — report what would be written/skipped/overwritten without touching the filesystem.
• --diff — show a line diff (incoming vs your current copy) for each file that already exists and differs.
• --install — install the npm dependencies with your package manager (detected from the lockfile; default is to just print the command).

Using a hosted registry (CDN)

By default the CLI reads the registry bundled in the installed package — offline-capable and versioned with the CLI binary. Because the registry ships inside the npm tarball, a CDN like jsDelivr serves it with zero extra hosting, so you can opt into the latest published registry without upgrading the CLI:

# latest published registry
seven add button --registry https://cdn.jsdelivr.net/npm/@etus/seven/registry/registry.json

# pin to a specific version for reproducibility
seven add button --registry https://cdn.jsdelivr.net/npm/@etus/[email protected]/registry/registry.json

The CLI fetches the component source files relative to that URL automatically. Keep the default (bundled) unless you specifically want a newer registry than your installed CLI.

Updating a component

There is no update command and no version lockfile — you own the copied code, so updates are git-based (same model as shadcn):

seven add button --diff --dry-run   # preview what would change, write nothing
seven add button --overwrite        # pull the latest, replacing your copy
git diff                            # reconcile your customizations with the upstream change

--diff shows what overwriting would do before you commit to it; git is the merge tool. There is intentionally no stored baseline or 3-way merge.

Safety

seven add never overwrites a file whose content has diverged from the registry (i.e. one you've customized) unless you pass --overwrite. Identical content is an idempotent no-op.

When to use this vs @etus/ui

See docs/distribution/react-consumption.md — the registry/CLI suits weight-sensitive public pages (blog, quiz) and apps that customize; package mode (@etus/ui) suits apps that consume Seven broadly and prefer a single auto-updating dependency.