Quickstart: Integrate Substrate into Your Project

This guide walks you through the vendored-checkout integration path: getting the Substrate engine into your repo, running substrate init, wiring the three public import aliases, and initializing the runtime so your app computes APCA-solved token values. By the end, your app renders through the Substrate cascade and you’ve verified it. APCA attribution and use restrictions: see About APCA.

The package is @unknown-creatives/substrate; a bare npx substrate still installs an unrelated third-party package — always use the scoped name.

1. Obtain Substrate

The CLI comes from npm: npx @unknown-creatives/substrate <cmd>. The engine is delivered separately and is never published to npm — clone the Substrate checkout you received from Unknown Creatives outside your project, then vendor the engine into your repo:

# Clone Substrate outside your project. No install step needed —
# the published CLI brings its own dependencies.
git clone <substrate-repo-url> ~/substrate
SUBSTRATE_REPO=~/substrate

# Vendor the engine: sealed engine dirs go to substrate/engine/,
# pipeline outputs seed substrate/generated/ (a sibling, NOT inside engine/)
cd ~/my-app
mkdir -p substrate/engine
for d in src skills agents references knowledge scripts; do
  cp -R "$SUBSTRATE_REPO/$d" "substrate/engine/$d"
done
cp -R "$SUBSTRATE_REPO/generated" substrate/generated

None of these directories need node_modules or any install step inside your repo. Vendor the whole src/ directory — if src/kernel/, src/platforms/, or src/types/ is missing, init reports each as a blocker and exits non-zero. Before running init, confirm the layout is detectable (--dry-run writes nothing):

npx @unknown-creatives/substrate init --dry-run --platform claude-code

The first line must read Found Substrate (client): substrate/engine.

2. Run `substrate init`

From your project root:

npx @unknown-creatives/substrate init

Every bare substrate <cmd> spelling in the rest of this guide means that scoped npx invocation.

Working on Substrate itself? Run the bin from your checkout instead — after (cd "$SUBSTRATE_REPO" && npm ci), a shell function makes the bare spelling literal: substrate() { node "$SUBSTRATE_REPO/packages/cli/bin/substrate-init.js" "$@"; }

init prints the Substrate it found, lets you pick which AI tools to configure, links the Substrate skills and the Bloom agent into each selected tool, scaffolds the client overlays, writes .substrate/state.yaml, and sets up the import aliases. Non-interactive alternatives:

substrate init --all               # configure every supported platform
substrate init --platform cursor   # configure exactly one platform
substrate init --dry-run           # preview every action, write nothing

The --platform flag selects an AI coding tool (claude-code, cursor, windsurf, …) — it is not an output-target selector. Re-running init is idempotent, and substrate init --refresh replays your recorded selections. The full CLI surface is init, add, upgrade, adopt, setup, and artifact.

3. Wire the three public aliases

Client code imports Substrate through exactly three public aliases — this is the whole import contract, and an engine swap never changes these import statements:

Alias	Resolves to (client repo)	Use it for
`@substrate/engine`	`substrate/engine/src/index.ts`	the runtime engine API (APCA solver, token sync)
`@substrate/components/*`	`substrate/components/*`	client-owned components (`Surface`, `Button`, catalog entries)
`@substrate/generated/*`	`substrate/generated/*`	pipeline output — the generated CSS, registries, intermediates

init auto-writes the aliases into tsconfig.json (idempotent; it manages only the @substrate/* zone and never touches your other options):

{
  "compilerOptions": {
    "paths": {
      "@substrate/engine": ["./substrate/engine/src/index.ts"],
      "@substrate/components/*": ["./substrate/components/*"],
      "@substrate/generated/*": ["./substrate/generated/*"]
    }
  }
}

Bundler and test configs are code, so init doesn’t edit them — it writes an importable manifest, .substrate/aliases.js, that you spread into your bundler’s alias config:

// vite.config.ts
import { defineConfig } from 'vite';
import { substrateAliases } from './.substrate/aliases.js';

export default defineConfig({
  resolve: { alias: substrateAliases },
});

To reprint every block without touching disk, run substrate init --report-aliases.

4. First import

Two things run at app startup: load the generated CSS barrel once at your app entry (it establishes the full cascade), then initialize the engine — the runtime APCA solver, the only JS Substrate requires. On the vendored path you add this yourself; on the supervised substrate setup path this exact module is generated for you as src/substrate.setup.ts: Any element then opts into the cascade with data-ucs plus a data-mode role (the full attribute contract is on Markup Opt-In): To move along the scheme axis (light ↔ dark), update the preference vector and re-sync — the CSS reacts automatically:

prefs.scheme = prefs.scheme === 0 ? 1 : 0;
syncPrefsToCssVars(prefs);
updateAllVars(brand, prefs);

There is no theme attribute to toggle: scheme is a continuous value (0 → 1), the runtime sets data-brand on the root itself, and named modes like dark or highContrast are presets over the same continuum — see Core Concepts.

5. Verify

These checks need nothing beyond Node and what init wrote:

# 1. Detection: prints `Found Substrate (client): substrate/engine`, writes nothing.
substrate init --dry-run --platform claude-code

# 2. Alias wiring: every @substrate/* target init wrote resolves on disk.
node --input-type=module -e "
import fs from 'node:fs';
import RuntimeInitExample from '/snippets/runtime-init-example.mdx';
import MarkupOptInExample from '/snippets/markup-optin-example.mdx';
const { substrateAliases } = await import('./.substrate/aliases.js');
for (const [alias, target] of Object.entries(substrateAliases)) {
  if (!fs.existsSync(target)) { console.error('MISSING', alias, '->', target); process.exit(1); }
  console.log('OK', alias, '->', target);
}
"

# 3. The generated CSS barrel is present.
node -e "require('node:fs').accessSync('substrate/generated/global/css/index.gen.css'); console.log('OK css barrel')"

To prove the engine itself is sound, run its always-on suite in the Substrate checkout (the vendored engine deliberately ships no test runner):

cd "$SUBSTRATE_REPO" && npm run test:unit

6. Discover catalog content

Substrate ships a catalog of starting-point content — component configs, brand configs — that you scaffold into your client-owned content root as you need it:

substrate add --list                                        # see what's available
substrate add components/badge --generate-command "npm run generate"

add scaffolds the entry’s files with provenance headers, records the fetch in .substrate/manifest.yaml, and runs your generate command so the pipeline picks the new config up immediately.

Runtime & Imports

The required wiring in depth: the alias contract, the three-call sequence, and the OS preference helpers.

Surface Component

Required when surfaces nest — cards, panels, insets — so contrast is re-solved against the local background.

Core Concepts

The runtime-solver mental model: intents, the preference vector, APCA solving per surface, and the cascade.

Brand Config Overview

Author your own brand: the YAML schema, the open intents map, and the flexibility bounds.

Get Started

Integrate

Tooling

Brand Config

Component Config

Modes & Accessibility

Platforms

Quickstart: Integrate Substrate into Your Project

1. Obtain Substrate

2. Run `substrate init`

3. Wire the three public aliases

4. First import

5. Verify

6. Discover catalog content

Runtime & Imports

Surface Component

Core Concepts

Brand Config Overview

​1. Obtain Substrate

​2. Run substrate init

​3. Wire the three public aliases

​4. First import

​5. Verify

​6. Discover catalog content

Runtime & Imports

Surface Component

Core Concepts

Brand Config Overview

1. Obtain Substrate

2. Run `substrate init`

3. Wire the three public aliases

4. First import

5. Verify

6. Discover catalog content