# 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
``` yaml
- name: Sky Blue
hex: "#38bdf8"
- name: Deep Navy
hex: "#1e3a5f"
- name: Coral
hex: "#f97316"
```
Then reference it with the shortcode in any `.qmd` page:
``` markdown
{{< 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):
``` markdown
{{< 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:
``` markdown
{{< color-swatch mode="rectangles" file="assets/brand-colors.yml" >}}
```
Here are three colors rendered as rectangular strips:
" aria-label="Primary, hex #2563eb, click to copy">
Primary \#2563eb AaAa
" aria-label="Secondary, hex #6b7280, click to copy">
Secondary \#6b7280 AaAa
" aria-label="Accent, hex #f97316, click to copy">
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`:
``` markdown
{{< 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:
``` markdown
{{< 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:
``` markdown
{{< 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:
``` markdown
{{< 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:
``` markdown
{{< 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.
``` markdown
{{< 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:
``` markdown
{{< 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:
``` markdown
{{< 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:
``` markdown
{{< 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
``` yaml
- 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.
- [Theming & Appearance](theming.md) covers gradient themes, dark mode, and other visual customization
- [Table Previews](table-previews.md) covers another visual component for rendering data tables
- [Configuration](configuration.md) covers all `great-docs.yml` options