handoff-app 2.0.0-12 → 2.0.0-13

package/docs/cli.md

@@ -1,78 +1,299 @@
 # Handoff CLI
 
-The Handoff cli allows you to interact with your Figma file and Handoff app
-via the command line. It allows you to run handoff in any folder with
-no other configuration or setup.  
+The `handoff-app` CLI fetches Figma foundations, builds and serves the
+documentation, and transfers content between a workspace and a registry. The
+[README](../README.md) explains the concepts and the configuration. This page
+lists every command and option.
 
-## Interacting with Figma
-The CLI will allow you to fetch all data from Figma, build the documentation
-app and run a local dev site. For these use the build, fetch, and serve commands
-documented below.  
+## Run the CLI
 
-## Configuring a handoff project
-The CLI will allow you to build the various kinds of configurations that you
-will need for interacting with Figma. Handoff has sane configuration defaults
-but the various kinds of configurations can be tailored or extended.
+`init` installs `handoff-app` in the project and adds npm scripts for the
+common commands. Use the npm scripts, so that local development and CI use the
+project version:
 
-Handoff has 4 configuration areas - 
+```bash
+npm run build -- --target registry
+```
 
-`handoff.config.*` - Defines the general handoff configuration. Supported files are `handoff.config.ts`, `handoff.config.js`, `handoff.config.cjs`, and `handoff.config.json` (resolved in that precedence order). Pass `-c, --config <file>` to load one specific file instead, resolved from the working directory (`HANDOFF_WORKING_PATH`, or the directory the command runs in).
-`pages` - Markdown files that will create or customize pages in the documentation
-app
-`exportables` - JSON schemas for each component in your figma file that you
-want to pull into handoff.
-`integration` - scss mappings and html templates for making it easy to map
-handoff tokens to your frontend framework.
+npm forwards the arguments after `--` to the CLI. For a command without an npm
+script, use `npx`:
 
-The CLI exposes two ways to manage the config - `make` and `eject`. 
+```bash
+npx handoff-app validate:components
+```
 
-__Eject__ commands will take the default configuration and eject them into
-the current working directory. If you customize these configurations, then run 
-handoff commands in that directory, these configs will be executed. `eject:config` now prompts for TypeScript or JavaScript config format.
-__Make__ commands will generate a boilerplate configuration in the current
-working directory. This is useful for extending handoff for different components
-or integrations.
+Show the help of the CLI or of one command:
 
-## Requirements
-Node.js 22 or newer and npm 10 or newer
+```bash
+npx handoff-app --help
+npx handoff-app publish --help
+```
 
-## Install the CLI 
+Each command runs against the working directory. The working directory is the
+directory that holds `handoff.config.ts`. It is the current directory, or the
+directory that `HANDOFF_WORKING_PATH` sets.
 
-`npm install -g handoff-app`
+## Shared options
 
