ctds

Install and onboarding CLI for CTDS, the hybrid design system.

Requirements

• Node.js 18+
• A Next.js App Router project (an app/ or src/app/ directory)

Compatibility and verification

The CLI declares Node.js 18+, React >=18.2 <20, and optional Next.js >=14 <17 compatibility. These are declared compatibility ranges, not a fully tested version matrix. Installation currently targets Next.js App Router; Vite is not yet a verified installation target.

Repository CI uses Node.js 24 (including native TypeScript execution in tests) and the exact Next.js/React versions in web/package-lock.json. It runs lint, source/registry/catalog checks, unit tests, TypeScript, the documentation build, gate integration, and isolated tarball installation. Package smoke tests verify packaged assets; they do not yet prove a complete new consumer application build across every declared peer version. Broader consumer/version testing is planned separately.

The release gate uses the exact Playwright Chromium version and runs Core keyboard/state/axe/reflow tests. Ubuntu CI renders exact Templates in smoke mode; a separate macOS 26 arm64 job compares reviewed Core and Template pixel baselines and retains visual diffs/traces on failure. Baselines use deterministic OS fallback fonts with remote requests blocked, and are separated by platform/architecture. Missing baselines fail. These checks do not replace real screen-reader or downloaded-webfont review. See web/tests/quality/README.md in the repository for commands and scope.

Automatic Next.js 16 compatibility fix. The turbopack.rules["*.css"] + @tailwindcss/turbopack combo that create-next-app@latest emits bypasses Turbopack's built-in Lightning CSS CSS Modules path, which makes .module.css class names resolve to undefined. ctds init detects this and automatically:

1. Removes the turbopack.rules["*.css"] block from next.config.ts
2. Creates a new postcss.config.mjs and registers the @tailwindcss/postcss plugin
3. Prints a console fallback explaining how to remove @tailwindcss/turbopack

On Next 15 LTS projects, none of these changes are applied and the setup works as-is.

Install (end user)

cd my-next-app
npx @conscience-technology/ctds init

What init does:

1. Detects the project (checks package.json plus an app/ directory)
2. Copies these assets:
   • components/ → components/ctds/ (or src/components/ctds/) (reusable React components plus tokens.css with fonts, tokens, and every axis selector)
   • prompts/ → prompts/
   • .claude/skills/ctds/ → .claude/skills/ctds/
3. Creates app/ctds/page.tsx (the onboarding route)
4. Prints two manual steps to the console:
   • Add @import "../components/ctds/tokens.css"; to the top of app/globals.css
   • Wrap app/layout.tsx with <ThemeController>

After install:

npm run dev
# Open http://localhost:3000/ctds, finish onboarding, click "Apply"

Clicking "Apply" writes two files to the project root:

• ctds.config.json: axis values. Consumed by AI agents (Claude Code and friends) and ThemeController.
• DESIGN.md: a prose summary of the theme and axes. Read by both humans and AI.

Commit both files. Other developers and AI agents need to read them.

Options

npx @conscience-technology/ctds init           # default
npx @conscience-technology/ctds init --dry     # print planned writes without touching disk
npx @conscience-technology/ctds init --force   # overwrite existing files

Debug:

CTDS_DEBUG=1 npx @conscience-technology/ctds init

Local development (contributors)

For editing and testing the CLI inside the CTDS repo:

cd packages/ctds-cli
npm link                     # symlink the `ctds` binary globally

cd /tmp/test-next-app        # a Next.js project to test against
ctds init --dry              # assets are pulled from the CTDS repo directly (no bundle step needed)

When assets/components is missing, getAssetSources() automatically falls back to the repo root (../../web/components, ../../prompts, ../../.claude/skills/ctds).

Publish

From the repository root:

npm run check:release
npm run pack:cli
npm run verify:cli-tarball

