---
title: "Themes"
description: "Built-in themes and how to create your own"
canonical_url: "https://docs.farming-labs.dev/docs/themes"
markdown_url: "https://docs.farming-labs.dev/docs/themes.md"
last_updated: "2018-10-20"
agent:
  tokenBudget: 750
  task: "Select and apply a built-in or custom theme to a Farming Labs docs site."
  outcome: "docs.config and the global stylesheet reference the same theme and docs pages render its visual defaults."
  appliesTo:
    framework:
      - "nextjs"
      - "tanstackstart"
      - "sveltekit"
      - "astro"
      - "nuxt"
    version:
      - ">=0.2.60"
    package:
      - "@farming-labs/docs"
      - "@farming-labs/theme"
  prerequisites:
    - "The docs app and its framework-specific global stylesheet already work."
    - "Choose a built-in preset before creating a custom theme unless requirements demand custom tokens."
  files:
    - "docs.config.tsx"
    - "src/lib/docs.config.ts"
    - "app/global.css"
    - "src/styles/app.css"
    - "src/app.css"
    - "nuxt.config.ts"
  sideEffects:
    - "Switching themes changes the default colors, typography, spacing, layout, and components for every docs page."
  verification:
    - description: "Build and open a docs page containing navigation, code, callouts, and tables."
      expect: "The production build succeeds and all elements use the selected theme without an unstyled flash."
  rollback:
    - "Restore the previous theme factory and matching CSS import."
  failureModes:
    - symptom: "The selected theme has no visual effect."
      resolution: "Import the matching theme CSS in the global stylesheet and restart the framework dev server."
    - symptom: "TypeScript cannot resolve the theme factory."
      resolution: "Install the correct framework theme package and import the documented exported preset name."
---

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

Task: Select and apply a built-in or custom theme to a Farming Labs docs site.
Outcome: docs.config and the global stylesheet reference the same theme and docs pages render its visual defaults.

### Applies To

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

### Prerequisites

- The docs app and its framework-specific global stylesheet already work.
- Choose a built-in preset before creating a custom theme unless requirements demand custom tokens.

### Files

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

### Side Effects

- Switching themes changes the default colors, typography, spacing, layout, and components for every docs page.

### Verification

- Build and open a docs page containing navigation, code, callouts, and tables.
  - Expected: The production build succeeds and all elements use the selected theme without an unstyled flash.

### Rollback

- Restore the previous theme factory and matching CSS import.

### Failure Modes

- The selected theme has no visual effect. — Recovery: Import the matching theme CSS in the global stylesheet and restart the framework dev server.
- TypeScript cannot resolve the theme factory. — Recovery: Install the correct framework theme package and import the documented exported preset name.
<!-- farming-labs:agent-contract:end -->

# Themes

## Themes task

Task: Select and apply a built-in or custom theme to a Farming Labs docs site.

Expected result: docs.config and the global stylesheet reference the same theme and docs pages render its visual defaults.

Exact implementation:

```tsx title="docs.config.ts"
import { defineDocs } from "@farming-labs/docs";
import { pixelBorder } from "@farming-labs/theme/pixel-border";

export default defineDocs({
  entry: "docs",
  theme: pixelBorder(),
});
```

```css title="app/global.css"
@import "tailwindcss";
@import "@farming-labs/theme/pixel-border/css";
```
## Themes prerequisites

- The docs app and its framework-specific global stylesheet already work.
- Choose a built-in preset before creating a custom theme unless requirements demand custom tokens.
- Applies to framework nextjs, tanstackstart, sveltekit, astro, nuxt; version >=0.2.60; package @farming-labs/docs, @farming-labs/theme.

## Themes verification

- Build and open a docs page containing navigation, code, callouts, and tables. Expected: The production build succeeds and all elements use the selected theme without an unstyled flash.
- Failure: The selected theme has no visual effect.
- Recovery: Import the matching theme CSS in the global stylesheet and restart the framework dev server.
- Rollback: Restore the previous theme factory and matching CSS import.

## Themes agent guidance

Select the factory and package subpath as a pair—for example, `pixelBorder` from `@farming-labs/theme/pixel-border` with `theme: pixelBorder()`—then import the matching `@farming-labs/theme/pixel-border/css` globally.
Test navigation, code blocks, callouts, and tables after switching presets. Use `createTheme()` for a reusable custom factory and `extendTheme()` to derive a theme from an existing preset.
If config builds but visuals do not change, repair the CSS entrypoint; if the factory cannot be resolved, copy its exact export and import path from the built-in themes table.

## 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).