Configuration Reference

This comprehensive reference documents every available configuration option in Handoff. Learn how to customize your design system's output, manage theme settings, and define breakpoints to build a documentation platform that perfectly matches your team's workflow and brand identity.

Configuration Reference

The handoff.config.js file (or config.json) is the central control point for your Handoff project. It allows you to define how tokens are fetched, how the documentation app behaves, and how your build pipeline functions.

Core Settings

OptionTypeDefaultDescription
figma_project_idstringnullYour Figma file ID. Found in the URL of your Figma file: figma.com/file/[ID]/....
dev_access_tokenstringnullYour Figma personal access token. Required for fetching data from Figma.
exportsOutputDirectorystring'exported'The directory where design tokens, CSS/Sass variables, and assets are saved.
sitesOutputDirectorystring'out'The directory where the static Handoff documentation site is generated.

App Configuration (app)

The app block controls the visual and functional aspects of the Handoff documentation website.

Metadata & Branding

  • title: (string) The title displayed in the browser tab and header. Default: 'Handoff Design System'.
  • client: (string) The client name displayed in the footer. Default: 'Handoff Technologies'.
  • theme: (string) The theme used for the documentation app. Default: 'default'.
  • attribution: (boolean) Whether to show Handoff attribution in the footer. Default: true.
  • google_tag_manager: (string) Your GTM Container ID (e.g., GTM-XXXXXX).

Token Display

  • type_copy: (string) The sample text used on the Typography page.
  • type_sort: (string[]) Explicit sort order for typography categories (e.g., ['Heading 1', 'Paragraph']).
  • color_sort: (string[]) Explicit sort order for color palettes (e.g., ['primary', 'secondary']).
  • component_sort: (string[]) Explicit sort order for component variants.

Layout & Responsive

  • base_path: (string) The base URL path if the app is hosted in a subdirectory (e.g. /docs).
  • breakpoints: (object) Defines the breakpoints used in the documentation previews. 
    example.javascript
    javascript
    1breakpoints: {
2  sm: { size: 576, name: 'Small' },
3  md: { size: 768, name: 'Medium' },
4  // ...
5}
  • ports: (object) The ports used for the local dev server. Default: { app: 3000, websocket: 3001 }.

Entry Points (entries)

Defines the file paths for your custom styles and scripts that should be included in the build.

  • scss: (string) Path to your main Sass entry point. Default: './sass/main.scss'.
  • js: (string) Path to your main JavaScript entry point. Default: './js/main.js'.
  • components: (string[]) Array of directories to search for custom component definitions. Default: ['./components'].

Asset Downloads (assets_zip_links)

Allows you to override the default asset ZIP generation with custom external links for icons and logos.

example.javascript
javascript
1assets_zip_links: {
2  icons: 'https://my-cdn.com/icons.zip',
3  logos: null, // If null, Handoff generates these automatically
4}

Extension Hooks (hooks)

Hooks allow you to intercept the build and transformation process. For a complete guide on using hooks, see the Hooking Architecture page.

  • jsBuildConfig: Customize Vite config for scripts.
  • cssBuildConfig: Customize Vite config for styles.
  • htmlBuildConfig: Customize Vite config for HTML generation.
  • validateComponent: Run custom validation logic on components.
  • getSchemaFromExports: Define how prop schemas are extracted.