-## Run the CLI
+Every command except `init` accepts these options:
+
+| Option | Description |
+| --- | --- |
+| `-c, --config <file>` | Load this config file, relative to the working directory, instead of `handoff.config.*` |
+| `--profile <name>` | Merge `handoff.config.<name>.*` onto the base config, and use the registry login of this profile. Has priority over `HANDOFF_PROFILE`. |
+| `-d, --debug` | Show debug logs |
+| `-f, --force` | Force the action. The effect depends on the command. |
+| `--help` | Show the help of the command |
+
+`handoff-app --version` shows the CLI version.
+
+`HANDOFF_LOG_LEVEL` (`debug`, `info`, `warn`, `error`, or `silent`) and
+`HANDOFF_LOG_SCOPES` (`handoff`, `vite`, `next`) control the log output of
+every command. The README lists all
+[environment variables](../README.md#environment-variables).
+
+## Project
+
+### init
+
+```bash
+npx handoff-app init
+```
+
+Creates a project with an interactive wizard. The wizard asks for the project
+name, sample content, JavaScript or TypeScript, an optional Vercel setup, and
+optional Figma credentials. It installs `handoff-app` and adds these npm
+scripts: `start`, `dev`, `fetch`, `build`, `login`, `logout`, `publish`,
+`checkout`, and `db:migrate`.
+
+### fetch
+
+```bash
+handoff-app fetch
+```
+
+Fetches tokens and assets from the Figma file and writes them to `exported/`.
+It reads `HANDOFF_FIGMA_PROJECT_ID` and `HANDOFF_DEV_ACCESS_TOKEN`. If a value
+is empty, `fetch` asks for it in the terminal. Without a terminal, `fetch`
+stops with an error that names the missing variable.
+
+### start
+
+```bash
+handoff-app start
+```
+
+Starts the workspace documentation server and the Handoff file watchers. While
+the command runs, Handoff rebuilds changed files and updates the
+documentation.
+
+### dev
+
+```bash
+handoff-app dev
+```
+
+Starts the workspace documentation server without the Handoff file watchers.
+
+### build
+
+```bash
+handoff-app build [--target static|registry] [--package standalone|vercel] [--skip-components]
+```
+
+Builds the documentation.
+
+| Option | Description |
+| --- | --- |
+| `--target static` | Default. Builds a static site in `out/static`. |
+| `--target registry` | Builds a standalone registry server in `out/registry`. The application is always in registry mode. |
+| `--package vercel` | Writes a Vercel Build Output bundle to `.vercel/output` for the selected target |
+| `--package standalone` | Writes the default output of the target |
+| `--skip-components` | Builds the application without a component build first |
+| `-f, --force` | Builds every component again, and ignores the build cache |
+
+`--package` never changes the target.
+
+### build:app
+
+```bash
+handoff-app build:app [--skip-components]
+```
+
+Builds the static site. It is the same as `build --target static`.
+
+### build:components
+
+```bash
+handoff-app build:components [component]
+```
+
+Builds the catalog items without the documentation application. A name builds
+only that item.
+
+### validate:components
+
+```bash
+handoff-app validate:components [--skip-build]
+```
+
+Validates the catalog items. `--skip-build` validates the existing build
+output without a build first.
+
+## Content
+
+### make:component
+
+```bash
+handoff-app make:component <name>
+```
+
+Creates a Handlebars catalog item: a template, a CommonJS declaration, and,
+if you select them, a JavaScript file and a Sass file. The item goes into the
+first directory in `catalog.include`, or into `components/`. If that directory
+is not registered, Handoff adds it to `catalog.include`. The name can contain
+letters, numbers, hyphens, and underscores. `--force` overwrites an existing
+template.
+
+### make:page
+
+```bash
+handoff-app make:page <name> [parent]
+```
+
+Creates a Markdown page in `pages/`, or in `pages/<parent>/`. If a default page
+has the same name, the new page starts with its content. `--force` overwrites
+an existing page.
+
+### scaffold
+
+```bash
+handoff-app scaffold
+```
+
+Creates catalog item stubs for the components in the fetched Figma data. The
+command asks which components to create and how.
+
+### eject:config
+
+```bash
+handoff-app eject:config
+```
+
+Writes the default config to the working directory. The command asks for
+TypeScript or JavaScript. `--force` overwrites an existing config file.
+
+### eject:pages
+
+```bash
+handoff-app eject:pages
+```
+
+Copies the default documentation pages to `pages/`, so that you can change
+them. `--force` adds the default pages that you did not change.
+
+### eject:theme
+
+```bash
+handoff-app eject:theme
+```
+
+Copies the Sass file of the selected theme to `theme/default.scss`, so that
+you can change it.
+
+## Registry
+
+### db:migrate
+
+```bash
+DATABASE_URL="postgresql://…" handoff-app db:migrate
+```
+
+Applies the registry database migrations. The command reads the project config
+and the database variables, and uses the same database driver as the registry
+build. Run it before the first deployment and before each upgrade. The build,
+the server start, and the installer never run migrations.
+
+### login
+
+```bash
+handoff-app login [--url <registry-url>] [--profile <name>] [--no-browser]
+```
+
+Authorizes the CLI through the device flow of the registry. The CLI saves the
+token in `.handoff/cli-auth.json`, under the selected profile.
+
+| Option | Description |
+| --- | --- |
+| `--url <registry-url>` | Registry URL, with its base path when the registry has one. Without it, the CLI uses the configured registry URL. |
+| `--profile <name>` | Saves the login under this profile. The profile needs no config file. |
+| `--no-browser` | Shows the approval URL, but does not open the browser. `HANDOFF_LOGIN_NO_BROWSER=true` does the same. |
+
+### logout
+
+```bash
+handoff-app logout [--profile <name>] [--url <registry-url>] [--all]
+```
+
+Revokes the saved token when possible. Then it removes the saved login of the
+selected profile.
+
+| Option | Description |
+| --- | --- |
+| `--url <registry-url>` | Revokes the login only if it belongs to this exact registry URL |
+| `--all` | Revokes and removes the logins of every profile |
+
+### publish
+
+```bash
+handoff-app publish <catalog|pages|tokens|assets|all> [id...] [--dry-run] [--no-build]
+```
+
+Builds the content and publishes it to the connected registry. `all` publishes
+every kind in dependency order. One or more ids limit the publish to those
+entities: catalog item ids, page ids, token set ids, or asset collections.
+`tokens` and `assets` run the Figma pipeline first.
 
-`handoff-app --help`
+| Option | Description |
+| --- | --- |
+| `--dry-run` | Lists the content that a real publish uploads. Does not connect to a registry. The build still runs. |
+| `--no-build` | Publishes the existing build output without a build first |
 
-## Commands and Flags
+### checkout
 
-Usage: handoff-app <cmd> <opts>
+```bash
+handoff-app checkout <catalog|pages|tokens|assets|all> [id...] [--dry-run]
+```
 
-Commands:
-  fetch [opts] - Fetches the design tokens from the design system
+Writes content from the connected registry into the workspace. Checkout writes
+declarations in the format that `runtime.workspace.declarationFormat` sets.
 
-  build [--target static|registry] [opts] - Builds the design system for the target (default: static export)
-    build:app [opts] - Builds the design system static application (alias of `build --target static`)
+| Option | Description |
+| --- | --- |
+| `--dry-run` | Lists the files that a real checkout creates or overwrites. Writes nothing. |
 
-  start [opts] - Starts the design system in development mode
+### Registry connection
 
-  db:migrate [opts] - Runs registry database migrations (Drizzle / PostgreSQL). Reads the project config and database env vars, applies the package-owned migration set, and runs independently of `build`.
+`publish` and `checkout` find the registry URL and the token in this order:
 
-  login [--profile <name>] --url <registry-url> - Authorizes this workspace in the browser and stores a revocable token in `.handoff/cli-auth.json`, under the selected profile.
+1. `HANDOFF_REGISTRY_URL` and `HANDOFF_REGISTRY_ACCESS_TOKEN`, or
+   `runtime.registryConnection` in the config.
+2. The saved login of the selected profile, if it belongs to the same registry
+   URL. A profile without a login uses the default login.
+3. `HANDOFF_SYNC_SECRET`, when no token and no login is available.
 
-  logout [--profile <name>] [--url <registry-url>] [--all] - Revokes the saved token when possible, then removes the local credential of the selected profile, or of every profile with `--all`.
+## Deprecated commands
 
-  make
-    make:component <name> [opts] - Creates a new catalog item with a declaration
-    make:page <component> <state> [opts] - Creates a new page
+These commands still work. Each shows a deprecation warning.
 
-  eject - Ejects the default entire configuration to the current directory
-    eject:config [opts] - Ejects the default configuration to the current directory
-    eject:integration [opts] - Ejects the default integration to the current directory
-    eject:pages [opts] - Ejects the default pages to the current directory
+| Command | Replacement |
+| --- | --- |
+| `push [type] [id...]` | `publish` |
+| `push:all` | `publish all` |
+| `push:tokens [setId...]` | `publish tokens` |
+| `push:assets [collection]` | `publish assets` |
+| `pull [type] [id...]` | `checkout` |
 
-Options:
-  -c, --config [file]      Define the path to the config file
-  -d, --debug              Show debug logs
-  -h, --help               Show this help message
-  -v, --version            Show the handoff version number
+The `push` and `pull` commands also accept `components` and `patterns` as the
+type. They accept the options for features that Handoff 2 does not have, and
+show a warning for each one.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handoff-app",
-  "version": "2.0.0-12",
+  "version": "2.0.0-13",
   "description": "Automated documentation toolchain for building client side documentation from figma",
   "author ": {
     "name": "Convertiv",
@@ -40,9 +40,9 @@
       "types": "./dist/pattern.d.ts",
       "default": "./dist/pattern.js"
     },
-    "./define": {
-      "types": "./dist/define.d.ts",
-      "default": "./dist/define.js"
+    "./providers": {
+      "types": "./dist/providers.d.ts",
+      "default": "./dist/providers.js"
     },
     "./package.json": "./package.json",
     "./*": "./*"
@@ -58,8 +58,8 @@
       "pattern": [
         "./dist/pattern.d.ts"
       ],
-      "define": [
-        "./dist/define.d.ts"
+      "providers": [
+        "./dist/providers.d.ts"
       ]
     }
   },
@@ -89,7 +89,7 @@
     "plugins": [
       "prettier-plugin-tailwindcss"
     ],
-    "tailwindConfig": "./tailwind.config.ts"
+    "tailwindStylesheet": "./src/app/css/index.css"
   },
   "dependencies": {
     "@ai-sdk/openai-compatible": "^3.0.53",

package/src/ai/define.ts

@@ -1,5 +1,5 @@
 /**
- * Typed identity helper for custom AI providers (mirrors `defineAssetStorage`): a consumer
+ * Typed identity helper for custom AI providers (mirrors `defineStorageProvider`): a consumer
  * default-exports its result from a **server-only** module and points a connection's `module` at
  * it. It must be its own module (not an inline `defineConfig` function) so the build can trace it
  * into the deployed registry. The default export may be the provider object, or a factory

package/src/ai/types.ts

@@ -2,7 +2,7 @@
  * Server-only AI provider contract for connections that are not OpenAI-compatible.
  *
  * Every built-in connection speaks the OpenAI-compatible `/chat/completions` API and needs no
- * adapter — Ollama, LiteLLM, OpenRouter, vLLM, LM Studio and Azure OpenAI all serve it, and each of
+ * custom module — Ollama, LiteLLM, OpenRouter, vLLM, LM Studio and Azure OpenAI all serve it, and each of
  * them fronts Anthropic, Google and xAI models. A provider that fits nothing else names a
  * {@link defineAiProvider} module instead of a base URL.
  */

package/src/app/components/Auth/AccountLayout.tsx

@@ -41,7 +41,7 @@ interface AccountLayoutProps {
 
 export function AccountLayout({ children, config, title, description }: AccountLayoutProps) {
   if (process.env.HANDOFF_RUNTIME_MODE !== 'registry') {
-    return <AuthShell title={title}>{null}</AuthShell>;
+    return <AuthShell config={config} title={title}>{null}</AuthShell>;
   }
 
   return (

package/src/app/components/Auth/AuthShell.tsx

@@ -3,6 +3,7 @@ import Head from 'next/head';
 import Link from 'next/link';
 import type { ClientConfig } from '@handoff/types/config';
 import type { ReactNode } from 'react';
+import { pageTitle } from '../../lib/utils';
 import { ConfigContextProvider } from '../context/ConfigContext';
 import { Header } from '../Layout/Header';
 import { Button } from '../ui/button';
@@ -21,9 +22,17 @@ interface AuthShellProps {
 }
 
 export function AuthShell({ children, config, title, description, wide = false, hideNav = false, centered = false }: AuthShellProps) {
+  const head = (
+    <Head>
+      <title>{pageTitle({ title }, config?.app?.title)}</title>
+      {description ? <meta name="description" content={description} /> : null}
+    </Head>
+  );
+
   if (!isRegistryRuntime) {
     return (
       <main className="flex min-h-screen items-center justify-center px-6">
+        {head}
         <div className="max-w-md text-center">
           <h1 className="text-2xl font-semibold">Registry only</h1>
           <p className="mt-2 text-sm text-muted-foreground">Account management is available only in a deployed registry.</p>
@@ -40,10 +49,7 @@ export function AuthShell({ children, config, title, description, wide = false,
 
   return (
     <ThemeProvider attribute="class" defaultTheme="system" enableSystem disableTransitionOnChange>
-      <Head>
-        <title>{title} · Handoff Registry</title>
-        {description ? <meta name="description" content={description} /> : null}
-      </Head>
+      {head}
       {centered ? (
         <main className="flex min-h-[calc(100vh-8rem)] items-center justify-center bg-background px-4 py-12">
           <div className="w-full max-w-md">{children}</div>

package/src/app/components/Foundations/ColorGrid.tsx

@@ -16,7 +16,7 @@ import {
 import { Separator } from '../ui/separator';
 import { Sheet, SheetClose, SheetContent, SheetHeader } from '../ui/sheet';
 import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '../ui/tooltip';
-import { hexToRgb } from '../util/colors';
+import { hexToRgb, hexToRgbaCss } from '../util/colors';
 import ColorContrast from './ColorContrast';
 import ColorInfo from './ColorInfo';
 import ColorSpaces from './ColorSpaces';
@@ -25,7 +25,6 @@ import ColorTailwind from './ColorTailwind';
 type ColorGridProps = {
   title: string;
   group: string;
-  description: string;
   colors: CoreTypes.IColorObject[];
 };
 
@@ -33,7 +32,7 @@ const LargeColorGrid: React.FC<{ colors: CoreTypes.IColorObject[]; setOpen: (col
   <div className="@container">
     <div className="mb-6 grid grid-cols-1 gap-6 @md:grid-cols-2">
       {colors.map((color) => (
-        <a href="#" className="flex flex-col items-start" key={color.group + '-' + color.name}>
+        <div className="flex flex-col items-start" key={color.group + '-' + color.name}>
           <div
             className="group relative mb-2 block h-32 w-full rounded-lg"
             style={{ background: color.value ?? '', backgroundBlendMode: color.blend ?? '' }}
@@ -42,7 +41,7 @@ const LargeColorGrid: React.FC<{ colors: CoreTypes.IColorObject[]; setOpen: (col
           </div>
           <p className="mb-1 text-sm font-medium line-clamp-1" title={color.name}>{color.name}</p>
           <small className="font-mono text-xs font-light text-gray-400 line-clamp-1" title={color.value}>{color.value}</small>
-        </a>
+        </div>
       ))}
     </div>
   </div>
@@ -52,10 +51,11 @@ const SmallColorGrid: React.FC<{ colors: CoreTypes.IColorObject[]; setOpen: (col
   // group colors by subgroup
   const groupedColors = colors.reduce(
     (acc, color) => {
-      if (!acc[color.subgroup]) {
-        acc[color.subgroup] = [];
+      const subgroup = color.subgroup ?? '';
+      if (!acc[subgroup]) {
+        acc[subgroup] = [];
       }
-      acc[color.subgroup].push(color);
+      acc[subgroup].push(color);
       return acc;
     },
     {} as Record<string, CoreTypes.IColorObject[]>
@@ -64,11 +64,11 @@ const SmallColorGrid: React.FC<{ colors: CoreTypes.IColorObject[]; setOpen: (col
     <>
       {Object.entries(groupedColors).map(([subgroup]) => (
         <div className="mb-5" key={`group-${subgroup}`}>
-          <HeadersType.H4 key={subgroup}>{startCase(subgroup.replaceAll('-', ' '))}</HeadersType.H4>
+          {subgroup && <HeadersType.H4>{startCase(subgroup.replaceAll('-', ' '))}</HeadersType.H4>}
           <div className="grid grid-cols-[repeat(auto-fit,minmax(60px,60px))] gap-6">
             {groupedColors[subgroup].map((color) => (
               <React.Fragment key={`group-${subgroup}-${color.name}`}>
-                <a href="" className="flex flex-col">
+                <div className="flex flex-col">
                   <div
                     className="group relative mb-2 block h-14 rounded-lg"
                     style={{ background: color.value ?? '', backgroundBlendMode: color.blend ?? '' }}
@@ -77,7 +77,7 @@ const SmallColorGrid: React.FC<{ colors: CoreTypes.IColorObject[]; setOpen: (col
                   </div>
                   <p className="mb-1 text-xs font-medium line-clamp-1" title={color.name}>{color.name}</p>
                   <small className="font-mono text-xs font-light text-gray-400 line-clamp-1" title={color.value}>{color.value}</small>
-                </a>
+                </div>
               </React.Fragment>
             ))}
           </div>
@@ -87,7 +87,7 @@ const SmallColorGrid: React.FC<{ colors: CoreTypes.IColorObject[]; setOpen: (col
   );
 };
 
-const ColorGrid: React.FC<ColorGridProps> = ({ title, description, colors, group }) => {
+const ColorGrid: React.FC<ColorGridProps> = ({ title, colors, group }) => {
   const [open, setOpen] = React.useState(false);
   const [selectedColor, setSelectedColor] = React.useState(null);
   const openSheet = (color) => {
@@ -96,8 +96,7 @@ const ColorGrid: React.FC<ColorGridProps> = ({ title, description, colors, group
   };
   return (
     <div id={`${group}-colors`} className="scroll-mt-24 scroll-smooth pb-10">
-      <h3 className="text-lg font-medium">{title}</h3>
-      <p className="mb-8">{description}</p>
+      <h3 className="mb-8 text-lg font-medium">{title}</h3>
       {colors.length < 5 ? <LargeColorGrid colors={colors} setOpen={openSheet} /> : <SmallColorGrid colors={colors} setOpen={openSheet} />}
       <ColorSheet color={selectedColor} open={open} setOpen={setOpen} />
     </div>
@@ -122,7 +121,7 @@ const ColorDropdown: React.FC<{ color: CoreTypes.IColorObject; openSheet: (color
         <Copy className="text-gray-400" /> HEX
         <DropdownMenuShortcut className="max-w-[100px] truncate">{color.value}</DropdownMenuShortcut>
       </DropdownMenuItem>
-      <DropdownMenuItem onClick={() => navigator.clipboard.writeText('rgba(0, 49, 82, 1)')}>
+      <DropdownMenuItem onClick={() => navigator.clipboard.writeText(hexToRgbaCss(color.value) ?? color.value)}>
         <Copy className="text-gray-400" /> RGBA
         <DropdownMenuShortcut className="max-w-[100px] truncate">{hexToRgb(color.value)}</DropdownMenuShortcut>
       </DropdownMenuItem>

package/src/app/components/Layout/Main.tsx

@@ -5,7 +5,7 @@ import { Header } from '../../components/Layout/Header';
 import { ThemeProvider } from '../../components/util/theme-provider';
 import SideNav from '../Navigation/SideNav';
 import { ConfigContextProvider } from '../context/ConfigContext';
-import { hasRenderableNav } from '../../lib/utils';
+import { hasRenderableNav, pageTitle } from '../../lib/utils';
 import { SidebarInset, SidebarProvider } from '../ui/sidebar';
 import { SectionLink } from '../util';
 
@@ -34,7 +34,7 @@ export default function Layout<LayoutComponentProps>({ children, config, menu, m
       <ConfigContextProvider defaultConfig={config} defaultMenu={menu}>
         <ThemeProvider attribute="class" defaultTheme="system" enableSystem disableTransitionOnChange>
           <Head>
-            <title>{metadata.metaTitle}</title>
+            <title>{pageTitle(metadata, config?.app?.title)}</title>
             <meta name="description" content={metadata.metaDescription} />
           </Head>
           <div className="absolute left-[-200px] top-[-200px] z-[-1] h-[400px] w-[600px] bg-[#111111] opacity-[0.05] blur-[350px]">