pack:cli regenerates assets before creating packages/ctds-cli/ctds-package.tgz. Verification installs that exact tarball offline and checks the manifest projection, public exports/prompts, catalog, WIP exclusion, and private recipe boundaries. Tag publishing runs the same required quality workflow as PRs, then packs, verifies, and publishes that tarball with lifecycle scripts disabled. Do not repack between verification and publication.

Install the test browser with cd web && npx playwright install chromium. For local Template smoke checks, set CTDS_VISUAL_MODE=smoke; without smoke mode, reviewed platform-specific pixel comparisons run.

Component status and stable IDs are maintained in the root component-manifest.json. After an intentional change, run npm run build:registry; the runtime registry and catalog are generated. Internal runtime helpers remain installed but are excluded from the UI catalog.

Known gaps (resolved before end-to-end stage 2)

Current status. The in-repo /ctds apply flow (stage 1) works. Running ctds init in a separate Next.js project (stage 2) used to break on the gaps below. Each has since been resolved.

1. tokens.css was not extracted (resolved 2026-10-07)

The token and axis selector block (lines 1 to 718) was moved out of web/app/globals.css into web/components/tokens.css, including font loading. After the CLI copies the assets, a single @import "../components/ctds/tokens.css"; at the top of app/globals.css makes CTDS fully active.

2. ThemeController referenced web/app/data.ts (resolved 2026-10-07)

web/app/data.ts was moved wholesale to web/components/_data.ts, carrying both axis types and preset data. Every importer (ThemeController, OnboardingAxisPanel, Icon, and others) now points at @/components/_data or ../_data, so copying components/ carries the data file along automatically.

3. Copied components used the @/components/* alias (resolved 2026-10-07)

All @/components/<name> imports inside components/ were rewritten to relative paths (../<name>). The @/lib/cn and @/lib/color utilities were moved to components/_cn.ts and components/_color.ts and all references updated to relative imports. The copied tree now works regardless of the consumer project's tsconfig aliases.

4. OnboardingPage export shape (resolved 2026-10-07)

The whole onboarding UI moved from web/app/onboarding/ to web/components/Onboarding/. OnboardingPage is now a named export. The CTDS repo's /onboarding route still works via a default-export wrapper. ThemeController and axisOptions moved under web/components/ too. The copied project imports via ../../components/ctds/Onboarding.

5. Dependency compatibility (resolved 2026-10-07)

The CLI now reads the consumer package.json deps and prints an npm install ... command for any missing CTDS runtime packages. See CTDS_RUNTIME_DEPS in src/utils/deps.js. End-to-end tests pass on Next 16 and React 18.3.

6. Server action process.cwd() assumption (resolved 2026-10-07)

findProjectRoot() in actions.ts now walks up from the current working directory and picks the outermost directory that contains package.json. This resolves the right root both for the in-repo test case (web/ vs root) and for end-to-end test projects.

Known small gaps (found during end-to-end testing, non-blocking)

7. .visually-hidden global utility (resolved)

SelectableCard references className="visually-hidden", but that class only lived in globals.css and was therefore not copied. It now lives in a new web/components/_utils.css file that tokens.css pulls in via @import "./_utils.css". Native radio and checkbox inputs are now correctly hidden.

8. web/public/onboarding/*.png not copied (resolved)

Onboarding theme hover previews (pure.png, spare.png, expressive.png) were added to the copy plan. The bundler (bundle-assets.mjs) and the repo fallback (getAssetSources) both include public/onboarding.

End-to-end test result (2026-10-07)

Ran node bin/ctds.js init in a fresh Next.js 16 project, followed the CLI's manual steps, opened /ctds, finished onboarding, and clicked "Apply".

• Assets copied (components/ctds/, prompts/, .claude/skills/ctds/, public/onboarding/)
• /ctds/page.tsx created
• Manual setup printed (globals.css import, layout.tsx wrapper, npm install deps)
• Dev server rendered correctly (radios, titles, background)
• Apply wrote ctds.config.json and DESIGN.md to the test project root
• findProjectRoot() picked cwd (/private/tmp/ctds-e2e) as expected

License

MIT