All documentation
Layouts and grouping/06

Cluster Labels and Backgrounds

Pro

Readable group headers and frame shapes.

Cluster labels and backgrounds make grouped boards readable after a cluster layout runs. FenSight creates a persisted label for each named group and a rounded frame around the group's bounds, then saves those generated items with the board.

How to adjust cluster labels

Keyboard

Alt + mouse wheel

Resize cluster label text on the board surface. Wheel up/down changes the size by 2 points and clamps between 6 and 640.

Toolbar

Layout dropdown -> Custom Cluster Layout... -> Label Colors

Use Text and Background fields for per-preset colors; blank fields use the global label setting.

Labels and frames

When a cluster layout is baked into board items, FenSight creates two synthetic overlay items for each group: a rectangle frame and, when the group has a label, a label item. The frame uses a rounded rectangle with fill, stroke, and corner radius 8. The label is positioned above the cluster bounds so the bucket name remains visible while the grouped items stay inside the frame.

  • Cluster frames use a ShapeItem SourcePath in the form "<cluster-frame:{groupId}>".
  • Cluster labels use a LabelItem SourcePath in the form "<cluster-label:{groupId}>".
  • Rendered overlays also draw rounded rectangles and label text above cluster bounds.
  • Cluster labels have their own size setting, separate from regular user label heading sizes.

Cluster label and background fields

FieldWhat it doesSource detail
Cluster labelPro
Displays the cluster or bucket name above a grouped set of items.Created as a LabelItem with SourcePath "<cluster-label:{groupId}>"; the label text, foreground, background, and group id are saved with the board.
Cluster backgroundPro
Frames a cluster so the grouped items read as one visual block.Created as a rectangle ShapeItem with SourcePath "<cluster-frame:{groupId}>", fill/stroke brushes, StrokeThickness 2, and CornerRadius 8.
TextPro
Sets the per-preset cluster label text color.Custom Cluster Layout exposes this under "Label Colors". A blank value stores null and falls back to the global label text color.
BackgroundPro
Sets the per-preset cluster label background color, including alpha when provided.Custom Cluster Layout exposes this under "Label Colors". A blank value stores null and falls back to the global label background color.
Alt + Scroll sizingPro
Changes cluster label text size directly from the board.BoardInteractionController routes Alt + mouse wheel to AdjustOverlayTextSizeFromWheelDelta; it changes ClusterLabelTextSize by +/-2 and clamps from 6.0 to 640.0.
Board persistencePro
Keeps generated cluster visuals stable across save/load.ClusterLabelPersistenceTests verifies round trip preservation for cluster-frame and cluster-label source paths plus label text and color fields.

Color fallback and defaults

A custom layout preset can store LabelTextColor and LabelBackgroundColor. At cluster-label creation time, FenSight uses the preset value first, then AppSettings global LabelTextColor and LabelBackgroundColor. Fresh settings default to LabelTextSize 14.0, ClusterLabelTextSize 14.0, LabelTextColor "#FFFFFF", and LabelBackgroundColor "#8C1E1E1E".

  • CustomLayoutDialog labels the color group "Label Colors" and the two fields "Text" and "Background".
  • Leaving a per-preset color blank means use the global label setting.
  • The global background default includes alpha, so the label remains readable without fully hiding the board behind it.

Connected guides

Follow these related pages when the workflow crosses into setup, search, organization, export, security, or another board-level system.