Skip to content

Commit 9ffd7cf

Browse files
rise-erpeldingrise-erpelding
authored
docs: add stackblitz how-to documentation (#6016)
1 parent 1dd0205 commit 9ffd7cf

File tree

3 files changed

+108
-0
lines changed

3 files changed

+108
-0
lines changed

‎CONTRIBUTOR-DOCS/01_contributor-guides/10_using-stackblitz.md‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
<!-- Generated breadcrumbs - DO NOT EDIT -->
2+
3+
[CONTRIBUTOR-DOCS](../README.md) / [Contributor guides](README.md) / Maintaining StackBlitz examples for Spectrum Web Components
4+
5+
<!-- Document title (editable) -->
6+
7+
# Maintaining StackBlitz examples for Spectrum Web Components
8+
9+
<!-- Generated TOC - DO NOT EDIT -->
10+
11+
<details open>
12+
<summary><strong>In this doc</strong></summary>
13+
14+
- [StackBlitz terminology](#stackblitz-terminology)
15+
- [Access prerequisites](#access-prerequisites)
16+
- [Adding a new project](#adding-a-new-project)
17+
- [Adding an existing project to the collection](#adding-an-existing-project-to-the-collection)
18+
- [Step 1: Locate the project in the SWC-Team workspace](#step-1-locate-the-project-in-the-swc-team-workspace)
19+
- [Step 2: Fork the project (if needed)](#step-2-fork-the-project-if-needed)
20+
- [Step 3: Add the project to the collection](#step-3-add-the-project-to-the-collection)
21+
- [Naming conventions](#naming-conventions)
22+
- [Replacing an existing project](#replacing-an-existing-project)
23+
24+
</details>
25+
26+
<!-- Document content (editable) -->
27+
28+
This document explains how to update and maintain StackBlitz examples for our library, including how to add new examples and manage existing ones within our shared collection.
29+
30+
## StackBlitz terminology
31+
32+
- **Project**: An individual StackBlitz example. Each project has its own URL and functions independently.
33+
- **Collection**: A curated group of projects. Collections are used to organize related examples.
34+
- **Workspace**: A workspace represents an account context in StackBlitz. You can have:
35+
- A **personal workspace** (your own account)
36+
- One or more **team workspaces** (such as **SWC-Team**)
37+
38+
Projects live inside a specific workspace. Only projects that exist in the **SWC-Team workspace** can be added to the **“Spectrum Web Components”** collection, which is the collection of example projects demonstrating correct usage of our web components in a realistic environment that we maintain.
39+
40+
## Access prerequisites
41+
42+
To add or manage projects in the Spectrum Web Components collection, you must have access to the **SWC-Team** StackBlitz account.
43+
44+
1. Create a StackBlitz account if you do not already have one.
45+
2. Ask for team access from a StackBlitz team admin.
46+
3. Be prepared to share your GitHub username and/or email address. You'll need to accept the invitation via email in order to have the SWC-Team workspace appear on your account.
47+
48+
When working with StackBlitz projects for Spectrum Web Components, it's important to ensure you are operating within the **SWC-Team workspace**, not your personal workspace. This applies when creating new projects, forking existing projects, and managing which projects appear in the collection.
49+
50+
## Adding a new project
51+
52+
To add a brand-new example to the collection:
53+
54+
1. Ensure you are logged into StackBlitz and using the **SWC-Team** workspace.
55+
2. Create a new project from the SWC-Team workspace.
56+
3. Once created, add the project to the **Spectrum Web Components** collection.
57+
58+
Follow the naming conventions outlined below before adding the project to the collection.
59+
60+
## Adding an existing project to the collection
61+
62+
In many cases, the project you want to add already exists.
63+
64+
### Step 1: Locate the project in the SWC-Team workspace
65+
66+
1. Go to the StackBlitz dashboard.
67+
2. Use the workspace dropdown to switch from your personal workspace to **SWC-Team**.
68+
3. Check whether the project appears in the SWC-Team project list.
69+
70+
### Step 2: Fork the project (if needed)
71+
72+
If the project does **not** appear in the SWC-Team workspace:
73+
74+
1. Open the project using its StackBlitz URL.
75+
2. Click the **Fork** button in the upper-left corner of the editor.
76+
3. In the fork dialog, open the destination dropdown (chevron or “Fork to…” control) and choose **“Fork to… SWC-Team.”**
77+
4. Confirm that the forked project now appears in the SWC-Team workspace.
78+
79+
### Step 3: Add the project to the collection
80+
81+
1. In the SWC-Team workspace project list (dashboard), locate the project.
82+
2. Click the **three-dot menu** (⋮) on the right side of the project row to open the actions menu.
83+
3. Select **“Add to collection.”**
84+
4. Choose **“Spectrum Web Components”** (currently our only collection).
85+
86+
You can verify the result by visiting the [Spectrum Web Components collection dashboard](https://stackblitz.com/orgs/custom/SWC-Team/collections/spectrum-web-components).
87+
88+
## Naming conventions
89+
90+
All projects added to the collection should follow the existing naming pattern (this should be something like `swc-component-name`), for example:
91+
92+
- `swc-alert-banner`
93+
- `swc-button`
94+
- `swc-modal`
95+
96+
Consistent naming helps keep the collection easy to scan and maintain.
97+
98+
## Replacing an existing project
99+
100+
If you are adding a new project intended to replace an existing example for the same component:
101+
102+
1. Add the new project to the **Spectrum Web Components** collection.
103+
2. Remove the old project from the collection.
104+
3. Optionally, remove the old project entirely from the SWC-Team projects list if it is no longer needed.
105+
106+
This ensures the collection always reflects the most current and recommended examples.

‎CONTRIBUTOR-DOCS/01_contributor-guides/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@
2121
- [AI agent instructions](07_authoring-contributor-docs/01_ai-agent-instructions.md)
2222
- [Patching dependencies](08_patching-dependencies.md)
2323
- [Accessibility testing](09_accessibility-testing.md)
24+
- [Maintaining StackBlitz examples for Spectrum Web Components](10_using-stackblitz.md)
2425

2526
</details>
2627

‎CONTRIBUTOR-DOCS/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@
2626
- [Authoring contributor docs](01_contributor-guides/07_authoring-contributor-docs/README.md)
2727
- [Patching dependencies](01_contributor-guides/08_patching-dependencies.md)
2828
- [Accessibility testing](01_contributor-guides/09_accessibility-testing.md)
29+
- [Maintaining StackBlitz examples for Spectrum Web Components](01_contributor-guides/10_using-stackblitz.md)
2930
- [Style guide](02_style-guide/README.md)
3031
- [2nd-Gen CSS](02_style-guide/01_css/README.md)
3132
- [Project planning](03_project-planning/README.md)

0 commit comments

Comments
 (0)