Color Swatches

Documenting a project’s colors (brand palette, theme variables, status indicators) is one of those tasks that looks simple until you actually try to do it well. Static screenshots go stale, hand-coded HTML is tedious to maintain, and plain text hex codes are meaningless without a visual reference beside them.

The {{< color-swatch >}} shortcode solves this by turning a small YAML file into an interactive, accessible color palette. Each swatch displays its hex code, shows RGB/HSL breakdowns on hover, evaluates WCAG contrast ratios, and lets readers copy values with a single click. You can render individual palettes, reference the built-in Great Docs gradient presets, or combine both approaches.

This guide walks through every feature (from a minimal first palette to advanced customization options) so you can present colors as clearly as you present code.

Quick Start

The fastest way to get a palette on the page is to create a YAML file with your colors and reference it from a shortcode. No configuration beyond the file path is needed.

Start by creating a YAML file somewhere in your project. Each entry needs a name and a hex value:

assets/colors.yml
- name: Sky Blue
  hex: "#38bdf8"
- name: Deep Navy
  hex: "#1e3a5f"
- name: Coral
  hex: "#f97316"

Then reference it with the shortcode in any .qmd page:

{{< color-swatch file="assets/colors.yml" >}}

Here is the result (three circle swatches with names and hex labels):

Sky Blue #38bdf8
Deep Navy #1e3a5f
Coral #f97316

Hover over any swatch to see its full color breakdown in a tooltip. Click a swatch to copy its hex value to the clipboard. That single shortcode line is all it takes to go from raw hex codes to a polished, interactive palette.

Display Modes

The shortcode supports two display modes, controlled by the mode parameter. The default is circles, which works well for compact palettes and quick visual reference. The rectangles mode is better suited for detailed documentation where contrast information needs to be front and center. Additional modes (grid, gradient) are planned for future releases.

Circles (Default)

Circle swatches are the default display mode. Each color appears as a filled circle with its name and hex code underneath, arranged in a responsive row that wraps as needed.

To render circle swatches, simply omit the mode parameter (or set mode="circles" explicitly):

{{< color-swatch file="assets/brand-colors.yml" >}}

Here is a five-color brand palette rendered as circles:

Primary #2563eb
Secondary #6b7280
Accent #f97316
Success #22c55e
Error #ef4444

Circles are compact and scannable, making them ideal for showcasing a handful of brand or theme colors at a glance. Each swatch is individually interactive (hover for details, click to copy).

Rectangles

Rectangle mode renders each color as a full-width horizontal strip. This is useful when you want to emphasize contrast information alongside the color itself.

Set mode="rectangles" to switch:

{{< color-swatch mode="rectangles" file="assets/brand-colors.yml" >}}

Here are three colors rendered as rectangular strips:

Primary #2563eb AaAa
Secondary #6b7280 AaAa
Accent #f97316 AaAa

Each strip displays the color name on the left, the hex code on the right, and white/black “Aa” contrast samples. The “Aa” labels are marked pass or fail against WCAG AA thresholds, so you can immediately see which text colors are safe to use on each background. Rectangle mode is especially valuable for design-system documentation where accessibility compliance is a primary concern.

Built-In Palette Presets

Great Docs ships with eight gradient presets that power the site’s gradient theming system. Rather than listing colors manually, you can reference any preset by name and the shortcode will render its color stops as swatches.

To use a preset, pass its name to the palette parameter instead of providing a file:

{{< color-swatch palette="sky" >}}

Here is the sky preset:

Sky 100 #e0f4ff
Sky 200 #d0ecf9
Sky 300 #c5e8f7
Sky 400 #b8e0f5

The full set of available presets is:

Preset Description
sky Soft sky blues
peach Peach and blush
prism Mint, sky, and lavender
lilac Lilac and pink
slate Cool grays
honey Warm cream and apricot
dusk Soft lavender-blue
mint Pale aqua

Each preset defines four color stops for both light and dark modes. The light-mode stops are shown by default. These are the same palettes available through the gradient-preset option in your site configuration, so the swatches you see here correspond exactly to the colors your site header and other gradient elements will use.

All Presets at a Glance

If you want to compare every preset side by side (for example, when choosing a gradient theme for your site) use palette="all" to render all presets in a single view:

{{< color-swatch palette="all" >}}

This renders every preset’s light-mode color stops, grouped by preset name:

Sky 100 #e0f4ff
Sky 200 #d0ecf9
Sky 300 #c5e8f7
Sky 400 #b8e0f5
Peach 100 #ffe4cc
Peach 200 #ffddc1
Peach 300 #fdd0d8
Peach 400 #fbc4d4
Prism 100 #d0e8f5
Prism 200 #c4f0e0
Prism 300 #e4d4f4
Prism 400 #d8cef0
Lilac 100 #f5d0e0
Lilac 200 #e8d0f0
Lilac 300 #f0d4f8
Lilac 400 #eac8ee
Slate 100 #eceff1
Slate 200 #e0e4e8
Slate 300 #dde2e6
Slate 400 #d5dadf
Honey 100 #ffedcc
Honey 200 #ffe0c2
Honey 300 #ffe5b4
Honey 400 #ffd6a8
Dusk 100 #dddff5
Dusk 200 #d8daf0
Dusk 300 #d4d0ee
Dusk 400 #dad4f2
Mint 100 #d5f0ec
Mint 200 #ccece8
Mint 300 #c4e8e4
Mint 400 #d0f2ee

