> ## Documentation Index
> Fetch the complete documentation index at: https://docs.outkit.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Theme Sync

> Detect, apply, and sync design tokens between your codebase and your Outkit profile

The theme commands keep your Outkit profile's design tokens in lockstep with your application's
real design system. No more copy-pasting hex codes.

## The Theme Cascade

`outkit theme detect` scans your repo in this order, stopping at the first source that
returns enough tokens:

1. shadcn/ui CSS variables
2. Tailwind v4 `@theme` blocks
3. Tailwind v3 config (`tailwind.config.{js,ts}`)
4. CSS-in-JS configs (Chakra, Mantine, Stitches, Panda, Tamagui)
5. Inline `<ThemeProvider>` JSX literals
6. Generic `:root { --… }` blocks
7. SVG logo extraction (primary color from your logo)
8. Repo-wide hex frequency

To see what would be detected without writing anything:

```bash theme={null}
outkit theme detect --json
```

## Interactive flow

```bash theme={null}
outkit theme
```

This is the friendliest entry point: it detects, previews swatches in your terminal, and
asks for confirmation before pushing.

## One-shot

```bash theme={null}
outkit theme apply
```

Runs the cascade, applies a contrast guard, and PATCHes the active profile.

| Flag               | Effect                                        |
| ------------------ | --------------------------------------------- |
| `--from <file>`    | Use a specific source instead of the cascade. |
| `--map <map.json>` | Override the canonical token name mapping.    |
| `--preset <id>`    | Use a curated palette instead of detecting.   |
| `-y`               | Skip the diff confirmation.                   |

## Presets

```bash theme={null}
outkit theme presets
```

Curated palettes shipped with the CLI:

* `modern-neutral`
* `vibrant-violet`
* `warm-editorial`
* `dark-first`

Apply one with `outkit theme apply --preset modern-neutral`.

## Round-tripping `outkit.theme.json`

```bash theme={null}
outkit theme pull    # write the active profile's tokens to outkit.theme.json
outkit theme push    # PATCH the profile from outkit.theme.json
outkit theme diff    # show local-vs-remote diff (exits non-zero when they differ)
```

Use `outkit theme diff` as a CI gate to ensure the deployed profile matches what's in your
repo.

## CI hook

```bash theme={null}
outkit theme sync --on-build
```

This adds a `prebuild` script to your `package.json` that runs `outkit theme sync` on every
build, so a token change in your codebase always lands in the deployed profile.

## Watch mode

```bash theme={null}
outkit theme watch
```

Re-syncs whenever a known source file changes. Useful while iterating on a design pass.

## Helpers

```bash theme={null}
outkit theme map --explain     # print the canonical name mapping table
outkit theme regen-surfaces    # recompute surfaceLowest…surfaceHighest from background
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Profiles and deploy" icon="rocket" href="/docs/cli/reference#profiles--deploy">
    Treat profiles as code: `outkit profiles diff / push / pull / deploy / rollback`.
  </Card>

  <Card title="Tail render logs" icon="terminal" href="/docs/cli/dev">
    Watch what your design tokens look like on real renders.
  </Card>
</CardGroup>