---
title: "Creating Your Own Theme"
description: "Step-by-step guide to building, publishing, and sharing custom themes"
canonical_url: "https://docs.farming-labs.dev/docs/themes/creating-themes"
markdown_url: "https://docs.farming-labs.dev/docs/themes/creating-themes.md"
last_updated: "2018-10-20"
agent:
  tokenBudget: 1200
  task: "Create, apply, and optionally publish a reusable Farming Labs docs theme."
  outcome: "The custom theme loads from docs.config, its CSS is present globally, and a production build renders the intended tokens and components."
  appliesTo:
    framework:
      - "nextjs"
      - "tanstackstart"
      - "sveltekit"
      - "astro"
      - "nuxt"
    version:
      - ">=0.2.60"
    package:
      - "@farming-labs/docs"
      - "@farming-labs/theme"
  prerequisites:
    - "Begin with a working docs application and identify the framework-specific global stylesheet."
    - "Decide whether to create a new theme, extend one preset, or override only a few theme values."
  files:
    - "themes/my-theme.ts"
    - "themes/my-theme.css"
    - "docs.config.tsx"
    - "src/lib/docs.config.ts"
    - "app/global.css"
    - "src/styles/app.css"
    - "src/app.css"
    - "nuxt.config.ts"
  sideEffects:
    - "Changing the active theme or its CSS affects layout and styling across the entire docs site."
    - "Publishing creates a versioned package consumed by other projects."
  verification:
    - description: "Run the project production build and inspect representative navigation, code, callout, table, and search components."
      expect: "The build succeeds with no missing CSS import and every component uses the intended theme tokens."
  rollback:
    - "Restore the previous theme factory and CSS import, then unpublish or deprecate an incorrect package version according to registry policy."
  failureModes:
    - symptom: "The theme configuration loads but pages look unstyled."
      resolution: "Import the theme's CSS from the framework global stylesheet and ensure its path matches the selected theme package."
    - symptom: "A shared theme works locally but fails for consumers."
      resolution: "Export the theme entry and CSS in package.json and test installation from the packed npm artifact."
---

<!-- farming-labs:agent-contract:start -->
## Agent Contract

Task: Create, apply, and optionally publish a reusable Farming Labs docs theme.
Outcome: The custom theme loads from docs.config, its CSS is present globally, and a production build renders the intended tokens and components.

### Applies To

- Framework: `nextjs`, `tanstackstart`, `sveltekit`, `astro`, `nuxt`
- Version: `>=0.2.60`
- Package: `@farming-labs/docs`, `@farming-labs/theme`

### Prerequisites

- Begin with a working docs application and identify the framework-specific global stylesheet.
- Decide whether to create a new theme, extend one preset, or override only a few theme values.

### Files

- `themes/my-theme.ts`
- `themes/my-theme.css`
- `docs.config.tsx`
- `src/lib/docs.config.ts`
- `app/global.css`
- `src/styles/app.css`
- `src/app.css`
- `nuxt.config.ts`

### Side Effects

- Changing the active theme or its CSS affects layout and styling across the entire docs site.
- Publishing creates a versioned package consumed by other projects.

### Verification

- Run the project production build and inspect representative navigation, code, callout, table, and search components.
  - Expected: The build succeeds with no missing CSS import and every component uses the intended theme tokens.

### Rollback

- Restore the previous theme factory and CSS import, then unpublish or deprecate an incorrect package version according to registry policy.

### Failure Modes

- The theme configuration loads but pages look unstyled. — Recovery: Import the theme's CSS from the framework global stylesheet and ensure its path matches the selected theme package.
- A shared theme works locally but fails for consumers. — Recovery: Export the theme entry and CSS in package.json and test installation from the packed npm artifact.
<!-- farming-labs:agent-contract:end -->

# Creating Your Own Theme

## Creating Your Own Theme task

Task: Create, apply, and optionally publish a reusable Farming Labs docs theme.

Expected result: The custom theme loads from docs.config, its CSS is present globally, and a production build renders the intended tokens and components.

Exact implementation:

```ts
import { createTheme } from "@farming-labs/docs";

export const myTheme = createTheme({
  name: "my-theme",
  ui: {
    colors: {
      primary: "#e11d48",
      background: "#09090b",
      muted: "#71717a",
      border: "#27272a",
    },
  },
});
```

```ts
import { extendTheme } from "@farming-labs/docs";
import { fumadocs } from "@farming-labs/theme";

export const myTheme = extendTheme(fumadocs(), {
  name: "my-fumadocs-variant",
  ui: {
    colors: { primary: "#22c55e", background: "#0c0c0c" },
    sidebar: { style: "bordered" },
  },
});
```
## Creating Your Own Theme prerequisites

- Begin with a working docs application and identify the framework-specific global stylesheet.
- Decide whether to create a new theme, extend one preset, or override only a few theme values.
- Applies to framework nextjs, tanstackstart, sveltekit, astro, nuxt; version >=0.2.60; package @farming-labs/docs, @farming-labs/theme.

## Creating Your Own Theme verification

- Run the project production build and inspect representative navigation, code, callout, table, and search components. Expected: The build succeeds with no missing CSS import and every component uses the intended theme tokens.
- Failure: The theme configuration loads but pages look unstyled.
- Recovery: Import the theme's CSS from the framework global stylesheet and ensure its path matches the selected theme package.
- Rollback: Restore the previous theme factory and CSS import, then unpublish or deprecate an incorrect package version according to registry policy.

## Creating Your Own Theme agent guidance

Build reusable presets with `createTheme` from `@farming-labs/docs`, give each one a unique `name`, and call its factory as `theme: myTheme()` inside `defineDocs()`. In contrast, pass the `DocsTheme` instance from `extendTheme()` as `theme: myTheme` without calling it.
Validate the production build plus navigation, search, code, callouts, and tables. Config-only themes need no custom CSS; when a package ships custom CSS, export it as `./css` and import it from the consumer's global stylesheet.
For an unstyled config-only theme, verify that the intended factory or extended instance reaches `defineDocs()`. For a package that only fails for consumers, verify `.` and, when present, `./css` in `package.json` exports against the packed artifact.

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).