The grid layout ensures each swatch is the same width, making visual comparison straightforward. This view is handy for theme selection pages or internal style guides.

Extend a Preset

Sometimes a preset is close to what you need but you want to add a few extra colors. You can combine a preset with a YAML file (the file’s colors are appended after the preset’s stops).

For example, to add a custom accent color after the sky preset:

{{< color-swatch palette="sky" file="assets/extra-colors.yml" >}}

Here is the sky preset extended with one additional brand accent color:

Sky 100 #e0f4ff
Sky 200 #d0ecf9
Sky 300 #c5e8f7
Sky 400 #b8e0f5
Brand Accent #ff6b6b

The preset colors appear first, followed by any colors from the file. This lets you document how your custom additions relate to the built-in palette without duplicating the preset definitions.

Tooltips

Every swatch shows a rich tooltip on hover. Tooltips provide the detailed color information that would clutter the main display but is essential for anyone working with the values.

Each tooltip contains:

  • A mini color preview square
  • The color name
  • Hex code with a clipboard copy button
  • RGB values
  • HSL values (rounded to integers)
  • APCA contrast ratio against white and against black (in Lc units)
  • WCAG AA pass/fail verdict for normal-size text

Tooltips are powered by the Tippy.js library that is already bundled with Great Docs, so no additional dependencies are needed. The tooltips appear on hover for mouse users and on focus for keyboard users, ensuring the information is accessible to everyone.

Click to Copy

One of the most common reasons to look up a color palette is to grab a specific value for use in code or design tools. The shortcode makes this effortless.

