@phronetic-admin/design-system

The CLI for the Phronetic design system. Wires the DS 1.0 theme into an existing Next.js, Vite + React, or Create React App project (Tailwind v4 is installed automatically for Next.js; Vite and CRA projects must already have Tailwind v4 configured), then lets you add components and sections from a registry of 1,100+ entries.

Components are copied into your project as source files — you own them. The CLI is only needed when setting up or adding new components.

This package pairs with @phronetic-admin/design-tokens — the versioned CSS custom properties (colors, typography, spacing, radius) that every component references. pds setup installs and wires up design-tokens for you automatically; you only need to install it yourself if you're skipping the CLI (see design-tokens's README for manual setup).

Private package. Published under the @phronetic-admin npm org with restricted access. You must be a member of the org (or hold a granted collaborator/read token) and be authenticated (npm login) before npm install or npx will resolve it.

Quick start

# Wire the design system into an existing Next.js, Vite + React, or CRA app (DS 1.0 theme by default)
npx @phronetic-admin/design-system setup

# Or specify the framework and theme up front, non-interactively
npx @phronetic-admin/design-system setup --framework vite --theme phronetic -y

# Add components
npx @phronetic-admin/design-system add button card dialog

# Add pre-built marketing sections
npx @phronetic-admin/design-system add --sections hero-1 pricing-3 footer-2

Or install globally for shorter commands:

npm install -g @phronetic-admin/design-system
pds setup
pds add button

What setup does

pds setup requires an existing Next.js, Vite + React, or Create React App project (it errors out with instructions if no package.json is found — it does not scaffold a new project). Tailwind v4 is installed automatically for Next.js. Vite and CRA targets instead require Tailwind v4 to already be configured; pds setup checks for this and errors out with setup instructions if it's missing.

Pass --framework <next|vite|cra> to specify the target explicitly, or omit it and pds setup will prompt you interactively.

