# Code Guides

## Patterns

### Inline Command In Instructional Copy

When to use:

- documentation or helper copy references a short command

Composition notes:

- wrap only the command itself in `Code`
- keep surrounding instructional text in `Text`

Trade-offs:

- easy to scan
- not suitable for multiline examples

```tsx
import { Code, Text } from '@vega-ui/react';

export default function InlineCommandInInstructionalCopy() {
  return (
    <Text asChild size={3}>
      <p style={{ maxWidth: '60ch' }}>
        If the dev server fails to start, delete <Code>node_modules</Code>, run <Code>pnpm install</Code> and try
        again.
      </p>
    </Text>
  );
}
```

### Inline Identifier

When to use:

- a field name, environment variable, or token needs emphasis

Composition notes:

- keep the identifier short
- avoid wrapping full explanatory sentences in `Code`

Trade-offs:

- clarifies machine-readable names
- can become noisy if overused

```tsx
import { Code, Text } from '@vega-ui/react';

const variables = [
  { name: 'DATABASE_URL', description: 'Postgres connection string for the primary database.' },
  { name: 'SENTRY_DSN', description: 'Error reporting endpoint. Leave empty to disable reporting.' },
  { name: 'VEGA_THEME', description: 'Forces the initial theme: light or dark.' },
];

export default function InlineIdentifier() {
  return (
    <dl style={{ display: 'grid', gap: 'var(--spacing-8)', width: '100%', margin: 0 }}>
      {variables.map((variable) => (
        <div key={variable.name} style={{ display: 'grid', gap: 'var(--spacing-2)' }}>
          <dt><Code size={2}>{variable.name}</Code></dt>
          <Text asChild size={2} style={{ color: 'var(--label-secondary)' }}>
            <dd style={{ margin: 0 }}>{variable.description}</dd>
          </Text>
        </div>
      ))}
    </dl>
  );
}
```

### Mixed Prose And Code

When to use:

- body copy contains one or two technical fragments

Composition notes:

- let `Text` handle the paragraph
- use `Code` only for the fragments with code semantics

Trade-offs:

- preserves readability
- long technical passages should move to a block example

```tsx
import { Code, Text } from '@vega-ui/react';

export default function MixedProseAndCode() {
  return (
    <Text asChild size={3}>
      <p style={{ maxWidth: '60ch' }}>
        The form sends the selected plan as <Code>plan_id</Code>. Read it on the server with{' '}
        <Code>formData.get('plan_id')</Code>; an empty value means the user kept the free tier.
      </p>
    </Text>
  );
}
```

## Comparison

### Quick Decision Rule

Use `Code` for inline commands, identifiers, and tokens. Use `Text` for prose and a dedicated code block solution for larger snippets.

### `Code` vs `Text`

- Use `Code` for inline code semantics.
- Use `Text` for prose.

### `Code` vs `Badge`

- Use `Code` for code-like identifiers or commands.
- Use `Badge` for status and categorization.

### `Code` vs fenced code blocks

- Use `Code` for short inline fragments.
- Use fenced markdown or a dedicated block component for multiline examples.

### Choose This Component When

- the content is a short code token, command, or identifier
- semantic `<code>` matters

### Do Not Choose This Component When

- the content is a paragraph
- the snippet is multiline or needs syntax highlighting

## Troubleshooting

### The Inline Code Snippet Wraps In Awkward Places

#### Symptom

Long commands or paths wrap and become harder to scan.

#### Likely Cause

`Code` is intended for inline snippets and allows wrapping to avoid overflow.

#### How To Verify

- inspect the content length
- check whether the snippet would read better as a block

#### Fix

Use a dedicated multiline code example when the content stops being truly inline.

### The Snippet Looks Like A Status Pill Instead Of Code

#### Symptom

The UI treats code snippets as if they were badges or tags.

#### Likely Cause

`Code` is being reused for generic highlighted labels.

#### How To Verify

- inspect whether the content is actually a command, token, or identifier

#### Fix

Switch to `Badge`, `Text`, or another semantic primitive when the content is not code.

### Custom Overrides Reduce Contrast

#### Symptom

Inline code becomes hard to read against its background.

#### Likely Cause

Theme or local overrides changed the fill or text color pairing.

#### How To Verify

- compare the rendered foreground and background tokens
- test readability in both light and dark themes

#### Fix

Prefer the default `--fills-secondary` and `--label-secondary` pairing or retest contrast when overriding them.