Skip to content

docs: clarify Replica onboarding paths #100

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nshki merged 9 commits into from
Oct 28, 2026
+829 −176
Merged

docs: clarify Replica onboarding paths #100

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
6d4bb18
docs: clarify Replica onboarding paths
Oct 23, 2026
8375d99
Enhance prototype sharing instructions
cmcnally Oct 23, 2026
94d6a2c
Enhance documentation for running Hub container
cmcnally Oct 23, 2026
39fff0c
Merge main into cmcnally-replica-onboarding
cmcnally Oct 23, 2026
a2ca61b
Improve formatting of getting started guide
yaili Oct 23, 2026
e925f8c
docs: distinguish onboarding steps from commentary
cmcnally Oct 27, 2026
75cc7d7
docs: reconcile onboarding with starter updates
cmcnally Oct 27, 2026
4bac279
docs: explain starter choices in plain language
cmcnally Oct 27, 2026
a7724f7
Merge branch 'main' into cmcnally-replica-onboarding
nshki Oct 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 43 additions & 18 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,40 +2,49 @@
<img src=".github/assets/replica-readme-banner.png" alt="Replica" width="1200">
</p>

# Replica: An open-source prototyping tool
# Replica: An open-source AI prototyping tool

Replica helps your entire product team prototype with your design system. It's an open-source tool that uses AI to turn ideas into interactive prototypes, guided by your components, patterns, and documentation.
Turn ideas into interactive prototypes using your own design system. Replica is an open-source, AI-powered prototyping tool created by GitHub Design for designers, product managers, and engineers.

Designers create and approve the guidance. People across design, product, and engineering can then describe a change in the GitHub Copilot app, try the result, and refine it with their team and users.
Designers define the guidance using your team's components, patterns, and documentation. Anyone on the product team can then use natural language in the GitHub Copilot app to create and refine prototypes that reflect how your product works. You can start locally without a server, domain, or Replica Hub.

Use prototypes to test assumptions and work through questions together. Your team still decides what should ship and how to build it.
## What can you do with Replica?

Replica is MIT-licensed. You can prototype locally without a server or set up Replica Hub for hosting and commenting.
- **Prototype with your design system:** Use your existing components, patterns, and approved guidance to shape AI-generated prototypes.
- **Turn ideas into interactive experiences:** Describe what you want to explore, then see, test, and refine the result beside your Copilot conversation.
- **Collaborate and gather feedback:** Publish prototypes to an optional Replica Hub hosted by your organization, where teammates can explore them and leave comments.
- **Adapt Replica to your team:** Customize the open-source tooling and guidance to fit your product and workflows.

## Try Replica
## See Replica in action

Explore Replica before setting anything up.
https://github.com/user-attachments/assets/36547180-aca9-43cc-8931-b538f0883885