By default, everything is written as TypeScript (.tsx/.ts). If your project is plain JavaScript, pass --js (or answer the JavaScript prompt) and pds setup, pds add, pds diff, and pds update will all emit .jsx/.js files instead — types, interfaces, generics, and import type are actually stripped (via esbuild), not just renamed, and typescript/@types/* are skipped from installed dev dependencies.

Running setup:

1. Installs @phronetic-admin/design-tokens as a project dependency (the DS 1.0 CSS variables)
2. Writes your project's main CSS file (src/app/globals.css for Next.js, src/index.css for Vite/CRA by default — override with --css <path>) with @import "@phronetic-admin/design-tokens/css" so token variables are available everywhere
3. Scaffolds src/assets/icons/ with a Lucide provider and 18 brand SVGs
4. Writes pds.config.json at the project root
5. Installs @phronetic-admin/design-tokens, clsx, tailwind-merge, class-variance-authority, lucide-react, and @base-ui/react as dependencies, plus typescript, React/Node type packages, tw-animate-css, and shadcn as dev dependencies (tailwindcss and @tailwindcss/postcss are also installed for Next.js — Vite and CRA are expected to already have Tailwind v4 configured)

Themes

DS 1.0 is the default. Pass --theme to choose another:

pds setup --theme ds1.0      # Phronetic brand (default)
pds setup --theme phronetic  # Phronetic legacy palette
pds setup --theme default    # Clean, minimal (zinc)
pds setup --theme indigo     # Soft, rounded (violet)
pds setup --theme brutalist  # Bold, hard shadows (hot pink)

Skip all prompts with -y:

npx @phronetic-admin/design-system setup --theme ds1.0 -y

Skip TypeScript and emit plain JavaScript instead:

npx @phronetic-admin/design-system setup --js -y

Commands

pds add

Copies components into src/components/ui/. Resolves transitive dependencies automatically — adding data-table also installs table, button, input, badge, etc.

pds add button
pds add button card dialog input label field   # multiple at once
pds add -y button card                         # skip confirmation
pds add --sections hero-1 pricing-3 footer-2  # marketing sections

pds list

pds list                  # all UI components + install status
pds list --sections       # all sections grouped by category
pds list --installed      # only installed components

pds diff

Shows what changed in the registry since you installed a component.

pds diff
pds diff button

pds update

Pulls upstream changes into installed components.

pds update          # all installed components
pds update button   # specific component

pds transform

Rewrites hardcoded Tailwind color utilities to CSS variable equivalents.

pds transform src/components/ui/button.tsx

Configuration

pds setup creates pds.config.json in your project root:

{
  "theme": "ds1.0",
  "framework": "next",
  "aliases": {
    "components": "@/components",
    "ui": "@/components/ui",
    "lib": "@/lib"
  },
  "css": "src/app/globals.css",
  "tsx": true
}

| Field | Description | |-------|-------------| | theme | Active theme name | | framework | Target framework: next, vite, or cra | | aliases.ui | Where components are written | | aliases.lib | Where cn() utility lives | | css | Path to your global CSS file | | tsx | true for TypeScript output, false for JavaScript (.jsx/.js) — set by --js at setup time |

How tokens work

pds setup installs @phronetic-admin/design-tokens as a dependency of your project and adds this to globals.css:

@import "@phronetic-admin/design-tokens/css";

This makes all DS 1.0 CSS custom properties (--color-primary, --color-background, --button-bg, etc.) available to Tailwind and your components.

When the design system updates token values (colors, spacing, radius), you pick up the changes with:

npm update @phronetic-admin/design-tokens

No need to re-run pds add or touch component files. See @phronetic-admin/design-tokens for details.

Component API conventions

• render prop — polymorphic components use render={<Element />}, not asChild
• Icons — always import { X } from "@/assets/icons", never from lucide-react directly
• Brand icons — import { Github } from "@/assets/icons/brand"
• cn() — import { cn } from "@/lib/utils" for conditional class merging
• Motion — import { motion } from "motion/react" (not framer-motion)
• Dark mode — toggled via .dark class on <html>, supported by all components out of the box

Available components (107)

Form: button, input, textarea, label, field, input-group, checkbox, radio-group, switch, select, combobox, multi-select, slider, number-input, rating, tag-input, file-upload, rich-text-editor, color-picker, date-range-picker, time-picker, input-otp

Overlay: dialog, sheet, alert-dialog, drawer, popover, tooltip, hover-card, context-menu, dropdown-menu, menubar, command, tour

Navigation: navigation-menu, breadcrumb, pagination, tabs, sidebar, app-shell

Display: card, badge, alert, avatar, separator, skeleton, progress, spinner, accordion, collapsible, scroll-area, resizable, aspect-ratio, toggle, toggle-group, segmented-control, description-list, empty, watermark

Data: data-table, chart, area-chart, bar-chart, line-chart, donut-chart, spark-chart, bar-list, tracker, stat-card, calendar

Media: carousel, image-zoom, video-player, video-grid, video-tile, audio-visualizer, qr-code

Communication: chat, chat-input, chat-message, message-bubble, notification-center, typing-indicator, sonner

Misc: kanban-board, transfer-list, tree-view, stepper, timeline, code-block, kbd, inline-cta, suggestion-chips

Sections

Sections are named {category}-{number} (e.g. hero-1, pricing-3). Use pds list --sections to see all 978.

pds add --sections hero-1 feature-5 pricing-2 footer-1

Import and render them directly:

import Hero1 from "@/components/sections/hero/hero-1"
import Pricing2 from "@/components/sections/pricing/pricing-2"

export default function Page() {
  return (
    <>
      <Hero1 />
      <Pricing2 />
    </>
  )
}

Updating the CLI / publishing

cd packages/novacn
npm run build        # rebuilds registry + CLI bundle
npm version <patch|minor|major>
npm publish --access restricted

If tokens/*.tokens.json or packages/tokens/ changed too, bump and publish @phronetic-admin/design-tokens first (from packages/tokens/), then update the @phronetic-admin/design-tokens dependency range in this package's package.json before publishing.

Publishing requires an npm account that is a member of the @phronetic-admin org with publish rights.