This is the abridged developer documentation for Pulumi Brand Guidelines

# About this guide

> Pulumi's brand guide and visual identity principles.

A brand is much more than a logo and a color palette. It's the sum of everything we say, do, and put out into the world — the collective expression of who we are and what makes us unique.

This guide covers the rules and resources of the Pulumi brand and visual identity and how they come together in practice. Everyone who creates on behalf of Pulumi shares responsibility for respecting and upholding these standards.

# Brand attributes

> Pulumi's brand attributes, purpose, and the values that guide everything we build and communicate.

Our brand attributes define our personality and guide everything we do, from the voice and tone we use when creating content to the visuals we use and the experiences we create.

#### Modern

We build for how our users work today, not for how they worked a decade ago. Our products, design, and communication style reflect our forward-looking perspective.

#### Trustworthy

Engineers trust us with their critical infrastructure. We earn and keep that trust through consistency, clarity, transparency, reliability, and commitment to getting the details right.

#### Innovative

We don't take small, conservative steps. We take big leaps, challenge assumptions, and ship tools that make working with the cloud significantly easier and better for our users.

#### Focused

Our brand is clear and intentional; every element has a purpose. And while our scope is ambitious, everything we do ties back to making Pulumi the brand our users love most.

#### Friendly & human

We're approachable and kind, and we speak like practitioners, not marketers. We're community-first and open-source-first — a member of the community, not just a commercial vendor — so we respect builders of all backgrounds, including the many who give their work away for free. We meet people where they are, whether they're just getting started or running at scale.

---

## Our purpose

To democratize the cloud for every engineer.

---

## Our values

