Best Practices and Common Patterns¶

Knowing the features of VIBE is the first step. Using them effectively is the next. Here are some best practices and patterns to help you build clean, robust, and maintainable templates.

1. Component vs. Definition: When to Use Which?¶

This is the most important architectural decision you'll make.

Use a definition when: You are defining a data structure—a standard set of fields that belong together. Think of it as a "data contract."
- Good examples: person, address, company, indemnity_properties.
Use a component when: You are creating a reusable piece of presentation—a chunk of .md or .docx content. Think of it as a "document building block."
- Good examples: signature_block, confidentiality_clause, title_page.

The best practice is to have your presentation-focused components declare which data definition they use.

2. Keep Logic Out of the Template¶

Your document template (.md or .docx) should be as "dumb" as possible. It should focus on layout and printing variables, not complex calculations.

Instead of this (in template.md):

Total: ${{ (base_price * (1 + tax_rate / 100)) * (1 - discount_rate / 100) }}

Do this (in config.yml):

total_price:
  type: computable
  compute: (base_price * (1 + tax_rate / 100)) * (1 - discount_rate / 100)

And this (in template.md):

Total: ${{ total_price }}

This makes your logic explicit, testable, and reusable.

3. Name Your Variables Clearly¶

Use descriptive, clear variable IDs.

Instead of: p_name, val, b
Prefer: project_name, contract_value, is_subsidiary

This makes both your config.yml and your templates much easier to read and understand months later.

4. Start Simple and Refactor¶

You don't need to design the perfect system from the start.

Begin by writing out the text in a single component.
As you identify variables, add them to the component's inputs.
If you find you're reusing the same set of inputs across multiple components, refactor them into a shared definition. This "start small, grow big" approach is much more manageable than trying to design everything upfront.

5. Use `safe_default` for a Better Preview Experience¶

Use the safe_default filter on variables that might not have an answer yet to keep previews readable, especially in optional sections. (See template-authoring-guide.md for details.)