# How to Customize Display Settings and Themes in cadjs: A Complete Guide

> Learn to customize cadjs display settings and themes. Control backgrounds, floor modes, edge colors, and materials with themeSettings for a personalized CAD experience.

- Repository: [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad)
- Tags: how-to-guide
- Published: 2026-08-01

---

**You can fully customize the visual appearance of CAD models in cadjs by overriding the `BASE_VIEWER_THEME` with a user-supplied `themeSettings` object that controls backgrounds, floor modes, edge colors, and material properties.**

The `cadjs` library from the `earthtojake/text-to-cad` repository provides a flexible theming system built on Three.js that allows developers to modify every visual aspect of the viewer without touching core rendering code. All display customization logic resides in [`packages/cadjs/src/lib/viewer/stageTheme.js`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadjs/src/lib/viewer/stageTheme.js), which handles theme resolution, texture generation, and contrast-aware color management.

## Understanding the cadjs Theme Architecture

The cadjs viewer uses a layered theme system that merges default values with user overrides. At the foundation lies the `BASE_VIEWER_THEME` constant defined in [`stageTheme.js`](https://github.com/earthtojake/text-to-cad/blob/main/stageTheme.js) (lines 8-55), which establishes default colors, gradients, and material parameters.

When initializing a viewer instance, you can supply a `themeSettings` object that overrides specific properties while inheriting defaults for unspecified values. The system supports four background types enumerated in `THEME_BACKGROUND_TYPES` (lines 58-62): solid color, linear gradient, radial gradient, and transparent.

```javascript
// Example themeSettings structure accepted by cadjs
const customTheme = {
  background: {
    type: "linear",
    linearStart: "#ffefd5",
    linearEnd: "#1e3a8a",
    linearAngle: 45
  },
  floor: {
    enabled: true,
    mode: "grid",
    color: "#222222"
  },
  materials: {
    roughness: 0.4,
    clearcoat: 0.2
  }
};

```

## Customizing Backgrounds in cadjs

Background customization in cadjs relies on the `createSceneBackgroundTexture` function (lines 34-81 in [`stageTheme.js`](https://github.com/earthtojake/text-to-cad/blob/main/stageTheme.js)) to generate canvas-based textures for solid colors or gradients. The `applySceneBackground` function (lines 37-58) then assigns these textures to the Three.js scene.

The system automatically handles hex color validation using `HEX_COLOR_PATTERN` and helper functions like `normalizeHexColor` (lines 65-73), ensuring that 3-digit hex codes expand properly and color values remain valid across different rendering contexts.

```javascript
import { applySceneBackground } from './stageTheme.js';

// Apply a radial gradient background
applySceneBackground(runtime, runtime.viewerTheme, {
  type: "radial",
  radialStart: "#ffffff",
  radialEnd: "#0f172a",
  radialCenterX: 0.5,
  radialCenterY: 0.5
});

```

## Configuring Floor Display Modes

The cadjs viewer supports three distinct floor modes controlled by `resolveFloorMode` (lines 83-97): grid overlay, solid stage plane, or hidden. When enabled, `createStageFloorPlane` (lines 95-81) generates a `MeshPhysicalMaterial` with configurable roughness, reflectivity, and glass factor.

Floor appearance respects both the base theme and user-supplied `themeSettings.floor` parameters, including horizon blending and opacity controls. The optional grid overlay implemented in [`stageGrid.js`](https://github.com/earthtojake/text-to-cad/blob/main/stageGrid.js) activates when `mode: "grid"` is specified.

```javascript
// Force a solid stage floor with specific material properties
runtime.updateFloor(runtime, {
  floor: {
    enabled: true,
    mode: "stage",
    color: "#1a1a1a",
    horizonBlend: 0.2,
    reflectivity: 0.15
  },
  materials: {
    roughness: 0.4,
    clearcoat: 0.2,
    envMapIntensity: 0.7
  }
});

```

## Managing Edge Colors and Contrast

Cadjs automatically ensures wireframe edges remain visible against varying backgrounds through the `resolveWireframeEdgeColor` function (lines 43-61). This utility calculates **relative luminance** and **contrast ratios** using `relativeLuminance` and `contrastRatio` helpers, falling back to adjusted colors when user selections fail to meet the minimum contrast threshold (default 3:1).

For stricter accessibility requirements, you can specify a higher `minimumContrastRatio` when resolving edge colors.

```javascript
import { resolveWireframeEdgeColor } from './stageTheme.js';

const safeEdgeColor = resolveWireframeEdgeColor({
  edgeColor: "#ff00ff",
  themeSettings: customTheme,
  viewerTheme: runtime.viewerTheme,
  minimumContrastRatio: 4.5  // WCAG AA compliant
});

```

## Implementing Complete Theme Overrides

To implement a comprehensive visual overhaul, pass a complete `themeSettings` object during skill initialization or viewer setup. The system accepts parameters for background, floor, materials, and lighting, merging your specifications with `BASE_VIEWER_THEME` defaults.

```javascript
const myThemeSettings = {
  background: {
    type: "linear",
    linearStart: "#ffefd5",
    linearEnd: "#1e3a8a",
    linearAngle: 45
  },
  floor: {
    enabled: true,
    mode: "grid",
    color: "#222222",
    horizonBlend: 0.2,
    reflectivity: 0.15
  },
  materials: {
    roughness: 0.4,
    clearcoat: 0.2,
    envMapIntensity: 0.7
  },
  lighting: {
    spot: {
      enabled: true,
      intensity: 1.2,
      color: "#ffdd00"
    }
  }
};

// Apply to runtime
runtime.applySceneBackground(runtime, runtime.viewerTheme, myThemeSettings.background);
runtime.updateFloor(runtime, myThemeSettings);

```

## Summary

- **Theme system**: Cadjs uses a base theme merged with user-supplied `themeSettings` defined in [`packages/cadjs/src/lib/viewer/stageTheme.js`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadjs/src/lib/viewer/stageTheme.js).
- **Background options**: Supports solid colors, linear gradients, radial gradients, and transparent backgrounds via `createSceneBackgroundTexture`.
- **Floor modes**: Choose between grid, solid stage, or hidden floors using `resolveFloorMode` and `createStageFloorPlane`.
- **Color safety**: The `resolveWireframeEdgeColor` function ensures minimum contrast ratios for wireframe visibility.
- **Validation**: Hex colors normalize automatically through `normalizeHexColor` and `HEX_COLOR_PATTERN`.

## Frequently Asked Questions

### How do I change the background to a transparent grid in cadjs?

Set the background type to `"transparent"` and enable the floor grid mode in your `themeSettings` object. The viewer will render the Three.js scene without a background texture while displaying the grid overlay defined in [`stageGrid.js`](https://github.com/earthtojake/text-to-cad/blob/main/stageGrid.js).

```javascript
const settings = {
  background: { type: "transparent" },
  floor: { enabled: true, mode: "grid" }
};

```

### What file controls the default colors in cadjs?

The `BASE_VIEWER_THEME` constant in [`packages/cadjs/src/lib/viewer/stageTheme.js`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadjs/src/lib/viewer/stageTheme.js) (lines 8-55) defines all default colors, gradients, and material parameters. Override these values by passing a `themeSettings` object to the viewer runtime rather than modifying the source file.

### How does cadjs ensure wireframe edges remain visible against dark backgrounds?

The `resolveWireframeEdgeColor` function automatically calculates contrast ratios using `relativeLuminance` and `contrastRatio` helpers. If your specified edge color fails to meet the minimum contrast threshold against the current background, the system selects a fallback color that satisfies the visibility requirement.

### Can I export the background texture created by cadjs for use in other applications?

Yes, the `createSceneBackgroundTexture` function returns a standard `THREE.CanvasTexture` that you can extract and export. Pass the Three.js namespace, viewer theme, and background settings to generate a canvas-based texture compatible with any Three.js application or export pipeline.