Creating a Template

Beyond the five built-in templates (feature, task, bug, chore, memo), you can create your own: an incident template for ops teams, an rfc template for design decisions, a review template for calibrations. Each template defines a new artifact type, with its own fields, its own row in the By type section of the sidebar, and its own picker entry.

Creating the template

Go to Settings → Templates and click New Template. Give it a name; that's both the template identifier (e.g. incident) and what shows up in the artifact picker. The name becomes the folder name on disk (artifacts/incident/).

Defining the fields

Every template needs at least one field. Common starter fields:

• Status (text) with a few options, typically the workflow for this type.
• Priority or Severity (text) if the type has an urgency dimension.
• Assignee (user).

Pick field types from the template field editor. See Field Types and Options for the full list, including how to constrain a text field with options, allow multiple selections, or mark a field required.

Modal to edit a field

Display properties

Templates carry display properties that control how artifacts render across Spruce: the color and icon used for the type, per-option colors on enum fields, and which fields appear as chips on artifact cards.

Template-level display

At the top of a template, the display block sets the type's color and icon:

display:
  color: '#06b6d4'
  icon: star-filled

• color: a hex color used for the type's sidebar chip, card border, and icon.
• icon: an icon name from the Tabler icon set (no prefix, just the base name, e.g. star-filled, bug, notes).

Per-option display

For constrained text fields (status, priority, size, etc.), each option carries its own display. This is how every view shows colored status chips and icons per value:

options:
  - value: Urgent
    label: Urgent
    description: Needs immediate attention
    display:
      color: '#ef4444'
      icon: alert-triangle
  - value: High
    label: High
    display:
      color: '#f97316'
      icon: flag-filled

The pinned field hint

The hints array on a field controls where and how it appears:

• pinned: render the field as a chip in the artifact header, and show it as a column on view cards by default.

Most of the built-in templates pin status, priority, size, and assignee.

Editing display properties

From the UI: Settings → Templates → (template) → Display. Or edit the template markdown file directly; the display block is plain YAML.

Choosing good colors and icons

• Use semantic color pairs that match your team's intuition: green for done, red for urgent, blue for in-progress.
• Use recognizable icons. Tabler has thousands; pick ones that read clearly at small sizes.
• Keep types visually distinct across templates; don't give your chore and bug both an orange color.

Example: an incident template

Fields:

Display: icon alert-triangle, color #ef4444.

Once saved, the new template appears in the artifact-creation menu, gets its own row in the By type section of the sidebar (a built-in view locked to that template), shows up in template filters on every other view, and is available anywhere else artifact types are listed.

Sharing custom templates with your team

Templates live in the Spruce project's templates/ folder, so pushing the project shares the new template along with everything else. You can also export it as a bundle for reuse across projects. See Importing and Exporting Bundles.

Related

• Editing Built-in Templates — same editor, different starting point.
• Field Types and Options — the available field types, including relationships.
• Artifact Types — the defaults for the built-in templates.