Creating Themes

@farming-labs/docs — Creating and Sharing Themes

Use this skill when: the user wants to create a custom theme, extend an existing theme, or publish/share a theme (e.g. as npm). For general setup (init, install, docs.config), use the getting-started skill.

Full guide: Creating your own theme.

Quick: create a theme

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

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

Use in docs.config:

import { defineDocs } from "@farming-labs/docs";
import { myTheme } from "./my-theme";

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

Users can override: theme: myTheme({ ui: { colors: { primary: "#3b82f6" } } }).

Copy prompt: match an existing website

Use this when a user wants docs that look like their main website.

Create or update an @farming-labs/docs theme so the documentation feels visually consistent with my existing website.

Inputs:
- Website URL: [WEBSITE_URL]
- Docs entry folder: [DOCS_ENTRY]
- Framework: [FRAMEWORK, defaults to Next.js]
- Brandfetch brand context: [BRAND_CONTEXT]

Use the @farming-labs/docs website as implementation context before coding:
- Framework docs: https://docs.farming-labs.dev
- Theme guide: https://docs.farming-labs.dev/docs/themes/creating-themes
- Components guide: https://docs.farming-labs.dev/docs/customization/components
- CLI guide: https://docs.farming-labs.dev/docs/cli

Use the Brandfetch brand context as brand hints, then inspect the existing website and extract its design system: brand colors, typography, spacing, border radius, shadows, navigation style, cards, buttons, callouts, code blocks, tables, and light/dark mode behavior.

Then implement the docs theme:
- choose the closest built-in theme as the base, or create a custom theme with createTheme() / extendTheme()
- update docs.config.ts[x] to use the theme
- add or update the theme CSS import in the app's global stylesheet
- add CSS overrides only where config tokens are not enough
- keep the docs readable, scannable, and documentation-first; do not copy marketing hero sections into docs pages
- preserve agent-ready docs features such as .md routes, llms.txt, AGENTS.md, skill.md, sitemap, robots.txt, MCP, JSON-LD, and markdown alternate links

Verification:
- run the docs dev server
- check desktop and mobile layouts
- confirm search, sidebar navigation, code blocks, callouts, tabs, and page actions still work
- list the files changed and explain which website design tokens were mapped into the docs theme

Full docs copy block: Creating your own theme.

Extend an existing theme

Use extendTheme() to build on a built-in preset:

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

export const myTheme = extendTheme(fumadocs(), {
  name: "my-variant",
  ui: {
    colors: { primary: "#22c55e" },
    sidebar: { style: "bordered" },
  },
});

For other frameworks use the same framework's theme package (e.g. @farming-labs/svelte-theme, @farming-labs/astro-theme, @farming-labs/nuxt-theme). You can extend any built-in: fumadocs, darksharp, pixelBorder, colorful, greentree, darkbold, shiny, ledger, shadcn, concrete, commandGrid, and hardline.

Important: extendTheme() returns a theme instance (not a factory). Use createTheme() when you want a reusable preset that others call as myTheme().

Config options (createTheme / extendTheme)

Only set what you want to change; the rest is inherited.

Cherry-pick from built-in themes

Mix defaults from different built-in themes:

import { DefaultUIDefaults } from "@farming-labs/theme/default";
import { DarksharpUIDefaults } from "@farming-labs/theme/darksharp";
import { PixelBorderUIDefaults } from "@farming-labs/theme/pixel-border";
import { createTheme } from "@farming-labs/docs";

export const myTheme = createTheme({
  name: "my-hybrid-theme",
  ui: {
    colors: PixelBorderUIDefaults.colors,
    typography: DefaultUIDefaults.typography,
    layout: DarksharpUIDefaults.layout,
    sidebar: { style: "floating" },
    components: {
      HoverLink: { linkLabel: "Open page", showIndicator: false },
    },
  },
});

Export your own defaults so others can extend: export { MyThemeDefaults };.

Publishing as an npm package

Package layout

my-docs-theme/
  src/
    index.ts       ← createTheme() and exports
    theme.css      ← optional CSS overrides
  package.json

package.json (minimal)

{
  "name": "my-docs-theme",
  "version": "1.0.0",
  "type": "module",
  "exports": {
    ".": { "import": "./dist/index.mjs", "types": "./dist/index.d.mts" },
    "./css": "./src/theme.css"
  },
  "peerDependencies": {
    "@farming-labs/docs": ">=0.0.1"
  }
}

If the theme has no CSS, omit the "./css" export. If it does, users import it in their global CSS (Next: app/global.css, SvelteKit: src/app.css, Nuxt: css in nuxt.config.ts, Astro: in layout or page).

How users install and use

npm install my-docs-theme
# or pnpm add / yarn add / bun add

import { myTheme } from "my-docs-theme";

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

@import "tailwindcss";
@import "my-docs-theme/css";

Optional: custom CSS file

For pixel-level control (sidebar, code blocks, callouts), ship a theme.css that:

1. Imports a base preset: @import "@farming-labs/theme/presets/black"; or @import "@farming-labs/theme/presets/neutral";
2. Overrides --color-fd-* and other variables in :root and .dark
3. Targets component selectors (e.g. aside#nd-sidebar, a[data-active]) as needed

See the Creating your own theme doc for the full list of selectors and presets.

Resources

• Full guide: docs.farming-labs.dev/docs/themes/creating-themes
• Themes overview: docs.farming-labs.dev/docs/themes
• Repo: github.com/farming-labs/docs