Skip to content

Live customizer

Preview colors, radius, fonts, and documentation layout without changing website content.

On this page

Open the customizer

Choose Customize this layout in the sidebar footer, or use the adjustments icon next to the color-mode button in either header. The color-mode button keeps its quick light/dark toggle.

The customizer previews appearance settings immediately. Your preferences stay in this browser and apply across routes. Website text, titles, descriptions, links, icons, SEO, and other content are not editable here.

Enable it in your app

The Indocio documentation app enables the customizer. Consuming apps opt in through their app configuration:

app/app.config.ts
<script setup lang="ts">
import type { DocsConfig } from '@igrislabs/indocio/types'

defineProps<{ settings: DocsConfig; page?: unknown }>()
</script>

<template>
  <footer class="mt-12 border-t border-border pt-6 text-sm">
    Your team's documentation. <a href="https://example.com/support">Get help</a>.
  </footer>
</template>

Set enabled: false to hide the controls and ignore saved customizer preferences. Customizing the site does not require enabling this panel; normal app configuration and CSS continue to work.

Appearance

The first screen keeps the common choices together: color mode, primary, accent, font, site size, and radius. Each row shows its current value. Primary and accent change the scheme currently shown in the preview.

Open Colors & contrast for independent background and foreground dropdowns for Primary, Secondary, and Accent. Choose Light colors or Dark colors to edit that scheme. The mode buttons on the main screen choose System, Light, or Dark for the preview; editing a dark palette does not overwrite the light palette.

  • Colors: Black, White, Neutral, Teal, Blue, Violet, Rose, Amber, Orange, and Green.
  • Site default: remove that token's override and restore the app's CSS.
  • Foreground: use an explicit color, or leave it automatic. An overridden background gets a contrasting black/white foreground unless you choose one.
  • Use primary: available for accent backgrounds, independently in each scheme. This explicitly links accent to primary.
  • Corner radius: choose a preset on the main screen, or open Typography for a synchronized slider and numeric input from 0 to 1.5rem.
  • Interface fonts: Inter, Roboto, Open Sans, Lato, DM Sans, Source Sans 3, or system sans.
  • Code fonts: JetBrains Mono, Fira Code, IBM Plex Mono, Source Code Pro, or system mono.

The layer registers the named webfonts through Nuxt Fonts. Font files are served locally, and browsers load the selected family on demand. Site-default font options preserve your existing CSS.

Color dropdowns display their own selected value and swatch. Changing accent does not change the primary or secondary selection. Colors in the other scheme remain unchanged. Secondary palettes affect secondary controls; accent usage elsewhere in documentation follows the existing theme behavior.

Sizes

Site size on the main screen scales typography, spacing, rem-based dimensions, and controls across landing and documentation pages. XS is compact (87.5%), M is the normal scale (100%), and XL is spacious (112.5%). The selected size also sets the global IPEX control default, including the product dropdown. Touch controls keep a minimum 44px height.

Choose Site default to restore the app's scale. Explicit pixel dimensions stay fixed; rem-based dimensions scale with the site.

Open Typography to set Reading text size (12–22px), Page title size (24–48px), and Code text size (11–20px) using numeric inputs. These explicit pixel sizes override the site scale for the default documentation article. They do not edit page text, titles, or metadata.

Layout

Adjust article maximum width using a positive CSS length, such as 42rem, 800px, or 75ch. Invalid values show a message and leave the last valid width in place.

Move the TOC beside the article or to the screen's right edge. Adjust heading depth, sidebar width, desktop sidebar collapse, docs header height, TOC width and gap, and the product switcher style when the site has at least two documentation spaces. Sidebar and header/TOC dimensions use numeric inputs.

The article stays centered on screen. The desktop TOC becomes an expandable page control when there is insufficient room. Heading depth can only reveal headings already generated by your Markdown parser.

Visible elements

Show or hide the sidebar, TOC, breadcrumbs, footer, previous/next links, search, and copy-link action. The header's customizer trigger stays available even when the sidebar is hidden.

The layout and element controls apply to documentation pages. The appearance controls also apply to the landing page.

Saved preferences and reset

Browser preferences preview above the normal page, space, and site settings. These preferences do not modify source files or other visitors' settings.

Reset removes all customizer overrides and restores System color mode. Page and product settings become active again. Storage is local to the site's origin, under indocio:customizer:v1; it is separate from Nuxt Color Mode's preference storage. Older saved palettes migrate to light/dark overrides automatically. If browser storage is unavailable, live preview still works for the current visit.

The customizer uses the IPEX Drawer with its sm overlay width, a fixed header and footer, and a scrolling settings area. Buttons, selects, number fields, and mode toggle groups use the shared IPEX size, radius, material, and focus recipes. Control size follows the site’s UI defaults; drawer width is independent of control size. Selected values align to the left within their controls, with chevrons on the right. Opening a detailed screen slides it in from the right; Back reverses the direction. The panel also slides and fades in and out from the right. Reduced-motion preferences remove the slides. The mobile TOC uses a chevron that rotates when expanded.

Preferences load after hydration. Server-rendered pages use the site's original defaults before saved previews are restored.

Copy settings into your project

Choose Get code in the panel footer, then use the file-specific copy buttons. Each copies a ready-to-use snippet for that file:

ButtonDestinationContents
Copy main.cssapp/assets/main.cssFormatted theme and typography CSS
Copy app.config.tsapp/app.config.tsdefineAppConfig with layout and product-switcher overrides
Copy nuxt.config.tsnuxt.config.tsdefineNuxtConfig with the color-mode preference
Copy ui.tsapp/plugins/ui.tsGlobal IPEX control-size configuration

Copy ui.ts becomes available after choosing a site size. Apply both the CSS and UI plugin snippets to preserve the complete size preview. With no theme overrides, Copy main.css copies a comment indicating that the existing site styles should be kept.

Merge configuration snippets into your existing files, and append or merge CSS with your app's stylesheet. Copying does not write project files or replace existing configuration.

Copy all (JSON) keeps the combined snapshot available, with appConfig.indocio, css, colorMode, and an optional uiConfig.defaults.size.

The Copy ui.ts button generates an app plugin for your selected site size. The CSS export carries the site scale and typography rules; the plugin carries IPEX control defaults. Module-level configuration uses the same default for server and client rendering:

app/plugins/ui.ts
import uiConfig from '@igrislabs/indocio/ui-config'

uiConfig.defaults = { ...uiConfig.defaults, size: 'lg' }

export default defineNuxtPlugin(() => {})

Only your overrides are exported. The snapshot excludes website content and metadata. Review the values and commit them through your normal workflow to make the design the site's default for everyone.

Keep accent and branding CSS in the consuming application. After applying the settings to source, reset the browser preview to check the new site defaults.

Custom triggers and overrides

DocsCustomizer provides the panel. DocsCustomizerTrigger provides a button, with compact enabled by default for headers. Use :compact="false" for a labeled sidebar button.

The layer's app.vue mounts the panel once when enabled. If you replace app.vue, include <DocsCustomizer /> when the customizer is enabled. If you replace DocsHeaderActions or DocsSidebarBottom, include <DocsCustomizerTrigger /> where you want the entry point.

useCustomizer() exposes enabled, open, preferences, and reset(). Use open.value = true for a custom trigger. reset() clears the appearance and layout overrides; the panel's reset button also restores System color mode.

Indocio · Built with Nuxt Content, IPEX, and Akaza UI.