How to contribute to Twig

Twig exists to teach PostHog. It does that through a fictional app people can use and a Playground that teaches within that app.

Twig, the fictional app

Twig is a vacation rental marketplace run by birds, for humans looking for a getaway. The birds are the hosts. Each has made a place their own (a nest of sorts) and now rents it to humans, whom they find a little odd.

• Guests: Humans who want to get away.
• Mission: Give humans a great place to stay.
• Products: Vacation rentals and an AI trip planner that helps guests find a stay.
• Tone: Warm, welcoming, and a little amused by humans. Each host has their own personality.

The Playground, Twig's learning experience

On Twig, you can browse the website as if it were any other website. Browse stays, plan a trip, book a rental.

You can also open the Playground and work through labs that reveal the PostHog instrumentation underneath those interactions.

The Playground marks Twig's PostHog product instrumentation with numbered dots called touchpoints. Each dot opens a lab about that instrumentation.

Lab events and AI responses are all teaching simulations designed to look and feel like a real product. This lets learners practice using a "real" product, inspect its PostHog data, and learn how to make product decisions in a controlled environment.

Add a Playground lab

The goal is for Twig to have all of PostHog's products instrumented. We're working on it.

Every time we instrument Twig with a PostHog product, we add a Playground lab for it. Adding a lab has two parts: instrument the product in Twig, then write and design the lesson that teaches it.

Part 1: Add the instrumentation

Before adding a lab, you'll need to add PostHog instrumentation:

1. Choose the PostHog product you want to add.
2. Find a natural place in Twig for the instrumentation. What would a human guest do there, and what would the PostHog product help Twig understand?
3. If Twig needs a new feature to make that possible, discuss the idea with #team-wizard-and-docs before adding it.
4. Open a PR to add the instrumentation in twig.com.

If you'd like to use an agent for the instrumentation, use this prompt:

Help me add PostHog product instrumentation to Twig.

Read the current PostHog/twig.com AGENTS.md, design guide, and nearby instrumentation. Then:
1. Find a natural guest action and explain what this product would help Twig understand. If it needs a new Twig feature, draft a proposal for #team-wizard-and-docs and pause for review.
2. Add the instrumentation using existing patterns. Keep guest-entered content and lab examples out of real PostHog events.
3. Verify the intended signal and identify where its Playground lab should open.

Show me the changes and checks before committing or opening a PR. Leave the lesson content for part 2.

Part 2: Write and design the lab

A lab teaches someone about the PostHog product through instrumentation. You can build a lab without having to write a corresponding pocket guide. Here's some tips to get started:

1. Sketch the learner's path. What will they do in Twig, what evidence will they inspect, and what should they understand by the end? Look at an existing lab for inspiration and see what other labs exist before inventing a new flow.
2. Build the reusable lesson in twig-components. Put the lab UI, example data, and simulated state there. Add a clickable example to its workbench.
3. Show the instrumentation in the Playground. Register the lab's ID and page in twig-components, then place Twig.com's existing Marker beside the action it teaches. This numbered touchpoint appears when the Playground is open – its number is page-specific, and its color comes from the PostHog product.
4. Try the full lab. Check that someone can find, complete, reset, and understand it on a narrow and wide screen. Explain what's simulated at the start, and ask the relevant product team to check the PostHog lesson.

Keep the vacation rental site's styling distinct from the Playground's lesson styling. Reuse existing components and follow the Twig site and shared component design guides. The Playground gets PostHog branding from the PostHog Brand Book.

The component integration guide covers how to release the shared package and update Twig.com when the lab is ready.

If you'd like to use an agent to write and build the lab, use this prompt:

Help me build a Twig Playground lab for [PostHog product] using the instrumentation at [Twig action].

Read the current PostHog/twig-components and PostHog/twig.com AGENTS.md files, existing labs, and design and integration guides. Then:
1. Outline what the learner will do, what evidence they'll inspect, and what they should understand at the end.
2. Write the lesson and build its reusable UI and local teaching data in twig-components. Reuse existing hosts, stays, and lab patterns. Add a clickable workbench example.
3. Register the lab and place the existing numbered Marker beside the relevant action in twig.com. Connect the lesson to the site's navigation and state.
4. Explain what's simulated, keep teaching data local, and use https://brand.posthog.com for Playground styling. Try the full flow at narrow and wide widths, including keyboard and reduced-motion states.

Show me the changes, checks, and package release steps before committing or opening a PR. Flag PostHog concepts that need product-team review.

How Twig fits into Learn

Twig and learn content are intertwined. While Twig is a great experience for those who learn by doing, it might not be ideal for someone who wants to read something.

So we integrated Twig into pocket guides as a canonical example app to drive stories! This is the split:

• Pocket guides drive the story, explanations, example data, and PostHog figures.
• Twig.com supplies the example product
• twig-components owns reusable Twig views, catalog data, styles, and lab UI that both experiences draw from

Where to make changes

The sites install published versions of twig-components, so a package change also needs a release and an update in whichever site uses it.