[<img width="960" height="540" alt="Watch the Replica introduction on YouTube" src="https://github.com/user-attachments/assets/ca887541-e5b7-4634-a9e0-c6eec673b243" />](https://www.youtube.com/watch?v=J2Z28CwIfsA)
<details>
<summary>Demo video music credits</summary>

*Music: [“Electrodoodle”](https://incompetech.com/music/royalty-free/index.html?isrc=USUAN1200079) by Kevin MacLeod ([incompetech.com](http://incompetech.com/)), licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). Excerpted, level-adjusted and faded for this video.*

</details>

[Watch the Replica introduction on YouTube](https://www.youtube.com/watch?v=J2Z28CwIfsA).

## Get started with Replica

Replica has four parts:
You don't need to set up everything at once. Start with the guide that matches your next step: trying Replica locally, setting up hosting, or joining your team's existing repository and Hub.

| Part | What it does |
| Your goal | Start here |
| --- | --- |
| **Starters** | Create a local prototype project from your choice of app, with shared agent skills. |
| **Copilot canvas extension** | Opens your local prototype alongside your Copilot conversation. |
| **Replica Hub (optional)** | Hosts published prototypes so your team can try them and leave comments. |
| **GitHub build action** | Builds prototypes for publishing to Hub. It is not needed for local prototyping. |
| Start or continue prototyping locally | [Create your first local prototype](docs/local-prototyping.md). Use the starter or an existing prototype repository, add team guidance, and build something useful. No Hub required. |
| Set up hosting and comments for your team | [Set up shared hosting and team feedback](docs/prototype-environment.md). Check hosting needs early, build with your team's design guidance, and connect Hub when it is ready. |
| Join a team with a repository and Hub already in use | [Join your team's Replica environment](docs/getting-started.md). Use its existing setup to create, publish, and review a prototype. |

**Ready to make prototypes?** Follow [Get started with Replica](docs/getting-started.md) to install the GitHub Copilot app, add your team's prototyping repository, install the canvas, and create your first prototype. It also covers connecting to Hub, publishing, sharing and commenting, and adding controls.
If hosting is blocked, you can work locally and connect the same repository later.
Comment on lines 31 to +41

@arniebradfo arniebradfo Oct 28, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@cmcnally, Sorry I was a bit late on this - its already merged. There was just one update that I would make. You could @copilot to do this if you want to.

I feel like the table is to much format, so I would opt for bolded first line CTAs. And also adding some kind of copy-pastable prompt so you can just have an agent do all this stuff would also be beneficial?

Get started with Replica

You don't need to set up everything at once. Start with the guide that matches your next step: trying Replica locally, setting up hosting, or joining your team's existing repository and Hub.

Create your first local prototype. Use a starter template or an existing prototype repository, add team guidance, and build something useful. No Hub required. Quick, easy, low-commitment, just to try it out.

Set up shared hosting and team feedback. Check hosting needs early, build with your team's design guidance, and connect Hub when it is ready.

Join your team's Replica environment. Use its existing setup to create, publish, and review a prototype.

If hosting is blocked, you can work locally and connect the same repository later.

Have Copilot help you get started

Paste the following prompt into the GitHub Copilot app to have Copilot handle this for you:

Please read the GitHub Replica README.md https://github.com/github/replica/. Ask which getting-started path fits my needs, then guide me through it step by step.


**Creating a prototyping repository?** Choose **Minimal**, a small React app with no component library, or **CoreAI Sandbox**, a React Router app with CoreAI components and a Foundry-style shell. Point your agent at [prototype repository setup](docs/prototype-repository-setup.md) to select an app, create the repository and verify its local preview. Local prototyping needs no Hub.
### What you need

**Setting up Replica for your organization?** Follow [environment setup](docs/prototype-environment.md) to add shared guidance and starting pages, deploy Hub, and connect publishing and team feedback. Your organization deploys and runs Hub on its own infrastructure. GitHub doesn't host it.
**Local prototyping** uses the [GitHub Copilot app](https://github.com/features/ai/github-app), Git, and Node.js with npm on macOS or Linux. Each walkthrough covers installation and the repository's requirements.

**How did setup go?** [Share your feedback](https://survey.alchemer.com/s3/9055055/Replica-feedback). It helps us make Replica easier to start.
**Hosted publishing and comments** also need a Linux server, a dedicated domain with wildcard DNS and HTTPS, network access, and GitHub permissions and approvals. The hosting guide starts with these checks.

### Copilot requirements

Expand All @@ -44,6 +53,22 @@ Replica has four parts:
- **Your own provider:** this option is in public preview and subject to change. The provider's costs and terms apply.
- **Viewing and review:** viewing a finished prototype or reviewing it in Hub does not require a Copilot subscription.

## What's included

| Part | What it does |
| --- | --- |
| **Starters** | Ready-made apps to build your prototype from, with shared skills for Copilot. |
| **Replica plugin** | Adds the Replica canvas to Copilot, showing your running prototype beside your conversation. |
| **Replica Hub (optional)** | Hosts published prototypes so your team can try them and leave comments. |
| **GitHub build action** | Builds prototypes for publishing to Hub. It is not needed for local prototyping. |

For a new repository, choose a starter:

- **Minimal:** A small example app to adapt to your own design system.
- **CoreAI Sandbox:** An app with an existing navigation layout and prebuilt interface elements, such as buttons and menus, from Microsoft's CoreAI design system.

Agents creating or adapting repositories should follow [prototype repository setup](docs/prototype-repository-setup.md).

## Data and privacy

Your organization operates its Hub and controls its configuration. Hub records publishing and review activity in its own database and retains those activity events for 90 days. Exporting them to Segment, Mixpanel, or a custom HTTPS endpoint requires configuration by a repository administrator. Replica does not automatically send those activity records to GitHub.
Expand Down
8 changes: 5 additions & 3 deletions docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,13 @@ These guides apply across the Replica monorepo. Start with [Contributing](../CON

## Prototype guides

[Get started with Replica](getting-started.md) walks new users through installing Copilot, adding their team's repository and canvas, creating and publishing a prototype, sharing feedback, and adding controls.
[Create your first local prototype](local-prototyping.md) walks you through the starter and canvas without Hub, then adding approved team guidance and building a useful prototype.

[Set up a prototype repository](prototype-repository-setup.md) guides agents through new or existing repository targets, starter installation, the fresh-session handoff, and a verified local preview before optional product guidance or team setup.
[Set up shared hosting and team feedback](prototype-environment.md) starts with hosting requirements, then team guidance and a useful local prototype. Teams can arrange hosting alongside that work, then connect Hub, publish, and invite teammates.

[Set up and configure your prototype environment](prototype-environment.md) walks environment maintainers through creating the shared repository, adding design-system guidance and templates, deploying Hub with Docker, connecting builds, and inviting the team.
[Join your team's Replica environment](getting-started.md) walks authors through using an existing team repository and Hub, creating and publishing a prototype, sharing feedback, and adding controls.

[Set up a prototype repository](prototype-repository-setup.md) is the supporting agent guide for new or existing repository targets, starter installation, session handoff, and verification. People following the walkthroughs above do not need to follow its agent instructions.

## Shared conventions

Expand Down
Loading
Loading