# Consistent Placeholders in Samples

**MUST** · **ID:** `content-consistent-placeholders` · **Category:** content
**Source:** [Vercel](https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)
**Interactive version:** https://ui-guides-agent-rules.netlify.app/principles/content-consistent-placeholders

> MUST: Use one loud, obviously-fake placeholder convention across all code samples — `YOUR_API_TOKEN_HERE` for strings, `0123456789` for numbers — never a mix of `<your-token>` / `xxx` / `abc123` / `[INSERT KEY]`. (This is about fill-me-in tokens in docs, not the HTML `placeholder` attribute.)

Use one placeholder convention across every code sample: YOUR_API_TOKEN_HERE for strings, 0123456789 for numbers

This is about the fill-me-in tokens inside documentation and code samples, not the HTML placeholder attribute on an input — that one is covered by the separate rule against using a placeholder as a label or a value. When a snippet mixes <your-token>, xxx, abc123, and [INSERT KEY], the reader cannot tell which strings are literal and which are theirs, so they paste a sample verbatim and get a 401. A single loud, obviously-fake convention — screaming snake case for strings, a monotone digit run for numbers — is unmistakably a slot, greppable, and safe to search-and-replace across a whole page.

## Bad — do not do this

`content-consistent-placeholders-bad`

```tsx
// Fill-me-in tokens inside a docs code sample — not the <input placeholder> attribute.
const PLACEHOLDER_PATTERN = /(<your-token>|xxx|abc123|\[INSERT KEY\]|123|0000)/g;

const SNIPPET = [
  'export API_TOKEN=<your-token>',
  'export TEAM_ID=abc123',
  '',
  'curl https://api.example.com/v1/projects/123 \\',
  '  -H "Authorization: Bearer xxx" \\',
  '  -H "X-Team: [INSERT KEY]" \\',
  '  -d \'{ "retries": 0000 }\'',
];

const CONVENTIONS = new Set(
  SNIPPET.flatMap((line) => line.match(PLACEHOLDER_PATTERN) ?? []),
);

function Line({ text }: { text: string }) {
  const parts = text.split(PLACEHOLDER_PATTERN);
  return (
    <div className="whitespace-pre-wrap font-mono text-xs text-foreground">
      {parts.map((part, i) =>
        i % 2 === 1 ? (
          <mark key={i} className="rounded bg-error/15 px-1 font-semibold text-error">
            {part}
          </mark>
        ) : (
          <span key={i}>{part}</span>
        ),
      )}
      {text === '' && ' '}
    </div>
  );
}

export function ConsistentPlaceholdersBad() {
  return (
    <div className="w-full max-w-md space-y-3">
      <div className="space-y-1 rounded-lg border border-border bg-muted p-4">
        {SNIPPET.map((line, i) => (
          <Line key={i} text={line} />
        ))}
      </div>

      <div className="flex flex-wrap items-center gap-2 text-xs">
        <span className="rounded border border-border bg-muted px-2 py-1 font-mono text-error">
          {CONVENTIONS.size} placeholder conventions in 1 snippet
        </span>
      </div>

      <p className="text-xs text-error">
        Which of these are literals? <code className="rounded bg-muted px-1 font-mono">abc123</code>{' '}
        and <code className="rounded bg-muted px-1 font-mono">123</code> look like real values, so
        they get pasted as-is and the request 401s. Nothing here is greppable.
      </p>
    </div>
  );
}
```

## Good — do this

`content-consistent-placeholders-good`

```tsx
// One convention: SCREAMING_SNAKE for strings, a monotone digit run for numbers.
const PLACEHOLDER_PATTERN = /(YOUR_API_TOKEN_HERE|YOUR_TEAM_ID_HERE|0123456789)/g;

const SNIPPET = [
  'export API_TOKEN=YOUR_API_TOKEN_HERE',
  'export TEAM_ID=YOUR_TEAM_ID_HERE',
  '',
  'curl https://api.example.com/v1/projects/0123456789 \\',
  '  -H "Authorization: Bearer YOUR_API_TOKEN_HERE" \\',
  '  -H "X-Team: YOUR_TEAM_ID_HERE" \\',
  '  -d \'{ "retries": 3 }\'',
];

function Line({ text }: { text: string }) {
  const parts = text.split(PLACEHOLDER_PATTERN);
  return (
    <div className="whitespace-pre-wrap font-mono text-xs text-foreground">
      {parts.map((part, i) =>
        i % 2 === 1 ? (
          <mark key={i} className="rounded bg-success/15 px-1 font-semibold text-success">
            {part}
          </mark>
        ) : (
          <span key={i}>{part}</span>
        ),
      )}
      {text === '' && ' '}
    </div>
  );
}

export function ConsistentPlaceholdersGood() {
  return (
    <div className="w-full max-w-md space-y-3">
      <div className="space-y-1 rounded-lg border border-border bg-muted p-4">
        {SNIPPET.map((line, i) => (
          <Line key={i} text={line} />
        ))}
      </div>

      <div className="flex flex-wrap items-center gap-2 text-xs">
        <span className="rounded border border-border bg-muted px-2 py-1 font-mono text-success">
          1 placeholder convention · strings: NAME_HERE · numbers: 0123456789
        </span>
      </div>

      <p className="text-xs text-success">
        Every slot is loud, obviously fake, and greppable. <code className="rounded bg-card px-1 font-mono">3</code>{' '}
        is plainly a literal because it does not look like a placeholder, and a single
        search-and-replace fills the whole page in.
      </p>
    </div>
  );
}
```

## References

- [Vercel Web Interface Guidelines](https://github.com/vercel-labs/web-interface-guidelines)
- [Google Style: Placeholders](https://developers.google.com/style/placeholders)