Adapted from [pulumi.com/about](https://www.pulumi.com/about/).

#### Customers first

When our customers are successful, so are we. Their success is our highest priority. We work hard to see and understand the world from their perspective and to build experiences that delight them.

#### Dream big

We can’t possibly succeed at our audacious purpose by taking small steps. Instead, we dream big, and we take big swings. We hire the best and brightest, imagine a better future together, and empower each other to invent that future.

#### Bias for action

We make fast decisions, learn, and own the outcomes; good today is better than perfect tomorrow. When in doubt, we empower action, experimentation, learning, and iteration. We build consensus so we're all bought in — but when we disagree, we commit and get going.

#### Play to win, as a team

As a global and inclusive team, every one of us has a seat at the table, regardless of background, experience, or title. We celebrate wins together, learn from our failures together, and are on this journey as a team together.

#### Be an owner

As early employees, we're all owners, and we behave accordingly. We're frugal, spend Pulumi’s resources as if they’re our own, and do our best to accomplish more with less.

# Assets & source files

> Where to find official brand assets, Figma source files, and how to use them.

## Source of truth

We use Figma as the source of truth for all color values, tokens, and design assets. Always reference the [Global Design Primitives Figma file](https://www.figma.com/design/I4WYbethjl5yBxhysRPXPb/Global-Design-Primitives?node-id=1-70&p=f&t=86eHLphYN38cDVaK-0) for accurate and up-to-date information, and use this library when working in other design files in Figma.

## Logo files

Logo source files are available in SVG, PNG, and PDF formats. Always use original source files; never recreate, modify, or redraw the logo from a screenshot or export.

- SVG is available for all digital use cases
- PNG is available for contexts where SVG isn't supported (or isn't a great fit)
- PDF is available for print and digital distribution

When naming a logo file, follow the pattern `pulumi-logo-[lockup]-[color]-[mode].[ext]`. Icon file naming follows the pattern `pulumi-icon-[shape]-[mode].[ext]`.

Standard logos are available in the downloadable [brand assets package](/identity/logo/#download-the-asset-package), individual variants can be [built interactively](/identity/logo/#build-a-logo), and any variant — including JPG, custom sizes, and other formats not shipped as source files — can be [rendered on demand from the logo API](/identity/logo/#render-from-the-api).

See the [Logo](/identity/logo/) page for details, definitions, examples, and usage guidelines.

## Neo icon files

Icons for [Pulumi Neo](/identity/mascot/#neo) are available in PNG and SVG format, and follow the same naming conventions.

## Color files

Some useful files for working with colors are included in the brand assets download, including:

- CSS files with variables defined for hex, RGB, HSL, and OKLCH colors.
- [An SVG](/brand-assets/color/colors.svg) with all colors displayed for dropping into design software other than Figma.

See the [Color](/identity/color/) page for details and usage guidelines.

## Font files

The Inter and Monaspace Neon font files are included in the [brand assets package](/pulumi-brand-assets.zip). Both are also available on GitHub ([Inter](https://github.com/rsms/inter), [Monaspace](https://github.com/githubnext/monaspace)) in additional formats if needed.

See the [Typography](/identity/typography/) page for details and usage guidelines.

## Accent line files

Example SVG files for [accent lines](/visuals/accent-lines/) are included in the [brand assets package](/pulumi-brand-assets.zip). These can be used as-is or modified according to the accent line [usage guidelines](/visuals/accent-lines/).

## For AI agents

These guidelines are also published in formats designed for LLMs and coding agents:

- [`/llms.txt`](/llms.txt) is an index of LLM-readable content, following the [llms.txt](https://llmstxt.org/) convention
- [`/llms-full.txt`](/llms-full.txt) includes every page, concatenated as Markdown
- [`/llms-small.txt`](/llms-small.txt) is a minified version for smaller context windows
- Per-page markdown is available by appending `.md` to any URL — e.g., [`/identity/logo.md`](/identity/logo.md)
- An asset manifest at [`/brand-assets/README.md`](/brand-assets/README.md) lists every downloadable file with naming conventions
- The publicly available MCP server at `https://brand.pulumi.com/mcp` exposes all brand content and assets as agent-friendly MCP resources, tools, and prompts

---

## Download

The brand-assets package includes all standard logos, colors, font files, and supporting imagery:

  
  Download

# Breaking the rules

> When it's okay to bend, and when it's not.

While it's important, as a rule, to follow the brand guidelines, there may be some cases where it's okay to bend them, as long as you do so thoughtfully and intentionally, and with a clear rationale for why it's necessary — but only when it serves the brand.

Areas where it's usually allowed include swag, community events, and internal communications. These can be fun and playful, and it's a space where we can experiment with the brand in ways that we wouldn't in more formal communications. If you're designing something like a t-shirt, sticker, or other piece of swag, you have more freedom to bend the rules — as long as the design still feels like it belongs to the Pulumi family.

# Generative AI

> How to use generative AI responsibly when creating content on behalf of the Pulumi brand.

Generative AI is a powerful tool, but without good guidance and clear context it'll happily produce off-brand, generic, or flat-out wrong output. When you use it to make something for the Pulumi brand, follow the rules below.

One principle above all: We don't hand our brand to an AI agent and walk away. AI is a powerful tool for drafting and reviewing, but everything we publish has to carry a real point of view — and that comes from you. Your experience, your judgment, and the quality of what you put in are what separate something valuable and [worth a reader's time](/voice/writing-style/#respect-the-readers-time-and-attention) from generic, bot-generated filler.

## Where AI helps

  - When it's grounded in the brand. Point your agent at our [brand guidelines MCP server](/mcp-server/) so it's working with good context instead of just guessing.
  - When it's given your thinking, a clear prompt, a good writing sample, and a solid outline as input.
  - When you're using it as a reviewer. Ask a different agent (or the same agent in a different session) to read the piece you're working on, evaluate it as your reader would, and tell you what's missing. See [the Review](/voice/writing-style/#review) for a prompt that can help with this.

## Always verify

AI still often hallucinates, inventing facts, numbers, APIs, and even features, and it does so with absolute confidence. Treat everything a model tells you as unverified until you've checked it against a real source yourself — the same standard we hold for any claim we make. (See [Attribution and accuracy](/voice/writing-style/#attribution-and-accuracy).)

## Never

  - Ship AI-generated copy you haven't reviewed and revised yourself, and never ship raw model output as a finished piece. Revise it until the words are genuinely your own before you submit for review, and never publish anything without a human reviewing it first.
  - Generate original images, illustrations, or other visual assets. Our visual language is specific, image models struggle to reproduce it cleanly, and the results almost always read off-brand.
  - Generate or modify the Pulumipus with AI. Ever. (See [Mascot](/identity/mascot/) for why.)

# Color

> The Pulumi color system — primary palettes, semantic roles, dark mode behavior, and accessibility.

## Color scales

Each palette has 11 steps: 50, 100, 200, 300, 400, 500, 600, 700, 800, 900, and 950. Lower values are lighter; higher values are darker. In dark mode, the same token names are used but resolve to different values, effectively inverting the scale — 50 becomes the darkest and 950 the lightest.

## Semantic colors

Each palette also has four defined semantic colors: Primary, Accent, Muted, and Background.

- **Primary** is mapped to the 700 value of each palette and should be used for the majority of color needs.
- **Accent** is mapped to the 500 value and should be used for emphasis and to add visual interest.
- **Muted** is mapped to the 200 value and should be used for secondary elements and bolder backgrounds.
- **Background** is mapped to the 50 value and should be used for backgrounds and surfaces.

**Exceptions:**

Orange and yellow primaries trend toward brown at the 700 value. Prefer the Accent (500) versions for decorative use, and reserve the primaries for contexts where contrast requirements are confirmed.

## Primary palettes

Violet is the primary color of the Pulumi brand, and it should be used prominently in all brand materials. It should be used alongside the gray palette as needed.

**Violet on primary buttons:**

When using violet as the background color for primary buttons or indicators, the color **should not change** when changing between light and dark mode. Primary buttons should always have white text with `#5a30c5` as their background color: `Violet 700` in light mode and `Violet 300` in dark mode. See the buttons on the homepage of this guide and its sidebar active state for an example.

## Supporting palettes

Other approved color palettes (green, aqua, blue, red, orange, and yellow) should be used sparingly — primarily for status indication, UI state, data visualization, or to add visual interest alongside the primary color.

## Utility colors

Utility colors (black and white) can be used as needed for text, backgrounds, and other elements. Service Black is `#1F1B21`, used in both light and dark modes. In UI contexts, Service Black should be used for text in light mode and backgrounds in dark mode.

## Dark mode

In dark mode contexts, all palette color values are inverted by scale position. For example, `Violet 50` in light mode maps to `Violet 950` in dark mode, `Violet 100` maps to `Violet 900`, and so on.

## Contrast and accessibility

All primary colors meet APCA Lc 75+ against white in light mode. In dark mode, most primary colors meet Lc 75+ against black, with the exceptions of violet (Lc 71) and red (Lc 65). Most primary colors also meet 75+ when placed on their respective 50 background, and all meet 60+. The Accent and Muted colors are not required to meet specific contrast ratios, but should be used with consideration for accessibility.

**Light mode** (Primary on background)

| Palette | White |  50   | 100  | 200  |
| ------- | :---: | :---: | :--: | :--: |
| Violet  | ✓✓ 86 | ✓✓ 81 | ✓✓ 75 | ✓ 67 |
| Gray    | ✓✓ 78 | ✓✓ 75 | ✓ 68 |  59  |
| Green   | ✓✓ 75 | ✓ 73  | ✓ 69 | ✓ 64 |
| Aqua    | ✓✓ 77 | ✓✓ 76 | ✓ 71 | ✓ 63 |
| Blue    | ✓✓ 78 | ✓✓ 75 | ✓ 69 | ✓ 61 |
| Red     | ✓✓ 80 | ✓✓ 75 | ✓ 66 |  55  |
| Orange  | ✓✓ 79 | ✓✓ 76 | ✓ 68 | ✓ 61 |
| Yellow  | ✓✓ 75 | ✓ 72  | ✓ 67 |  59  |

**Dark mode** (Primary on background)

| Palette | Black |  50   |  100  | 200  |
| ------- | :---: | :---: | :---: | :--: |
| Violet  | ✓ 71  | ✓ 69  | ✓ 65  | ✓ 60 |
| Gray    | ✓✓ 75 | ✓ 71  | ✓ 64  |  58  |
| Green   | ✓✓ 85 | ✓✓ 82 | ✓✓ 77 | ✓ 70 |
| Aqua    | ✓✓ 88 | ✓✓ 86 | ✓✓ 78 | ✓ 71 |
| Blue    | ✓✓ 76 | ✓ 70  | ✓ 63  |  58  |
| Red     | ✓ 65  | ✓ 62  |  58   |  50  |
| Orange  | ✓✓ 75 | ✓ 71  | ✓ 64  |  58  |
| Yellow  | ✓✓ 81 | ✓✓ 78 | ✓ 69  | ✓ 62 |

Lc 75 = Body text (minimum)\
Lc 60 = Small text (non-body), UI elements\
Lc 45 = Large text, minimum of 24px (bold) or 36px (regular)

## Print colors

CMYK and spot colors are not specified as part of the design guidelines. For print materials, use the RGB values as a starting point to convert to CMYK in your design software. Work with your printer to determine the best CMYK or spot color equivalents and always request a proof to ensure color accuracy before printing large runs.

## Deprecated colors

  - Do not use the Purple, Fuchsia, or Salmon palettes.

## CSS variables

# Iconography

> Icon library, usage rules, and the product icon set for Pulumi offerings.

## Icon library

Pulumi Iconography

[Phosphor](https://phosphoricons.com/) is the official icon library for the Pulumi brand.

- Use Phosphor icons for all icons in brand materials, including UI elements, marketing materials, and presentations.
- In UI, use the Regular weight for icons 16px and larger. For smaller system icons at 12/14px (carets, dropdown arrows, etc.), use the Bold weight.
- In marketing materials, the Duotone weight can be used for decorative icons, but should never be used for UI elements.
- Add custom icons only when a suitable icon cannot be found in the Phosphor library. Custom icons should follow the same design principles as Phosphor icons, including line weight, corner radius, and overall style.

## Product icons

Certain custom icons represent Pulumi products and offerings. Use these consistently across all brand materials and UI. Don't use them to represent anything other than their associated product, and don't use them in contexts where they might be confused for general-purpose icons.

**Neo icon usage:**

Use the `Fill` weight for the Neo icon when pairing it with other `Regular` icons — the fill is what makes the sunglasses read as sunglasses.

## Brand icons

Don't use Phosphor icons to represent other companies' brands. Use a library that reproduces official brand marks exactly, such as [Simple Icons](https://simpleicons.org/).

# Logo

> Rules for using the Pulumi logo, including lockups, sizing, backgrounds, file formats, and what to avoid.

## General rules

  - Keep it legible and give it space
  - Use only approved versions of the logo
  - Don't alter the logo's colors, proportions, or orientation
  - Don't add effects, textures, or patterns

## Lockups & variants

The logo can appear as a _logomark_ or combination mark _lockup_. The logomark is a standalone icon that can be used in contexts where the full logo may not fit, or when a more minimal representation is called for. The combination mark lockup includes both the logomark and the _wordmark_. Never use the wordmark without the logomark.

Pulumi Logo Lockups Color

The logo has two type lockups: horizontal and stacked. The horizontal lockup is the primary version and should be used whenever possible. The stacked lockup may be used when a more vertical orientation is necessary or when a more compact logo is needed.

Pulumi Logo Lockups Monochrome

Monochrome versions of the mark and each lockup are available for use when the color logo doesn't provide sufficient contrast or when a single-color logo is preferred for aesthetic reasons.

Pulumi Logo Icons

Icons with backgrounds included are also provided for easily updating profile pictures and app icons.

## Sizing & reproduction

Pulumi Logo Placement and Sizing

  - Give the logo adequate breathing room by maintaining a clear space around it. The minimum clear space should be equal to half the logo's height (if the logo height is `N`, clear space is `N/2`). This space should be free of any other graphic elements, text, or images.
  - The horizontal logo should never be reproduced smaller than 0.25 inches (6.35 mm) in height for print or 16 pixels in height for digital use to ensure legibility. The stacked logo should never be reproduced smaller than 0.75 inches (19 mm) in height for print or 50 pixels in height for digital use.
  - Don't reproduce the logo at low resolution or allow it to appear pixelated or blurry.

## Background & contrast

  - Only place the color logo on white, black, service black, brand grays, or the following brand violet colors: Light: `Violet 50`, `Violet 100`, Dark: `Violet 900`, `Violet 950`
  - For glass or transparent signage, default to the white monochrome logo unless the black monochrome logo provides better contrast in the specific location.
  - Don't place the logo on busy or cluttered backgrounds
  - Don't place the logo on backgrounds that create insufficient contrast

## Composition & placement

  - Don't use the logo as a repeating pattern or texture
  - Don't crop, clip, or partially hide the logo
  - Don't place the logo inside a shape or container (badge, circle, box) other than the provided icon variants
  - Don't stack or overlap other logos directly on top of the logo

## Effects & styling

  - Don't apply drop shadows, gradients, glows, or outlines
  - Don't apply opacity or transparency effects
  - Don't apply filters or blend modes to the color versions of the logo

## File usage

  - Always use original source files; never recreate or redraw the logo
  - Always use vector versions of the logo when possible
  - Don't screenshot or export the logo from a PDF/presentation for reuse

## Get the logo

There are four ways to get an approved logo: download the full asset package, build a single variant interactively, ask an AI assistant for one, or generate one on demand from the logo API.

### Download the asset package

The brand-assets package contains all standard logos, colors, font files, and supporting imagery:

  
  Download

### Build a logo

Pick a lockup, background, size, and format to preview an approved logo variant, then download the file or copy its permanent URL.

### Ask your agent

Working in an AI assistant? Point it at the logo service and describe what you need in plain English — it builds the right link and returns the image or a download URL.

- **Any assistant** — paste `https://brand.pulumi.com/api` into the chat; it reads the self-describing schema, then fetches the logo you describe.
- **MCP clients** (Claude, Cursor, and friends) — connect once to `https://brand.pulumi.com/mcp` for a dedicated `get_logo` tool, plus the rest of the brand guidelines. See the [Brand MCP server](/mcp-server/) page for setup.

> _"Use brand.pulumi.com/api to get a full-color Pulumi logo, 1024×1024 PNG, under 1 MB."_

### Render from the API

In addition to the logo files included in the brand-assets package, there's also a self-describing API endpoint that dynamically renders approved logo variants on request:

```bash
curl https://brand.pulumi.com/api
```

```bash
curl https://brand.pulumi.com/api/logo?format=svg&width=600
```

API responses return valid image variants as bytes, along with `Content-Location` and `Link` headers that denote the generated image's permanent URL:

```bash
curl -sI "https://brand.pulumi.com/api/logo?lockup=horizontal&background=violet-950&width=400&height=160&format=png"
```

```http
HTTP/2 200
content-type: image/png
content-location: /media/images/logos/horizontal-violet-950-400x160.png
link: </media/images/logos/horizontal-violet-950-400x160.png>; rel="canonical"
```

These URLs (at `/media`) are the _canonical_ ones. You should use these — and _not_ raw `/api` URLs — in `<img>` tags, for example, as they're stable, cached, self-describing, and have no query strings.

```html
<img src="https://brand.pulumi.com/media/images/logos/horizontal-violet-950-400x160.png">
```

#### Parameters

| Name                | Values                                                                            | Default                 |
| ------------------- | --------------------------------------------------------------------------------- | ----------------------- |
| `lockup`            | `horizontal` `stacked` `mark` `icon-circle` `icon-rounded` `icon-square` `auto`   | `auto`                  |
| `treatment`         | `color` `monotone`                                                                | `color`                 |
| `theme`             | `light` `dark`                                                                    | `light`, `dark` when a dark `background` is specified |
| `background`        | `transparent` `white` `black` `service-black` `violet-50` `violet-950`            | `transparent`           |
| `width`, `height`   | Integers up to 4096                                                               | Source width/height |
| `units`             | `px` `cm` `in`                                                                    | `px`                    |
| `dpi`               | Integers up to 600                                                                | `300`                   |
| `format`            | `svg` `png` `jpg` `pdf`                                                           | `svg`                   |
| `usage`             | `web` `print` `social-avatar` `slide-deck` `favicon` `email-signature`            | —                       |

Raster formats (`png` / `jpg`) need at least one dimension; `svg` and `pdf` scale on their own. If you omit `theme`, the service picks the variant that stays legible on your `background` (dark backgrounds get the dark artwork). Set this explicitly when a `transparent` logo will sit on a dark surface.

##### Presets

Several presets are available (in all supported formats) for convenience:

| Preset            | Example |
| ----------------- | ------- |
| `web`             | `https://brand.pulumi.com/media/images/logos/web.svg` |
| `print`           | `https://brand.pulumi.com/media/images/logos/print.pdf` |
| `social-avatar`   | `https://brand.pulumi.com/media/images/logos/social-avatar.jpg` |
| `slide-deck`      | `https://brand.pulumi.com/media/images/logos/slide-deck.pdf` |
| `favicon`         | `https://brand.pulumi.com/media/images/logos/favicon.png` |
| `email-signature` | `https://brand.pulumi.com/media/images/logos/email-signature.png` |
| `custom`          | `https://brand.pulumi.com/media/images/logos/custom.svg` |

##### Common examples

###### Web wordmark (SVG)

```bash
curl -I https://brand.pulumi.com/api/logo?usage=web
```

###### Social avatar

```bash
curl -I https://brand.pulumi.com/api/logo?usage=social-avatar
```

###### Favicon

```bash
curl -I https://brand.pulumi.com/api/logo?usage=favicon
```

###### Horizontal on violet, 2000&times;800 PNG

```bash
curl -I /api/logo?lockup=horizontal&background=violet-950&width=2000&height=800&format=png
```

###### Horizontal on white, 1200&times;480 PNG

```bash
curl -I /api/logo?lockup=horizontal&background=white&width=1200&height=480&format=png
```

###### Monotone dark mark, PDF

```bash
curl -I /api/logo?lockup=mark&treatment=monotone&theme=dark&format=pdf
```

## Trademark usage

For questions about trademark usage, licensing, and third-party use of the Pulumi name and logo, see the [Pulumi Trademark Usage Policy](https://www.pulumi.com/trademark/).

# Mascot

> Guidelines for using the Pulumipus — when to use it, when not to, and what to avoid.

The Pulumipus is a platypus and the official mascot of Pulumi.

**Heads up:**

The Pulumipus is currently being reworked and will be available for use again soon. **As of March 23, 2026, existing Pulumipus assets should not be used in any new materials.**

## Usage

The Pulumipus plays a specific role in the Pulumi brand. It represents our warmth, personality, and overall genial vibe. That role is best served when the Pulumipus is used intentionally. Reaching for the Pulumipus to fill empty space or add visual interest cheapens its presence. Save it for moments where it genuinely fits.

  - Bring the Pulumipus out for community events, swag, and in marketing contexts where brand energy and enthusiasm are high.
  - Feature it in internal contexts like office art, milestone swag, and team celebrations.
  - Use it to spark curiosity and delight.
  - Don't use old or deprecated Pulumipus assets. Use only approved versions.
  - Don't treat the Pulumipus as a logo or feature it in co-branding with other companies or organizations.
  - Don't use it in product flows or in sales, support, or training contexts where it would feel intrusive.
  - Don't associate the Pulumipus with topics that call for credibility and gravity — e.g., finance, security, enterprise offerings, and the like.
  - Never use generative AI to create or alter Pulumipus imagery.

One exception to these rules is the Neo icon, which _may_ be used in approved product flows and other contexts. See [Neo](#neo) below.

**Generative AI:**

Never use generative AI to create or modify the Pulumipus. The mascot should be a consistent and recognizable character that reflects the brand's personality. AI-generated variations risk creating an inconsistent and diluted brand image, so are therefore disallowed.

## Neo

Neo is our AI infrastructure agent, and is represented as a platypus wearing sunglasses.

- In UI, see the [iconography](/identity/iconography/) guidelines for using the Neo icon. At standard UI sizes, use the `Fill` weight when pairing it with other `Regular` icons.
- In any other communications, use the same icon to represent Neo.
- At larger sizes, use the `Outline` weight and scale the whole icon so the stroke weights scale with it.
- If you need an avatar to represent Neo, use one of the approved avatars below, both of which are available in the [assets download](/pulumi-brand-assets.zip).
- In the terminal, use one of the approved ASCII renditions below.

**Retired Neo:**

Never use the retired 3D-style Neo.

### Avatars

Pulumi Neo

Pulumi Neo

### ASCII

```text
      ▇▇▇▇▇▇▇▇▇▇▇
    ▇▇           ▇▇        ░███    ░██ ░██████████   ░██████
   ░░░░░░░░░░░░░░░░░       ░████   ░██ ░██          ░██   ░██
  ░░░░░░░░   ░░░░░░░░      ░██░██  ░██ ░██         ░██     ░██
   ░░░░         ░░░░       ░██ ░██ ░██ ░█████████  ░██     ░██
    ▇    ▇   ▇    ▇        ░██  ░██░██ ░██         ░██     ░██
  ▇▇               ▇▇      ░██   ░████ ░██          ░██   ░██
   ▇▇▇▇▇       ▇▇▇▇▇       ░██    ░███ ░██████████   ░██████
     ▇▇▇▇▇▇▇▇▇▇▇▇▇
```

```text
          ▇▇▇▇▇▇▇▇▇▇▇▇▇
       ▇▇▇             ▇▇▇
      ▇▇                 ▇▇
     ░░░░░░░░░░░░░░░░░░░░░░░          ░███    ░██ ░██████████   ░██████
    ░░░░░░░░░░░░░░░░░░░░░░░░░         ░████   ░██ ░██          ░██   ░██
   ░░░░░░░░░░░     ░░░░░░░░░░░        ░██░██  ░██ ░██         ░██     ░██
    ░░░░░░░░░       ░░░░░░░░░         ░██ ░██ ░██ ░█████████  ░██     ░██
     ▇▇                   ▇▇          ░██  ░██░██ ░██         ░██     ░██
    ▇▇       ▇▇   ▇▇       ▇▇         ░██   ░████ ░██          ░██   ░██
  ▇▇                         ▇▇       ░██    ░███ ░██████████   ░██████
  ▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇
    ▇▇▇▇▇▇▇▇▇       ▇▇▇▇▇▇▇▇▇
        ▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇
```

```text
      ▇▇▇▇▇▇▇▇▇▇▇
    ▇▇           ▇▇
   ░░░░░░░░░░░░░░░░░
  ░░░░░░░░   ░░░░░░░░
   ░░░░         ░░░░
    ▇    ▇   ▇    ▇
  ▇▇               ▇▇
   ▇▇▇▇▇       ▇▇▇▇▇
     ▇▇▇▇▇▇▇▇▇▇▇▇▇
```

```text
          ▇▇▇▇▇▇▇▇▇▇▇▇▇
       ▇▇▇             ▇▇▇
      ▇▇                 ▇▇
     ░░░░░░░░░░░░░░░░░░░░░░░
    ░░░░░░░░░░░░░░░░░░░░░░░░░
   ░░░░░░░░░░░     ░░░░░░░░░░░
    ░░░░░░░░░       ░░░░░░░░░
     ▇▇                   ▇▇
    ▇▇       ▇▇   ▇▇       ▇▇
  ▇▇                         ▇▇
  ▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇
    ▇▇▇▇▇▇▇▇▇       ▇▇▇▇▇▇▇▇▇
        ▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇
```

```text
░███    ░██ ░██████████   ░██████
░████   ░██ ░██          ░██   ░██
░██░██  ░██ ░██         ░██     ░██
░██ ░██ ░██ ░█████████  ░██     ░██
░██  ░██░██ ░██         ░██     ░██
░██   ░████ ░██          ░██   ░██
░██    ░███ ░██████████   ░██████
```

# Typography

> Pulumi's typefaces, usage rules, typographic scale, and code highlighting standards.

## Primary typeface

The primary typeface for the Pulumi brand is [Inter](https://github.com/rsms/inter/). If Inter is not available, acceptable fallback system fonts include Helvetica Neue, Helvetica, and Arial.

Pulumi Typography Inter

- Use Inter for all headings, body text, and other typographic needs in brand materials.
- The Semibold weight of Inter is the primary weight for headings and emphasis, while the Regular weight is the primary weight for body text and longer form copy.
- When used for headings, Inter's tracking (letter spacing) should be set to -5% (-0.05em). In places where letter spacing is not adjustable but Google fonts are available, such as in Google Slides and Docs, use Inter Tight for headings.
- In headings, Inter line height should be set to 110% (1.1em), and in body text and longer form copy it should be set to 130% (1.3em) for readability.

### Font stack

```
Inter, 'Helvetica Neue', Helvetica, Arial, -apple-system, BlinkMacSystemFont, sans-serif
```

## Mono typeface

Pulumi Typography Monaspace Neon

The mono typeface for the Pulumi brand is [Monaspace Neon](https://github.com/githubnext/monaspace). If Monaspace Neon is not available, but Google Fonts are (e.g., in Google Slides and Docs), Cascadia Mono is an acceptable fallback. Acceptable system font fallbacks include Menlo and Consolas.

- Use Monaspace Neon for code snippets, technical documentation, and any context where a monospaced font is appropriate.
- It can also be used for labels and overlines. When used for this purpose, it should be set in all caps with tracking set to +5%.
- Use the Regular weight by default, but the other weights are available if they make sense for uses like larger format designs.

### Font stack

```
'Monaspace Neon', Menlo, Consolas, ui-monospace, monospace
```

## Get the fonts

The brand-assets package contains all fonts, standard logos, colors, and supporting imagery:

  
  Download

## Typographic scale

Typographic scales are defined in more detail in specific design systems and component libraries. Follow those guidelines for specific use cases. In general, use the following guiding principles:

- Establish clear hierarchy between headings, subheadings, and body text
- Headings: Semibold weight, -5% tracking, 110% line height
- Body: Regular weight, 0% tracking, 130% line height

## Font features

Apply the following OpenType font feature settings by default across all digital implementations.

**Tailwind CSS v4**

```css
@theme {
  --default-font-feature-settings: "liga" 1, "calt" 1, "cv11" 1;
}
```

**CSS**

```css
body {
  font-feature-settings: "liga" 1, "calt" 1, "cv11" 1;
}
```

- **`liga`** — enables standard ligatures (e.g., `fi`, `fl`)
- **`calt`** — enables contextual alternates for more natural letter connections
- **`cv11`** — enables Inter's character variant for `1` (adds a serif crossbar for improved legibility)

## Code highlighting

Always use [Min Theme](https://github.com/miguelsolorio/min-theme) for code snippets. Replace the default background color of the theme with `Violet 50` light (`#f5f5ff`) and dark (`#231f33`). It's okay to use the Min Dark theme in light mode contexts if more contrast is desired for code snippets.

  
    ```typescript
    import * as pulumi from "@pulumi/pulumi";
    import * as aws from "@pulumi/aws";

    const bucket = new aws.s3.Bucket("my-bucket");

    export const bucketName = bucket.id;
    ```

  
  
    ```python
    import pulumi
    from pulumi_aws import s3

    bucket = s3.Bucket("my-bucket")

    pulumi.export("bucketName", bucket.id)
    ```

  
  
    ```go
    package main

    import (
    	"github.com/pulumi/pulumi-aws/sdk/v7/go/aws/s3"
    	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
    )

    func main() {
    	pulumi.Run(func(ctx *pulumi.Context) error {
    		bucket, err := s3.NewBucket(ctx, "my-bucket", nil)
    		if err != nil {
    			return err
    		}
    		ctx.Export("bucketName", bucket.ID())
    		return nil
    	})
    }
    ```

  
  
    ```csharp
    using Pulumi;
    using Pulumi.Aws.S3;

    class MyStack : Stack
    {
        public MyStack()
        {
            var bucket = new Bucket("my-bucket");
            this.BucketName = bucket.Id;
        }

        [Output]
        public Output<string> BucketName { get; set; }
    }
    ```

  
  
    ```java
    package s3site;

    import com.pulumi.Context;
    import com.pulumi.Pulumi;
    import com.pulumi.aws.s3.Bucket;

    public class Infra {
        public static void main(String[] args) {
            Pulumi.run(Infra::stack);
        }

        private static void stack(Context ctx) {
            final var myBucket = new Bucket("my-bucket");
            ctx.export("bucketName", myBucket.id());
        }
    }
    ```

  
  
    ```yaml
    name: my-stack
    runtime: yaml
    resources:
        bucket:
            type: aws:s3:Bucket
    outputs:
        bucketName: ${bucket.id}
    ```
  

# Brand MCP server

> A remote Model Context Protocol server that exposes the Pulumi brand guidelines as structured resources, tools, and prompts for AI agents and LLM-powered workflows.

**Notice:**

Please review the [Generative AI Guidelines](/guidelines/generative-ai/) before using the Brand MCP Server.

The Pulumi Brand MCP Server is a remote [Model Context Protocol](https://modelcontextprotocol.io) server that exposes the Pulumi brand guidelines as structured resources, tools, and prompts. It's designed to be consumed by AI agents and LLM-powered workflows that create, review, or audit brand content, and it's deployed at `brand.pulumi.com` and compatible with any MCP client that supports streamable HTTP.

## Configuration

Point any MCP-compatible client at the public URL:

```
https://brand.pulumi.com/mcp
```

In the snippets below, we've named the connection `pulumi-brand`, but you can change that if you like.

### Claude

You can use the MCP server with Claude Code, Claude Desktop, and in the browser at Claude.ai.

#### Claude Code

Add the MCP server with the CLI:

```bash
claude mcp add --transport http pulumi-brand https://brand.pulumi.com/mcp
```

By default, the server is scoped to the current project. Add `--scope user` to make it available across all of your projects:

```bash
claude mcp add --transport http --scope user pulumi-brand https://brand.pulumi.com/mcp
```

To confirm the connection succeeded, run `claude mcp list`. To inspect the server's tools, run `/mcp` in an active Claude Code session.

#### Claude Desktop

You can configure Claude Desktop with the MCP server in one of two ways.

##### With a custom connector

1. In Claude Desktop, open **Customize → Connectors**.
1. Click **Add → Add custom connector**.
1. Enter a name (e.g., "Pulumi Brand") and paste the URL: `https://brand.pulumi.com/mcp`.
1. Save the connector and begin using the MCP server.

##### With a local MCP server

This approach uses the [`mcp-remote`](https://github.com/geelen/mcp-remote) connector.

1. In Claude Desktop, open **Developer → Local MCP servers**.
1. Click **Edit config** and open the file in your text editor of choice.
1. Add a `pulumi-brand` block to the `mcpServers` list (add that list if it doesn't exist):

    ```json
    {
        "mcpServers": {
            "pulumi-brand": {
                "command": "npx",
                "args": ["-y", "mcp-remote", "https://brand.pulumi.com/mcp"]
            }
        }
    }
    ```

1. Save the file and begin using the MCP server.

#### Claude.ai

1. Visit https://claude.ai, sign in, and navigate to **Customize → Connectors**.
1. Click **Add → Add custom connector**.
1. Enter a name (e.g., "Pulumi Brand") and paste the URL: `https://brand.pulumi.com/mcp`.
1. Save the connector and begin using the MCP server.

### Codex

1. Add the following block to `~/.codex/config.toml` for all projects, or to `./.codex/config.toml` for the current one:

    ```toml
    [mcp_servers.pulumi-brand]
    url = "https://brand.pulumi.com/mcp"
    ```

1. Save the file, restart Codex, and begin using the MCP server.

### Cursor

You can use the MCP server with Cursor in several ways.

#### Cursor Desktop

1. Open **Settings → Cursor Settings → Tools &amp; MCPs**.
1. Under Installed MCP Servers, click **Add Custom MCP**.
1. Add the following block to `~/.cursor/mcp.json` for all projects, or to `./.cursor/mcp.json` for the current one:

    ```json
    {
        "mcpServers": {
            "pulumi-brand": {
                "transport": "http",
                "url": "https://brand.pulumi.com/mcp"
            }
        }
    }
    ```

1. Save the file and begin using the MCP server.

#### Cursor CLI

1. Add the following block to `~/.cursor/mcp.json` for all projects, or to `./.cursor/mcp.json` for the current one:

    ```json
    {
        "mcpServers": {
            "pulumi-brand": {
                "transport": "http",
                "url": "https://brand.pulumi.com/mcp"
            }
        }
    }
    ```

1. Save the file, restart Cursor, and begin using the MCP server.

### OpenCode

1. Add the following block to `~/.config/opencode/opencode.json` for all projects, or to `./opencode.json` for the current one:

    ```json
    {
        "$schema": "https://opencode.ai/config.json",
        "mcp": {
            "pulumi-brand": {
                "type": "remote",
                "url": "https://brand.pulumi.com/mcp",
                "enabled": true
            }
        }
    }
    ```

1. Save the file, restart OpenCode, and begin using the MCP server.

### Other clients

Any MCP client that supports a remote Streamable HTTP server works. Give it the URL `https://brand.pulumi.com/mcp` directly if it accepts one, or bridge through stdio with `npx -y mcp-remote https://brand.pulumi.com/mcp` (the same pattern as the Claude Desktop config-file option above).

## Resources

Static brand content served via `resources/read`. Each resource uses a `brand://` URI scheme.

| URI | Name | Content |
| --- | ---- | ------- |
| `brand://colors` | Brand Colors | Full color system — 8 palettes × 11 steps, semantic roles, utility colors, accessibility notes |
| `brand://colors/{palette}` | Brand Color Palette | A single palette (e.g., `brand://colors/violet`) |
| `brand://typography` | Brand Typography | Inter + Monaspace Neon typefaces, font stacks, usage rules, typographic scale |
| `brand://voice` | Brand Voice & Tone | Voice principles, tone-by-context matrix, preferred/avoided words, inclusive language |
| `brand://writing-style` | Writing Style | Grammar, punctuation, style rules (Chicago Manual of Style) |
| `brand://logo` | Logo Guidelines | Lockups, sizing, approved backgrounds, clear space, dos/don'ts |
| `brand://identity` | Brand Identity | Brand attributes, purpose, values, Phosphor iconography guidelines |
| `brand://visuals` | Visual Guidelines | Illustration style, accent lines, photography, mascot (Pulumipus) |
| `brand://guidelines` | Usage Guidelines | Generative AI usage rules, when to bend brand rules |

## Tools

The tools fall into two groups: **brand lookup** (colors, typography, search) and **asset generation** (logos).

### `get_brand_overview`

Return the brand orientation — how to use this server and which `get_guidelines` section to pull for the task at hand. The same text MCP clients receive as server `instructions` at session start; call this when your client doesn't surface those, or to re-orient mid-task. It routes you to the rules rather than restating them — use `get_guidelines` for the full guidance on a topic.

Takes no arguments.

### `get_guidelines`

Return the complete text of a brand guideline section — the full guidance, not a summary. Call it before producing or reviewing the matching kind of artifact (for example, `voice` and `writing-style` before writing copy). For color, use the color tools below; to search across sections, use `search_guidelines`.

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `section` | string | Yes | One of: `voice`, `writing-style`, `typography`, `logo`, `identity`, `visuals`, `guidelines` |

### `get_color_palette`

Get a specific brand color palette with all 11 steps (50–950) and semantic roles.

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `palette` | string | Yes | One of: `violet`, `gray`, `green`, `aqua`, `blue`, `red`, `orange`, `yellow`, or `utility` (black, white, Service Black) |
| `format` | string | No | Color format hint: `hex`, `hsl`, `rgb`, `oklch`. Stored values are hex; other formats available via `brand://colors`. |
| `response_format` | string | No | `json` (default) for structured data or `markdown` for a human-readable table |

### `find_nearest_brand_color`

Find the perceptually closest brand color to any CSS color value using OKLab Euclidean color difference.

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `color` | string | Yes | Any CSS color: `#6366f1`, `rgb(99,102,241)`, `hsl(239,84%,67%)`, `oklch(...)`, or a named color |
| `mode` | string | No | `light`, `dark`, or `both` (default). Which mode's palette to match against. |

Returns the matched token name, palette, step, mode, and hex value with a replacement recommendation.

### `get_color_tokens`

Get semantic color tokens (primary, accent, muted, background) for one or all palettes.

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `palette` | string | No | A specific palette name. Omit to get tokens for all 8 palettes. |

### `check_color_accessibility`

Check contrast between two colors using **WCAG 3 APCA** (Accessible Perceptual Contrast Algorithm). Returns the Lc value, polarity, pass/fail thresholds, and a font-size lookup per weight.

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `foreground` | string | Yes | Hex value or brand token name (e.g., `violet-700-light`) |
| `background` | string | Yes | Hex value or brand token name |

**APCA thresholds:**

| Lc (absolute) | Use case |
| ------------- | -------- |
| ≥ 90 | Preferred body text |
| ≥ 75 | Body text minimum |
| ≥ 60 | Large / heading text |
| ≥ 45 | Large non-text elements |
| ≥ 30 | Non-text / spot elements |
| < 30 | Insufficient — do not use |

### `get_font_stack`

Get the correct brand font stack and usage rules for a given typographic context.

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `context` | string | Yes | `heading` (Inter Semibold), `body` (Inter Regular), or `mono` (Monaspace Neon) |

### `search_guidelines`

Full-text search across all brand guideline content. Returns excerpts with surrounding context.

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `query` | string | Yes | Search terms or natural language question about the brand |

### `get_logo`

Return a URL for a Pulumi logo in any approved variant, format, background, and size. The URL is served by the brand site's logo endpoint at [`brand.pulumi.com/api/logo`](/api) (CDN-cached) — surface it directly to the user. Pass `inline: true` to embed the bytes (SVG markup or a base64 data URI) in the tool response instead, for runtimes that can't fetch a URL at render time.

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `usage` | string | No | Preset that sets sensible defaults: `web`, `print`, `slide-deck`, `email-signature`, `favicon`, `social-avatar`, `custom`. Explicit params override. |
| `lockup` | string | No | `auto` (default), `mark`, `horizontal`, `stacked`, or `icon-circle` / `icon-rounded` / `icon-square` |
| `treatment` | string | No | `color` (default) or `monotone`. Icons are always color. |
| `theme` | string | No | `light` or `dark`. Auto-derived from the background when omitted. |
| `format` | string | No | `svg` (default), `png`, `jpg`, or `pdf` |
| `background` | string | No | `transparent` (default), `white`, `black`, `service-black`, `violet-50`, `violet-950` |
| `width` / `height` | number | No | Size in `units`. One alone → logo-only; both → centered on a padded canvas. |
| `units` | string | No | `px` (default), `cm`, or `in` (with `dpi`, default 300) |
| `inline` | boolean | No | `true` to embed the asset bytes in the response instead of returning a URL. Default `false`. |

## Prompts

Pre-built prompt templates that inject brand context for LLM-powered workflows.

Prompts are **user-invoked** — the agent doesn't call them automatically. You trigger one, fill in its arguments, and it expands into a ready-made message (pre-loaded with the relevant brand guidelines) that's sent to the model. How you invoke them depends on your client:

- **Claude Code** — they appear as slash commands. Type `/` and look for the `pulumi-brand` entries (e.g., `/mcp__pulumi-brand__review_copy`).
- **Claude Desktop / Claude.ai** — open the `+` (connectors) menu in the composer, pick the **pulumi-brand** server, choose the prompt, and fill in the fields.
- **Other clients** — wherever the client surfaces MCP prompts (a command palette or MCP panel). Under the hood it's the standard `prompts/list` → `prompts/get` flow.

Note that `review_image` takes no arguments — attach the image to your message first, then invoke it.

### `review_copy`

Review text content for compliance with brand voice, tone, and writing style. Returns an overall assessment, a list of specific issues with quotes and suggested rewrites, and a clean rewritten version if issues were found.

| Argument | Required | Description |
| -------- | -------- | ----------- |
| `copy` | Yes | The text content to review |
| `context` | No | `product`, `marketing` (default), `community`, or `enterprise` |

### `review_image`

Evaluate an image against brand visual guidelines — color, typography, iconography, illustration, and photography. Attach the image to your message, then invoke the prompt.

Takes no arguments — the prompt reads the attached image directly.

### `review_design`

Review a design in Figma for brand adherence — covers colors, typography, logo usage, spacing, and overall alignment. Works in combination with the Figma MCP, which retrieves the design from the URL.

| Argument | Required | Description |
| -------- | -------- | ----------- |
| `figma_url` | Yes | Figma file or node URL (`figma.com/design/…`) to review |

# Accent lines

> How to use Pulumi's curved accent lines in compositions.

Pulumi Accent Lines

A collection of curved accent lines can be combined and either used on their own or integrated into larger compositions.

  - Always terminate lines off canvas or fade them into the background.
  - Space multiple lines evenly and arrange them in a balanced, intentional way.
  - Keep all lines the same weight.
  - Lines can be used to indicate connection between elements.
  - Don't end lines abruptly or crop them in a way that creates a hard edge.
  - Don't let lines bisect or overlap each other in a way that creates visual clutter.
  - Don't use lines in complex flow diagrams to indicate directionality — use simpler connectors instead. (See [Illustration](/visuals/illustration/).)

# Illustration

> Pulumi's illustration style — line art, isometric shapes, and the distinction between illustrations and diagrams.

## Illustration style

Pulumi Illustration

The illustration style for the Pulumi brand is a simple line art style featuring the brand violet as the primary color, with supporting colors used as needed.

- Isometric shapes can be included, but should avoid making important text illegible.
- All stroke weights should match within a composition. This is typically 1px for digital use, but can be adjusted as needed for larger format designs.
- Use Phosphor [icons](/identity/iconography/) where icons are needed within illustrations.

## Illustrations vs. diagrams

Pulumi Illustration vs Diagrams

**Illustrations** are used to communicate high-level concepts, add visual interest, and for empty states. These can be more abstract and decorative, and can include more complex compositions with isometric shapes and accent lines.

**Diagrams** are used to communicate more detailed concepts or flows and should be created in a simple style that prioritizes clarity and ease of understanding. Avoid isometric views here and use simple connector lines to clearly show flows and relationships.

# Photography

> Guidelines for using photography in Pulumi brand materials.

Photography should be used sparingly — primarily in blog posts, event content, community content, and company culture materials.

  - Feature real people and aim for an authentic, candid feel rather than overly staged or posed compositions.
  - Don't use stock photography or AI-generated photographic images.

# Voice & tone

> Pulumi's voice principles, tone by context, and word choices.

Everything we put out into the world — every blog post, doc, page, guide, deck, and social-media post — is an expression of the Pulumi brand. The content we create doesn't exist separately from the brand; it _is_ the brand, and one of the main ways our users connect with us.

## Voice

Our voice — the language we use and how we use it — should be as authentic and consistent as we can make it across all of our communications, from blogs and demos to case studies and whitepapers. How we communicate is an expression of who we are, so we do our best to adhere to certain key principles.

* **Practitioner-first**. Most of our content is written for people who use technical products like ours, so we write like engineers in conversation with engineers, with the words and language our audience uses, without dumbing things down or dressing anything up.

* **Direct and confident**. Technical people appreciate clarity, so we say what we mean, and we're tactfully and respectfully open about our opinions when we have them. When we're talking about Pulumi, we're clear about what the product actually does, not what it almost does.

* **Concrete over abstract**. Wherever possible, we show, don't tell, with examples and concrete numbers where it helps. "A P99 performance improvement of 93%" is better than "significantly faster", and "supports AWS and Azure" is better than "supports most major cloud providers". Ambiguity leads to confusion.

* **Honest and respectful**. We openly acknowledge real-world tradeoffs and alternatives because that's what our audience needs and appreciates. "Already happy with Pulumi open source? Many teams are — and we love that." That's true, so we say it. And we never trash competitor brands or products. And when Pulumi isn't the right fit, we say that too, because doing so builds trust, and trust is what it's all about.

* **Warm, but not cute**. We're genuinely approachable and conversational, so our prose should reflect that ("it just works", "Pulumi takes care of the rest"), but we don't force humor or cleverness. We keep it light, but always professional.

Everywhere we communicate, we should sound like ourselves: human, kind, warm, approachable, empathetic, opinionated but balanced, and honest. Authenticity and trust, above all, are the goal.

### Your own voice

Our collective voice is important, but when your name is on a piece — a blog post, a conference talk, a byline of any kind — we want _you_ to come through, too. We don't all sound the same, so we encourage you to write like yourself and let your personality come through. These guidelines keep us recognizable and trustworthy, but they aren't here to flatten us all into a uniform blob. When in doubt, lean toward sounding human. That's the one rule that always stands.

## Who we write for

We write for people. The web may be heavily trafficked by bots, but our words are intended to serve our fellow humans. When we write, we're aware there's a person on the other end of the line, so we craft our words accordingly, even if what we're writing is intended to connect with that person by way of a bot.

## Tone by context

While our voice should stay consistent, the tone we use may shift depending on audience and context.

* **In product and technical content**, we lead with the motivating problem, then move into the solution, how it works, and the value it delivers. We keep it brisk, but don't go so fast that we don't leave room to deliver the substance the reader needs. We're specific and scannable, and we assume technical competence, using bullet points and bold text to make details easy to find.

* **In marketing and landing pages**, we're more narrative, but still grounded in concrete details, and we avoid vague, inflated language. We don't just list features, we communicate the value those features deliver, because that's what the reader cares about. Context and well-chosen examples are much better than feature lists, which require the reader to fill in the blanks on their own.

* **In community and social content**, we're casual and conversational. For these, we use the first person plural perspective (_we_) because it reads more naturally and it's a better fit for communicating genuine enthusiasm.

* **In enterprise and sales content**, our tone is more grounded and less casual, but still human, and we're careful to avoid using overly promotional, salesy or marketing-heavy language.

For guidance on whether to address the reader as _you_ or _we_, see [Person and point of view](/voice/writing-style/#person-and-point-of-view).

## Words and phrases

The following word choices help carry our voice. For how to spell, capitalize, and hyphenate specific terms, including Pulumi product names, see [Names and terminology](/voice/writing-style/#names-and-terminology).

### Prefer

- _Engineers_ and _developers_ over _users_ or _customers_. (The latter are colder and less personal.)
- _Humans and agents_ as a natural pairing when describing who Pulumi is built for.
- _Agents_ or _coding agents_ when referring to AI agents that provision and manage infrastructure.
- _Building blocks_, _components_, and _composable_ when describing our compositional capabilities.
- _Estate_ for the full scope of an organization's infrastructure, as opposed to the less specific _environment_ or _footprint_.
- _Build_, _deploy_, _ship_, and _manage_ as active, concrete verbs.
- _Works with_ or _integrates with_ over the more awkward and inflated _leverages_ or _utilizes_.
- Short sentences and parallel structure in lists.

### Avoid

- Superlatives without evidence like _the best_, _the only_, _the most powerful_, etc.
- Tired buzzwords like _synergy_ and the like.
- Exclamation points and emojis just about everywhere other than social-media posts.
- Sharply negative or combative language and profanity.

## Inclusive language

Pulumi strives to use language that is clear, inclusive, and respectful.

- Avoid ableist terms. Instead of _crazy_, use _wild_. Instead of _dummy_, use _placeholder_.
- Avoid unnecessarily gendered language. Instead, use words like _folks_, _everyone_.
- Avoid violent or aggressive terms like _kill_ or _clobber_.
- Avoid pop-culture references that may not be globally understood.
- When writing docs, consider _select_ or _choose_ over _click_.
- Instead of _go to_ use _navigate to_.
- Avoid directional terms like _above_ or _below_ unless the reference is in close proximity.
- Avoid words like _easy_ or _simple_, as these may alienate readers.

# Writing style

> Grammar, punctuation, and style rules for Pulumi communications.

While closely related to [voice and tone](/voice/voice-and-tone/), style is more about the mechanics of how writing (and content in general) is constructed. Where voice and tone are about emotion and personality, style is more about structure and technique.

## The essentials

- Always [write like a human](#natural-voice). Even when you've used an LLM to assist, your words belong to you.
- Always [respect the reader's time and attention](#respect-the-readers-time-and-attention).
- Give every piece a clear [thesis or driving question](#revision).
- Use headings to [carry the structure and convey the gist](#headings-and-titles).
- Almost always, [address the reader directly](#person-and-point-of-view).
- Nothing ships without [revision and human review](#review).

## Respect the reader's time and attention

Our time and attention are among our most precious resources. When writing for a human (which you should pretty much [always be doing](/voice/voice-and-tone/#who-we-write-for)), always remember there's someone on the other end of the line trying to get value out of your words as they read them. None of us has the time or energy to slog through vague, incomplete, unedited, or overly inflated prose.

See [Drafting, revising, and reviewing](#drafting-revision-and-review) below for guidance.

## Natural voice

All of the copy we write should sound like a human being wrote it, even if an LLM helped to create it. Pulumians are people, and our readers assume the words we write are our own. So we write like the people we are, not like machines, avoiding patterns that signal generated text, such as:

- Staccato sentence fragments used for emphasis. Like this. And this.
- Leading negatives, with or without the usual em-dashes, like _This isn't just about foo — it's about bar._ Cut the negative, say it's about bar, and get on with it.
- Three-item series. They're a big AI tell. They're fine when you write them yourself, but LLMs use them as filler. Ensure they say what you mean and if not, revise or delete.
- Overuse of tables. Unless the table is truly valuable as a table (i.e., it's data), consider rewriting it as a list or in prose — or simply delete it.
- Too many bullet lists. A few well-placed bullets are great, but a screenful of them is another AI signal. Consider revising as prose to break things up and make the writing more human.

As a rule: Never ship raw LLM output. Every piece of writing we produce must go through a human review and revision cycle in which you, as the author, bring the copy in line with how you — and how we — would say it. See [Drafting, revising, and reviewing](#drafting-revision-and-review) for details.

## Person and point of view

### Addressing the reader

In technical content for hands-on engagement (blogs, tutorials, how-to guides), we use the second-person singular perspective (_you_), not the first-person plural (_we_). This is because _we_ aren't doing anything — the reader is. So the focus is kept on their learning and experience: "In this walkthrough, _you'll_ build", not "_we'll_ build".

The same is true in most marketing content. Instead of "ESC enables teams and organizations to consolidate secrets management", privilege "ESC lets you manage all of your secrets in one place". There are exceptions, but as a rule, second person is clearer and more engaging — as well as how we'd most likely say it in conversation.

## Attribution and accuracy

Every claim we make in our copy should come from an attributable source, even if that source is our own internal data.

- Never round up, infer, or embellish.
- If the source describes one person's experience, don't generalize it as "companies" or "teams".
- If the source doesn't give a number, don't invent or estimate one.

## Grammar and punctuation

- We use the Oxford (or serial) comma, so it's "build, deploy, and manage", not "build, deploy and manage".
- Human writers use em-dashes ("—"), so you can, too. Feel free to use em-dashes when you're writing them yourself. Revise away, however, the em-dashes emitted by LLMs, because they're strong markers of LLM-generated copy. Do not, however, simply swap them out for other punctuation like hyphens or commas, as that's just another marker of lazily revised LLM-generated copy. Make the words and the phrasing both grammatically correct and your own.
- Contractions are not only fine, they're preferable, even in docs. ([We write for people](/voice/voice-and-tone/#who-we-write-for).)
- Put commas and periods outside the closing quotation mark unless they belong to the quoted text to keep punctuation from looking like part of a literal. For example, write "us-west-2", and a quoted phrase like "it just works", with the punctuation outside.
- Reserve "e.g.," and "i.e.," — both followed by commas — for parenthetical asides, and spell out "for example" or "that is" in running prose.

## Dates, times, and numbers

- Write dates as "June 14, 2026" in prose, and use ISO 8601 ("2026-06-14") in technical and code contexts.
- Write times in 12-hour form with a lowercase "am" or "pm", and always include the time zone, as in "9:00am UTC". Default to UTC unless there's a good reason not to.
- Use an en-dash for numeric ranges ("10–20"), commas in numbers of a thousand or more ("10,000"), and spelled-out scale for large round numbers ("$5 million", not "$5,000,000").

## Code samples

When writing code samples:

- Use four-space indentation for all languages except YAML and Go. With YAML, use two-space indentation. With Go, use tabs.
- Use double-quotes across all languages, single quotes within double-quoted strings.
- Use comments and highlights to call out important sections of the code. Keep comments brief, ideally to one line.
- When quoting a section of code that's indented in the source, omit the leading indentation. For example, to declare a local variable in the body of a JavaScript method belonging to a class (e.g., two levels of indentation), do this:

    ```javascript
    const foo = "bar";
    ```

    Not this:

    ```javascript
            const foo = "bar";
    ```

    The latter may be truer to the source, but without local context, the leading space looks unintentional and can push longer lines and further nesting out of view.

- Horizontal scrolling in code samples is usually fine, except when the code under discussion drifts out of view. Consider splitting up longer lines to ensure the important parts are visible at desktop width.

- Split long CLI commands into multiple lines to help readers see what's important:

    ```bash
    pulumi do aws:s3:BucketV2 create \
        --aws:region us-west-2 \
        --aws:access-key <your-access-key-id> \
        --aws:allowed-account-ids <your-allowed-account-ids> \
        --force-destroy \
        --yes
    ```

## Text formatting

- Use `code` font (backticks) for code, commands, filenames, paths, environment variables, and literal values, as in `pulumi up`, `~/.pulumi`, `AWS_REGION`, and `true`.
- Use bold sparingly for the names of UI elements the reader acts on ("click **Save**"), and for the rare phrase that genuinely needs emphasis. Bold sprinkled throughout is both visually noisy and a common AI tell.
- Use italics for a word or short term you're introducing, defining, or describing — for example: _setup_ is a noun, _set up_ is a verb. Italics are also generally appropriate for emphasis, but should be used sparingly.
- Write placeholders in angle brackets with code elements, like `<your-access-key-id>`, so it's obvious what the reader should replace.

## Headings and titles

- Avoid clickbaity titles.
- Always use sentence case for headings (e.g., "This is a heading", not "This Is a Heading").
- Avoid ending headings with punctuation.
- Use headings to communicate structure and content. Skimming only the headings, the reader should be able to discern the piece's overall outline and what it's about. Avoid clever headings that don't convey meaning.
- Nest headings properly. For example, don't put an `h3` (`###`) directly under an `h1`. Make it an `h2` instead.
- Keep SEO in mind. Use titles and headings that contain the keywords you're targeting. This'll make it easier for humans to find your content by helping the bots index and rank it.
- Scrub for common LLMisms like "Stop doing X. Y.", "Why this matters", "What this unlocks", and "What this means — and what it doesn't". See [Generative AI](/guidelines/generative-ai/) for additional details.

## Names and terminology

- Always capitalize Pulumi product names correctly:

    - Pulumi IaC
    - Pulumi Cloud, Pulumi console, Pulumi Cloud console (but not Pulumi UI)
    - Pulumi ESC (Environments, Secrets, and Configuration)
    - Pulumi Neo
    - Pulumi Deployments
    - Pulumi Insights
    - Pulumi Policies
    - Pulumi IDP

- Expand product names on first mention ("Pulumi ESC"), then use just the product name ("ESC") afterward. Similarly, for non-Pulumi acronyms, spell out the acronym on first use, then use the abbreviation (e.g., "Virtual Private Cloud (VPC)", then just "VPC"). Widely known acronyms (API, HTTP, REST) don't need explanation.
- Don't overcapitalize. Only [proper nouns](https://en.wikipedia.org/wiki/Proper_noun) should be capitalized — not concepts (even Pulumi-specific ones). So for example, it's _stack_, not _Stack_; _environment_, not _Environment_; _token_, not _Token_; and _infrastructure as code_, not _Infrastructure as Code_.
- The phrase _infrastructure as code_ can be used as a noun or an adjective. The noun form ("infrastructure as code is the practice of...") should never be hyphenated. The adjectival form ("Pulumi is an infrastructure-as-code tool") _may_ be hyphenated, but typically doesn't need to be. If the sentence is clear and unambiguous without the hyphens, omit them.
- Use _public preview_ for pre-GA features, not _public beta_.
- It's _open source_ when used as a noun ("Pulumi is open source"), but _open-source_ when used as an adjective ("an open-source platform"); _set up_ as a verb but _setup_ as a noun; _log in_ as a verb but _login_ as a noun; and _command line_ as a noun but _command-line_ as an adjective.
- _Cloud_ and _internet_ are both lowercase, and _data center_ is two words. _Frontend_ and _backend_ are both one.
- Match each project's own casing for names like Kubernetes, GitHub, and npm. When a lowercase name like npm would land at the start of a sentence, reword so it doesn't.

For which words to prefer or avoid for voice and tone, see [words and phrases](/voice/voice-and-tone/#words-and-phrases).

## Links

- Make link text descriptive. Avoid linking nondescript words like _here_ or _click here_, and describe what the link points to or what will happen when the reader follows it. This is helpful for humans as well as SEO.
- Look for opportunities for internal linking. When writing about a Pulumi feature, link to that feature's documentation, landing page, or other related resources. This encourages readers to engage and continue learning and also strengthens overall SEO.

## Images and alt text

- Give every meaningful image alt text that describes its content or function in a few words. Omit phrases like "image of" and "screenshot of", since screen readers already announce images.
- Name image files descriptively, both for accessibility and for SEO. (See [the review checklist](#review).)

## Lists

- Introduce lists with a complete sentence, usually ending in a colon.
- Write list items as complete sentences — capitalized, and ending with a period — unless the list is deliberately terse, like a set of single terms, in which case drop the periods. Either way, stay consistent within a single list.
- Keep list items parallel. If the first one starts with a verb, they all should.
- Only use lists when lists are called for, and prefer prose otherwise. See [Natural voice](#natural-voice) for additional guidance.

## Paragraphs

- Keep paragraphs short, ideally to five sentences or fewer.
- Separate paragraphs with a blank line.
- Mind how paragraphs stack up on one another. Each one should follow from the last and set up the next. If two in a row feel interchangeable, or the jump between them is jarring, reorder or rewrite until the piece reads as one continuous line of thought.

## Drafting, revision, and review

The following guide applies mainly to longer-form work like blog posts, docs, and whitepapers. Shorter pieces need less, but everything we publish still needs a human review before it gets published.

### Drafting

- Start by asking _What do I want to say?_ _Who is this for?_ and _What will they want to know?_ Answering these questions up front helps you define your thesis and point of view, which makes the writing more interesting, and keeps things focused on what's actually useful to the reader.
- Sketch an outline before you start writing, so the structure is deliberate rather than something you figure out as you go.
- Keep the scope under control. Any piece over 2,500 words is almost surely too long. If you can't say what you need to say within that range, consider breaking it up into multiple pieces.

### Revision

- First drafts aren't final drafts, they're starting points. Every first draft deserves at least one revision.
- When you're finished with the first draft, read it aloud. If it sounds like you, great. If it doesn't, revise the parts that don't until it does. Remember, [we're humans writing for humans](/voice/voice-and-tone/#who-we-write-for).
- After that, set it aside — at least for an hour, ideally overnight — then give it another read. Does it say what you want it to say? Does it deliver the value the user expects? If not, continue revising.
- Before reviewing, check your title, headings, and overall narrative progression. Sections should build on one another, and you should end with next steps and a clear (and contextually appropriate) call to action, not a "conclusion".

### Review

- Conduct a self-review with your agent of choice, asking it to critique the piece from the reader's point of view. The [brand MCP server](/mcp-server/) does this against the guidelines in this guide. [Add the MCP server](/mcp-server#configuration), paste your draft, and ask your agent for a review:

    ```text
    You're the reader I wrote this for: [describe your audience]. Read the draft
    below and tell me: What's the one thing I'm trying to say, and does it land?
    What questions does it leave unanswered? Where is it too long, too vague, or
    too generic? What did I overlook, and how could it be stronger? Use the Pulumi
    brand guidelines in your assessment.
    ```

- Ensure you've covered the SEO basics:
    - Use the keywords you're targeting in the URL slug, page title, H1, and H2s.
    - Use a descriptive, social media-friendly meta description.
    - Use descriptive link text, and be sure to include links to relevant internal and external resources.
    - Use well-labeled images.
- Request a human review. Every piece — docs, blogs, landing pages, social posts, even ad copy — must be reviewed by one of your fellow Pulumians before you can publish it. Longer-form works must be reviewed by a member of the Editorial Board.
- Address the feedback. If a human raises an issue, you must address and resolve the issue before publishing.

## See also

- [Guidelines for voice and tone](/voice/voice-and-tone/)
- [Rules for using generative AI](/guidelines/generative-ai/)