Click any swatch to copy its hex value (including the #) to the clipboard. A brief checkmark animation confirms the copy succeeded. Inside the tooltip, each hex code also has a dedicated clipboard button for a more targeted copy action.

The copied value is always the full hex code (e.g., #38bdf8), which is the format most commonly pasted into CSS, design tools, and configuration files.

Contrast Checks

Choosing colors that look good is only half the job: they also need to be readable. The shortcode uses the APCA (Accessible Perceptual Contrast Algorithm) to evaluate every color against white (#FFFFFF) and black (#000000) text. This is the same algorithm that powers the automatic navbar text-color selection elsewhere in Great Docs.

By default, contrast information appears in tooltips and in the “Aa” samples on rectangle swatches. You can control this behavior with the show-contrast parameter.

Display Options

The show-contrast parameter accepts three values:

show-contrast value Behavior
"true" (default) Contrast info appears in tooltips and rectangle “Aa” samples
"inline" Contrast ratios also appear below the hex code on each circle swatch
"false" Contrast info is hidden everywhere

Setting show-contrast="inline" places the contrast ratios directly on the swatch, which is useful when contrast is the primary focus of the documentation:

{{< color-swatch show-contrast="inline" file="assets/contrast-demo.yml" >}}

Here are two colors with inline contrast ratios visible beneath the hex codes:

Dark Slate #1e293b 104.3/0.0 Lc
Light Gray #f1f5f9 0.0/99.7 Lc

The inline display shows the Lc (lightness contrast) value for both white-on-color and black-on-color combinations, along with a pass/fail indicator. Use this mode when your audience needs to evaluate contrast at a glance without hovering.

Controlling What’s Shown

Sometimes you want a simpler display (perhaps just the color circles with names, without hex codes cluttering the view). The shortcode provides three toggle parameters that control label visibility.

Parameter Default Effect
show-names "true" Show or hide color names below swatches
show-hex "true" Show or hide hex codes below swatches
show-contrast "true" Show or hide contrast info (see above)

For example, to show only the swatches and their names without hex labels:

{{< color-swatch show-hex="false" file="assets/colors.yml" >}}

Here is a minimal palette with hex codes hidden:

Rose
Violet
Teal

The hex values are still available in the tooltip on hover (hiding them from the main display reduces visual noise when the color names alone are sufficient). You can combine these toggles freely: show-names="false" show-hex="false" gives you bare swatches with all information deferred to tooltips.

Customization

The shortcode offers several parameters for fine-tuning the appearance of the palette container and individual swatches. These let you adapt the display to different contexts (from a prominent hero palette to a compact inline reference).

Title and Description

Add a heading and optional description above the palette to give it context within your page. This is especially useful when you have multiple palettes on the same page and need to label each one.

{{< color-swatch title="Brand Colors" description="Our primary brand palette for 2026." file="assets/brand.yml" >}}

Here is a palette with a title and description:

Brand Colors
Our primary brand palette for 2026.
Blue #2563eb
Orange #f97316

The title renders as a heading within the palette container, and the description appears as a subtitle beneath it. Both are optional and can be used independently.

Swatch Size

The default circle diameter is 56px, which works well for most layouts. For hero sections, style guides, or situations where you want the colors to be more prominent, increase the size:

{{< color-swatch size="80px" file="assets/colors.yml" >}}

Here is a single swatch rendered at 80px:

Large #8b5cf6

The size parameter accepts any valid CSS length value. Smaller sizes (like 40px) work well for dense reference tables, while larger sizes (like 100px) make colors the focal point of the page.

Border

By default, the palette container has a subtle border that visually groups the swatches. If you prefer a cleaner look (for example, when the palette sits inside a callout or a card that already has its own border) you can disable it:

{{< color-swatch border="false" palette="mint" >}}

Here is the mint preset without a container border:

Mint 100 #d5f0ec
Mint 200 #ccece8
Mint 300 #c4e8e4
Mint 400 #d0f2ee

The swatches themselves are unchanged; only the outer container border is removed.

Extra CSS Classes

For advanced styling, add custom CSS classes to the palette wrapper with the class parameter:

{{< color-swatch class="my-special-palette" palette="lilac" >}}

You can then target .my-special-palette in your custom CSS to override spacing, alignment, background, or any other property. This provides an escape hatch for layouts that the built-in parameters don’t cover.

Color Entry Format

Every YAML color file follows a simple structure. Each entry is a list item with two required properties:

Property Required Description
name Yes Display name shown below the swatch
hex Yes Hex color value (e.g., "#38bdf8")

A minimal file looks like this:

assets/my-colors.yml
- name: Primary
  hex: "#2563eb"
- name: Accent
  hex: "#f97316"

Hex values must include the # prefix and can use either three-digit (#fff) or six-digit (#ffffff) notation. The shortcode normalizes all values to six digits internally for consistent display. Quoting the hex values in YAML is recommended to avoid parsing issues with the # character.

Accessibility

The color-swatch shortcode is designed to be usable by everyone, including keyboard-only users and screen-reader users.

Key accessibility features include:

  • Keyboard navigation: Every swatch is focusable via Tab and can be activated with Enter or Space to copy its hex value.
  • ARIA labels: Each swatch carries an aria-label describing the color name, hex value, and available actions.
  • Live announcements: Copy confirmations are announced through an aria-live region so screen readers report the result.
  • Visibility safeguards: Very light colors (nearly white) automatically receive a subtle border ring so they remain visible against the page background. Very dark colors get the same treatment in dark mode.
  • Reduced motion: The prefers-reduced-motion media query disables hover and copy animations for users who have requested reduced motion in their OS settings.

These features ensure that color documentation is not just visual as the information is available through assistive technology as well.

Dark Mode

Swatches adapt to the page theme automatically. When a reader toggles dark mode, the palette adjusts without any extra configuration:

  • Container borders and shadow intensities shift for dark backgrounds.
  • Border rings on very light and very dark colors swap direction (light rings appear around dark colors in dark mode, and dark rings appear around light colors in light mode).
  • Tooltips inherit the page’s current theme context.

When using a palette preset, the light-mode color stops are shown regardless of page theme. Dark-mode palette display (showing the preset’s dark-mode stops when the page is in dark mode) is planned for a future release.

Responsive Behavior

The swatch layout is responsive and adjusts to smaller screens automatically.

On mobile viewports (below 576px):

  • Circle swatches shrink to 44px and grid gaps tighten to keep the layout compact.
  • Rectangle strips stack their labels vertically to avoid horizontal overflow.

On wider screens, the grid expands to fill the available width with equal-size columns. No media-query configuration is needed on your part as the built-in CSS handles all breakpoints.

Parameters Reference

The table below lists every parameter available on the {{< color-swatch >}} shortcode. All parameters are optional and, at minimum, you need either file or palette (or both) to provide colors.

Parameter Type Default Description
file string — Path to a YAML file with color definitions (relative to project root)
palette string — Preset name: sky, peach, prism, lilac, slate, honey, dusk, mint, or all
mode string "circles" Display mode: circles or rectangles
size string "56px" Circle swatch diameter (CSS length)
show-contrast string "true" "true", "false", or "inline"
show-names string "true" Show or hide color names
show-hex string "true" Show or hide hex values
copy-format string "hex" Clipboard format: hex
title string — Title above the palette
description string — Description below the title
border string "true" Show or hide container border
id string auto Custom HTML id for the wrapper
class string — Additional CSS classes

When both file and palette are provided, the preset colors appear first and the file colors are appended after them.

Next Steps

Color swatches turn color definitions into visual, interactive documentation. Whether you maintain a design system or just want to showcase your package’s theme palette, the shortcode handles rendering, contrast checks, and copy-to-clipboard.