# deeepSpace Documentation - Complete Reference Archive > The continuous source of truth for design systems. Connect Figma components with code, detect drift, and stream living context to AI coding agents. --- ## Section: index --- title: "deeepSpace Documentation" sidebarTitle: "Overview" description: "The continuous source of truth for design systems. Connect Figma components with code, detect drift, and stream living context to AI coding agents." keywords: "design system source of truth, figma code sync, design token drift, ai coding context" icon: "house" --- ## Keep Design and Code Continuously Aligned **deeepSpace is the one source of truth for your design system, connecting designers, developers, and the AI agents they use while keeping design and code continuously aligned.** It connects Figma components with their corresponding code components, tracks and versions both sides, detects structural, styling, token, variant, and visual mismatches, and helps teams understand exactly what changed and where design and implementation have drifted apart. By giving people and their AI agents access to the same design-system context, deeepSpace creates a shared bridge between design and development where teams and AI can understand, maintain, and evolve the design system together. **deeepSpace connects designers, developers, and AI agents around the same design system — Sync → Version → Detect → Verify → Align.**
Start with deeep CLI → Read the Docs
## Quick Start Discover how deeepSpace acts as the single source of truth across your design system. Install the deeep CLI on macOS, Linux, or Windows. Link your local Git repository to a deeepSpace project and configure component discovery. Discover local components and sync their manifest with deeepSpace. ## Product Ecosystem **The designer-side connection** Designers selectively sync components, variants, properties, styles, and design tokens into deeepSpace. **The developer-side connection** Analyzes UI codebases, discovers components and Storybook stories, and syncs code representations. **The central design-system hub** Explore components, connect Figma-to-code mappings, inspect versions, and review visual diffs. **Model Context Protocol server** Connects AI coding agents and IDE tools to live design-system context for automated alignment. ## Continuous Alignment Workflow Designers push from Figma via the plugin; developers sync code components with `deeep init` and `deeep sync`. deeepSpace tracks versions, detects styling/prop drift, and visually verifies rendered components against Figma. Use Web Space and the AI Connector (MCP) to resolve differences and maintain continuous consistency. --- ## Section: guides/intro --- title: "Architecture & Core Pillars" sidebarTitle: "Introduction" description: "Learn the Define, Orbit, and Broadcast architecture of deeepSpace. Eliminate design-code drift across Figma, code repositories, and AI models." keywords: "living design system architecture, define orbit broadcast, zero drift" icon: "book-open" --- ## Welcome to deeepSpace **deeepSpace is the one source of truth for your design system, connecting designers, developers, and the AI agents they use while keeping design and code continuously aligned.** It connects Figma components with their corresponding code components, tracks and versions both sides, detects structural, styling, token, variant, and visual mismatches, and helps teams understand exactly what changed and where design and implementation have drifted apart. By giving people and their AI agents access to the same design-system context, deeepSpace creates a shared bridge between design and development where teams and AI can understand, maintain, and evolve the design system together. **deeepSpace connects designers, developers, and AI agents around the same design system — Sync → Version → Detect → Verify → Align.** --- ## deeepSpace Products **The designer-side connection** Designers selectively sync components from Figma into deeepSpace, including variants, properties, styles, tokens, and design specifications. **The developer-side connection** Analyzes your UI codebase, discovers components and Storybook stories, normalizes metadata, and syncs code-side representations to deeepSpace. **The central design-system hub** Explore components, connect Figma and code mappings, inspect versions, identify mismatches, review visual diffs, and manage projects. **The Model Context Protocol server** Connects AI coding agents and IDE tools to live design-system context so AI operates with the actual source of truth. --- ## Core Capabilities Keep Figma and code components connected and synchronized as the design system evolves over time. Track versions on both design and code sides to understand exactly what changed and when. Detect structural, styling, token, and variant drift between Figma designs and code implementations. Compare rendered code components with their Figma visuals to verify that implementation matches design. Equip AI agents with shared design-system context to understand differences and keep design and code in sync. --- ## Getting Started with the deeep CLI ### Quick Installation Follow the [installation guide](/guides/installation) for your platform, installer availability, and PATH setup. Once installed, run: ```bash deeep auth ``` **New to deeepSpace?** [Create a free account](https://app.deeepspace.com) to get started. ### Continuous Alignment Workflow Designers push from Figma via the plugin; developers sync code components with `deeep init` and `deeep sync`. deeepSpace tracks versions, detects styling/prop drift, and visually verifies rendered components against Figma. Use Web Space and the AI Connector (MCP) to resolve differences and maintain continuous consistency. --- ## Next Steps 1. [Install the deeep CLI](/guides/installation) 2. [Authenticate Your Account](/guides/authentication) 3. [Connect Your Project](/guides/connect) 4. [Sync Components](/guides/sync) --- ## Section: guides/installation --- title: "Install the deeep CLI" sidebarTitle: "Installation" description: "Install the deeep CLI binary on macOS, Windows, and Linux. Set up your system PATH, verify dependencies, and configure global terminal access." keywords: "install deeep cli, design system cli install, terminal binary setup" icon: "download" --- The deeep CLI is the command-line client for deeepSpace. It authenticates your account, links a local Git repository to a deeepSpace project, and syncs your local components with the design system. ## Requirements Before installing, make sure you have: - **Git** (for version control and component synchronization) - A **deeepSpace account** - An accessible operating system keyring for authentication The packaged installers bundle Python. Python 3.13 or newer is required when running or installing from source. Storybook building additionally requires the Node.js runtime, package manager, and dependencies expected by your project. ## Install Installer availability checked on September 16, 2026: the Apple Silicon and Linux URLs responded successfully, but the Intel Mac and Windows URLs returned HTTP 403. If your platform download is unavailable, contact [support@deeepspace.com](mailto:support@deeepspace.com) for an accessible installer. The platform paths below match the CLI's release configuration. For Apple Silicon Macs: ```bash curl -fsSL https://cloud.deeepspace.com/deeep-cli/macos/silicon/latest/install.zip -o install.zip unzip install.zip ./install/deeep_installer ``` For Intel Macs, replace `macos/silicon` with `macos/intel` in the URL. ```bash curl -fsSL https://cloud.deeepspace.com/deeep-cli/linux/latest/install.zip -o install.zip unzip install.zip ./install/deeep_installer ``` 1. Download the installer archive: ```text https://cloud.deeepspace.com/deeep-cli/windows/latest/install.zip ``` 2. Extract the archive and run `deeepSetup.exe`. 3. Follow the installation wizard. After installation, open a new terminal and run: ```bash deeep auth ``` ## Verify the installation Check that the CLI is available: ```bash deeep --version ``` You should see the installed version, for example: ```bash deeep CLI v1.0.0 ``` **PATH not found?** If the `deeep` command is not found, close and reopen your terminal to refresh your PATH. ## Update the CLI To update to the latest version: ```bash deeep update ``` This checks the version reported by the API and downloads a platform-specific installer when a newer version is available. If updating fails, download the installer above and reinstall. ## Uninstall The CLI does not provide an `uninstall` command. To remove it manually: Run `deeep logout` first to clear stored credentials. Then delete the installed binary directory: ```bash rm -rf ~/.deeep/bin ``` The installer adds `. "$HOME/.deeep/env"` to `~/.profile`, `~/.zprofile`, `~/.bashrc`, and `~/.zshrc`. Remove that line from each profile that contains it, then remove `~/.deeep/env`. Also remove any older direct PATH entry for `~/.deeep/bin`. Project configuration files are separate from the installed binary. Run `deeep logout`, then use Windows Settings to uninstall **deeep CLI** from the installed apps list. ## Troubleshooting - **Permission errors on macOS/Linux**: Make the installer executable with `chmod +x ./install/deeep_installer` before running it. - **PATH issues on macOS/Linux**: Restart your terminal, or run `source "$HOME/.deeep/env"` in your current shell. Keep the complete installed bundle, including `_internal`; copying only the executable is insufficient. - **Installation fails**: Contact [support@deeepspace.com](mailto:support@deeepspace.com) for help. ## Next steps 1. [Authenticate](/guides/authentication) with your deeepSpace account 2. [Connect your project](/guides/connect) 3. [Sync components](/guides/sync) with deeepSpace --- ## Section: guides/authentication --- title: "Authenticate the deeep CLI" sidebarTitle: "Authentication" description: "Authenticate the deeep CLI using browser email verification or secure API tokens. Store credentials safely in your local operating system keyring." keywords: "deeep cli login, authenticate deeepspace, os keyring credential storage" icon: "key" --- Authentication connects your local development environment with deeepSpace, enabling you to link projects and sync components. **Before You Begin** Make sure you have: - A deeepSpace account (sign up at [app.deeepspace.com](https://app.deeepspace.com) if needed) - deeep CLI installed on your machine ([Installation Guide](/guides/installation)) ## Getting Started ### Logging In The authentication process uses email verification to ensure secure access to your deeepSpace account. Here's how to get started: Run the `auth` command: ```bash deeep auth ``` Enter the email address associated with your deeepSpace account. Check your inbox for the verification code and enter it in the prompt: The CLI allows up to three verification attempts. On success, it confirms the authenticated email and suggests running `deeep init`. The CLI stores your access token, refresh token, and email in the operating system keyring under the `deeep` service. They are not written into `deeep.json`. A working keyring backend is required. See [Environment and local data](/reference/environment) for credentials and optional sign-in telemetry. ## Account Management ### Checking Authentication Status You can verify your current authentication status at any time: ```bash deeep whoami ``` ### Logging Out To log out and remove stored credentials: ```bash deeep logout ``` Remember to log out when using shared or public computers to protect your account access. To fully clean a machine you no longer use for deeepSpace development — removing both the stored credentials and a linked repository's local files in one step — run `deeep unlink --logout` from inside that repository. Credentials can also be cleared alone with `deeep logout`. ## Troubleshooting Common authentication issues and solutions: #### No verification code received - Check your spam or junk folder. - Request a new code by running `deeep auth` again. #### Invalid code error - Make sure you're using the most recent code sent to your email. #### Session expired - The CLI attempts token refresh when the server reports an expired access token. If refresh fails or the session expires, run `deeep auth` again. #### Too many attempts - Wait a few minutes before retrying. Restarting authentication does not bypass server rate limits. #### Keyring unavailable - Make sure the operating system keyring is available and unlocked. Headless environments need a supported keyring backend; the CLI does not offer a token flag or noninteractive login. ## Next Steps Now that you're authenticated, you can: 1. Connect to your deeepSpace projects — see the [Connect Project](/guides/connect) guide. 2. [Sync components](/guides/sync) between your codebase and deeepSpace. 3. Access your team's shared design system in [Web Space](https://app.deeepspace.com). --- ## Section: guides/connect --- title: "Connect a Git Repository" sidebarTitle: "Connect Project" description: "Link your local Git repository to deeepSpace using deeep init. Detect your frontend framework, configure discovery globs, and generate deeep.json." keywords: "deeep init, connect git repository, link deeepspace project, deeep.json setup" icon: "plug" --- After installing and authenticating the CLI, link your local Git repository to a deeepSpace project. This connection lets you sync your local components with your design system in deeepSpace. ## Prerequisites Before connecting, make sure you have: - [Installed](/guides/installation) the deeep CLI - [Authenticated](/guides/authentication) with your deeepSpace account - A Git repository whose remote matches the repository connected to the selected project - A matching project in deeepSpace, or permission to create one **New to deeepSpace?** If you haven't created a project yet, visit [app.deeepspace.com](https://app.deeepspace.com) to create one, or use `deeep init --create` to create a project directly from the current repository. ## Initialize the project Navigate to your project's root directory and run: **Run from the repository root:** the CLI reads and writes `deeep.json` in the current directory. Creating a project requires an `origin` remote on GitHub, GitLab, or Bitbucket and the corresponding Git-provider connection in deeepSpace. ```bash deeep init ``` The command runs through four steps: Select the deeepSpace workspace to use. Link an existing project or create a new one from this repository. Choose between CLI discovery and Storybook discovery. Confirm the configuration before `deeep.json` is written. After confirmation, `init` records your chosen discovery method on deeepSpace and attempts the first component sync. Prepare committed component sources and a named branch as described in [Sync components](/guides/sync). It then detects your tech stack and asks whether to update project settings. If indexing or syncing fails, the project configuration is saved so you can fix the issue and retry with `deeep sync`. Setup registration is separate from component sync: the Home tab can show the selected method even before a successful sync. If registration fails, local setup continues with a warning; use `deeep init --force` to retry setup for an initialized project. ### Create a new project To skip only the create/link selection prompt and create a new deeepSpace project from the current repository: ```bash deeep init --create ``` `--create` still asks for the workspace, project name, optional description, discovery settings, and confirmation. A blank project name defaults to the repository directory name. Supported remote forms include `https://github.com/owner/repo.git` and `git@github.com:owner/repo.git`, with equivalent GitLab and Bitbucket URLs. Nested GitLab subgroup paths and `ssh://` URLs are not supported by the current project-creation parser. ### Reconnect to a different project To change the linked project or update discovery settings: ```bash deeep init --force ``` --- ## Component discovery During initialization you choose how the CLI finds your components. ### deeep CLI discovery The CLI scans directories that contain component source files, for example: ```text src/components/**/*.{js,jsx,mjs,ts,tsx,vue} packages/*/src/components/**/*.{js,jsx,mjs,ts,tsx,vue} ``` You can confirm, select, or manually enter the directories to scan. ### Storybook discovery If Storybook is detected, you can choose to use your Storybook stories and `index.json` instead. The CLI will ask for: - The `.storybook` configuration directory - The path to the generated Storybook `index.json` - The story file glob patterns - An optional deployed Storybook URL - Whether to host Storybook on deeep during sync See [Storybook discovery and hosting](/guides/storybook) for monorepos, the required first build, and publishing behavior. Enabling hosting during `init` saves the preference; publishing runs on `deeep sync`. --- ## Configuration file After linking, the CLI creates a `deeep.json` file in your repository root. This file contains the project link, project settings, and discovery configuration. ```json { "project": { "name": "My Awesome Project", "uuid": "550e8400-e29b-41d4-a716-446655440000", "projectSettings": { "framework": "react", "language": "tsx", "styling": "tailwind", "styleMode": "external" }, "gitRepoName": "my-org/my-awesome-project", "gitRepoUrl": "https://github.com/my-org/my-awesome-project", "version": 1 }, "discovery": { "type": "CLI", "componentIndexJsonPath": ".deeep.index.json", "components": [ "src/components/**/*.{js,jsx,mjs,ts,tsx,vue}" ], "exclude": [ "**/*.test.*", "**/*.spec.*", "**/*.stories.*", "**/node_modules/**", "**/dist/**", "**/build/**", "**/coverage/**" ] } } ``` For a full reference of all available options, visit the [Project Settings Reference](/reference/project-settings) page. --- ## Check connection status Verify your project connection: ```bash deeep status ``` Example output: ```text Project Status ================================================== Project Name: My Project Workspace: Default Space Project Settings ────────────────────────────── Framework: react Styling: tailwind Language: tsx Style Mode: external Version Information ────────────────────────────── Current Version: 1 ================================================== ``` --- ## Remove the local link To detach this repository from its deeepSpace project — for example before archiving or handing off a codebase — run: ```bash deeep unlink ``` The command asks for confirmation, then deletes `deeep.json` and the generated component index (`.deeep.index.json`, or your configured `componentIndexJsonPath`) from the repository. Everything in deeepSpace stays intact: the project, its synced components, and the connected repository are untouched. Add `--logout` to also clear the stored credentials from the machine, and `-y` to skip the confirmation prompt. To permanently delete the project or disconnect its repository, use the deeepspace web app. `deeep unlink` only cleans the local codebase — you can link the repository again at any time with `deeep init`. --- ## Troubleshooting ### Project not found - Verify you're in the correct directory. - Check that you're logged in with the correct account (`deeep whoami`). - Ensure the project exists in deeepSpace. ### Git repository required - `deeep init` must be run from inside a Git repository. - Creating a project requires a supported `origin` remote. Syncing an existing project requires a local remote matching its connected repository name. ### Git provider connection required - Connect your Git provider account in deeepSpace before linking a repository. ### Configuration errors - For valid configuration that needs changes, run `deeep init --force`. - For malformed JSON, repair the file or back it up outside the repository before removing it and running `deeep init` again. Configuration is loaded before command handling, so `--force` cannot bypass invalid JSON. To remove the local link entirely, run `deeep unlink` instead of deleting the file by hand. - If issues persist, contact [support@deeepspace.com](mailto:support@deeepspace.com) for help. --- ## Next steps Now that your project is connected: 1. [Sync components](/guides/sync) with deeepSpace 2. Learn how to manage your [project settings](/reference/project-settings) --- ## Section: guides/sync --- title: "Component & Token Sync" sidebarTitle: "Sync Components" description: "Scan local components, preview detected changes with dry runs, and sync component manifests and design tokens to deeepSpace with Git commit tracking." keywords: "deeep sync, component discovery dry run, design token sync" icon: "refresh-cw" --- Run `deeep sync` from the root of your linked Git repository to rebuild the local component index and send a component manifest to deeepSpace. ## Before you begin - [Install the CLI](/guides/installation), [authenticate](/guides/authentication), and [connect your project](/guides/connect). - Check out a named branch with at least one commit. Detached HEAD is not supported for uploads. - Make sure a local Git remote matches the linked project's repository name. - Commit the component entry files, discovered local source dependencies, styles, and Storybook story files. Both staged and unstaged changes to these files block uploads; unrelated working-tree changes do not. - Push that commit to your connected Git provider so deeepSpace can access the referenced revision. The CLI does not push Git commits or verify that HEAD has been pushed. - For Storybook discovery, build an up-to-date local Storybook index first. See [Storybook discovery and hosting](/guides/storybook). ## Inspect discovery before uploading ```bash deeep sync --dry-run ``` This writes the component index to `discovery.componentIndexJsonPath` (default `.deeep.index.json`). Inspect its `summary`, `entries`, and `diagnostics` to check what was found. Dry-run still requires authentication, a linked project with `gitRepoName`, and a valid discovery mode. It does not upload components, update remote stack settings, or build or host Storybook, even with `--storybook-hosting`. Dry-run validates discovery, not upload readiness. It skips remote matching, branch/commit checks, committed-file checks, the 1,000-component upload limit, and the empty-manifest guard. A successful dry-run can still be followed by a failed upload. ## Sync your components ```bash deeep sync ``` The CLI: 1. Rebuilds the index using CLI directory discovery or the local Storybook index. 2. Checks the linked repository, branch, commit, component count, and committed source files. 3. Sends a manifest identifying the project, discovery method, branch, commit SHA, components, and content hashes. 4. Requires a `COMPLETED` response and prints created, updated, and unchanged counts. 5. Detects your tech stack and asks whether to update project settings if they differ. 6. Builds and publishes Storybook if hosting is enabled and no existing URL causes it to skip. 7. Builds your components for [design comparison](/guides/compare) and uploads the build privately. The manifest contains file paths, exports, package declarations, hashes, and applicable Storybook metadata. It does not upload raw component source files. Storybook hosting separately uploads the static build. See [Component index and sync data](/reference/component-index). Sync sends the complete discovered component set, not only newly added files. Narrowing discovery can omit previously synced components. An empty manifest is blocked to prevent deactivating all existing components accidentally; inspect dry-run results before changing discovery scope. ## Storybook hosting controls ```bash # Build and publish, including when a Storybook URL is already saved deeep sync --storybook-hosting # Sync components without hosting this time deeep sync --no-storybook-hosting ``` These flags override `discovery.hostStorybook` for the current run. A hosting failure does not roll back a successful component sync. See the [hosting workflow](/guides/storybook) for first-build requirements and republishing. ## Daily workflow 1. Develop your components and stories. 2. Run `deeep sync --dry-run` and review diagnostics. 3. Commit and push the relevant source files. 4. Rebuild Storybook if using Storybook discovery. 5. Run `deeep sync`, or `deeep sync --storybook-hosting` to refresh the hosted build. 6. Review the components in deeepSpace. The project's Home tab shows the registered discovery method and latest reported sync status. ## Troubleshooting | Message or symptom | What to do | | --- | --- | | Authentication required | Run `deeep auth`. | | No project linked / discovery configuration missing | Run `deeep init`, or `deeep init --force` for an existing setup. | | Connected repository required | Connect the project to its Git repository in deeepSpace, then reinitialize locally. | | No matching Git remote | Select the project connected to this repository or correct your local remote. | | Detached HEAD / HEAD cannot resolve | Check out a named branch and create the repository's first commit if needed. | | Untracked / changed component files | Commit the listed files, including dependencies, styles, and stories, then push and retry. | | No components discovered | Review patterns and index diagnostics. For Storybook, build the local index before syncing. | | More than 1,000 components | Review discovery scope and split the component set across appropriate projects. Consider previously synced components before changing scope. | | Index contains warnings or errors | Inspect `.deeep.index.json`; these diagnostics do not always stop the command. | | Storybook hosting failed | Component sync has already completed. Fix the build or upload issue and rerun with `--storybook-hosting`. | The current CLI does not consistently return a nonzero process exit code for command-level failures. For automation, inspect command output and remote sync results; do not treat exit code zero alone as confirmation of sync or hosting success. Initialization and stack updates can also prompt interactively. --- ## Section: guides/compare --- title: "Design Comparison" sidebarTitle: "Design Comparison" description: "Compare your coded components with their Figma design: deeepSpace renders your code in a real browser, measures it, and lists every difference in size, spacing, color, typography and content." keywords: "design vs code comparison, figma code comparison, visual regression design system" icon: "git-compare" --- deeepSpace renders each component from your code in a real browser, in every variant you designed in Figma, and compares it with the design: sizes, spacing, colors, borders, corner radius, typography, text, icons, and a pixel comparison of the whole component. ## Before you begin - **React** components (`.tsx`, `.ts`, `.jsx`, `.js`). Vite, Next.js, webpack and Create React App projects are supported, with or without Storybook. - The component is pushed from Figma with the latest **deeepSpace Figma plugin**. - The Figma component is **linked to its code component** in deeepSpace: on the component page, the **Details** panel → **Code** → **Link the code** (or **Match components** on the Components page, to link them all at once). Every component your files export can be linked, including parts that live next to a main component (a `TableRow` beside `Table`). - Your project's dependencies are installed (`npm install`, `pnpm install`…): the CLI builds your components with them. ## How it runs 1. Run `deeep sync`. After syncing your components, the CLI builds them into a small preview app with your project's own settings (path aliases, Tailwind/PostCSS, CSS modules, Sass, fonts, global styles and providers) and uploads it **privately** to deeepSpace. 2. deeepSpace renders every Figma variant of each linked component in a sandboxed browser, then compares it with the design. 3. Open the component in deeepSpace: each variant shows how closely the code matches it. A comparison usually takes about a minute. The sync output ends with one of: | Message | Meaning | |---|---| | **Design comparison started** | Your build was uploaded; results appear in a minute or so. | | **Design comparison up to date** | Nothing changed since the last comparison. | | **Design comparison skipped** | The build couldn't be made; the message says why. Your component sync itself succeeded. | A component that fails to build (a missing import, for example) is **set aside**: the sync output names it and the reason, and every other component is still compared. The preview page is the default. If it can't be built and the project has Storybook, the CLI uses your Storybook instead, opening each component's story with the design's values as story args. ## Reading the results Everything is on the component page. - **Score**: the pill at the top, such as *87% · Close to the design*, is how closely the component matches its design across all variants. Green from 95%, orange from 80%, red below. Click it to open the variant that needs the most work. - **Variants**: every variant designed in Figma, as cards, each with its own score and number of differences. Filter them by Figma property. Move the mouse across a card to swipe between the design and your rendered code. - **One variant**: click a card to open it. Switch between **Design**, **Code** (your component, rendered), **Side by side** and **Swipe** (drag the line between the design and the code). Use ← → or the strip at the bottom to move between variants, and Esc to go back to all of them. - **Differences**: each one is a numbered pin on the image and a line in the panel on the right, in plain words: *Font size: 16px in design, 14px in code*. Click a pin or a line, or use ↑ ↓: the spot is outlined, the rest of the image fades, and its values show next to it. - **High** and **Medium** differences are the ones you can see. **Minor** ones (a color or size that isn't a design token, details barely visible) are folded into one line; **Show** lists them and pins them too. - A difference caused by another one (a button is narrower because its font is smaller) is listed under its cause, not as a separate difference. - The same difference on repeated elements (five accordion titles) is one difference, *in 5 places*. - **How it's rendered** (in the panel of a variant): the exact code rendered, for example ``, and how each Figma property was turned into a prop. You can correct it. - **What's checked** (in the panel of a variant): what was matched and checked, and what isn't checked yet. Use **Compare again** (the **Details** panel → **Code**) to run the comparison now, even if nothing changed. ## When something isn't right | You see | What to do | |---|---| | **Your code couldn't be rendered** for a variant | Open the variant → **How it's rendered**: a Figma value may need a different prop or value. Edit the row; your correction applies from the next comparison, which starts right away. | | The wrong code component is compared | The **Details** panel → **Code** → **Change**, then pick the right one. | | A difference that isn't real | Select it, then **Not right?**: it is stored for review and doesn't change the result. | | *Font "…" is not in the code build* | Your project's build doesn't load a font the design uses, so text is drawn with a fallback and its size differences barely count. Load the font in your app's global styles or root layout. | | **The comparison failed** | It is retried automatically. If it still fails, the page says why: use **Compare again**. | Mappings come from your **Figma Code Connect** files when you have them, otherwise from matching names. Your corrections always win. ## Known limits The comparison doesn't check everything yet. Knowing what it can't see keeps a result from being read as more (or less) than it is. | Limit | What you'll see | |---|---| | **Animations, transitions, loading and skeleton states** | These variants are listed but not compared yet. | | **Other screen sizes** | Each variant is compared at the width it has in Figma only. | | **Shapes drawn in CSS only** (`::before` / `::after`, such as a switch's knob or a custom check mark) | Their size and color aren't measured. The pixel comparison still sees them: a difference there shows as *looks different in this area*. | | **Sample content that only exists in the design** (a modal's example paragraph, a card's placeholder text) | Text the design shows is passed to your component's text props automatically. When the component has no prop for it (the page fills it in), the code renders without it and it shows as missing: mark it **Not right?** if that's expected. | | **Parts that only work inside their parent** (form fields that need their form, resizable panels that need their group) | The preview places a part inside its parent automatically when it can. When it can't, the part fails to render or looks different on its own: compare the parent component instead. | | **Storybook rendering** | When the comparison renders from your Storybook (the fallback, or `"source": "storybook"`), only components with a story are compared. The preview page has no such limit. | ## Settings Add an optional `compare` block to `deeep.json`: ```json deeep.json { "compare": { "enabled": true, "source": "auto", "css": ["src/styles/globals.css"], "head": "compare-head.html", "wrapper": "src/test/Providers.tsx", "decorators": true, "stories": { "Button": "components-button--primary" } } } ``` | Key | Default | Meaning | |---|---|---| | `enabled` | `true` | `false` turns the comparison build off for this project. | | `source` | `"auto"` | `"preview"` or `"storybook"` forces one way of rendering; `"auto"` uses the preview page and falls back to Storybook. | | `css` | detected | Global stylesheets to load, when the CLI doesn't find them in your app's entry, root layout or Storybook preview. | | `head` | detected | An HTML file with extra `` tags (font links, for example). | | `wrapper` | detected | A component that wraps every render (theme or providers). By default your Storybook decorators are reused. | | `decorators` | `true` | `false` stops reusing your Storybook decorators. | | `stories` | automatic | For Storybook rendering, the story to use per component name. | ## Privacy Your build is uploaded privately and only used to render your components. Comparison images are visible only to people with access to your project. Old builds and images are cleaned up automatically. --- ## Section: guides/storybook --- title: "Storybook Integration & Hosting" sidebarTitle: "Storybook" description: "Extract CSF component metadata, parse Storybook index versions (v2-v5), sync stories, and host static builds directly on deeepSpace for live previews." keywords: "storybook component discovery, host storybook deeepspace, csf metadata sync" icon: "book-open" --- Storybook discovery joins your generated story index with local component and story source files. You can use an existing deployed Storybook URL or publish a static build through deeepSpace. ## Prepare your Storybook Install your project's dependencies and build Storybook using the script already defined in its `package.json`. For example, if your script is named `build-storybook`: ```bash npm run build-storybook ``` Find the generated `index.json` (commonly `storybook-static/index.json`). Legacy story indexes with a `stories` collection are also supported. Commit and push the component sources, their dependencies and styles, and the story files before syncing. The generated Storybook output does not need to be committed. Component sync runs before hosting. Even `deeep sync --storybook-hosting` needs a usable local index first when discovery is `STORYBOOK`. Hosting cannot bootstrap a sync blocked by a missing or empty index. ## Connect Storybook discovery Run `deeep init` for a new setup, or `deeep init --force` to change an existing one. Choose Storybook and review: - The Storybook configuration directory. - The generated index path. - Story patterns and the deeep component index output path. - An optional deployed Storybook URL for live previews and deep links. - Whether to host Storybook on deeep during sync (off by default). The CLI discovers Storybook configuration directories and index files, and can infer output paths from package scripts and supported wrapper scripts. You can enter a path manually if detection is incorrect. If Storybook is not detected, initialization shows setup instructions and stops that selection. This example is the `discovery` section of an initialized `deeep.json`: ```json { "discovery": { "type": "STORYBOOK", "storybookConfigDirectory": ".storybook", "storybookIndexJsonPath": "storybook-static/index.json", "componentIndexJsonPath": ".deeep.index.json", "stories": ["src/**/*.stories.@(js|jsx|mjs|ts|tsx)"], "exclude": ["**/node_modules/**", "**/dist/**"], "hostStorybook": true } } ``` All file paths are relative to the Git repository root. In a monorepo, use paths such as `packages/ui/.storybook` and `packages/ui/storybook-static/index.json`. Run `deeep` from the repository root containing `deeep.json`. Storybook import paths are resolved against the package owning the configuration first, then the repository root. The generated Storybook index determines which stories are processed. The saved `stories` and `exclude` fields are metadata in the current implementation; they do not filter the Storybook index. Change your Storybook configuration and rebuild its index to change the synced story set. ## Use an existing deployed Storybook Set `discovery.storybookUrl` to your deployment's base URL, for example `https://storybook.example.com`. It must start with `http://` or `https://`; trailing slashes are removed in the sync manifest. ```bash deeep sync --no-storybook-hosting ``` The URL accompanies Storybook discovery metadata. It does not replace the local index or local story source files, and the CLI does not download the remote index. ## Host Storybook on deeep ```bash deeep sync --storybook-hosting ``` After component sync succeeds, the CLI finds a package script containing `storybook build`, `build-storybook`, or a recognized wrapper. It runs the build in that package, uploads the output files, updates the project's `storybookUrl` setting, and saves the public URL in `discovery.storybookUrl` locally. Build output is inferred from explicit `--output-dir` / `-o` options, supported `outDir` configuration or wrapper patterns, then defaults to `storybook-static` in the build package. Script and configuration parsing is heuristic; verify the chosen command and directory in custom setups. For monorepos, the CLI considers nested packages and makes ancestor `node_modules/.bin` directories available. Yarn Plug'n'Play builds run through `yarn run`. ### Hosting precedence and republishing | Setting or flag | Behavior | | --- | --- | | No flag, no `hostStorybook` | Hosting is off. | | `hostStorybook: true`, no saved URL | Attempt hosting after sync. | | `hostStorybook: true`, existing `storybookUrl` | Skip hosting to preserve the existing URL. | | `--storybook-hosting` | Attempt hosting and override the existing-URL skip. | | `--no-storybook-hosting` | Skip hosting for this run. | | `--dry-run` | Never build or host, regardless of other flags. | After the first successful publish saves a URL, use `--storybook-hosting` to republish changes. Setting `hostStorybook: true` alone does not rebuild on every sync. `deeep init` can save the hosting preference but does not run the hosting pipeline. Hosting is also available after CLI discovery when your repository has a discoverable Storybook build script. The flags do not change your discovery mode. ## Limits and recovery - The build timeout defaults to 600 seconds. Set `DEEEP_STORYBOOK_BUILD_TIMEOUT` to change it. - If a build command is missing and Storybook is declared in the repository, an interactive terminal offers to install dependencies and retry once. It detects npm, pnpm, Yarn, or Bun from the nearest lockfile. Noninteractive runs show instructions instead. - Dependency installation defaults to a 1,800-second timeout, configurable with `DEEEP_STORYBOOK_INSTALL_TIMEOUT`. - More than 5,000 output files stops publishing. Output larger than 500 MiB produces a warning but still uploads. File symlinks are skipped. - Uploads retry network failures and server errors; HTTP 4xx failures are reported without retry. Error output includes affected paths and response details. - No recognized build script or an empty output directory skips hosting. A missing output directory or failed upload reports a hosting failure. - If the server reports missing `index.html`, check that the detected output directory contains the complete static site. Hosting uploads the static build to a public URL, including assets and any source maps your build produces. Review the output you intend to publish. A hosting failure leaves the earlier component sync intact. For unresolved stories, unsupported index versions, and source-analysis limits, see [Component index and sync data](/reference/component-index). --- ## Section: guides/ai-connector --- title: "Connect Your AI Agent" sidebarTitle: "AI Connector (MCP)" description: "Give Claude, Cursor, VS Code and other AI agents read-only access to your deeepSpace design system through the AI Connector (MCP server): components, Figma ↔ code mappings, design vs code differences and design tokens." keywords: "deeepspace mcp, ai connector, model context protocol, claude code mcp, cursor mcp, vs code mcp, design tokens for ai" icon: "bot" --- The AI Connector is deeepSpace's **MCP server** (Model Context Protocol). Once connected, your AI agent can read your design system while it works, so the code it writes uses your real components and tokens instead of guesses. **What your agent can read:** - **Components:** every Figma component of a project, its variants and properties - **Figma ↔ code mappings:** which code component builds each design component, and its source file - **Design vs code differences:** the latest comparison of a component, variant by variant - **Design tokens:** colors, typography, and the spacing, radius, size and shadow tokens synced from your Figma variables and effect styles - **Project context:** settings, versions, the connected Git repository, comments **Read-only:** the AI Connector never changes anything in deeepSpace. Your agent only sees the workspaces and projects your account can open. ## Prerequisites Before connecting, make sure you have: - A deeepSpace account, with access to the project your agent should read - An AI tool that supports remote MCP servers over HTTP (Claude Code, Claude Desktop, Cursor, VS Code…) - For mappings and differences: components [synced](/guides/sync) and [compared](/guides/compare); for tokens: the style guide synced from the Figma plugin ## Server address ```text https://mcp.deeepspace.com/mcp ``` The connection uses the **Streamable HTTP** transport. You sign in with your deeepSpace account the first time (see [Sign in](#sign-in)). ## Add it to your AI tool Add the server from your terminal: ```bash claude mcp add --transport http deeep https://mcp.deeepspace.com/mcp ``` Then, in Claude Code, run `/mcp`, select **deeep** and choose **Authenticate**. Your browser opens the deeepSpace sign-in page. 1. Open **Settings → Connectors**. 2. Choose **Add custom connector**. 3. Name it `deeep` and enter the URL `https://mcp.deeepspace.com/mcp`. 4. Select **Connect**: your browser opens the deeepSpace sign-in page. Add the server to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project): ```json { "mcpServers": { "deeep": { "url": "https://mcp.deeepspace.com/mcp" } } } ``` In **Settings → MCP**, select **Login** next to **deeep** to open the deeepSpace sign-in page. Add the server to `.vscode/mcp.json` in your workspace: ```json { "servers": { "deeep": { "type": "http", "url": "https://mcp.deeepspace.com/mcp" } } } ``` Or from a terminal: ```bash code --add-mcp '{"name":"deeep","type":"http","url":"https://mcp.deeepspace.com/mcp"}' ``` Start the server from `mcp.json` (or **MCP: List Servers**) and approve the sign-in when VS Code asks. Use it from Copilot Chat in **Agent** mode. **Other tools:** any MCP client that supports remote servers over HTTP with OAuth sign-in works the same way: give it the server address above. ## Sign in The first time your AI tool connects, it opens deeepSpace's sign-in page in your browser: The page shows **Connect to deeepSpace** and the name of the app asking for access. Only continue if you started this from your own AI tool. Use the email of your deeepSpace account and select **Send code**. The code arrives by email and expires after 5 minutes. Once it's accepted, you're sent back to your AI tool, already connected. Your AI tool keeps you signed in and renews the login by itself. To disconnect, remove the server from the tool (for example `claude mcp remove deeep`). ### Tools without browser sign-in If your MCP client can't open a browser sign-in, it can sign in from the chat instead: send the header `X-Deeep-Login: chat` with its requests. Two extra tools then appear: `deeep-connect` emails you a code, and `deeep-verify` checks it. The login stays on the server for that session; it's never shown in the conversation. ## Find your project Most tools take a **project UUID**. It's in the address of your project in deeepSpace: ```text https://app.deeepspace.com/project/1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d └──────────── project UUID ───────────┘ ``` You can also just name the project: your agent can list your workspaces (`fetch-all-workspaces`) and their projects (`get-all-projects`) to find it. ## What to ask "Build a settings form with the components and tokens of my Fintech Design System project." "Which spacing and radius tokens does the Fintech Design System define? Use them in this card." "How does ButtonSecondary differ from its design? Fix the code to match." "Which code component and file implement the Figma ButtonDanger?" The server also offers two ready-made prompts your tool may show: - **Implement a deeepSpace component** (`implement-component`): build a component with the project's tokens, colors and typography instead of hard-coded values. - **Check design vs code drift** (`check-design-drift`): compare a project's design components with their linked code and list what differs. For every tool and what it returns, see the [AI Connector tools reference](/reference/ai-connector-tools). ## Troubleshooting Your tool isn't signed in yet, or its login expired and couldn't be renewed. Start the sign-in again from the tool (for example `/mcp` → **Authenticate** in Claude Code). The tools only see what your account can open in deeepSpace. Check the project UUID, and that your account is a member of that project's workspace. The design component isn't linked to a code component yet, or it hasn't been compared. Link it in deeepSpace, then run `deeep sync` (see [Compare design and code](/guides/compare)). These come from your Figma **number variables** and **effect styles**. Sync your style guide from the deeepSpace Figma plugin to send them. --- ## Section: reference/cli-commands --- title: "CLI Command Reference" sidebarTitle: "CLI Commands" description: "Complete terminal command reference for the deeep CLI. Syntax, arguments, and flags for auth, init, sync, status, whoami, logout, and unlink commands." keywords: "deeep cli commands, cli syntax flags options, terminal reference" icon: "terminal" --- This guide provides a reference for all commands in the deeep CLI. Run bare `deeep` for the command overview. Run `deeep --help` or `deeep --help` at any time for command-specific options. ## Global options | Option | Description | |--------|-------------| | `-v`, `--version` | Show the CLI version | | `-h`, `--help` | Show help information | --- ## Commands ### `deeep auth` Authenticate with deeepSpace. The command prompts for your email and then asks for a one-time verification code sent to your inbox. ```bash deeep auth ``` ### `deeep init` Initialize the current Git repository as a deeepSpace project. The command walks you through selecting a workspace, choosing or creating a project, and configuring component discovery. ```bash deeep init ``` **Options:** | Option | Description | |--------|-------------| | `-f`, `--force` | Reinitialize an already linked project | | `-c`, `--create` | Choose project creation without the create/link selection prompt; workspace, project details, discovery, and confirmation remain interactive | `init` records the chosen discovery method remotely and attempts the first component sync. It then offers to update detected stack settings. Index or sync failures can leave a saved, usable project configuration: fix the reported issue and run `deeep sync`. An initialized project requires `--force` to change its setup. ### `deeep sync` Scan your local components and sync the component index with the linked deeepSpace project. ```bash deeep sync ``` **Options:** | Option | Description | |--------|-------------| | `--dry-run` | Write the local index without uploading, updating remote stack settings, or hosting Storybook | | `--storybook-hosting` | Build and host Storybook after component sync, overriding a saved URL | | `--no-storybook-hosting` | Skip hosting even if enabled in `deeep.json` | See [sync prerequisites and dry-run limits](/guides/sync) and [Storybook hosting precedence](/guides/storybook). Pass only one hosting flag; if both are supplied, the last flag wins. ### `deeep status` Show the current project status, including the linked project name, workspace, and project settings. ```bash deeep status ``` ### `deeep whoami` Display the email address of the currently authenticated user and the CLI version. ```bash deeep whoami ``` ### `deeep update` Check for updates and install the latest version of the deeep CLI. ```bash deeep update ``` ### `deeep logout` Remove locally stored authentication tokens and sign out of deeepSpace. ```bash deeep logout ``` ### `deeep unlink` Remove this repository's local deeepSpace link. The command deletes `deeep.json` and the generated component index (`.deeep.index.json`, or the configured `componentIndexJsonPath`). Nothing is deleted from deeepSpace — the project, its components, and the connected repository stay intact, and you can link the repository again at any time with `deeep init`. ```bash deeep unlink ``` **Options:** | Option | Description | |--------|-------------| | `-y`, `--yes` | Remove the link without asking for confirmation | | `--logout` | Also clear the stored deeepSpace credentials from this machine | To permanently delete a project or disconnect its repository, use the deeepspace web app — `unlink` only cleans the local codebase. --- ## Common workflow ```bash # Authenticate deeep auth # Link or create a project deeep init # Sync components deeep sync # Check project status deeep status ``` All subcommands accept `-h` / `--help`. The CLI intentionally has no `pull`, `push`, `link`, `ls`, or `uninstall` commands; `deeep unlink` is the supported way to detach a repository, and its `-y` / `--yes` flag is the only noninteractive confirmation skip. For more details about the configuration file, see the [Project Settings Reference](/reference/project-settings). --- ## Section: reference/project-settings --- title: "Project Settings (deeep.json)" sidebarTitle: "Project Settings" description: "Comprehensive reference for deeep.json settings. Configure component globs, Storybook index locations, build commands, and Git repository links." keywords: "deeep.json schema reference, project configuration, component patterns" icon: "sliders-horizontal" --- The `deeep.json` file in your repository root stores the link between your local project and deeepSpace, plus the settings used to discover and sync your components. Run commands from the repository root containing this file: the CLI loads configuration from the current working directory, not by searching parent directories. Discovery paths are relative to the Git root. The file is maintained by the CLI and may also be rewritten after other successful commands. Use valid JSON and repository-relative paths without `..`; paths resolving outside the repository are rejected. Repair malformed JSON before reinitializing, since `--force` does not bypass configuration loading. --- ## Configuration structure ```json { "project": { "name": "My Awesome Project", "uuid": "550e8400-e29b-41d4-a716-446655440000", "projectSettings": { "framework": "react", "language": "tsx", "styling": "tailwind", "styleMode": "external", "remBaseFontSize": 16, "customInstructions": "" }, "gitRepoName": "my-org/my-awesome-project", "gitRepoUrl": "https://github.com/my-org/my-awesome-project", "version": 1 }, "discovery": { "type": "CLI", "componentIndexJsonPath": ".deeep.index.json", "components": [ "src/components/**/*.{js,jsx,mjs,ts,tsx,vue}", "packages/*/src/components/**/*.{js,jsx,mjs,ts,tsx,vue}" ], "exclude": [ "**/*.test.*", "**/*.spec.*", "**/*.stories.*", "**/node_modules/**", "**/dist/**", "**/build/**", "**/coverage/**" ] } } ``` --- ## Project fields | Field | Type | Description | |-------|------|-------------| | `project.name` | string | Name of the linked deeepSpace project | | `project.uuid` | string | Unique identifier of the deeepSpace project | | `project.projectSettings` | object | Tech stack and code-generation preferences | | `project.gitRepoName` | string | Connected Git repository name, for example `owner/repo` | | `project.gitRepoUrl` | string | URL of the connected Git repository | | `project.version` | number | Project version saved when linking; component sync does not refresh this value | --- ## Project settings fields | Field | Type | Description | |-------|------|-------------| | `projectSettings.framework` | string | Frontend framework | | `projectSettings.language` | string | Programming language / JSX flavor | | `projectSettings.styling` | string | Styling technology | | `projectSettings.styleMode` | string | How styles are organized | | `projectSettings.remBaseFontSize` | number | Base font size used for `rem` conversions | | `projectSettings.customInstructions` | string | Free-text instructions for code generation | | `projectSettings.storybookUrl` | string | Remote Storybook URL updated after successful hosting; the local discovery URL is stored separately in `discovery.storybookUrl` | --- ## Stack detection After initialization, the CLI detects `framework`, `language`, `styling`, and `styleMode` and asks whether to update the remote project settings. After sync, it skips this prompt when those four values already match. Declining keeps the existing settings; an API update failure is reported as a warning. Other preferences such as `remBaseFontSize` and `customInstructions` are not inferred by stack detection. Detection uses the root `package.json` and source-file signals. Review its suggestion in monorepos or mixed-framework repositories. Editing local `projectSettings` alone is not a general remote-settings update command. ## Detected values ### Frameworks | Value | Description | |-------|-------------| | `react` | React | | `reactNative` | React Native | | `vue` | Vue | | `angular` | Angular | | `svelte` | Svelte | | `none` | No framework detected | ### Languages | Value | Description | |-------|-------------| | `js` | JavaScript | | `ts` | TypeScript | | `jsx` | JavaScript with JSX | | `tsx` | TypeScript with JSX | | `none` | No language detected | ### Styling | Value | Description | |-------|-------------| | `css` | Plain CSS | | `scss` | SCSS / Sass | | `less` | Less | | `tailwind` | Tailwind CSS | | `styledJs` | CSS-in-JS (for example styled-components or Emotion) | | `none` | No styling detected | ### Style modes | Value | Description | |-------|-------------| | `external` | Styles in separate files | | `scoped` | Scoped styles (for example CSS modules or Vue scoped styles) | | `dynamic` | Dynamic CSS-in-JS | | `none` | No style mode detected | The detector does not emit `inline`. Framework detection does not imply full source-analysis support: for example, `svelte` is detected as a stack value, but `.svelte` files are not scanned by CLI discovery. See [discovery coverage](/reference/component-index). --- ## Discovery configuration The `discovery` object tells the CLI how to find your components. ### CLI discovery Use this method when you want the CLI to scan your source files directly. ```json { "discovery": { "type": "CLI", "componentIndexJsonPath": ".deeep.index.json", "components": [ "src/components/**/*.{js,jsx,mjs,ts,tsx,vue}" ], "exclude": [ "**/*.test.*", "**/*.spec.*", "**/*.stories.*", "**/node_modules/**", "**/dist/**", "**/build/**", "**/coverage/**" ] } } ``` | Field | Description | |-------|-------------| | `type` | Must be `CLI` | | `componentIndexJsonPath` | Output path; defaults to `.deeep.index.json` when omitted | | `components` | Glob patterns for component source files | | `exclude` | Glob patterns to ignore | ### Storybook discovery Use this method when your components are documented with Storybook. ```json { "discovery": { "type": "STORYBOOK", "storybookConfigDirectory": ".storybook", "storybookIndexJsonPath": "storybook-static/index.json", "componentIndexJsonPath": ".deeep.index.json", "stories": [ "src/**/*.stories.@(js|jsx|mjs|ts|tsx)" ], "exclude": [ "**/node_modules/**", "**/dist/**" ] } } ``` | Field | Description | |-------|-------------| | `type` | Must be `STORYBOOK` | | `storybookConfigDirectory` | Path to your `.storybook` config directory | | `storybookIndexJsonPath` | Path to the generated Storybook `index.json` | | `componentIndexJsonPath` | Output path; defaults to `.deeep.index.json` when omitted | | `stories` | Saved story-pattern metadata; does not filter the generated Storybook index in the current implementation | | `exclude` | Saved exclusion metadata; does not filter Storybook entries in the current implementation | | `storybookUrl` | Optional deployed base URL starting with `http://` or `https://`; included in Storybook sync metadata | | `hostStorybook` | Boolean, default `false`; enables hosting after sync, unless an existing URL causes it to skip | The generated Storybook index determines the story set. `storybookConfigDirectory` defaults to `.storybook` during index generation; `storybookIndexJsonPath` must be configured. `hostStorybook` can also be used with CLI discovery when the repository has a Storybook build script. See [Storybook discovery and hosting](/guides/storybook) for full behavior. --- ## Legacy configuration When there is no nonempty `discovery` object, the CLI recognizes the older `project.discoveryType` values `cli` and `storybook` case-insensitively and supplies default discovery settings. It removes that legacy field from the loaded project. Run `deeep init --force` to review and save explicit settings for the current layout. ## Best practices 1. **Keep `deeep.json` in version control** so the whole team uses the same project link and discovery rules. 2. **Do not edit `uuid` or `gitRepoUrl` manually** unless you know the values are correct. 3. **Use `deeep init --force`** to safely change discovery settings or relink the project. 4. **Verify discovery with `deeep sync --dry-run`** before syncing to deeepSpace. --- ## Section: reference/component-index --- title: "Component Index (.deeep.index.json)" sidebarTitle: "Component Index" description: "Deep-dive into local component indexing, static prop type analysis, package boundary resolution, and secure sync manifest payload schemas." keywords: ".deeep.index.json, static prop analysis, component manifest payload" icon: "component" --- Both discovery modes generate a local `.deeep.index.json` by default. Use `deeep sync --dry-run` to inspect it without uploading components. The index is generated output; change your source or `deeep.json` and regenerate it instead of editing entries manually. ## Local index structure | Field | Contents | | --- | --- | | `schemaVersion` | Index schema version, currently `1`. | | `type` | `deeep-component-index`. | | `generatedAt` | UTC generation timestamp. | | `generator` | CLI name and version. | | `project` | Framework, language, and styling settings when available. | | `discovery` | Discovery mode and its configuration; Storybook also records the index format version and optional URL. | | `entries` | Component entries keyed by generated identifiers. | | `summary` | Component, scanned-file, warning, and error counts; Storybook adds story and story-file counts. | | `diagnostics` | Messages with severity, code, and available file/component/story context. | Entries include names, source and import paths, exports, framework/language, props and analysis status, local dependencies, declared package versions, styles, asset paths, and a source hash. Storybook entries also include story file paths and story metadata. The local index is more detailed than the upload manifest. Props, asset lists, diagnostics, and the complete index file are not sent as the component-sync payload. ## CLI discovery coverage The scanner reads `.js`, `.jsx`, `.mjs`, `.ts`, `.tsx`, and `.vue` files matching `components`, then applies `exclude`. It skips `.d.ts`, symlinked files/directories, and common dependency/build directories, including `node_modules`, `.git`, `dist`, `build`, and `storybook-static`. Use repository-relative patterns such as `src/components/**/*.{js,jsx,mjs,ts,tsx,vue}`. Brace alternatives and `**/` matching are supported. Re-export-only `index` files are skipped as component entries; point discovery at implementation directories. Analysis recognizes common exported components, Vue single-file components, and Angular component declarations. It extracts props from supported TypeScript declarations and local type imports, React PropTypes, Vue props, Angular inputs, JSDoc, defaults, and usage. Local source imports and supported TypeScript/JavaScript path aliases contribute dependency paths. Analysis is static and heuristic. It does not execute your application or provide full TypeScript compiler resolution. Review `propsAnalysis` and diagnostics when types are inferred, partial, or unresolved. Svelte can be detected as a project framework, but `.svelte` files are not supported by the direct component scanner. Source files larger than 2 MiB are skipped with `SOURCE_TOO_LARGE`. Unreadable or non-UTF-8 source produces `SOURCE_READ_FAILED`. ## Storybook metadata The reader recognizes index format versions `2`, `3`, `4`, and `5` (the index's `v` field, not the installed Storybook major version). Other versions are parsed on a best-effort basis with a warning. Both modern `entries` and legacy `stories` collections are accepted; modern docs-only entries are excluded. Component resolution supports common CSF metadata, typed `Meta` patterns, namespace imports, local aliases, workspace package imports, and supported barrel re-exports. When a component implementation cannot be resolved, a synthetic entry based on the story file may be retained with `COMPONENT_SOURCE_UNRESOLVED`; inspect it before uploading. Story metadata includes available IDs, names, export names, titles, tags, JSON-safe args, and per-story argTypes. Meta-level args are merged with story overrides. Functions, expressions, JSX-like values, deeply nested values, and oversized values are omitted rather than executed. Sanitization limits nested containers to six levels and drops dictionary values whose JSON serialization exceeds 4,096 characters. When present, `.storybook/preview.js`, `.jsx`, `.ts`, or `.tsx` under the configured directory is attached as `previewPath` during manifest creation. It is not part of the component `sourcePaths` list or its content hash. Commit and push preview configuration as well so the referenced revision contains it. The Storybook index size limit is 25 MiB. A missing index generates a warning and empty local index; a real sync rejects the empty manifest. Invalid JSON or a missing entries/stories collection blocks index generation. ## Package versions For each component, package imports are matched against the nearest owning `package.json`, walking toward the repository root. The first manifest found is used; undeclared packages are omitted rather than guessed from ancestor manifests. Declaration precedence is `dependencies`, then `peerDependencies`, then `devDependencies`. Versions are declared ranges, not exact installed or lockfile-resolved versions. Registry ranges such as `^18.0.0` are preserved. Dist-tags without digits and recognized non-registry protocols such as `workspace:`, `file:`, and `git+` become `*`. ## Uploaded manifest | Field | Contents | | --- | --- | | `projectUuid` | Linked project identifier. | | `discoveryType` | `CLI` or `STORYBOOK`. | | `branch`, `commitSha` | Named local Git branch and full HEAD commit SHA. | | `components` | Complete discovered component set, limited to 1,000 entries. | | `storybookUrl` | Optional deployed URL from Storybook discovery. | | `manifestHash` | SHA-256 of the canonical discovery, revision, components, and optional URL payload. | Each component contains `externalId`, `name`, `exportName`, `entryPath`, `sourcePaths`, and `packages`, with optional `storybook` metadata and `contentHash`. Source paths combine discovered local source dependencies, styles, and story files, excluding the entry path itself. Asset paths are not included in this list. The component `contentHash` is a SHA-256 digest of sorted, unique entry/source paths and their file bytes, separated by null bytes. It differs from the local index's `sourceHash`, which hashes only the entry file and uses a `sha256:` prefix. The content hash is omitted if a required file is missing. The canonical manifest hash supports repeatable sync requests; timestamps from the local index are not included. ## Common diagnostics | Code | Meaning and next step | | --- | --- | | `NO_COMPONENT_FILES` | Check include patterns and excluded directories. | | `NO_COMPONENT_EXPORT` | Check that the file exports a recognizable component. | | `BARREL_FILE_SKIPPED` | Informational: a re-export-only index is not a component. | | `UNRESOLVED_PROPS` | Review unsupported or unresolved type expressions. | | `STORYBOOK_INDEX_MISSING` | Build Storybook and verify its configured index path. | | `STORYBOOK_INDEX_VERSION_UNKNOWN` | Inspect results and check for a CLI update. | | `STORY_SOURCE_UNRESOLVED` / `STORY_SOURCE_READ_FAILED` | Check index import paths against local story sources. | | `COMPONENT_SOURCE_UNRESOLVED` | Review the synthetic entry and component import resolution. | Warning/error counts in the generated index do not necessarily fail the command. Review them along with the discovered set before syncing. --- ## Section: reference/environment --- title: "Environment Variables & Storage" sidebarTitle: "Environment" description: "Configure process environment variables, custom API endpoints, network timeouts, and local credential storage locations used by the deeep CLI." keywords: "deeep cli environment variables, custom endpoint config, keyring storage" icon: "settings" --- The CLI reads these variables from its process environment. Set them before running `deeep`. | Variable | Default | Purpose | | --- | --- | --- | | `DEEEP_API_URL` | `https://api.deeepspace.com` | API base URL for GraphQL and token refresh. | | `DEEEP_WEB_URL` | `https://app.deeepspace.com` | Web app base URL used for account signup guidance. | | `DEEEP_CDN_URL` | `https://cloud.deeepspace.com` | Base URL used for CLI update downloads. | | `DEEEP_TIMEOUT` | `180` | API read timeout in seconds; the connect timeout is 10 seconds. Use an integer. | | `DEEEP_STORYBOOK_BUILD_TIMEOUT` | `600` | Storybook build timeout in seconds. Non-integer values fall back to the default. | | `DEEEP_STORYBOOK_INSTALL_TIMEOUT` | `1800` | Dependency-install timeout in seconds during missing-command recovery. Non-integer values fall back to the default. | | `DEEEP_MIXPANEL_TOKEN` | Empty | Optional Mixpanel token enabling sign-in telemetry. Empty disables the client. | For example, allow 15 minutes for a Storybook build on macOS/Linux: ```bash DEEEP_STORYBOOK_BUILD_TIMEOUT=900 deeep sync --storybook-hosting ``` In PowerShell: ```powershell $env:DEEEP_STORYBOOK_BUILD_TIMEOUT = "900" deeep sync --storybook-hosting ``` These timeouts do not configure static-file uploads. Storybook upload requests use a 10-second connection timeout and 120-second read timeout. ## Credentials and project files Authentication stores the access token, refresh token, and email in the operating system's keyring through Python `keyring`, under the `deeep` service. `deeep logout` removes these entries. They are not stored in `deeep.json`. A working, accessible keyring backend is required, including in headless environments; the CLI has no token or noninteractive login flag. `deeep.json` stores the project link and discovery settings. Configuration is read from the current working directory, so run project commands from the repository root where that file lives. Index paths are resolved relative to the Git root. Successful commands can rewrite `deeep.json`, including account commands; it is not exclusively written by `init`. Commit `deeep.json` when the team should share the setup. The generated `.deeep.index.json` can be ignored by Git. Review [sync prerequisites](/guides/sync) for the source files that must be committed. ## Optional telemetry With a nonempty `DEEEP_MIXPANEL_TOKEN`, the CLI uses the account email as the Mixpanel identifier, updates a CLI-user profile property, and reports a `Sign In` event containing the email, platform, and sign-in method. This telemetry is identifiable, not anonymous. It does not send source files or authentication tokens to Mixpanel. To disable this client for a shell session: ```bash export DEEEP_MIXPANEL_TOKEN="" ``` Component manifests and optional Storybook build uploads are separate from sign-in telemetry. See [Component index and sync data](/reference/component-index) and [Storybook hosting](/guides/storybook). --- ## Section: reference/ai-connector-tools --- title: "AI Connector Tools" sidebarTitle: "AI Connector Tools" description: "Reference for the tools, prompts and resources of the deeepSpace AI Connector (MCP server): what each one returns and the inputs it takes." keywords: "deeepspace mcp tools, ai connector reference, fetch-tokens, fetch-code-mappings, fetch-component-differences" icon: "wrench" --- Your AI agent calls these tools by itself while it works; you don't call them directly. This page lists what each one gives the agent. To connect a tool, see [Connect your AI agent](/guides/ai-connector). All tools are **read-only** and only return what your deeepSpace account can open. Most take a project UUID: see [Find your project](/guides/ai-connector#find-your-project). ## Design and code | Tool | What it returns | Inputs | |------|-----------------|--------| | `fetch-code-mappings` | Every Figma component of a project with the code component linked to it (name, source file, export name), or nothing when it isn't linked yet. `sharedWith` lists other design components built by the same code component. | `uuid` (project) | | `fetch-component-differences` | The latest design vs code comparison of one Figma component: its linked code component, overall score, and per variant its status, score, how it was rendered (Figma property → code prop) and its differences (severity, element, property, design value vs code value). `state` is `READY` when results exist; otherwise it says what's missing (`NOT_LINKED`, `NOT_COMPARED`, `COMPARING`…). | `componentId` (design component), `variant` (optional: one variant, for example `Size=Large, State=Default`), `includeMinor` (optional: include low-severity notes, default `false`) | | `fetch-components` | The components of a project: name, slug and latest version. | `uuid` (project) | | `fetch-component` | One component version in full: design data, variants, thumbnail, creator. Takes the **version** UUID (`version.uuid` from `fetch-components`, or `figmaComponent.versionUuid` from `fetch-code-mappings`), not the component id. | `uuid` (component version) | | `search-components` | Components of a project matching a name or keyword. | `uuid` (project), `query` | | `fetch-component-comments` | Comments on a component or asset, paginated. | `componentId` or `assetId`, `size` (optional, default 10, max 100), `page` (optional) | ## Design tokens | Tool | What it returns | Inputs | |------|-----------------|--------| | `fetch-tokens` | The tokens synced from Figma variables and effect styles: spacing, radius, sizes, border widths, opacity, font sizes and weights, line heights, letter spacing, and shadows with ready-to-use CSS. Each variable has its value in every mode and the variable it points to when it's an alias. | `uuid` (project), `kind` (optional: `spacing`, `radius`, `size`, `borderWidth`, `opacity`, `fontSize`, `fontWeight`, `lineHeight`, `letterSpacing`, `other` or `shadow`) | | `fetch-colors` | The color tokens of the project's style guide. | `uuid` (project) | | `fetch-typography` | The typography tokens of the project's style guide. | `uuid` (project) | | `get-style-guide-versions` | The style guide's version history, with its colors and typography. | `uuid` (project), `version` (optional) | | `fetch-design-system` | The layout values deeepSpace derived from the project's components (spacing, radius, border width and sizing found in them, grid, breakpoints, container, content). For the tokens defined in Figma, use `fetch-tokens`. | `projectUuid` | | `get-project-layout` | Layout values derived from components, for older projects. | `uuid` (project) | ## Projects and workspaces | Tool | What it returns | Inputs | |------|-----------------|--------| | `get-current-user` | Your deeepSpace profile, workspaces, projects and settings. | None | | `fetch-all-workspaces` | Your workspaces, with plan and status. | None | | `get-all-projects` | The projects of one workspace, with an optional name filter. | `workspaceId`, `query` (optional), `skip` and `take` (optional pagination, `take` max 100) | | `search-projects` | Projects of a workspace matching a name. | `workspaceId`, `query`, `skip` and `take` (optional) | | `fetch-project-info` | A project's name, status, settings and dates. | `uuid` (project) | | `fetch-project-versions` | All versions of a project. | `uuid` (project) | | `fetch-project-generation-preferences` | The project's code generation settings: framework, language, styling. | `projectUuid` | | `fetch-collections` | The project's collections (groupings of components, colors, typography, assets). | `projectUuid` | | `fetch-assets` | The project's images, icons and other media. | `projectUuid` | | `fetch-project-folder-structure` | The generated file and folder structure, from the components' Git paths. | `projectUuid` | ## Git repository | Tool | What it returns | Inputs | |------|-----------------|--------| | `fetch-connected-repository` | The Git repository connected to the project. | `projectUuid` | | `fetch-repository-tree` | Files and folders of the connected repository. | `projectUuid`, `path` (optional, default the root), `branch` (optional, default the repository's default branch) | | `fetch-repository-file-content` | The contents of one file of the connected repository. | `projectUuid`, `path`, `branch` (optional) | | `get-git-connections` | The Git services connected to your account. | None | ## Connection | Tool | What it returns | Inputs | |------|-----------------|--------| | `health` | Whether the connection to deeepSpace and its services works. | None | | `deeep-connect` | Chat sign-in only: emails you a 6-digit code. Available when the client sends `X-Deeep-Login: chat`. | `email` | | `deeep-verify` | Chat sign-in only: checks the code and keeps the login for this session. | `email`, `code` | ## Prompts | Prompt | What it does | |--------|--------------| | `implement-component` | Builds a component of a deeepSpace project with its design tokens, colors and typography instead of hard-coded values. | | `check-design-drift` | Compares a project's design components with their linked code and lists what differs. | ## Resources | Resource | Contents | |----------|----------| | `user://me` | Your deeepSpace profile. | | `git://status` | Your Git connections and their status. | | `components://{uuid}/catalog` | The components of a project. | | `project://{uuid}/info` | A project's details and settings. | | `design-system://{uuid}/tokens` | A project's design tokens in one snapshot: colors, typography, Figma number variables and shadows (as `fetch-tokens` returns them). | | `config://app` | The AI Connector's configuration. | --- ## Section: reference/release --- title: "CLI Updates & Releases" sidebarTitle: "CLI Updates" description: "Check your installed deeep CLI version, learn how to update the binary, and understand release distribution channels across supported platforms." keywords: "update deeep cli, check cli version, cli release notes, binary updates" icon: "history" --- ## Version and documentation scope ```bash deeep --version deeep update ``` The audited CLI source identifies itself as **v1.0.0**. These docs cover source changes through commit `d518e9a`, including Storybook hosting and discovery registration. That source version alone does not confirm which changes are included in a downloaded installer. Use `deeep sync --help` to check whether your installation offers the hosting flags. ## Changes covered in this documentation | Area | Behavior | | --- | --- | | Commands | Authentication, project creation/linking, sync and dry-run, status, account information, logout, and updates. | | Discovery setup | Initialization records CLI or Storybook discovery on the project independently of component-sync success. | | Git validation | Component uploads identify branch and commit and require committed source paths matching the connected repository. | | Content tracking | Canonical component content hashes and manifest hashes support repeatable sync requests. | | Packages | Components include package declarations from their owning package manifest, including monorepo packages. | | Storybook metadata | Stories, JSON-safe args, argTypes, supported preview paths, and optional deployed URLs accompany component metadata. | | Storybook discovery | Improved index detection, typed CSF, workspace imports, aliases, barrel re-exports, and legacy/unknown index handling. | | Storybook hosting | Optional build/upload after sync, explicit hosting flags, saved public URLs, configurable timeouts, dependency recovery, and monorepo/Yarn PnP handling. | | Upload reliability | Retried transient uploads, server-provided content types and object ACL headers, and useful upload failure details. | See [Storybook discovery and hosting](/guides/storybook), [Component index and sync data](/reference/component-index), and [Environment and local data](/reference/environment) for the configuration and limits. ## Resources - [Installation and update instructions](/guides/installation) - [CLI command reference](/reference/cli-commands) - [Support](mailto:support@deeepspace.com)