From 8e461253f3aa5bab2333ec75c0ef391139abb4ec Mon Sep 17 00:00:00 2001 From: Nikki Massaro Date: Tue, 9 Dec 2025 09:46:00 -0500 Subject: [PATCH 01/10] docs(contributor-guides): mrigrated contributor guides --- .../accessibility-testing.mdx | 432 ++++++++++++++++++ .../ai-agent-instructions.mdx | 284 ++++++++++++ .../authoring-contributor-docs.mdx | 137 ++++++ .../contributor-guides/contributor-guides.mdx | 3 + .../contributor-guides/getting-involved.mdx | 70 +++ .../making-a-pull-request.mdx | 176 +++++++ .../participating-in-pr-reviews.mdx | 97 ++++ .../patching-dependencies.mdx | 59 +++ .../contributor-guides/releasing-swc.mdx | 165 +++++++ .../using-the-issue-tracker.mdx | 49 ++ .../working-in-the-swc-repo.mdx | 124 +++++ 2nd-gen/packages/swc/.storybook/preview.ts | 11 + 12 files changed, 1607 insertions(+) create mode 100644 2nd-gen/packages/swc/.storybook/guides/contributor-guides/accessibility-testing.mdx create mode 100644 2nd-gen/packages/swc/.storybook/guides/contributor-guides/ai-agent-instructions.mdx create mode 100644 2nd-gen/packages/swc/.storybook/guides/contributor-guides/authoring-contributor-docs.mdx create mode 100644 2nd-gen/packages/swc/.storybook/guides/contributor-guides/contributor-guides.mdx create mode 100644 2nd-gen/packages/swc/.storybook/guides/contributor-guides/getting-involved.mdx create mode 100644 2nd-gen/packages/swc/.storybook/guides/contributor-guides/making-a-pull-request.mdx create mode 100644 2nd-gen/packages/swc/.storybook/guides/contributor-guides/participating-in-pr-reviews.mdx create mode 100644 2nd-gen/packages/swc/.storybook/guides/contributor-guides/patching-dependencies.mdx create mode 100644 2nd-gen/packages/swc/.storybook/guides/contributor-guides/releasing-swc.mdx create mode 100644 2nd-gen/packages/swc/.storybook/guides/contributor-guides/using-the-issue-tracker.mdx create mode 100644 2nd-gen/packages/swc/.storybook/guides/contributor-guides/working-in-the-swc-repo.mdx diff --git a/2nd-gen/packages/swc/.storybook/guides/contributor-guides/accessibility-testing.mdx b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/accessibility-testing.mdx new file mode 100644 index 0000000000..e7a8e1b469 --- /dev/null +++ b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/accessibility-testing.mdx @@ -0,0 +1,432 @@ +# Accessibility testing + +## About this guide + +This guide covers automated accessibility testing for Spectrum Web Components using Playwright. You'll learn how to write, run, and maintain accessibility tests for both 1st-gen and 2nd-gen components. + +## Quick start + +```bash +# From project root, 1st-gen, or 2nd-gen directory +yarn test:a11y # Run all tests (both generations) +yarn test:a11y:1st # Run only 1st generation tests +yarn test:a11y:2nd # Run only 2nd generation tests +yarn test:a11y:ui # Interactive UI mode (great for debugging) +``` + +Tests automatically start the required Storybook instances and run in Chromium. + +## What we test + +Two complementary approaches: + +### 1. ARIA snapshots + +Captures the accessibility tree structure and compares it to a baseline. Detects unintentional changes to: + +- ARIA roles +- ARIA attributes +- Text content +- Accessibility tree structure + +**Coverage:** ~40% of accessibility issues + +### 2. aXe-core validation + +Automatically checks ~50+ WCAG 2.0/2.1 Level A/AA rules: + +- Color contrast +- Keyboard navigation +- ARIA validity +- Semantic HTML +- Focus management + +**Coverage:** ~50% of accessibility issues + +**Together:** These catch the most common accessibility issues early in development. + +## Adding tests to a component + +### 1st generation components + +Create `.a11y.spec.ts` in your component's `test/` directory: + +```typescript +// 1st-gen/packages/badge/test/badge.a11y.spec.ts + +import { expect, test } from '@playwright/test'; +import AxeBuilder from '@axe-core/playwright'; +import { gotoStory } from '../../../test/a11y-helpers.js'; + +test.describe('Badge - ARIA Snapshots', () => { + test('should have correct accessibility tree', async ({ page }) => { + const badge = await gotoStory(page, 'badge--default', 'sp-badge'); + await expect(badge).toMatchAriaSnapshot(); + }); +}); + +test.describe('Badge - aXe Validation', () => { + test('should not have accessibility violations', async ({ page }) => { + await gotoStory(page, 'badge--default', 'sp-badge'); + + const results = await new AxeBuilder({ page }) + .withTags(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa']) + .analyze(); + + expect(results.violations).toEqual([]); + }); +}); +``` + +**Key details:** + +- Story ID: `'badge--default'` (check Storybook URL at `localhost:8080`) +- Element name: `'sp-badge'` (the custom element tag name) +- Helper import: `'../../../test/a11y-helpers.js'` (1st-gen test helpers) + +### 2nd generation components + +Same pattern, different details: + +```typescript +// 2nd-gen/packages/swc/components/badge/test/badge.a11y.spec.ts + +import { expect, test } from '@playwright/test'; +import AxeBuilder from '@axe-core/playwright'; +import { gotoStory } from '../../../utils/a11y-helpers.js'; + +test.describe('Badge - ARIA Snapshots', () => { + test('should have correct accessibility tree', async ({ page }) => { + const badge = await gotoStory( + page, + 'components-badge--default', // 2nd gen story ID format + 'swc-badge' // 2nd gen element name + ); + await expect(badge).toMatchAriaSnapshot(); + }); +}); + +test.describe('Badge - aXe Validation', () => { + test('should not have accessibility violations', async ({ page }) => { + await gotoStory(page, 'components-badge--default', 'swc-badge'); + + const results = await new AxeBuilder({ page }) + .withTags(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa']) + .analyze(); + + expect(results.violations).toEqual([]); + }); +}); +``` + +**Key differences:** + +- Story ID: `'components-badge--default'` (check Storybook URL at `localhost:6006`) +- Element name: `'swc-badge'` (instead of `sp-badge`) +- Helper import: `'../../../utils/a11y-helpers.js'` (from swc utils directory) +- Storybook port: 6006 (vs 8080 for 1st gen) - automatically handled by Playwright + +## Test helper reference + +Test helpers are available in each generation: + +- 1st gen: `1st-gen/test/a11y-helpers.ts` +- 2nd gen: `2nd-gen/packages/swc/utils/a11y-helpers.ts` + +### `gotoStory(page, storyId, elementSelector)` + +Navigate to a Storybook story and wait deterministically for the component to be ready. + +**Parameters:** + +- `page`: Playwright Page object +- `storyId`: Storybook story ID (from the URL) +- `elementSelector`: CSS selector for the component (usually the custom element name) + +**Returns:** Playwright `Locator` for the component + +**Example:** + +```typescript +// Wait for component to be fully ready +const badge = await gotoStory(page, 'badge--default', 'sp-badge'); + +// Now safe to test +await expect(badge).toMatchAriaSnapshot(); +``` + +**How it works:** + +1. Navigates to story URL +2. Waits for custom element definition (`customElements.whenDefined`) +3. Waits for Storybook to render content +4. Waits for element visibility +5. Waits for Web Component upgrade + +This eliminates flaky tests caused by testing components before they're ready. + +### `waitForCustomElement(page, tagName)` + +Wait for a custom element to be defined. + +```typescript +await waitForCustomElement(page, 'sp-badge'); +``` + +### `waitForStoryReady(page, elementSelector)` + +Wait for Storybook story to render and component to be visible. + +```typescript +const element = await waitForStoryReady(page, 'sp-badge'); +``` + +## Finding story IDs + +Open Storybook and navigate to your component. The story ID is in the URL: + +**1st gen** (`localhost:8080`): + +``` +http://localhost:8080/?path=/story/badge--default + ^^^^^^^^^^^^^ + Story ID +``` + +**2nd gen** (`localhost:6006`): + +``` +http://localhost:6006/?path=/story/components-badge--default + ^^^^^^^^^^^^^^^^^^^^^^^^ + Story ID +``` + +## Running tests + +### From project root + +```bash +yarn test:a11y # All tests (both generations) +yarn test:a11y:1st # Only 1st generation +yarn test:a11y:2nd # Only 2nd generation +yarn test:a11y:ui # Interactive UI mode +``` + +### From generation directories + +```bash +# From 1st-gen +cd 1st-gen +yarn test:a11y # All tests (both generations) +yarn test:a11y badge # Specific component +yarn test:a11y:1st # Only 1st gen +yarn test:a11y:2nd # Only 2nd gen +yarn test:a11y badge --update-snapshots # Update ARIA baselines +yarn test:a11y:ui # UI mode + +# From 2nd-gen (new home for shared infrastructure) +cd 2nd-gen +yarn test:a11y # All tests (both generations) +yarn test:a11y:1st # Only 1st gen +yarn test:a11y:2nd # Only 2nd gen +yarn test:a11y:ui # UI mode +``` + +### Updating snapshots + +When you intentionally change a component's accessibility tree: + +```bash +yarn test:a11y --update-snapshots +``` + +This updates the baseline ARIA snapshots in `.a11y.spec.ts-snapshots/`. + +## Test results + +### ARIA snapshot files + +ARIA snapshots are saved as YAML files in `-snapshots/`: + +```yaml +# Example: Badge default variant +- text: 'Default' +``` + +These files are: + +- ✅ **Committed to git** - They're the baseline +- ✅ **Updated with** `--update-snapshots` +- ✅ **Compared on every run** - Detect regressions + +**When snapshots fail:** + +1. Review the diff in the test output +2. If the change is intentional, update snapshots +3. If unexpected, fix the component + +### aXe violations + +When aXe finds violations, it reports: + +- **What's wrong** - Rule that failed +- **Where it is** - Element selector +- **How to fix it** - Link to documentation + +**Example:** + +``` +Expected: [] +Received: [ + { + id: "color-contrast", + impact: "serious", + description: "Ensures the contrast between foreground and background colors meets WCAG 2 AA", + help: "Elements must have sufficient color contrast", + helpUrl: "https://dequeuniversity.com/rules/axe/4.4/color-contrast", + nodes: [...] + } +] +``` + +## Best practices + +### Test coverage + +**Do test:** + +- Default state +- All semantic variants (positive, negative, info, etc.) +- Size variants (s, m, l, xl) +- Interactive states (disabled, selected, focused) +- With different content (text, icons, numbers) + +**Don't need to test:** + +- Every color combination +- Every possible prop combination +- Styling details (use visual regression for that) + +### When tests fail + +**ARIA snapshot failures:** + +1. Review the diff - is this intentional? +2. If yes: Update snapshots with `--update-snapshots` +3. If no: Fix the component to restore expected structure + +**aXe violations:** + +1. Read the violation message and linked docs +2. Fix the component to address the issue +3. Re-run tests to verify + +**Test timeout/hanging:** + +- Check that Storybook is running +- Verify the story ID is correct +- Ensure the element selector matches + +### Tips + +- **Start with ARIA snapshots** - They're fast to write and catch structural changes +- **Add aXe tests for critical paths** - Form controls, navigation, overlays +- **Use UI mode for debugging** - `yarn test:a11y:ui` shows live browser +- **Test variants separately** - One test per story keeps failures focused +- **Commit ARIA snapshots** - They're living documentation + +## Configuration + +### Playwright config + +`playwright.a11y.config.ts` (at the root) defines two projects: + +```typescript +projects: [ + { + name: '1st-gen', + testMatch: '**/packages/*/test/**/*.a11y.spec.ts', + use: { baseURL: 'http://localhost:8080' }, + }, + { + name: '2nd-gen', + testMatch: '**/packages/swc/components/*/test/**/*.a11y.spec.ts', + use: { baseURL: 'http://localhost:6006' }, + }, +]; +``` + +This allows both generations to run against their respective Storybook instances. + +### Auto-starting Storybook + +Tests automatically start Storybook when needed: + +```typescript +webServer: [ + { + command: 'cd ../1st-gen && yarn storybook', + port: 8080, + reuseExistingServer: !process.env.CI, + }, + { + command: 'cd packages/swc && yarn storybook', + port: 6006, + reuseExistingServer: !process.env.CI, + }, +]; +``` + +## File structure + +``` +spectrum-web-components/ +├── playwright.a11y.config.ts # Playwright config (both gens) +├── CONTRIBUTOR-DOCS/ +│ └── 01_contributor-guides/ +│ └── 09_accessibility-testing.md # This guide +├── 1st-gen/ +│ ├── package.json # Test scripts (points to root config) +│ ├── test/ +│ │ └── a11y-helpers.ts # 1st gen test helpers +│ └── packages/ +│ ├── badge/test/ +│ │ ├── badge.a11y.spec.ts # Tests +│ │ └── badge.a11y.spec.ts-snapshots/ # ARIA baselines +│ └── status-light/test/ +│ ├── status-light.a11y.spec.ts +│ └── status-light.a11y.spec.ts-snapshots/ +└── 2nd-gen/ + ├── package.json # Test scripts (points to root config) + └── packages/swc/ + ├── utils/ + │ └── a11y-helpers.ts # 2nd gen test helpers + └── components/ + ├── badge/test/ + │ ├── badge.a11y.spec.ts + │ └── badge.a11y.spec.ts-snapshots/ + └── status-light/test/ + ├── status-light.a11y.spec.ts + └── status-light.a11y.spec.ts-snapshots/ +``` + +## Resources + +- [Playwright accessibility testing](https://playwright.dev/docs/accessibility-testing) +- [Playwright ARIA snapshots](https://playwright.dev/docs/aria-snapshots) +- [aXe-core rules](https://github.com/dequelabs/axe-core/blob/develop/doc/rule-descriptions.md) +- [WCAG 2.1 quick reference](https://www.w3.org/WAI/WCAG21/quickref/) + +## Benefits + +**For developers:** + +- Catch issues in seconds, not days +- Clear, actionable failure messages +- No manual testing needed for basic checks + +**For the project:** + +- Scalable to all components +- CI-ready (runs on every PR) +- Complements manual testing diff --git a/2nd-gen/packages/swc/.storybook/guides/contributor-guides/ai-agent-instructions.mdx b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/ai-agent-instructions.mdx new file mode 100644 index 0000000000..b2e476059a --- /dev/null +++ b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/ai-agent-instructions.mdx @@ -0,0 +1,284 @@ +# AI agent instructions + +This document defines two distinct roles for AI agents working with the CONTRIBUTOR-DOCS navigation system. + +## Role 1: Operator + +Run the regeneration script to update breadcrumbs and TOCs. + +### When to run + +Execute the script when: + +- A file or folder is added, removed, or renamed +- A file is moved to a different location +- Document H1 headings are changed (these become display names) +- Document H2/H3 headings are added, removed, or changed +- The folder structure changes +- A human maintainer or another AI agent requests it + +### How to run + +```bash +cd CONTRIBUTOR-DOCS/01_contributor-guides/07_authoring-contributor-docs +node update-nav.js ../../ +``` + +**Expected time:** ~20-200ms for entire CONTRIBUTOR-DOCS tree (includes automatic link verification) + +### Responsibilities + +1. **Execute** the script with appropriate parameters +2. **Verify success** - check that the script completed without errors +3. **Report results** - show the output summary (files updated, time taken) +4. **Debug if needed** - if errors occur, investigate and fix or report to the user + +### Debugging errors + +If the script fails: + +1. **Check the error message** - the script provides clear error output +2. **Verify file structure** - ensure all markdown files have the required marker +3. **Check file permissions** - ensure files are writable +4. **Validate markdown** - ensure H1 headings use proper syntax (`# Title`, not `##`) +5. **Report to user** - if you can't resolve, explain what you found + +### Debugging output issues + +When the auto-generated navigation appears incorrect or malformed: + +1. **First, investigate the script** - Check if the issue can be fixed by updating `update-nav.js` + - Read the script to understand how it processes the problematic content + - Look for edge cases or patterns it doesn't handle correctly + - Consider whether a fix to the script would allow the current document structure to work + +2. **Only suggest content changes as a last resort** - Don't immediately suggest modifying document content + - Document authors may have good reasons for their structure choices + - Script improvements benefit all documents, not just one + - Content changes may limit what authors can express in their docs + +3. **Example**: If headings with links generate malformed TOC entries: + - ✅ Good: Investigate the script's heading extraction, find it doesn't strip link syntax, add a fix + - ❌ Bad: Tell the user to remove links from their headings + +**Philosophy:** The script should adapt to reasonable document structures, not the other way around. + +### Handling link verification errors + +The script automatically verifies all internal markdown links after updating navigation. When broken links are found, they are reported in the script output with structured error details. + +**Your role as an AI agent:** + +1. **Analyze each error** - Review the error details provided by the script +2. **Fix straightforward cases automatically** - Don't ask for human input when the fix is clear: + - File was renamed/moved → Find new location in metadata and update link + - Anchor was renamed → Find matching or similar anchor in target file + - Wrong relative path depth → Recalculate correct relative path + - Case sensitivity issues → Fix capitalization + - Missing or incorrect file extension → Add `.md` extension if needed + +3. **Consult human for ambiguous cases** - Ask for guidance when: + - Target file was completely removed (need decision on alternative link target) + - Multiple possible anchor matches exist with similar names + - Link intent is unclear or may need conceptual rethinking + - You cannot determine the correct fix with high confidence + +4. **Report fixes clearly** - After fixing, summarize: + - How many links were broken + - What fixes were applied + - Any remaining issues that need human review + +**Example workflow:** + +``` +Script reports: "File not found: ../migration/overview.md" +→ Search metadata for files matching "migration" or "overview" +→ Find: "03_project-planning/01_migration-status.md" +→ Update link with correct relative path +→ Report: "Fixed broken link: updated path to migration status doc" +``` + +--- + +## Role 2: Maintainer + +Review and update the regeneration script when requirements or specifications change. + +### Requirements and specifications + +The script's behavior is defined by: + +1. **Human maintainer instructions** (`human-maintainer-instructions.md`) + - File and folder naming conventions + - Numbering rules + - Document structure requirements + - Display name derivation rules + +2. **File structure conventions** (implicit in the codebase) + - README.md files as folder overviews + - Lowercase kebab-case naming + - Optional sequential numbering + - HTML comment markers for separating content + +3. **Output format requirements** + - Breadcrumb format and linking rules + - TOC structure ("In this doc" and "Beneath this doc" sections) + - Collapsible `
` elements + - GitHub-style anchor links + +### When to maintain + +Update the script when: + +- Naming or numbering conventions change +- Breadcrumb or TOC format requirements change +- New edge cases are discovered +- Display name derivation rules change +- File structure conventions evolve +- Performance optimizations are needed + +### Maintenance process + +1. **Review the change request** + - Understand what requirement or specification has changed + - Identify which part of the script needs updating + +2. **Update the script** (`update-nav.js`) + - Modify the relevant functions + - Maintain code quality and comments + - Preserve existing functionality where applicable + +3. **Test thoroughly** + - Run the script on the entire CONTRIBUTOR-DOCS tree + - Verify output matches new requirements + - Check that existing functionality still works + - Spot-check several files manually + +4. **Update documentation** + - Update this file if the operator role changes + - Update human maintainer instructions if conventions change + - Add comments in the script explaining non-obvious logic + +5. **Report changes** + - Summarize what was changed and why + - Note any breaking changes or new behaviors + - Provide examples of the new output format + +### Script architecture + +The script (`update-nav.js`) is organized into several sections: + +1. **Configuration** - Constants for markers and behavior settings +2. **Utility Functions** - Helper functions for text processing and code block detection +3. **Metadata Extraction** - Scans the documentation tree and builds relationships +4. **Navigation Generation** - Creates breadcrumbs and table of contents +5. **File Update** - Replaces auto-generated content while preserving manual edits + +For implementation details, see the script source code which includes inline comments explaining the logic. + +--- + +## Script behavior details + +### What the script does + +**Step 1: Extract metadata** (~10-15ms) + +- Walks the entire documentation tree +- Extracts H1 headings (used as display names) +- Extracts H2/H3 headings (for "In this doc" TOC section) +- Maps parent-child relationships +- Identifies folders with/without README files + +**Step 2: Generate navigation** (~2-4ms) +For each file: + +- Creates breadcrumbs linking to parent READMEs +- Creates "In this doc" TOC from H2/H3 headings +- Creates "Beneath this doc" TOC from child files/folders +- Wraps TOC in collapsible `
` element + +**Step 3: Update files** (~2-4ms) + +- Finds the content marker +- Replaces everything above it with new breadcrumbs and TOC +- Preserves all content below the marker +- Handles edge cases (duplicate markers in code blocks) + +**Step 4: Verify links** (~10-150ms) + +- Extracts all markdown links from document content (excluding auto-generated sections and code blocks) +- Validates that target files exist +- Validates that anchor references point to existing headings +- Reports any broken links with detailed error information + +### Breadcrumb format + +```markdown +[ROOT](../../README.md) / [Parent](../README.md) / Current Page +``` + +**Rules:** + +- Root is always `CONTRIBUTOR-DOCS` linking to root README.md +- Parent folders link to their README.md (if it exists) +- Folders without README show as plain text (no link) +- Current page is plain text (not linked) +- Display names from H1 headings, not filenames + +### TOC format + +```markdown +
+Contents + +- **In this doc** + - [Section heading](#section-heading) +- **Beneath this doc** + - [Child file](./child.md) + - [Child folder](./folder/README.md) + +
+``` + +**Rules:** + +- Omit "In this doc" if no H2/H3 headings exist +- Omit "Beneath this doc" if no child files/folders exist +- Omit entire TOC if both sections would be empty +- Use GitHub-style anchors (lowercase, hyphens, no special chars) +- Recursively include grandchildren with proper indentation + +### Display name derivation + +**For files:** Extract H1 heading + +- `# Migration Status` → "Migration Status" + +**For folders with README:** Extract H1 from README.md + +- README contains `# Workstream Info` → "Workstream Info" + +**For folders without README:** Derive from folder name + +1. Remove number prefix: `02_project-planning` → `project-planning` +2. Replace hyphens with spaces: `project-planning` → `project planning` +3. Apply title case: `workstream info` → `Workstream Info` + +--- + +## Testing checklist + +After running or modifying the script: + +- [ ] Script completed without errors +- [ ] All files were updated (check the count in output) +- [ ] Link verification completed (check counts of valid/broken links) +- [ ] Spot-check breadcrumbs are correct and links work +- [ ] Spot-check TOCs reflect current structure +- [ ] Display names are human-readable (from H1 headings) +- [ ] Folders without README show as plain text (no link) +- [ ] Collapsible TOC sections work properly +- [ ] Manual content below the marker is preserved +- [ ] No trailing spaces or formatting issues +- [ ] Any broken links reported have been addressed diff --git a/2nd-gen/packages/swc/.storybook/guides/contributor-guides/authoring-contributor-docs.mdx b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/authoring-contributor-docs.mdx new file mode 100644 index 0000000000..0c4215f240 --- /dev/null +++ b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/authoring-contributor-docs.mdx @@ -0,0 +1,137 @@ +# Authoring contributor docs + +## Overview + +This document provides guidance for maintainers of the Spectrum Web Components contributor docs, which are located in the CONTRIBUTOR_DOCS folder at the root of the repository. + +For the most part, the contributor docs are just ordinary Markdown (`.md`) files located in a nested folder structure. + +The navigational structure of the docs is derived from the location of the files within the folder structure and the Markdown headings within each doc. + +To help with browsability and navigation: + +- There are some conventions around file organization and naming (described in this document). +- There is a script that automatically [generates / updates breadcrumbs and TOCs](#updating-auto-generated-navigation). + + You can run this script manually, but we recommend invoking it via an AI agent, so that the agent can help with verification and troubleshooting as needed. + +## Writing & editing docs + +### Creating a new doc + +To create a new doc, just decide where you want to put it (see [Organizing docs](#organizing-docs)), then write a standard Markdown file. This file should contain an H1 heading representing the document title, along with whatever content you want to include. + +```markdown +# Your Document Title + +Your content goes here. + +## Section One + +More content... +``` + +You should not include navigational elements (breadcrumbs and TOCs), as these are [auto-generated and updated](#updating-auto-generated-navigation) upon request. + +### Editing existing docs + +When you are editing existing docs, you'll find [auto-generated breadcrumbs and TOCs](#updating-auto-generated-navigation) alongside the document content. + +Each doc file has the following structure, with markers clearly separating auto-generated and editable content: + +```markdown +[Auto-generated breadcrumb navigation] + +# Your Document Title + +[Auto-generated table of contents] + +[Document content] +``` + +**What's editable:** + +- The H1 title (between the breadcrumb marker and the TOC marker) +- All content after the TOC section + +### Titles and headings + +- As noted previously, each document should have a title, represented by a Markdown H1 (`#`) heading. + + This title is displayed in the document, and used in generated breadcrumbs and TOCs. + +- Within each document, use proper heading hierarchy (don't skip levels). +- Avoid duplicate heading names in the same document (they'll create conflicting anchor links in the TOC). + +### Links + +- When linking to other doc files, use relative links +- Always link to files, not folders: + - Correct: `[Workstreams](../../03_project-planning/02_workstreams/README.md)` + - Incorrect: `[Workstreams](../../03_project-planning/02_workstreams/)` + +## Organizing docs + +### Folder structure + +- Keep the hierarchy shallow when possible (avoid deeply nested structures) +- Group related content into folders + +### Use `README.md` for index files + +- Although not required, it often makes sense for a folder to have a "main" (index) file. The index file: + - Serves as a standard place to include overview content for a section of the docs + - Lets a folder appear as a clickable link in breadcrumbs and TOCs. + +- Naming a file `README.md` makes it the index file for the containing folder. + + _We borrow this convention from GitHub, so you'll see the content when navigating to a folder in the GitHub UI._ + +- If a folder doesn't contain a `README.md` file, the folder name will appear as plain text (no link) in breadcrumbs and TOCs. + +### File and folder naming conventions + +- File and folder names don't matter very much, since titles are taken from the H1 headings in Markdown files. +- There are two ways in which file and folder names DO matter: + - File and folder names determine the order of TOC entries (see **Ordering**, below). + - In breadcrumbs and TOCs, the display name of a folder without a `README.md` file is derived from the folder's name. +- By convention: + - Use lowercase kebab-case for all file and folder names: `2nd-gen-component-migration`. + - Exception: `README.md` files use conventional capitalization + - See **Ordering** for numbering conventions. + +### Ordering + +- Within each section of the auto-generated TOC, entries are ordered alphanumerically. +- If the order of entries in a given section doesn't matter, there's no need to do anything special; entries will end up in alphabetical order by default. +- Where needed, use numeric prefixes in your file and folder names to specify ordering. + - Numeric prefixes should be two digits, with leading zeros as needed, and followed by an underscore: `01_important-first.md`, `02_next.md`, etc. + +## Updating auto-generated navigation + +Request generation of breadcrumbs and TOC when you: + +- Add, remove, or rename a file or folder +- Move a file to a different location +- Add, remove, or rename section headings in a document +- Change the organizational structure + +The script also automatically verifies all internal markdown links and reports any broken links, which an AI agent will typically fix automatically. + +You can request an update by asking an AI Agent, pointing it to the [AI Agent Instructions](?path=/docs/guides-contributor-guides-ai-agent-instructions--docs). + +> If you're using Cursor, you can just ask an agent to "update the contributor docs"; a project-level Cursor rule will help the agent find the applicable instructions. + +> If you don't have access to an AI Agent or prefer not to use one, you can also run the script manually. See [the AI Agent Instructions](?path=/docs/guides-contributor-guides-ai-agent-instructions--docs) for details. + +### Verifying and troubleshooting + +The logic for generating navigational elements is quite simple, so it's unlikely that things will go wrong, but it's a good idea to do a quick spot-check to ensure that breadcrumbs and TOCs look correct, especially in areas of the docs that you have edited. + +**Link verification:** The script automatically checks all internal markdown links and reports any broken links. When working with an AI agent, broken links are typically fixed automatically without human intervention. The agent will only ask for guidance if the fix is ambiguous (e.g., when a target file has been completely removed). + +If you encounter any issues, try asking an AI agent to help you troubleshoot, pointing the agent to the [AI Agent Instructions](?path=/docs/guides-contributor-guides-ai-agent-instructions--docs). + +## Committing updates + +Because auto-generated navigation lives in the source files alongside manually edited content, you should [update the navigation](#updating-auto-generated-navigation) before committing any edits. This ensures that, at any given point in the commit history, the navigation will match the content in the docs. diff --git a/2nd-gen/packages/swc/.storybook/guides/contributor-guides/contributor-guides.mdx b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/contributor-guides.mdx new file mode 100644 index 0000000000..ab83302942 --- /dev/null +++ b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/contributor-guides.mdx @@ -0,0 +1,3 @@ +# Contributor guides + +(Content to be added) diff --git a/2nd-gen/packages/swc/.storybook/guides/contributor-guides/getting-involved.mdx b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/getting-involved.mdx new file mode 100644 index 0000000000..d2690938c2 --- /dev/null +++ b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/getting-involved.mdx @@ -0,0 +1,70 @@ +# Getting involved + +## Welcome + +Welcome! We're excited you're interested in improving Spectrum Web Components. Whether you're reporting bugs, adding new features, writing documentation, or helping other users, your contributions make this project better for everyone. + +Here you'll find a broad overview of how you can get involved. Please read through these guidelines to help keep the contribution process smooth and to ensure we're all on the same page. + +## Community & support + +A fantastic first step to contributing is filing an issue. This is where you can: + +- Ask questions, file bugs, and troubleshoot with other users. +- Propose new features and ideas or get feedback on your own through a linked pull request. +- Additionally, you can check GitHub Discussions to stay up-to-date with any major announcements about the project. + +### External contributors + +**Adobe Employees, read Internal contributors section below.** +If you need support or have a question about how something works, filing an issue is the best place to start. A team member will be in touch to either triage your issue or follow-up with you in the comments. + +### Internal contributors + +If you work for Adobe, our Slack channel #spectrum_web_components has some great workflows to get you started. Be sure to read the Welcome Canvas when you join. + +--- + +## How you can contribute + +There's a common misconception that you need to code in order to contribute. In reality, there are many different ways to help: + +- Filing well-structured bug reports that show what's broken and how to reproduce it. +- Suggesting new features that improve the current design system. +- Improving our documentation to make it clearer for the next person. +- Reviewing pull requests from other community members and sharing feedback. +- Helping other users on GitHub Discussions. +- Advocating for the project on social media or at meetups. + +Of course, contributing code is also welcome, from fixing a bug to building a brand-new component. All types of contributions help keep Spectrum Web Components thriving. + +--- + +## Contributor license agreement + +We require all external contributors to sign our [Contributor License Agreement](https://opensource.adobe.com/cla.html) (CLA). If you haven't signed it before making your first contribution, please do so—otherwise, we can't merge your changes. + +--- + +## Code of conduct + +Spectrum Web Components abides by the [Adobe Code of Conduct](https://github.com/adobe/spectrum-web-components/blob/main/CODE_OF_CONDUCT.md). By participating, you agree to treat all community members kindly and respectfully. We're committed to fostering a welcoming, inclusive environment. +Should any behavior fall short of these expectations, please report it to . + +--- + +## Developing locally + +Read the steps outlined in [Working in the SWC repo](?path=/docs/guides-contributor-guides-working-in-the-swc-repo--docs) to get your environment set up. + +If you encounter hurdles, feel free to ask for help in your pull request or in the community forum. + +--- + +## Thank you + +We appreciate everyone who invests time, energy, and expertise into Spectrum Web Components. Your contributions—big or small—help this library evolve to serve a broader audience and remain at a high standard of quality. + +If you have any suggestions for improving these guidelines, feel free to open a pull request or bring it up in our community discussions. We're always eager to make the contribution experience better. + +Happy contributing! diff --git a/2nd-gen/packages/swc/.storybook/guides/contributor-guides/making-a-pull-request.mdx b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/making-a-pull-request.mdx new file mode 100644 index 0000000000..f4c48cda02 --- /dev/null +++ b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/making-a-pull-request.mdx @@ -0,0 +1,176 @@ +# Making a pull request + +This document outlines our team's expectations and best practices for creating and submitting pull requests for Spectrum Web Components. + +## Scoping and planning your PR + +### Testing + +Quality and stability are important. We require writing tests for any fixes or features you introduce. This helps ensure: + +- Bugs don't resurface later. +- New features work as intended for all users. +- Overall library reliability remains high. + +For 1st-gen testing guidance, see the [1st-gen README.md](https://github.com/adobe/spectrum-web-components/blob/main/1st-gen/README.md). Testing guidance for 2nd-gen is forthcoming. + +If you're unsure how to write tests for certain parts of the library, don't hesitate to ask maintainers for guidance. We appreciate every effort to keep the code solid! + +### Documentation + +In addition to well-tested code, documentation is crucial. Whenever you add or change a feature, include documentation for it in the relevant areas: + +- **README.md**: Each component has a README within its directory. Ensure your changes are included here. This file is used in our generated documentation site. +- **Comment annotations**: We use comment-based documentation ([JSDocs](https://jsdoc.app/)) so that references are generated automatically where possible. + +Accessible, helpful docs are a huge win for everyone, especially newcomers. + +### Code formatting + +We rely on automated tools like Prettier, ESLint, and Stylelint to enforce style preferences. Setting up these tools in your editor saves time and prevents minor style conflicts from slowing down reviews. + +### Accessibility + +Since this project is used by a diverse audience, the accessibility of our product is of utmost importance. Features will be evaluated for inclusivity by: + +- The use of semantic markup. +- The appropriate [ARIA roles, properties, and states](https://www.w3.org/WAI/ARIA/apg/example-index/) to indicate affordances that are not already indicated via semantic HTML. +- Applying [descriptive labels](https://www.w3.org/WAI/ARIA/apg/practices/names-and-descriptions/). +- The use of the expected [keyboard navigation](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/). +- Sufficient color contrast as recommended in the [Web Content Accessibility Guidelines (WCAG)](https://www.w3.org/WAI/standards-guidelines/wcag/). + +If you're unsure about an accessibility detail, the [Web Accessibility Initiative (WAI) ARIA Practices Guide (APG)](https://www.w3.org/WAI/ARIA/apg/patterns/) is a good place to start. You can also open a discussion or ask in your PR. + +--- + +## Developing your PR + +### Branch naming + +We use a straightforward branch naming convention: + +- `[username]/[short-description]` (e.g., `alex/fix-dropdown-bug`) +- If referencing a known issue, incorporate the issue number (e.g., `alex/123-fix-dropdown-bug`) + +### Changeset requirements + +For PRs that add or update a component, you must include a changeset to trigger the release train and update the CHANGELOG. + +#### What are changesets? + +Each changeset represents changes that have enough significance to warrant a new version. A changelog represents a single release. A changelog may contain several changesets. + +There are three levels of releases that a changeset can describe, which are described by semantic versioning: + +- **Patch** (1.0.0 → 1.0.1): Bug fixes and non-breaking changes +- **Minor** (1.0.0 → 1.1.0): New features, backwards-compatible +- **Major** (1.0.0 → 2.0.0): Breaking changes requiring user update + +Each change should be categorized under one of these types: + +- **Added**: New features or capabilities +- **Changed**: Changes in existing functionality +- **Deprecated**: Soon-to-be removed features +- **Removed**: Features that have been removed +- **Fixed**: Bug fixes + +#### Writing changesets + +Changesets are different from commit messages. **Commit messages** are used to document the changes for _contributors_. **Changesets** are used to communicate the changes to the _consumers_ of the design system. + +When writing changesets: + +- **Be specific and component-focused**: Reference components by their tag names, include links to the PR, and specify what changed, why, and how users should update their code (if applicable) +- **Document breaking changes**: Clearly mark breaking changes with migration guidance, listing each change on its own line +- **Focus on user impact**: Describe changes from the user's perspective, not implementation details +- **Use past tense**: Write changes in past tense to describe what has been modified + +For detailed examples and best practices, see the [Writing Changesets guide](https://opensource.adobe.com/spectrum-web-components/guides/writing-changesets/#writing-changesets). + +### Conventional commits + +We follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification to make change tracking predictable: + +Format: `type(component?): subject` + +The component is optional but should reference the package you are updating. + +Types include: + +- `feat`: New features or enhancements +- `fix`: Bug fixes +- `docs`: Documentation changes +- `style`: Formatting, linting (not CSS changes) +- `chore`: Build tooling, repo management, dependency updates +- `perf`: Performance improvements +- `test`: Adding or updating tests + +Examples: + +- `feat(sp-card): add shadow styles for theme consistency` +- `fix(sp-action-menu): correct arrow key navigation in nested menus` +- `docs: clarify how to submit bug reports` + +For breaking changes, add a `!` after the type/scope: + +- `feat(sp-button)!: change API for icon placement` + +--- + +## Submitting your PR + +### Pull request template + +When creating a pull request, you'll be presented with our template. Complete all sections to the best of your ability, including: + +- Description of the changes +- Related issues (using proper [GitHub keywords](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/using-keywords-in-issues-and-pull-requests#linking-a-pull-request-to-an-issue) to auto-close issues i.e. `fixes`, `resolves`, or `closes`) +- Type of change in the PR title (bug fix, feature, breaking change) +- Steps you took to test your changes that reviewers can follow to also test them +- Checklist of items completed +- Screenshots/videos for visual changes + +Incomplete templates may delay the review process. + +### Labels for PR authors + +As a PR author, you can use these labels to communicate the status of your pull request: + +- `Status: Ready for review`: PR is ready for maintainer review or re-review +- `Status: WIP`: PR is still being worked on, not ready for review +- `Status: Addressing feedback`: PR owner is addressing review comments. +- `Component: [Name]`: PR affects this component + +For a complete list of labels and their meanings, including reviewer-specific labels, see [Participating in PR reviews](?path=/docs/guides-contributor-guides-participating-in-pr-reviews--docs#labels-and-their-meanings). + +--- + +## Specific requirements by element type + +### New components + +When creating or reviewing new components, ensure: + +#### Documentation + +- README contains a clear description and minimal example +- Inline documentation for all public APIs +- Accessibility documentation that aligns with WCAG patterns + +See [Documenting a component](https://opensource.adobe.com/spectrum-web-components/guides/adding-component/#documenting-the-component) for more information on our documentation standards and structure. + +#### API documentation utilizing JSDocs + +- **Slots**: All slots documented in the element class docblock +- **Events**: All dispatched events documented with `@fires` docblock +- **Class fields**: All public/protected fields have proper docblocks +- **Methods**: All public/protected methods have docblocks with parameters and return types +- **CSS custom properties**: All public CSS custom properties documented +- **CSS shadow parts**: All shadow parts documented + +#### Technical requirements + +- Component follows established patterns and conventions +- Accessibility is thoroughly considered +- Responsive design best practices are followed +- Supported cross-browser compatibility is verified diff --git a/2nd-gen/packages/swc/.storybook/guides/contributor-guides/participating-in-pr-reviews.mdx b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/participating-in-pr-reviews.mdx new file mode 100644 index 0000000000..6f5dd9622d --- /dev/null +++ b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/participating-in-pr-reviews.mdx @@ -0,0 +1,97 @@ +# Participating in PR reviews + +This document outlines our team's expectations and best practices for reviewing pull requests and participating in the PR review process for Spectrum Web Components. + +## Labels and their meanings + +[See the complete list of labels on Github. ](https://github.com/adobe/spectrum-web-components/labels) + +- `Contribution`: This label denotes the PR is from someone other than the maintainers of SWC. +- `Status: Ready for review`: PR is ready for maintainer review +- `Status: Ready for merge`: PR has two approvals and all tests pass. +- `Status: WIP`: PR is still being worked on, not ready for review +- `Status: Blocked`: PR is blocked for some reason, eg another PR needs to go in first +- `Status: On hold`: PR on hold pending more discussion. +- `Status: Addressing feedback`: PR owner is addressing review comments and will request re-review when ready. +- `Status: Ready for design review`: PR needs to be checked by the Spectrum Design team +- `Breaking`: PR contains changes that break backward compatibility +- `High priority PR review`: PR is related to a SEV 1 issue or other critical work +- `Component: [Name]`: PR affects this component + +Apply labels promptly to help maintainers prioritize and manage the review queue. + +--- + +## Pull request review process + +### Review timing + +- Maintainers aim to review PRs in a timely manner +- If your PR hasn't received attention, feel free to ping the team in the PR comments + +### Review expectations + +Reviewers will check for: + +- Adherence to code style and component patterns +- Proper test coverage +- Documentation completeness +- Accessibility compliance +- Visual regression test coverage +- Performance considerations + +### Review etiquette + +Pull requests are the start of a conversation. During the process, we aim to provide feedback that is constructive, respectful, and actionable. Suggestions will be focused on team coding standards but not on an individual's coding preferences unless there are specific considerations or risks in one approach over another. + +Both reviewers and PR authors should follow these guidelines: + +#### For reviewers + +- **Maintain momentum**: Complete reviews in a timely manner to keep the project moving forward. +- **Provide clear, actionable feedback**: Help contributors succeed by offering specific guidance and explaining the reasoning behind suggested changes. +- **Offer solutions**: When identifying areas for improvement, suggest alternative approaches and use code suggestions to make implementation easier. +- **Seek understanding**: Ask questions to clarify intent and approach, fostering a collaborative environment for learning and improvement. +- **Recognize excellence**: Celebrate well-written code and thoughtful design decisions to encourage continued high-quality contributions. +- **Focus on impact**: Prioritize feedback on architecture, functionality, and performance to ensure the most important aspects are addressed first. +- **Focus on value**: Prioritize feedback that improves code quality and maintainability over personal style preferences. If you make a suggestion that is non-blocking feedback, prepend the comment with `nit:`. +- **Consider context**: Tailor feedback to the PR author's experience level and the scope of changes. +- **Use changes requested thoughtfully**: Reserve the Changes Requested status for instances where critical issues need to be addressed. +- **Review VRTs with care**: Thoroughly examine visual regression test results and communicate approval status to authors. + +#### For PR authors + +- **Self review your PR**: Take a first pass at reviewing and commenting on your own submission. This gives reviewers valuable context and may pre-emptively answer questions that might otherwise arise. +- **Resolve/respond to all comments**: Address each review comment, either with code changes or explanations of your approach. +- **Ask for clarification**: If review feedback is unclear, ask questions to understand the concern. +- **Notify when ready**: After addressing feedback, notify reviewers that the PR is ready for another look either in Slack or by requesting a new review in GitHub. +- **Explain complex changes**: For non-obvious changes, explain your reasoning in the PR description or comments. +- **Break down large PRs**: When possible, split large changes into smaller, more manageable PRs. +- **Test thoroughly**: Before requesting review, ensure your code meets the project's quality standards. + +#### Resolving disagreements + +- **Focus on data**: Back up opinions with data, documentation, or examples where possible. +- **Refer to standards**: Use project conventions and industry best practices to guide decisions. +- **Compromise when appropriate**: Be willing to find middle ground when opinions differ. +- **Escalate respectfully**: If consensus can't be reached, involve a third team member or technical lead for guidance. +- **Document decisions**: Record the reasoning behind significant technical decisions for future reference. + +Remember that code reviews are a collaborative process aimed at improving code quality, knowledge sharing, and maintaining project standards. Approaching reviews with empathy and professionalism benefits everyone involved. + +--- + +## Merge criteria + +A PR is ready to merge when: + +1. It has received approval from two maintainers +2. All CI checks are passing + - Unit tests passing + - Integration tests passing + - Visual regression tests passing (**VRT golden images should not be updated until an approver confirms they look good**) + - Linting checks passing +3. All requested changes have been addressed +4. PR follows conventional commit standards +5. Includes proper changeset (when applicable) +6. Documentation has been updated as needed diff --git a/2nd-gen/packages/swc/.storybook/guides/contributor-guides/patching-dependencies.mdx b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/patching-dependencies.mdx new file mode 100644 index 0000000000..9fb2e32e96 --- /dev/null +++ b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/patching-dependencies.mdx @@ -0,0 +1,59 @@ +# Patching dependencies + +## About patches + +Sometimes you may need to temporarily patch a dependency to fix a bug or add functionality while waiting for an upstream fix. This project uses **Yarn 4's built-in patching system** instead of external tools like `patch-package`. + +## Creating a patch + +1. **Extract the package** for editing: + + ```bash + yarn patch + ``` + + Example: + + ```bash + yarn patch @web/test-runner-playwright + ``` + +2. **Edit the extracted files** in the temporary directory that Yarn creates. Yarn will show you the path where you can make your changes. + +3. **Commit the patch** once you're done editing: + + ```bash + yarn patch-commit -s + ``` + + Example: + + ```bash + yarn patch-commit -s /private/var/folders/.../user + ``` + +## How patches work + +- Patches are automatically stored in `.yarn/patches/` directory +- They are applied automatically during `yarn install` +- Patches are version-specific and will need to be recreated if the dependency version changes +- All patches are committed to the repository so they apply for all contributors + +## Updating existing patches + +To modify an existing patch: + +```bash +yarn patch --update +``` + +This will extract the current patched version, allowing you to make additional changes. + +## Best practices + +- **Keep patches minimal**: Only change what's necessary to fix the specific issue +- **Document the reason**: Add comments in your pull request explaining why the patch is needed +- **Plan for removal**: Patches should be temporary until the upstream fix is available +- **Test thoroughly**: Ensure your patch doesn't break other functionality + +For more details, see the [Yarn patching documentation](https://yarnpkg.com/features/patching). diff --git a/2nd-gen/packages/swc/.storybook/guides/contributor-guides/releasing-swc.mdx b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/releasing-swc.mdx new file mode 100644 index 0000000000..18e9b961cb --- /dev/null +++ b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/releasing-swc.mdx @@ -0,0 +1,165 @@ +# Releasing SWC + +Users with permissions in the `@spectrum-web-components` organization on NPM can follow these steps to create and publish a new version. + +## Prerequisites + +### Main successfully builds + +Merge all pull requests to be included in the release, and wait for the `main` branch to show that it has completed the required Circle CI jobs. + +Check [Circle Ci build for `main`](https://app.circleci.com/pipelines/github/adobe/spectrum-web-components?branch=main) shows a `success` status. 1. If it failed, click `rerun` dropdown and select `rerun from failed`. 2. If it continues to fail, investigate further until you can successfully get the `main` branch building. + +--- + +### The correct version of Node is installed + +This is important to confirm before next step because differing node versions will cause build issues. + +#### Using Node Version Manager + +Run `nvm use` (assumes a Node Version Manager install), and confirm you're on an operable version of Node. + +#### Manually checking + +1. Run `node --version` to see what version you have installed +2. Check `.nvmrc` for node version requirements. +3. If the versions don't match, run `node install [version]` + +#### Troubleshooting + +If you need to install the correct yarn version and/or have issues with `yarn` command not being recognized, run `corepack enabled`. Yarn 4 uses corepack and needs to be enabled to access the commands. + +--- + +### Github Token is set up + +Check you have a GitHub token set up, run `echo $GITHUB_TOKEN`. + +#### Generate a Github token + +1. If you do not have one, set it up in [Github settings > Developer settings > Personal access tokens](https://github.com/settings/personal-access-tokens) + 1. Create a classic token + - Note: SWC changeset release token + - Set the expiration to a year or less + - Scopes: + - `repo (all)` + - `read:user` +2. Add generated token to `~/.zshrc` with `export GITHUB_TOKEN='token'` + - Make sure there isn't another export with the same name +3. Close your terminal to reset your profile, open terminal back up + +--- + +### Logged in to NPM + +Run `npm whoami` ensure that you are logged in with the user account for the public NPM registry. + +If not logged in, run `npm login` to sign in to your account. + +--- + +### NPM 2FA authenticator app + +1. Go to `Account Settings` on NPM +2. Click `Modify 2FA` in the Two-Factor Authentication section +3. Follow the instructions to configure the authenticator app (i.e. Google Authenticator) of your choice + 1. Should be able generate a 6-digit password that updates regularly + +--- + +## Releasing to NPM — the good stuff + +The publishing workflow is handled by a single unified script (`scripts/publish.js`) that automates the entire process: cleaning, building, versioning, publishing, and git operations. + +1. **Prepare your workspace:** + - Run `git checkout main && git fetch && git pull` to ensure you have the latest code + - Confirm the working directory is clean with `git status` +2. **Review changesets:** + - Scan the `.changeset` directory for pending changes + - In your IDE search `': major`, `': minor`, `': patch` to verify the release impact + - Exclude files: `.changeset/README.md` + - The highest level takes precedence (major > minor > patch) + - Confirm the changes match your expectations +3. **Prepare for publishing:** + - Open your authenticator app to have it ready + - You'll need to enter a one-time password twice during the process: + 1. Once for the main SWC packages + 2. Once for the React wrapper packages +4. **Run the publish command:** + - **Regular release:** `yarn publish` + - Creates git tags + - Publishes to npm with `latest` tag + - Commits changes to `main` + - **Snapshot release:** `yarn publish:snapshot` + - No git tags + - Publishes to npm with `snapshot` tag + - No git commits + - **Custom tag release:** `node ./scripts/publish.js --tag beta` + - No git tags + - Publishes to npm with custom tag (e.g., `beta`, `alpha`, `rc`, `nightly`) + - No git commits +5. **What happens during publishing:** + 1. The script cleans all build artifacts and reinstalls dependencies + 2. Builds all packages (1st-gen and 2nd-gen) + 3. Generates custom elements manifests + 4. Versions packages with changesets + 5. Publishes to npm (you'll enter your first OTP here) + 6. Builds React wrapper packages + 7. Publishes React wrappers to npm (you'll enter your second OTP here) + 8. For regular releases: commits changes and creates git tags +6. **Verify the release:** + - For regular releases, confirm the build on `main` passes + - Check the [tags page](https://github.com/adobe/spectrum-web-components/tags) to verify new tags were created + - The docs site will publish automatically if the commit message includes `#publish` and checks pass + +### Troubleshooting + +If publishing fails with an error: + +- Check the [list of tags](https://github.com/adobe/spectrum-web-components/tags) to see if new tags have been released for your publishing attempt. +- If they were, run `yarn publish` again (or the appropriate command for your release type). + +### Custom npm tags + +For special releases like beta, alpha, nightly, or release candidates, you can use custom npm tags with the `--tag` flag: + +```bash +# Beta release +node ./scripts/publish.js --tag beta + +# Alpha release +node ./scripts/publish.js --tag alpha + +# Nightly release +node ./scripts/publish.js --tag nightly + +# Release candidate +node ./scripts/publish.js --tag rc +``` + +Users can then install these versions with: + +```bash +yarn add @spectrum-web-components/button@beta +yarn add @spectrum-web-components/button@alpha +yarn add @spectrum-web-components/button@nightly +yarn add @spectrum-web-components/button@rc +``` + +--- + +## Publishing the documentation site manually + +### From GitHub + +1. Navigate to SWC's [Actions](https://github.com/adobe/spectrum-web-components/actions) and click the `Site publish` workflow. +2. At the top of the table, click the `Run workflow` dropdown — Use workflow from `main` branch, and click the `run workflow` button. + +### From the terminal + +If you have the [GitHub CLI](https://cli.github.com) installed, you can alternatively run `gh workflow run publish.yml --ref main` from the command line. + +### References + +[Running manual workflows](https://docs.github.com/en/actions/managing-workflow-runs/manually-running-a-workflow), GitHub documentation diff --git a/2nd-gen/packages/swc/.storybook/guides/contributor-guides/using-the-issue-tracker.mdx b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/using-the-issue-tracker.mdx new file mode 100644 index 0000000000..c380da5d0a --- /dev/null +++ b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/using-the-issue-tracker.mdx @@ -0,0 +1,49 @@ +# Using the issue tracker + +We use GitHub Issues for two purposes: + +1. Bug Reports +2. Feature Requests (after initial discussion) + +If you're having a usage issue or need support, do not open an issue. Instead, reference the Community & Support section. This helps us keep issues focused on actual bugs and actionable tasks. + +## Before creating a new issue + +1. Check the [Open Issues](https://github.com/adobe/spectrum-web-components/issues) to see if the problem has already been reported. + - TIP: Apply the component label to make your search process more straightforward. +2. If it has and the issue is still open, add a comment to the existing issue instead of opening a new one. +3. Check if you can reproduce the problem in the latest version of Spectrum Web Components by forking a code example in [Stackblitz](https://stackblitz.com/orgs/custom/SWC-Team/collections/spectrum-web-components). +4. If there are no related open issues and it is reproducible in isolation, then open a [Bug Report](https://github.com/adobe/spectrum-web-components/issues/new?template=bug_report.yaml). + +## Filing a bug report + +When you file a bug, please use the `Bug Report` template provided in GitHub. Include the following information: + +- A concise summary of the problem. +- Relevant components involved in the issue. +- Issue Severity based on our classifications defined below. +- What you expected vs. what actually happened, along with any errors logged in the console. +- Steps to reproduce the issue, preferably in an isolated environment, so that we can narrow down where the bug is originating from, preferably by forking an example from our [Stackblitz project](https://stackblitz.com/orgs/custom/SWC-Team/collections/spectrum-web-components). Be detailed if you write out the steps! +- Relevant environment details (OS, browser, library version). + +Clear bug reports speed up the triage process, help us replicate the issue, and keep the project robust. + +## Classifying issue severity + +Providing the correct issue severity classification helps us adequately assess and prioritize your issue. We reserve the right to adjust the severity of your bug during triage. +Below is our issue severity classification criteria: + +| Severity level | Description | Examples | +| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| 🔥 SEV 1 | A critical design or functionality issue that breaks the design system, causes significant usability problems, or exposes critical security vulnerabilities. This issue impacts all users and/or essential workflows, making users unable to complete any tasks. Requires immediate attention. | Broken navigation system, complete unresponsiveness on all devices, components not rendering, inaccessible primary actions, security vulnerabilities.

Accessibility: The end user is not able to complete core tasks or activities (e.g., key navigational elements not accessible via keyboard, missing or incorrect form labels that prevent screen reader users from completing forms or actions, critical color contrast issues that prevent users from reading or interacting with essential content). | +| 🔴 SEV 2 | A significant problem affecting the design, usability, or functionality of the system or components for a subset of users. This issue causes major disruptions and prevent users from completing tasks or workflows.

Accessibility: Does not conform with WCAG 2.1 Level AA criteria and blocks core user tasks (no known workaround). | Content that is out of view or unreachable by customers, critical buttons or links not functioning, or actions that cannot be submitted. Unintentional breaking changes causing disruptions in production environments.

Accessibility: Issue with a component or controller with widespread use and blocks core user tasks (no known workaround). | +| 🟠 SEV 3 | A design or functionality issue that causes noticeable errors or minor usability problems for users which either cause confusion or degrade the user experience, but do not prevent task completion.

Accessibility: Does not conform with WCAG 2.1 Level AA criteria and is either non-blocking for core user tasks or blocking for non-core user tasks. | Misleading labels, inconsistent component behavior, unexpected interactions, decreases in system performance.

Accessibility: Workarounds are available and discoverable for the end user to complete core user tasks, or the end user is not able to complete non-core user tasks (e.g., inadequate ARIA labels, improper focus management, insufficient color contrast for non-critical elements). | +| 🟡 SEV 4 | A minor design flaw that affects user experience, but doesn't have a serious impact on overall usability or functionality. This issue does not prevent users from completing tasks.

Accessibility: Does not conform with WCAG 2.1 Level AA criteria but has lower user impact. | Minor visual inconsistencies, non-critical content misalignment, or minor layout issues.

Accessibility: A WCAG violation is present in areas not frequently visited by end users, or it has a lower impact on overall accessibility and usability. | +| 🟢 SEV 5 | A low-level design inconsistency or minor issue that slightly affects usability or aesthetics, with minimal impact on users. | Slight color deviations, minor typographical errors, or small spacing inconsistencies that do not impact functionality. | + +## Requesting a feature or a new component + +Is there something you wish the project did differently? Have a new component in mind? We love hearing new ideas and are eager to collaborate! + +- Start with a discussion: Share your idea in Discussions to gather feedback and see if it aligns with project goals. +- Open a feature request issue: After some positive initial conversation, open an issue using the `Feature Request` or `New Component` template with details and potential use cases. diff --git a/2nd-gen/packages/swc/.storybook/guides/contributor-guides/working-in-the-swc-repo.mdx b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/working-in-the-swc-repo.mdx new file mode 100644 index 0000000000..b5547f9687 --- /dev/null +++ b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/working-in-the-swc-repo.mdx @@ -0,0 +1,124 @@ +# Working in the SWC repo + +## About this guide + +This guide covers the essential information you need to work effectively in the Spectrum Web Components (SWC) repository. + +## Getting started + +### Prerequisites + +Before you begin, ensure you have the following installed: + +- **Node.js**: Version 20.10.0 or higher (check with `node --version`) +- **Yarn**: Version 4.6.0 or higher (check with `yarn --version`) +- **Git**: For version control (check with `git --version`) + +### Installation + +1. Clone the repository: + +```bash +git clone https://github.com/adobe/spectrum-web-components.git +``` + +2. Install dependencies: + +```bash +cd spectrum-web-components +yarn install +``` + +## Repository structure + +SWC is currently in transition from its first generation (**1st-gen**) to its second generation (**2nd-gen**). + +> This transition is motivated by some important strategic goals. For more information, see [Objectives and Strategy](?path=/docs/guides-project-planning--docs). + +Instead of creating a separate branch or repo for 2nd-gen, we are working on the 1st-gen and 2nd-gen projects side-by-side in this repository, with some core functionality being shared between 1st- and 2nd-gen components. This strategy makes it easier for us to continue actively improving and supporting 1st-gen even as we devote much of our attention to defining and building 2nd-gen. + +Reflecting the side-by-side strategy, the repository is organized into two top-level workspaces: + +- **`1st-gen/`** contains all of the 1st-gen packages, tooling, and supporting materials. + + Most of what lives here will be left behind in the transition to 2nd-gen; the core component functionality we'll carry forward is gradually being moved into the `2nd-gen` workspace. + + While we'll continue doing work in `1st-gen` as needed to accomplish our goals, we expect this work to decrease steadily toward none. + +- **`2nd-gen/`** is a new workspace that we're building from the ground up to serve as a clean foundation for our future work. It includes: + - A Core library (`packages/core/`), which contains the functionality shared between 1st- and 2nd-gen + + - The 2nd-gen SWC library (`packages/swc/`). + +During this transition, depending on what you're trying to accomplish, you may end up working in `1st-gen`, `2nd-gen`, or both. If you have any questions, [please ask](?path=/docs/guides-contributor-guides-getting-involved--docs#community--support)—we're happy to help. + +## Development workflow + +The project's top-level `package.json` file defines [several commands](#command-reference) that can be run from the repository root, covering the most important parts of the development workflow. + +> By default, each command is run in both the 1st-gen and 2nd-gen workspaces, but you can add a `:1st-gen` or `:2nd-gen` suffix to any command to run it for only one workspace. + +### Developing + +We use Storybook to interact with and test components as we develop them, as well as to document components and demonstrate usage patterns for our customers. There are separate Storybooks for 1st- and 2nd-gen. + +**To start Storybook:** + +```bash +yarn start +``` + +This command launches Storybook for both 1st- and 2nd-gen and opens a browser tab for each. + +### Testing + +**To run all tests:** + +```bash +yarn test +``` + +### Linting + +The linter runs before each commit, but you can also run it manually. + +**To check for linting issues:** + +```bash +yarn lint +``` + +### Building + +You should rarely need to trigger build explicitly, but you can do so as necessary. + +**To build all packages:** + +```bash +yarn build +``` + +## Command reference + +Here are the most frequently used commands available from the repository root: + +| Command | Description | +| -------------------- | -------------------------------------------- | +| `yarn start` | Start Storybook for both 1st-gen and 2nd-gen | +| `yarn start:1st-gen` | Start Storybook for 1st-gen only | +| `yarn start:2nd-gen` | Start Storybook for 2nd-gen only | +| `yarn test` | Run tests for both 1st-gen and 2nd-gen | +| `yarn test:1st-gen` | Run tests for 1st-gen only | +| `yarn test:2nd-gen` | Run tests for 2nd-gen only | +| `yarn test:a11y` | Run accessibility tests (both generations) | +| `yarn test:a11y:1st` | Run accessibility tests for 1st-gen only | +| `yarn test:a11y:2nd` | Run accessibility tests for 2nd-gen only | +| `yarn test:a11y:ui` | Interactive accessibility test UI | +| `yarn lint` | Check for linting issues (staged files) | +| `yarn lint:1st-gen` | Check for linting issues in 1st-gen only | +| `yarn lint:2nd-gen` | Check for linting issues in 2nd-gen only | +| `yarn build` | Build all packages (2nd-gen then 1st-gen) | +| `yarn build:1st-gen` | Build 1st-gen packages only | +| `yarn build:2nd-gen` | Build 2nd-gen packages only | + +For more specific workflows and advanced topics, refer to the other contributor guides, especially [Accessibility testing](?path=/docs/guides-contributor-guides-accessibility-testing--docs) for detailed information about writing and running accessibility tests. diff --git a/2nd-gen/packages/swc/.storybook/preview.ts b/2nd-gen/packages/swc/.storybook/preview.ts index 52564c3a35..1635ef7dc4 100644 --- a/2nd-gen/packages/swc/.storybook/preview.ts +++ b/2nd-gen/packages/swc/.storybook/preview.ts @@ -75,6 +75,17 @@ const preview = { 'First Gen vs Second Gen', ], 'Components', + [ + 'Gettiing involved', + 'Using the issue tracker', + 'Working in the SWC repo', + 'Making a pull request', + 'Participating in PR reviews', + 'Releasing SWC', + 'Authoring contributor docs', + 'Patching dependencies', + 'Accessibility testing', + ], 'Guides', [ 'Getting started guide', From a4e570aace8be510531fe39ed8fe4b4f37ae4b14 Mon Sep 17 00:00:00 2001 From: Nikki Massaro Date: Tue, 9 Dec 2025 09:52:12 -0500 Subject: [PATCH 02/10] docs(contributor-docs): updated contributor docs to reflect storybook migration --- .../authoring-contributor-docs.mdx | 165 +++++++----------- 1 file changed, 63 insertions(+), 102 deletions(-) diff --git a/2nd-gen/packages/swc/.storybook/guides/contributor-guides/authoring-contributor-docs.mdx b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/authoring-contributor-docs.mdx index 0c4215f240..0cb40b2c8b 100644 --- a/2nd-gen/packages/swc/.storybook/guides/contributor-guides/authoring-contributor-docs.mdx +++ b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/authoring-contributor-docs.mdx @@ -1,137 +1,98 @@ -# Authoring contributor docs +# Authoring contributor guides ## Overview -This document provides guidance for maintainers of the Spectrum Web Components contributor docs, which are located in the CONTRIBUTOR_DOCS folder at the root of the repository. - -For the most part, the contributor docs are just ordinary Markdown (`.md`) files located in a nested folder structure. - -The navigational structure of the docs is derived from the location of the files within the folder structure and the Markdown headings within each doc. - -To help with browsability and navigation: - -- There are some conventions around file organization and naming (described in this document). -- There is a script that automatically [generates / updates breadcrumbs and TOCs](#updating-auto-generated-navigation). - - You can run this script manually, but we recommend invoking it via an AI agent, so that the agent can help with verification and troubleshooting as needed. +This document provides guidance for maintainers of the Spectrum Web Components contributor guides. The contributor guides are MDX files (`.mdx`) located in the `.storybook/guides/` directory and rendered through Storybook. ## Writing & editing docs ### Creating a new doc -To create a new doc, just decide where you want to put it (see [Organizing docs](#organizing-docs)), then write a standard Markdown file. This file should contain an H1 heading representing the document title, along with whatever content you want to include. +To create a new doc: -```markdown -# Your Document Title +1. Decide where to place it within the `.storybook/guides/` directory structure +2. Create an MDX file with your content +3. Add the document to the story sort order in `preview.ts` (see [Ordering docs](#ordering-docs)) + +Your MDX file should contain an H1 heading representing the document title, along with whatever content you want to include: + +```mdx +# Your document title Your content goes here. -## Section One +## Section one More content... ``` -You should not include navigational elements (breadcrumbs and TOCs), as these are [auto-generated and updated](#updating-auto-generated-navigation) upon request. - ### Editing existing docs -When you are editing existing docs, you'll find [auto-generated breadcrumbs and TOCs](#updating-auto-generated-navigation) alongside the document content. - -Each doc file has the following structure, with markers clearly separating auto-generated and editable content: - -```markdown -[Auto-generated breadcrumb navigation] - -# Your Document Title - -[Auto-generated table of contents] - -[Document content] -``` - -**What's editable:** - -- The H1 title (between the breadcrumb marker and the TOC marker) -- All content after the TOC section +When editing existing docs, simply modify the MDX content directly. There are no auto-generated sections or special markers to work around. ### Titles and headings -- As noted previously, each document should have a title, represented by a Markdown H1 (`#`) heading. +- Each document should have a title, represented by a Markdown H1 (`#`) heading +- Within each document, use proper heading hierarchy (don't skip levels) +- Avoid duplicate heading names in the same document (they'll create conflicting anchor links in the table of contents) - This title is displayed in the document, and used in generated breadcrumbs and TOCs. +### Links -- Within each document, use proper heading hierarchy (don't skip levels). -- Avoid duplicate heading names in the same document (they'll create conflicting anchor links in the TOC). +When linking to other docs, use Storybook's path query parameter format: -### Links +```mdx +[Getting involved](?path=/docs/guides-contributor-guides-getting-involved--docs) +``` -- When linking to other doc files, use relative links -- Always link to files, not folders: - - Correct: `[Workstreams](../../03_project-planning/02_workstreams/README.md)` - - Incorrect: `[Workstreams](../../03_project-planning/02_workstreams/)` +The path follows the pattern: `?path=/docs/{category}-{subcategory}-{doc-name}--docs` ## Organizing docs ### Folder structure - Keep the hierarchy shallow when possible (avoid deeply nested structures) -- Group related content into folders - -### Use `README.md` for index files - -- Although not required, it often makes sense for a folder to have a "main" (index) file. The index file: - - Serves as a standard place to include overview content for a section of the docs - - Lets a folder appear as a clickable link in breadcrumbs and TOCs. - -- Naming a file `README.md` makes it the index file for the containing folder. - - _We borrow this convention from GitHub, so you'll see the content when navigating to a folder in the GitHub UI._ - -- If a folder doesn't contain a `README.md` file, the folder name will appear as plain text (no link) in breadcrumbs and TOCs. - -### File and folder naming conventions - -- File and folder names don't matter very much, since titles are taken from the H1 headings in Markdown files. -- There are two ways in which file and folder names DO matter: - - File and folder names determine the order of TOC entries (see **Ordering**, below). - - In breadcrumbs and TOCs, the display name of a folder without a `README.md` file is derived from the folder's name. -- By convention: - - Use lowercase kebab-case for all file and folder names: `2nd-gen-component-migration`. - - Exception: `README.md` files use conventional capitalization - - See **Ordering** for numbering conventions. - -### Ordering - -- Within each section of the auto-generated TOC, entries are ordered alphanumerically. -- If the order of entries in a given section doesn't matter, there's no need to do anything special; entries will end up in alphabetical order by default. -- Where needed, use numeric prefixes in your file and folder names to specify ordering. - - Numeric prefixes should be two digits, with leading zeros as needed, and followed by an underscore: `01_important-first.md`, `02_next.md`, etc. - -## Updating auto-generated navigation - -Request generation of breadcrumbs and TOC when you: - -- Add, remove, or rename a file or folder -- Move a file to a different location -- Add, remove, or rename section headings in a document -- Change the organizational structure - -The script also automatically verifies all internal markdown links and reports any broken links, which an AI agent will typically fix automatically. - -You can request an update by asking an AI Agent, pointing it to the [AI Agent Instructions](?path=/docs/guides-contributor-guides-ai-agent-instructions--docs). - -> If you're using Cursor, you can just ask an agent to "update the contributor docs"; a project-level Cursor rule will help the agent find the applicable instructions. - -> If you don't have access to an AI Agent or prefer not to use one, you can also run the script manually. See [the AI Agent Instructions](?path=/docs/guides-contributor-guides-ai-agent-instructions--docs) for details. - -### Verifying and troubleshooting - -The logic for generating navigational elements is quite simple, so it's unlikely that things will go wrong, but it's a good idea to do a quick spot-check to ensure that breadcrumbs and TOCs look correct, especially in areas of the docs that you have edited. - -**Link verification:** The script automatically checks all internal markdown links and reports any broken links. When working with an AI agent, broken links are typically fixed automatically without human intervention. The agent will only ask for guidance if the fix is ambiguous (e.g., when a target file has been completely removed). +- Group related content into folders within `.storybook/guides/` + +### File naming conventions + +- Use lowercase kebab-case for all file names: `getting-involved.mdx`, `working-in-the-swc-repo.mdx` +- No numeric prefixes are needed; ordering is controlled separately in `preview.ts` + +### Ordering docs + +Document order in the Storybook sidebar is controlled by the `storySort` configuration in `.storybook/preview.ts`. + +To add or reorder docs, update the `order` array in the `storySort` options: + +```typescript +options: { + storySort: { + method: 'alphabetical-by-kind', + order: [ + 'Get Started', + 'Components', + 'Guides', + [ + 'Contributor guide', + [ + 'Getting involved', + 'Using the issue tracker', + 'Working in the SWC repo', + // Add new docs here in desired order + ], + ], + ], + }, +}, +``` -If you encounter any issues, try asking an AI agent to help you troubleshoot, pointing the agent to the [AI Agent Instructions](?path=/docs/guides-contributor-guides-ai-agent-instructions--docs). +- Documents not listed in the `order` array will appear alphabetically after explicitly ordered items +- Nested arrays represent subcategories ## Committing updates -Because auto-generated navigation lives in the source files alongside manually edited content, you should [update the navigation](#updating-auto-generated-navigation) before committing any edits. This ensures that, at any given point in the commit history, the navigation will match the content in the docs. +When adding new docs, make sure to: + +1. Create the MDX file with your content +2. Update the `storySort` order in `preview.ts` if you need specific positioning +3. Commit both changes together to keep the navigation in sync with content From bf9052b71bc78d9a8c5838f51d89f2016aaa9f2b Mon Sep 17 00:00:00 2001 From: Nikki Massaro Date: Tue, 9 Dec 2025 09:57:17 -0500 Subject: [PATCH 03/10] docs(contributor-guides): updated based on new IA and use of storybook --- .../.storybook/guides/contributor-guide.mdx | 73 ++++++++++++++++++- ...thoring-spectrum-web-component-guides.mdx} | 0 .../contributor-guides/getting-involved.mdx | 70 ------------------ 2nd-gen/packages/swc/.storybook/preview.ts | 24 +++--- 4 files changed, 81 insertions(+), 86 deletions(-) rename 2nd-gen/packages/swc/.storybook/guides/contributor-guides/{authoring-contributor-docs.mdx => authoring-spectrum-web-component-guides.mdx} (100%) delete mode 100644 2nd-gen/packages/swc/.storybook/guides/contributor-guides/getting-involved.mdx diff --git a/2nd-gen/packages/swc/.storybook/guides/contributor-guide.mdx b/2nd-gen/packages/swc/.storybook/guides/contributor-guide.mdx index 42d2bd92fa..731384de69 100644 --- a/2nd-gen/packages/swc/.storybook/guides/contributor-guide.mdx +++ b/2nd-gen/packages/swc/.storybook/guides/contributor-guide.mdx @@ -1,10 +1,75 @@ import { Meta, Markdown } from '@storybook/addon-docs/blocks'; import ReadMe from '../../../../../CONTRIBUTOR-DOCS/README.md?raw'; - + -What is cool about this is that we can use MDX to write the documentation for the contributor docs, and then use the Storybook to render it. +# Contributor guides -This also allows us to use the same documentation for the contributor docs and the Storybook guides but control which docs are shown in the Storybook. +## Welcome -{ReadMe} +Welcome! We're excited you're interested in improving Spectrum Web Components. Whether you're reporting bugs, adding new features, writing documentation, or helping other users, your contributions make this project better for everyone. + +Here you'll find a broad overview of how you can get involved. Please read through these guidelines to help keep the contribution process smooth and to ensure we're all on the same page. + +## Community & support + +A fantastic first step to contributing is filing an issue. This is where you can: + +- Ask questions, file bugs, and troubleshoot with other users. +- Propose new features and ideas or get feedback on your own through a linked pull request. +- Additionally, you can check GitHub Discussions to stay up-to-date with any major announcements about the project. + +### External contributors + +**Adobe Employees, read Internal contributors section below.** +If you need support or have a question about how something works, filing an issue is the best place to start. A team member will be in touch to either triage your issue or follow-up with you in the comments. + +### Internal contributors + +If you work for Adobe, our Slack channel #spectrum_web_components has some great workflows to get you started. Be sure to read the Welcome Canvas when you join. + +--- + +## How you can contribute + +There's a common misconception that you need to code in order to contribute. In reality, there are many different ways to help: + +- Filing well-structured bug reports that show what's broken and how to reproduce it. +- Suggesting new features that improve the current design system. +- Improving our documentation to make it clearer for the next person. +- Reviewing pull requests from other community members and sharing feedback. +- Helping other users on GitHub Discussions. +- Advocating for the project on social media or at meetups. + +Of course, contributing code is also welcome, from fixing a bug to building a brand-new component. All types of contributions help keep Spectrum Web Components thriving. + +--- + +## Contributor license agreement + +We require all external contributors to sign our [Contributor License Agreement](https://opensource.adobe.com/cla.html) (CLA). If you haven't signed it before making your first contribution, please do so—otherwise, we can't merge your changes. + +--- + +## Code of conduct + +Spectrum Web Components abides by the [Adobe Code of Conduct](https://github.com/adobe/spectrum-web-components/blob/main/CODE_OF_CONDUCT.md). By participating, you agree to treat all community members kindly and respectfully. We're committed to fostering a welcoming, inclusive environment. +Should any behavior fall short of these expectations, please report it to . + +--- + +## Developing locally + +Read the steps outlined in [Working in the SWC repo](?path=/docs/guides-contributor-guides-working-in-the-swc-repo--docs) to get your environment set up. + +If you encounter hurdles, feel free to ask for help in your pull request or in the community forum. + +--- + +## Thank you + +We appreciate everyone who invests time, energy, and expertise into Spectrum Web Components. Your contributions—big or small—help this library evolve to serve a broader audience and remain at a high standard of quality. + +If you have any suggestions for improving these guidelines, feel free to open a pull request or bring it up in our community discussions. We're always eager to make the contribution experience better. + +Happy contributing! diff --git a/2nd-gen/packages/swc/.storybook/guides/contributor-guides/authoring-contributor-docs.mdx b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/authoring-spectrum-web-component-guides.mdx similarity index 100% rename from 2nd-gen/packages/swc/.storybook/guides/contributor-guides/authoring-contributor-docs.mdx rename to 2nd-gen/packages/swc/.storybook/guides/contributor-guides/authoring-spectrum-web-component-guides.mdx diff --git a/2nd-gen/packages/swc/.storybook/guides/contributor-guides/getting-involved.mdx b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/getting-involved.mdx deleted file mode 100644 index d2690938c2..0000000000 --- a/2nd-gen/packages/swc/.storybook/guides/contributor-guides/getting-involved.mdx +++ /dev/null @@ -1,70 +0,0 @@ -# Getting involved - -## Welcome - -Welcome! We're excited you're interested in improving Spectrum Web Components. Whether you're reporting bugs, adding new features, writing documentation, or helping other users, your contributions make this project better for everyone. - -Here you'll find a broad overview of how you can get involved. Please read through these guidelines to help keep the contribution process smooth and to ensure we're all on the same page. - -## Community & support - -A fantastic first step to contributing is filing an issue. This is where you can: - -- Ask questions, file bugs, and troubleshoot with other users. -- Propose new features and ideas or get feedback on your own through a linked pull request. -- Additionally, you can check GitHub Discussions to stay up-to-date with any major announcements about the project. - -### External contributors - -**Adobe Employees, read Internal contributors section below.** -If you need support or have a question about how something works, filing an issue is the best place to start. A team member will be in touch to either triage your issue or follow-up with you in the comments. - -### Internal contributors - -If you work for Adobe, our Slack channel #spectrum_web_components has some great workflows to get you started. Be sure to read the Welcome Canvas when you join. - ---- - -## How you can contribute - -There's a common misconception that you need to code in order to contribute. In reality, there are many different ways to help: - -- Filing well-structured bug reports that show what's broken and how to reproduce it. -- Suggesting new features that improve the current design system. -- Improving our documentation to make it clearer for the next person. -- Reviewing pull requests from other community members and sharing feedback. -- Helping other users on GitHub Discussions. -- Advocating for the project on social media or at meetups. - -Of course, contributing code is also welcome, from fixing a bug to building a brand-new component. All types of contributions help keep Spectrum Web Components thriving. - ---- - -## Contributor license agreement - -We require all external contributors to sign our [Contributor License Agreement](https://opensource.adobe.com/cla.html) (CLA). If you haven't signed it before making your first contribution, please do so—otherwise, we can't merge your changes. - ---- - -## Code of conduct - -Spectrum Web Components abides by the [Adobe Code of Conduct](https://github.com/adobe/spectrum-web-components/blob/main/CODE_OF_CONDUCT.md). By participating, you agree to treat all community members kindly and respectfully. We're committed to fostering a welcoming, inclusive environment. -Should any behavior fall short of these expectations, please report it to . - ---- - -## Developing locally - -Read the steps outlined in [Working in the SWC repo](?path=/docs/guides-contributor-guides-working-in-the-swc-repo--docs) to get your environment set up. - -If you encounter hurdles, feel free to ask for help in your pull request or in the community forum. - ---- - -## Thank you - -We appreciate everyone who invests time, energy, and expertise into Spectrum Web Components. Your contributions—big or small—help this library evolve to serve a broader audience and remain at a high standard of quality. - -If you have any suggestions for improving these guidelines, feel free to open a pull request or bring it up in our community discussions. We're always eager to make the contribution experience better. - -Happy contributing! diff --git a/2nd-gen/packages/swc/.storybook/preview.ts b/2nd-gen/packages/swc/.storybook/preview.ts index 1635ef7dc4..449d776a87 100644 --- a/2nd-gen/packages/swc/.storybook/preview.ts +++ b/2nd-gen/packages/swc/.storybook/preview.ts @@ -75,21 +75,21 @@ const preview = { 'First Gen vs Second Gen', ], 'Components', - [ - 'Gettiing involved', - 'Using the issue tracker', - 'Working in the SWC repo', - 'Making a pull request', - 'Participating in PR reviews', - 'Releasing SWC', - 'Authoring contributor docs', - 'Patching dependencies', - 'Accessibility testing', - ], 'Guides', [ 'Getting started guide', - 'Contributor guide', + 'Contributor guides', + [ + 'Gettiing involved', + 'Using the issue tracker', + 'Working in the SWC repo', + 'Making a pull request', + 'Participating in PR reviews', + 'Releasing SWC', + 'Authoring spectrum web component guides', + 'Patching dependencies', + 'Accessibility testing', + ], 'Style guide', 'Project planning', 'Accessibility guides', From 66da06cb17043184569453a64d24d9de31fd4ba3 Mon Sep 17 00:00:00 2001 From: Nikki Massaro Date: Tue, 9 Dec 2025 10:10:02 -0500 Subject: [PATCH 04/10] docs(contributor-guides): fixed MDX errors --- .../getting-involved.mdx} | 17 +-- .../using-the-issue-tracker.mdx | 121 +++++++++++++++++- .../components/badge/stories/badge.usage.mdx | 2 +- 3 files changed, 118 insertions(+), 22 deletions(-) rename 2nd-gen/packages/swc/.storybook/guides/{contributor-guide.mdx => contributor-guides/getting-involved.mdx} (94%) diff --git a/2nd-gen/packages/swc/.storybook/guides/contributor-guide.mdx b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/getting-involved.mdx similarity index 94% rename from 2nd-gen/packages/swc/.storybook/guides/contributor-guide.mdx rename to 2nd-gen/packages/swc/.storybook/guides/contributor-guides/getting-involved.mdx index 731384de69..10940b2c83 100644 --- a/2nd-gen/packages/swc/.storybook/guides/contributor-guide.mdx +++ b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/getting-involved.mdx @@ -1,9 +1,8 @@ import { Meta, Markdown } from '@storybook/addon-docs/blocks'; -import ReadMe from '../../../../../CONTRIBUTOR-DOCS/README.md?raw'; - + -# Contributor guides +# Gettiing involved ## Welcome @@ -28,8 +27,6 @@ If you need support or have a question about how something works, filing an issu If you work for Adobe, our Slack channel #spectrum_web_components has some great workflows to get you started. Be sure to read the Welcome Canvas when you join. ---- - ## How you can contribute There's a common misconception that you need to code in order to contribute. In reality, there are many different ways to help: @@ -43,20 +40,14 @@ There's a common misconception that you need to code in order to contribute. In Of course, contributing code is also welcome, from fixing a bug to building a brand-new component. All types of contributions help keep Spectrum Web Components thriving. ---- - ## Contributor license agreement We require all external contributors to sign our [Contributor License Agreement](https://opensource.adobe.com/cla.html) (CLA). If you haven't signed it before making your first contribution, please do so—otherwise, we can't merge your changes. ---- - ## Code of conduct Spectrum Web Components abides by the [Adobe Code of Conduct](https://github.com/adobe/spectrum-web-components/blob/main/CODE_OF_CONDUCT.md). By participating, you agree to treat all community members kindly and respectfully. We're committed to fostering a welcoming, inclusive environment. -Should any behavior fall short of these expectations, please report it to . - ---- +Should any behavior fall short of these expectations, please report it to [Grp-opensourceoffice@adobe.com](mailto:Grp-opensourceoffice@adobe.com). ## Developing locally @@ -64,8 +55,6 @@ Read the steps outlined in [Working in the SWC repo](?path=/docs/guides-contribu If you encounter hurdles, feel free to ask for help in your pull request or in the community forum. ---- - ## Thank you We appreciate everyone who invests time, energy, and expertise into Spectrum Web Components. Your contributions—big or small—help this library evolve to serve a broader audience and remain at a high standard of quality. diff --git a/2nd-gen/packages/swc/.storybook/guides/contributor-guides/using-the-issue-tracker.mdx b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/using-the-issue-tracker.mdx index c380da5d0a..24bb225086 100644 --- a/2nd-gen/packages/swc/.storybook/guides/contributor-guides/using-the-issue-tracker.mdx +++ b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/using-the-issue-tracker.mdx @@ -1,3 +1,5 @@ +import '@spectrum-web-components/table/elements.js'; + # Using the issue tracker We use GitHub Issues for two purposes: @@ -33,13 +35,118 @@ Clear bug reports speed up the triage process, help us replicate the issue, and Providing the correct issue severity classification helps us adequately assess and prioritize your issue. We reserve the right to adjust the severity of your bug during triage. Below is our issue severity classification criteria: -| Severity level | Description | Examples | -| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| 🔥 SEV 1 | A critical design or functionality issue that breaks the design system, causes significant usability problems, or exposes critical security vulnerabilities. This issue impacts all users and/or essential workflows, making users unable to complete any tasks. Requires immediate attention. | Broken navigation system, complete unresponsiveness on all devices, components not rendering, inaccessible primary actions, security vulnerabilities.

Accessibility: The end user is not able to complete core tasks or activities (e.g., key navigational elements not accessible via keyboard, missing or incorrect form labels that prevent screen reader users from completing forms or actions, critical color contrast issues that prevent users from reading or interacting with essential content). | -| 🔴 SEV 2 | A significant problem affecting the design, usability, or functionality of the system or components for a subset of users. This issue causes major disruptions and prevent users from completing tasks or workflows.

Accessibility: Does not conform with WCAG 2.1 Level AA criteria and blocks core user tasks (no known workaround). | Content that is out of view or unreachable by customers, critical buttons or links not functioning, or actions that cannot be submitted. Unintentional breaking changes causing disruptions in production environments.

Accessibility: Issue with a component or controller with widespread use and blocks core user tasks (no known workaround). | -| 🟠 SEV 3 | A design or functionality issue that causes noticeable errors or minor usability problems for users which either cause confusion or degrade the user experience, but do not prevent task completion.

Accessibility: Does not conform with WCAG 2.1 Level AA criteria and is either non-blocking for core user tasks or blocking for non-core user tasks. | Misleading labels, inconsistent component behavior, unexpected interactions, decreases in system performance.

Accessibility: Workarounds are available and discoverable for the end user to complete core user tasks, or the end user is not able to complete non-core user tasks (e.g., inadequate ARIA labels, improper focus management, insufficient color contrast for non-critical elements). | -| 🟡 SEV 4 | A minor design flaw that affects user experience, but doesn't have a serious impact on overall usability or functionality. This issue does not prevent users from completing tasks.

Accessibility: Does not conform with WCAG 2.1 Level AA criteria but has lower user impact. | Minor visual inconsistencies, non-critical content misalignment, or minor layout issues.

Accessibility: A WCAG violation is present in areas not frequently visited by end users, or it has a lower impact on overall accessibility and usability. | -| 🟢 SEV 5 | A low-level design inconsistency or minor issue that slightly affects usability or aesthetics, with minimal impact on users. | Slight color deviations, minor typographical errors, or small spacing inconsistencies that do not impact functionality. | + + + Severity level + Description + Examples + + + + 🔥 SEV 1 + + A critical design or functionality issue that breaks the design + system, causes significant usability problems, or exposes + critical security vulnerabilities. This issue impacts all users + and/or essential workflows, making users unable to complete any + tasks. Requires immediate attention. + + + Broken navigation system, complete unresponsiveness on all + devices, components not rendering, inaccessible primary actions, + security vulnerabilities. +
+
+ Accessibility: The end user is not able to complete core tasks + or activities (e.g., key navigational elements not accessible + via keyboard, missing or incorrect form labels that prevent + screen reader users from completing forms or actions, critical + color contrast issues that prevent users from reading or + interacting with essential content). + + + + 🔴 SEV 2 + + A significant problem affecting the design, usability, or + functionality of the system or components for a subset of users. + This issue causes major disruptions and prevent users from + completing tasks or workflows. +
+
+ Accessibility: Does not conform with WCAG 2.1 Level AA criteria + and blocks core user tasks (no known workaround). + + + Content that is out of view or unreachable by customers, + critical buttons or links not functioning, or actions that + cannot be submitted. Unintentional breaking changes causing + disruptions in production environments. +
+
+ Accessibility: Issue with a component or controller with + widespread use and blocks core user tasks (no known workaround). + + + + 🟠 SEV 3 + + A design or functionality issue that causes noticeable errors or + minor usability problems for users which either cause confusion + or degrade the user experience, but do not prevent task + completion. +
+
+ Accessibility: Does not conform with WCAG 2.1 Level AA criteria + and is either non-blocking for core user tasks or blocking for + non-core user tasks. + + + Misleading labels, inconsistent component behavior, unexpected + interactions, decreases in system performance. +
+
+ Accessibility: Workarounds are available and discoverable for + the end user to complete core user tasks, or the end user is not + able to complete non-core user tasks (e.g., inadequate ARIA + labels, improper focus management, insufficient color contrast + for non-critical elements). + + + + 🟡 SEV 4 + + A minor design flaw that affects user experience, but doesn't + have a serious impact on overall usability or functionality. + This issue does not prevent users from completing tasks. +
+
+ Accessibility: Does not conform with WCAG 2.1 Level AA criteria + but has lower user impact. + + + Minor visual inconsistencies, non-critical content misalignment, + or minor layout issues. +
+
+ Accessibility: A WCAG violation is present in areas not + frequently visited by end users, or it has a lower impact on + overall accessibility and usability. + + + + 🟢 SEV 5 + + A low-level design inconsistency or minor issue that slightly + affects usability or aesthetics, with minimal impact on users. + + + Slight color deviations, minor typographical errors, or small + spacing inconsistencies that do not impact functionality. + + + + ## Requesting a feature or a new component diff --git a/2nd-gen/packages/swc/components/badge/stories/badge.usage.mdx b/2nd-gen/packages/swc/components/badge/stories/badge.usage.mdx index c1ccaeebaf..761f6819b4 100644 --- a/2nd-gen/packages/swc/components/badge/stories/badge.usage.mdx +++ b/2nd-gen/packages/swc/components/badge/stories/badge.usage.mdx @@ -104,7 +104,7 @@ When a badge's label is too long for the available horizontal space, it wraps to The badge component implements several accessibility feature: -- **Color Meaning**: Colors are used in combination with text labels to ensure that status information is not conveyed through color alone. +- **Labeling**: Uses the `label` attribute value as `aria-label` #### Best Practices From e53259b5be1f692008b9f8e31b782088e0758cb1 Mon Sep 17 00:00:00 2001 From: Nikki Massaro Date: Tue, 9 Dec 2025 10:16:27 -0500 Subject: [PATCH 05/10] docs(contributor-guides): fixed TOC --- .../accessibility-testing.mdx | 4 + .../ai-agent-instructions.mdx | 284 ------------------ ...uthoring-spectrum-web-component-guides.mdx | 8 +- .../contributor-guides/contributor-guides.mdx | 3 - .../contributor-guides/getting-involved.mdx | 4 +- .../making-a-pull-request.mdx | 4 + .../participating-in-pr-reviews.mdx | 4 + .../patching-dependencies.mdx | 4 + .../contributor-guides/releasing-swc.mdx | 4 + .../using-the-issue-tracker.mdx | 3 + .../working-in-the-swc-repo.mdx | 4 + 11 files changed, 35 insertions(+), 291 deletions(-) delete mode 100644 2nd-gen/packages/swc/.storybook/guides/contributor-guides/ai-agent-instructions.mdx delete mode 100644 2nd-gen/packages/swc/.storybook/guides/contributor-guides/contributor-guides.mdx diff --git a/2nd-gen/packages/swc/.storybook/guides/contributor-guides/accessibility-testing.mdx b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/accessibility-testing.mdx index e7a8e1b469..f0d53e0b68 100644 --- a/2nd-gen/packages/swc/.storybook/guides/contributor-guides/accessibility-testing.mdx +++ b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/accessibility-testing.mdx @@ -1,3 +1,7 @@ +import { Meta } from '@storybook/addon-docs/blocks'; + + + # Accessibility testing ## About this guide diff --git a/2nd-gen/packages/swc/.storybook/guides/contributor-guides/ai-agent-instructions.mdx b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/ai-agent-instructions.mdx deleted file mode 100644 index b2e476059a..0000000000 --- a/2nd-gen/packages/swc/.storybook/guides/contributor-guides/ai-agent-instructions.mdx +++ /dev/null @@ -1,284 +0,0 @@ -# AI agent instructions - -This document defines two distinct roles for AI agents working with the CONTRIBUTOR-DOCS navigation system. - -## Role 1: Operator - -Run the regeneration script to update breadcrumbs and TOCs. - -### When to run - -Execute the script when: - -- A file or folder is added, removed, or renamed -- A file is moved to a different location -- Document H1 headings are changed (these become display names) -- Document H2/H3 headings are added, removed, or changed -- The folder structure changes -- A human maintainer or another AI agent requests it - -### How to run - -```bash -cd CONTRIBUTOR-DOCS/01_contributor-guides/07_authoring-contributor-docs -node update-nav.js ../../ -``` - -**Expected time:** ~20-200ms for entire CONTRIBUTOR-DOCS tree (includes automatic link verification) - -### Responsibilities - -1. **Execute** the script with appropriate parameters -2. **Verify success** - check that the script completed without errors -3. **Report results** - show the output summary (files updated, time taken) -4. **Debug if needed** - if errors occur, investigate and fix or report to the user - -### Debugging errors - -If the script fails: - -1. **Check the error message** - the script provides clear error output -2. **Verify file structure** - ensure all markdown files have the required marker -3. **Check file permissions** - ensure files are writable -4. **Validate markdown** - ensure H1 headings use proper syntax (`# Title`, not `##`) -5. **Report to user** - if you can't resolve, explain what you found - -### Debugging output issues - -When the auto-generated navigation appears incorrect or malformed: - -1. **First, investigate the script** - Check if the issue can be fixed by updating `update-nav.js` - - Read the script to understand how it processes the problematic content - - Look for edge cases or patterns it doesn't handle correctly - - Consider whether a fix to the script would allow the current document structure to work - -2. **Only suggest content changes as a last resort** - Don't immediately suggest modifying document content - - Document authors may have good reasons for their structure choices - - Script improvements benefit all documents, not just one - - Content changes may limit what authors can express in their docs - -3. **Example**: If headings with links generate malformed TOC entries: - - ✅ Good: Investigate the script's heading extraction, find it doesn't strip link syntax, add a fix - - ❌ Bad: Tell the user to remove links from their headings - -**Philosophy:** The script should adapt to reasonable document structures, not the other way around. - -### Handling link verification errors - -The script automatically verifies all internal markdown links after updating navigation. When broken links are found, they are reported in the script output with structured error details. - -**Your role as an AI agent:** - -1. **Analyze each error** - Review the error details provided by the script -2. **Fix straightforward cases automatically** - Don't ask for human input when the fix is clear: - - File was renamed/moved → Find new location in metadata and update link - - Anchor was renamed → Find matching or similar anchor in target file - - Wrong relative path depth → Recalculate correct relative path - - Case sensitivity issues → Fix capitalization - - Missing or incorrect file extension → Add `.md` extension if needed - -3. **Consult human for ambiguous cases** - Ask for guidance when: - - Target file was completely removed (need decision on alternative link target) - - Multiple possible anchor matches exist with similar names - - Link intent is unclear or may need conceptual rethinking - - You cannot determine the correct fix with high confidence - -4. **Report fixes clearly** - After fixing, summarize: - - How many links were broken - - What fixes were applied - - Any remaining issues that need human review - -**Example workflow:** - -``` -Script reports: "File not found: ../migration/overview.md" -→ Search metadata for files matching "migration" or "overview" -→ Find: "03_project-planning/01_migration-status.md" -→ Update link with correct relative path -→ Report: "Fixed broken link: updated path to migration status doc" -``` - ---- - -## Role 2: Maintainer - -Review and update the regeneration script when requirements or specifications change. - -### Requirements and specifications - -The script's behavior is defined by: - -1. **Human maintainer instructions** (`human-maintainer-instructions.md`) - - File and folder naming conventions - - Numbering rules - - Document structure requirements - - Display name derivation rules - -2. **File structure conventions** (implicit in the codebase) - - README.md files as folder overviews - - Lowercase kebab-case naming - - Optional sequential numbering - - HTML comment markers for separating content - -3. **Output format requirements** - - Breadcrumb format and linking rules - - TOC structure ("In this doc" and "Beneath this doc" sections) - - Collapsible `
` elements - - GitHub-style anchor links - -### When to maintain - -Update the script when: - -- Naming or numbering conventions change -- Breadcrumb or TOC format requirements change -- New edge cases are discovered -- Display name derivation rules change -- File structure conventions evolve -- Performance optimizations are needed - -### Maintenance process - -1. **Review the change request** - - Understand what requirement or specification has changed - - Identify which part of the script needs updating - -2. **Update the script** (`update-nav.js`) - - Modify the relevant functions - - Maintain code quality and comments - - Preserve existing functionality where applicable - -3. **Test thoroughly** - - Run the script on the entire CONTRIBUTOR-DOCS tree - - Verify output matches new requirements - - Check that existing functionality still works - - Spot-check several files manually - -4. **Update documentation** - - Update this file if the operator role changes - - Update human maintainer instructions if conventions change - - Add comments in the script explaining non-obvious logic - -5. **Report changes** - - Summarize what was changed and why - - Note any breaking changes or new behaviors - - Provide examples of the new output format - -### Script architecture - -The script (`update-nav.js`) is organized into several sections: - -1. **Configuration** - Constants for markers and behavior settings -2. **Utility Functions** - Helper functions for text processing and code block detection -3. **Metadata Extraction** - Scans the documentation tree and builds relationships -4. **Navigation Generation** - Creates breadcrumbs and table of contents -5. **File Update** - Replaces auto-generated content while preserving manual edits - -For implementation details, see the script source code which includes inline comments explaining the logic. - ---- - -## Script behavior details - -### What the script does - -**Step 1: Extract metadata** (~10-15ms) - -- Walks the entire documentation tree -- Extracts H1 headings (used as display names) -- Extracts H2/H3 headings (for "In this doc" TOC section) -- Maps parent-child relationships -- Identifies folders with/without README files - -**Step 2: Generate navigation** (~2-4ms) -For each file: - -- Creates breadcrumbs linking to parent READMEs -- Creates "In this doc" TOC from H2/H3 headings -- Creates "Beneath this doc" TOC from child files/folders -- Wraps TOC in collapsible `
` element - -**Step 3: Update files** (~2-4ms) - -- Finds the content marker -- Replaces everything above it with new breadcrumbs and TOC -- Preserves all content below the marker -- Handles edge cases (duplicate markers in code blocks) - -**Step 4: Verify links** (~10-150ms) - -- Extracts all markdown links from document content (excluding auto-generated sections and code blocks) -- Validates that target files exist -- Validates that anchor references point to existing headings -- Reports any broken links with detailed error information - -### Breadcrumb format - -```markdown -[ROOT](../../README.md) / [Parent](../README.md) / Current Page -``` - -**Rules:** - -- Root is always `CONTRIBUTOR-DOCS` linking to root README.md -- Parent folders link to their README.md (if it exists) -- Folders without README show as plain text (no link) -- Current page is plain text (not linked) -- Display names from H1 headings, not filenames - -### TOC format - -```markdown -
-Contents - -- **In this doc** - - [Section heading](#section-heading) -- **Beneath this doc** - - [Child file](./child.md) - - [Child folder](./folder/README.md) - -
-``` - -**Rules:** - -- Omit "In this doc" if no H2/H3 headings exist -- Omit "Beneath this doc" if no child files/folders exist -- Omit entire TOC if both sections would be empty -- Use GitHub-style anchors (lowercase, hyphens, no special chars) -- Recursively include grandchildren with proper indentation - -### Display name derivation - -**For files:** Extract H1 heading - -- `# Migration Status` → "Migration Status" - -**For folders with README:** Extract H1 from README.md - -- README contains `# Workstream Info` → "Workstream Info" - -**For folders without README:** Derive from folder name - -1. Remove number prefix: `02_project-planning` → `project-planning` -2. Replace hyphens with spaces: `project-planning` → `project planning` -3. Apply title case: `workstream info` → `Workstream Info` - ---- - -## Testing checklist - -After running or modifying the script: - -- [ ] Script completed without errors -- [ ] All files were updated (check the count in output) -- [ ] Link verification completed (check counts of valid/broken links) -- [ ] Spot-check breadcrumbs are correct and links work -- [ ] Spot-check TOCs reflect current structure -- [ ] Display names are human-readable (from H1 headings) -- [ ] Folders without README show as plain text (no link) -- [ ] Collapsible TOC sections work properly -- [ ] Manual content below the marker is preserved -- [ ] No trailing spaces or formatting issues -- [ ] Any broken links reported have been addressed diff --git a/2nd-gen/packages/swc/.storybook/guides/contributor-guides/authoring-spectrum-web-component-guides.mdx b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/authoring-spectrum-web-component-guides.mdx index 0cb40b2c8b..400c68f39c 100644 --- a/2nd-gen/packages/swc/.storybook/guides/contributor-guides/authoring-spectrum-web-component-guides.mdx +++ b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/authoring-spectrum-web-component-guides.mdx @@ -1,8 +1,12 @@ -# Authoring contributor guides +import { Meta } from '@storybook/addon-docs/blocks'; + + + +# Authoring SWC guides ## Overview -This document provides guidance for maintainers of the Spectrum Web Components contributor guides. The contributor guides are MDX files (`.mdx`) located in the `.storybook/guides/` directory and rendered through Storybook. +This document provides guidance for maintainers of the Spectrum Web Components guides. The SWC guides are MDX files (`.mdx`) located in the `.storybook/guides/` directory and rendered through Storybook. ## Writing & editing docs diff --git a/2nd-gen/packages/swc/.storybook/guides/contributor-guides/contributor-guides.mdx b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/contributor-guides.mdx deleted file mode 100644 index ab83302942..0000000000 --- a/2nd-gen/packages/swc/.storybook/guides/contributor-guides/contributor-guides.mdx +++ /dev/null @@ -1,3 +0,0 @@ -# Contributor guides - -(Content to be added) diff --git a/2nd-gen/packages/swc/.storybook/guides/contributor-guides/getting-involved.mdx b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/getting-involved.mdx index 10940b2c83..c7b225f396 100644 --- a/2nd-gen/packages/swc/.storybook/guides/contributor-guides/getting-involved.mdx +++ b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/getting-involved.mdx @@ -1,6 +1,6 @@ -import { Meta, Markdown } from '@storybook/addon-docs/blocks'; +import { Meta } from '@storybook/addon-docs/blocks'; - + # Gettiing involved diff --git a/2nd-gen/packages/swc/.storybook/guides/contributor-guides/making-a-pull-request.mdx b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/making-a-pull-request.mdx index f4c48cda02..b1035c4447 100644 --- a/2nd-gen/packages/swc/.storybook/guides/contributor-guides/making-a-pull-request.mdx +++ b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/making-a-pull-request.mdx @@ -1,3 +1,7 @@ +import { Meta } from '@storybook/addon-docs/blocks'; + + + # Making a pull request This document outlines our team's expectations and best practices for creating and submitting pull requests for Spectrum Web Components. diff --git a/2nd-gen/packages/swc/.storybook/guides/contributor-guides/participating-in-pr-reviews.mdx b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/participating-in-pr-reviews.mdx index 6f5dd9622d..85b19de289 100644 --- a/2nd-gen/packages/swc/.storybook/guides/contributor-guides/participating-in-pr-reviews.mdx +++ b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/participating-in-pr-reviews.mdx @@ -1,3 +1,7 @@ +import { Meta } from '@storybook/addon-docs/blocks'; + + + # Participating in PR reviews This document outlines our team's expectations and best practices for reviewing pull requests and participating in the PR review process for Spectrum Web Components. diff --git a/2nd-gen/packages/swc/.storybook/guides/contributor-guides/patching-dependencies.mdx b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/patching-dependencies.mdx index 9fb2e32e96..6bdaf9a903 100644 --- a/2nd-gen/packages/swc/.storybook/guides/contributor-guides/patching-dependencies.mdx +++ b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/patching-dependencies.mdx @@ -1,3 +1,7 @@ +import { Meta } from '@storybook/addon-docs/blocks'; + + + # Patching dependencies ## About patches diff --git a/2nd-gen/packages/swc/.storybook/guides/contributor-guides/releasing-swc.mdx b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/releasing-swc.mdx index 18e9b961cb..cfe0d9376b 100644 --- a/2nd-gen/packages/swc/.storybook/guides/contributor-guides/releasing-swc.mdx +++ b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/releasing-swc.mdx @@ -1,3 +1,7 @@ +import { Meta } from '@storybook/addon-docs/blocks'; + + + # Releasing SWC Users with permissions in the `@spectrum-web-components` organization on NPM can follow these steps to create and publish a new version. diff --git a/2nd-gen/packages/swc/.storybook/guides/contributor-guides/using-the-issue-tracker.mdx b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/using-the-issue-tracker.mdx index 24bb225086..f34fb99234 100644 --- a/2nd-gen/packages/swc/.storybook/guides/contributor-guides/using-the-issue-tracker.mdx +++ b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/using-the-issue-tracker.mdx @@ -1,5 +1,8 @@ +import { Meta } from '@storybook/addon-docs/blocks'; import '@spectrum-web-components/table/elements.js'; + + # Using the issue tracker We use GitHub Issues for two purposes: diff --git a/2nd-gen/packages/swc/.storybook/guides/contributor-guides/working-in-the-swc-repo.mdx b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/working-in-the-swc-repo.mdx index b5547f9687..3420b7a7ab 100644 --- a/2nd-gen/packages/swc/.storybook/guides/contributor-guides/working-in-the-swc-repo.mdx +++ b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/working-in-the-swc-repo.mdx @@ -1,3 +1,7 @@ +import { Meta } from '@storybook/addon-docs/blocks'; + + + # Working in the SWC repo ## About this guide From c96fda4adf74a14bb77915fb22d367a4ab2b833b Mon Sep 17 00:00:00 2001 From: Nikki Massaro Date: Tue, 9 Dec 2025 10:23:46 -0500 Subject: [PATCH 06/10] docs(contributor-guides): fixed typo --- .../guides/contributor-guides/making-a-pull-request.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/2nd-gen/packages/swc/.storybook/guides/contributor-guides/making-a-pull-request.mdx b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/making-a-pull-request.mdx index b1035c4447..1e3e38d963 100644 --- a/2nd-gen/packages/swc/.storybook/guides/contributor-guides/making-a-pull-request.mdx +++ b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/making-a-pull-request.mdx @@ -1,6 +1,6 @@ import { Meta } from '@storybook/addon-docs/blocks'; - + # Making a pull request From 91369bf7f88a78dbdd75e76b4b96ef51f415bfcc Mon Sep 17 00:00:00 2001 From: Nikki Massaro Date: Tue, 9 Dec 2025 10:24:51 -0500 Subject: [PATCH 07/10] docs(contributor-guides): fixed TOC --- 2nd-gen/packages/swc/.storybook/preview.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/2nd-gen/packages/swc/.storybook/preview.ts b/2nd-gen/packages/swc/.storybook/preview.ts index 449d776a87..c55165b719 100644 --- a/2nd-gen/packages/swc/.storybook/preview.ts +++ b/2nd-gen/packages/swc/.storybook/preview.ts @@ -86,7 +86,7 @@ const preview = { 'Making a pull request', 'Participating in PR reviews', 'Releasing SWC', - 'Authoring spectrum web component guides', + 'Authoring SWC guides', 'Patching dependencies', 'Accessibility testing', ], From 0075f8c45a3518dd6e0cd3bc1fe282108e3a1762 Mon Sep 17 00:00:00 2001 From: Nikki Massaro Date: Tue, 9 Dec 2025 13:07:13 -0500 Subject: [PATCH 08/10] docs(project-planning): migrated project-planning docs to storybook --- .../.storybook/guides/project-planning.mdx | 15 - .../guides/project-planning/components.mdx | 7 + .../guides/project-planning/milestones.mdx | 17 +- .../guides/project-planning/overview.mdx | 31 +- .../1st-gen-spectrum-2-enhancements.mdx | 7 + .../add-2nd-gen-swc-component.mdx | 8 +- .../add-stories-for-2nd-gen-swc-component.mdx | 8 +- ...tor-rendering-out-of-1st-gen-component.mdx | 8 +- .../formalize-spectrum-data-model.mdx | 8 +- ...rendering-and-styles-from-spectrum-css.mdx | 19 +- .../move-base-class-to-2nd-gen-code.mdx | 8 +- .../2nd-gen-component-migration/overview.mdx | 642 ++++++++++++++++++ .../2nd-gen-defnition-and-development.mdx | 10 +- .../workstreams/about-workstreams.mdx | 35 +- .../accessibility-improvements.mdx | 11 + .../workstreams/component-improvements.mdx | 12 + 2nd-gen/packages/swc/.storybook/preview.ts | 26 +- .../01_status.md | 80 --- .../02_2nd-gen-component-migration/README.md | 34 - .../03_accessibility-improvements/README.md | 15 - .../04_component-improvements/README.md | 16 - .../README.md | 11 - .../03_components/README.md | 11 - .../03_project-planning/README.md | 55 -- 24 files changed, 735 insertions(+), 359 deletions(-) delete mode 100644 2nd-gen/packages/swc/.storybook/guides/project-planning.mdx create mode 100644 2nd-gen/packages/swc/.storybook/guides/project-planning/components.mdx rename CONTRIBUTOR-DOCS/03_project-planning/04_milestones/README.md => 2nd-gen/packages/swc/.storybook/guides/project-planning/milestones.mdx (75%) rename CONTRIBUTOR-DOCS/03_project-planning/01_objectives-and-strategy.md => 2nd-gen/packages/swc/.storybook/guides/project-planning/overview.mdx (85%) create mode 100644 2nd-gen/packages/swc/.storybook/guides/project-planning/workstreams/1st-gen-spectrum-2-enhancements.mdx rename CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/04_implement-2nd-gen-component.md => 2nd-gen/packages/swc/.storybook/guides/project-planning/workstreams/2nd-gen-component-migration/add-2nd-gen-swc-component.mdx (69%) rename CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/06_add-stories-for-2nd-gen-component.md => 2nd-gen/packages/swc/.storybook/guides/project-planning/workstreams/2nd-gen-component-migration/add-stories-for-2nd-gen-swc-component.mdx (69%) rename CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_factor-rendering-out-of-1st-gen-component.md => 2nd-gen/packages/swc/.storybook/guides/project-planning/workstreams/2nd-gen-component-migration/factor-rendering-out-of-1st-gen-component.mdx (72%) rename CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/03_formalize-spectrum-data-model.md => 2nd-gen/packages/swc/.storybook/guides/project-planning/workstreams/2nd-gen-component-migration/formalize-spectrum-data-model.mdx (73%) rename CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/05_migrate-rendering-and-styles.md => 2nd-gen/packages/swc/.storybook/guides/project-planning/workstreams/2nd-gen-component-migration/migrate-rendering-and-styles-from-spectrum-css.mdx (89%) rename CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/02_move-base-class-to-2nd-gen-core.md => 2nd-gen/packages/swc/.storybook/guides/project-planning/workstreams/2nd-gen-component-migration/move-base-class-to-2nd-gen-code.mdx (58%) create mode 100644 2nd-gen/packages/swc/.storybook/guides/project-planning/workstreams/2nd-gen-component-migration/overview.mdx rename CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/01_2nd-gen-definition-and-development/README.md => 2nd-gen/packages/swc/.storybook/guides/project-planning/workstreams/2nd-gen-defnition-and-development.mdx (62%) rename CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/README.md => 2nd-gen/packages/swc/.storybook/guides/project-planning/workstreams/about-workstreams.mdx (60%) create mode 100644 2nd-gen/packages/swc/.storybook/guides/project-planning/workstreams/accessibility-improvements.mdx create mode 100644 2nd-gen/packages/swc/.storybook/guides/project-planning/workstreams/component-improvements.mdx delete mode 100644 CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/01_status.md delete mode 100644 CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/README.md delete mode 100644 CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/03_accessibility-improvements/README.md delete mode 100644 CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/04_component-improvements/README.md delete mode 100644 CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/05_1st-gen-spectrum-2-enhancements/README.md delete mode 100644 CONTRIBUTOR-DOCS/03_project-planning/03_components/README.md delete mode 100644 CONTRIBUTOR-DOCS/03_project-planning/README.md diff --git a/2nd-gen/packages/swc/.storybook/guides/project-planning.mdx b/2nd-gen/packages/swc/.storybook/guides/project-planning.mdx deleted file mode 100644 index d5a87b28c3..0000000000 --- a/2nd-gen/packages/swc/.storybook/guides/project-planning.mdx +++ /dev/null @@ -1,15 +0,0 @@ -import { Meta } from '@storybook/addon-docs/blocks'; - - - -# Project planning - -This guide will help you understand the project planning for SWC. - -## What is the project planning? - -The project planning is a set of rules that help you write code that is consistent with the SWC style. - -## What are the rules? - -The rules are: diff --git a/2nd-gen/packages/swc/.storybook/guides/project-planning/components.mdx b/2nd-gen/packages/swc/.storybook/guides/project-planning/components.mdx new file mode 100644 index 0000000000..f1248be2b5 --- /dev/null +++ b/2nd-gen/packages/swc/.storybook/guides/project-planning/components.mdx @@ -0,0 +1,7 @@ +import { Meta } from '@storybook/addon-docs/blocks'; + + + +# Components + +(Content to be added) diff --git a/CONTRIBUTOR-DOCS/03_project-planning/04_milestones/README.md b/2nd-gen/packages/swc/.storybook/guides/project-planning/milestones.mdx similarity index 75% rename from CONTRIBUTOR-DOCS/03_project-planning/04_milestones/README.md rename to 2nd-gen/packages/swc/.storybook/guides/project-planning/milestones.mdx index 8e41d57b09..b4634f883a 100644 --- a/CONTRIBUTOR-DOCS/03_project-planning/04_milestones/README.md +++ b/2nd-gen/packages/swc/.storybook/guides/project-planning/milestones.mdx @@ -1,22 +1,9 @@ - +import { Meta } from '@storybook/addon-docs/blocks'; -[CONTRIBUTOR-DOCS](../../README.md) / [Project planning](../README.md) / Milestones - - + # Milestones - - -
-In this doc - -- [Barebones](#barebones) - -
- - - Project milestones represent significant checkpoints in our work, typically marking the completion of a major phase or the achievement of a strategic goal. ## Barebones diff --git a/CONTRIBUTOR-DOCS/03_project-planning/01_objectives-and-strategy.md b/2nd-gen/packages/swc/.storybook/guides/project-planning/overview.mdx similarity index 85% rename from CONTRIBUTOR-DOCS/03_project-planning/01_objectives-and-strategy.md rename to 2nd-gen/packages/swc/.storybook/guides/project-planning/overview.mdx index e0b23e0a05..e74a0fb270 100644 --- a/CONTRIBUTOR-DOCS/03_project-planning/01_objectives-and-strategy.md +++ b/2nd-gen/packages/swc/.storybook/guides/project-planning/overview.mdx @@ -1,29 +1,22 @@ - +import { Meta } from '@storybook/addon-docs/blocks'; -[CONTRIBUTOR-DOCS](../README.md) / [Project planning](README.md) / Objectives and strategy + - +# Overview -# Objectives and strategy - - +This section contains strategic planning documentation for the Spectrum Web Components project, including objectives, workstreams, component roadmaps, and milestones. -
-In this doc +The documentation here helps us: -- [Current objectives](#current-objectives) - - [Unify Spectrum CSS & Spectrum Web Components](#unify-spectrum-css--spectrum-web-components) - - [Build a clean foundation for future work](#build-a-clean-foundation-for-future-work) - - [Enable Spectrum 2 adoption](#enable-spectrum-2-adoption) - - [Improve accessibility](#improve-accessibility) - - [Continually improve components](#continually-improve-components) -- [Strategy](#strategy) - - [Disruptive vs. non-disruptive change](#disruptive-vs-non-disruptive-change) - - [Side-by-side development of 1st-gen and 2nd-gen](#side-by-side-development-of-1st-gen-and-2nd-gen) +- Understand the strategic context and goals driving our work +- Track progress across multiple workstreams +- Coordinate efforts that span multiple components +- Monitor individual component roadmaps and status +- Define and track project milestones -
+Together, these views help us manage the project roadmap, ensuring we make progress on strategic objectives while maintaining clarity about the state and evolution of individual components. - +# Objectives and strategy ## Current objectives diff --git a/2nd-gen/packages/swc/.storybook/guides/project-planning/workstreams/1st-gen-spectrum-2-enhancements.mdx b/2nd-gen/packages/swc/.storybook/guides/project-planning/workstreams/1st-gen-spectrum-2-enhancements.mdx new file mode 100644 index 0000000000..ea3dc307d4 --- /dev/null +++ b/2nd-gen/packages/swc/.storybook/guides/project-planning/workstreams/1st-gen-spectrum-2-enhancements.mdx @@ -0,0 +1,7 @@ +import { Meta } from '@storybook/addon-docs/blocks'; + + + +# 1st-gen Spectrum 2 Enhancements + +Ongoing refinement of the `spectrum-two` theme in 1st-gen as needed to deliver production-quality Spectrum 2 support for customers using 1st-gen components. diff --git a/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/04_implement-2nd-gen-component.md b/2nd-gen/packages/swc/.storybook/guides/project-planning/workstreams/2nd-gen-component-migration/add-2nd-gen-swc-component.mdx similarity index 69% rename from CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/04_implement-2nd-gen-component.md rename to 2nd-gen/packages/swc/.storybook/guides/project-planning/workstreams/2nd-gen-component-migration/add-2nd-gen-swc-component.mdx index e2ac26999f..e33aa09706 100644 --- a/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/04_implement-2nd-gen-component.md +++ b/2nd-gen/packages/swc/.storybook/guides/project-planning/workstreams/2nd-gen-component-migration/add-2nd-gen-swc-component.mdx @@ -1,13 +1,9 @@ - +import { Meta } from '@storybook/addon-docs/blocks'; -[CONTRIBUTOR-DOCS](../../../../README.md) / [Project planning](../../../README.md) / [Workstreams](../../README.md) / [2nd-gen Component Migration](../README.md) / Step By Step / Add 2nd-gen SWC component - - + # Add 2nd-gen SWC component - - - Create directory structure: `2nd-gen/packages/swc/components/[component]/` - Create `[Component].ts` file extending from `[Component]Base` - Import S2-specific types and constants from `[Component].types.ts` diff --git a/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/06_add-stories-for-2nd-gen-component.md b/2nd-gen/packages/swc/.storybook/guides/project-planning/workstreams/2nd-gen-component-migration/add-stories-for-2nd-gen-swc-component.mdx similarity index 69% rename from CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/06_add-stories-for-2nd-gen-component.md rename to 2nd-gen/packages/swc/.storybook/guides/project-planning/workstreams/2nd-gen-component-migration/add-stories-for-2nd-gen-swc-component.mdx index e546240abb..8228e9a6db 100644 --- a/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/06_add-stories-for-2nd-gen-component.md +++ b/2nd-gen/packages/swc/.storybook/guides/project-planning/workstreams/2nd-gen-component-migration/add-stories-for-2nd-gen-swc-component.mdx @@ -1,13 +1,9 @@ - +import { Meta } from '@storybook/addon-docs/blocks'; -[CONTRIBUTOR-DOCS](../../../../README.md) / [Project planning](../../../README.md) / [Workstreams](../../README.md) / [2nd-gen Component Migration](../README.md) / Step By Step / Add stories for 2nd-gen component - - + # Add stories for 2nd-gen component - - - Create `stories/[component].stories.ts` file - Add section headers: METADATA, STORIES, HELPER FUNCTIONS (if needed) - In METADATA section: diff --git a/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_factor-rendering-out-of-1st-gen-component.md b/2nd-gen/packages/swc/.storybook/guides/project-planning/workstreams/2nd-gen-component-migration/factor-rendering-out-of-1st-gen-component.mdx similarity index 72% rename from CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_factor-rendering-out-of-1st-gen-component.md rename to 2nd-gen/packages/swc/.storybook/guides/project-planning/workstreams/2nd-gen-component-migration/factor-rendering-out-of-1st-gen-component.mdx index d66da29bee..512300f753 100644 --- a/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_factor-rendering-out-of-1st-gen-component.md +++ b/2nd-gen/packages/swc/.storybook/guides/project-planning/workstreams/2nd-gen-component-migration/factor-rendering-out-of-1st-gen-component.mdx @@ -1,13 +1,9 @@ - +import { Meta } from '@storybook/addon-docs/blocks'; -[CONTRIBUTOR-DOCS](../../../../README.md) / [Project planning](../../../README.md) / [Workstreams](../../README.md) / [2nd-gen Component Migration](../README.md) / Step By Step / Factor rendering out of 1st-gen component - - + # Factor rendering out of 1st-gen component - - - Use `git mv` to rename `[Component].ts` to `[Component].base.ts` - Create a new `[Component].ts` file - In `[Component].base.ts`, edit the component definition to make it an abstract class named `[Component]Base` diff --git a/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/03_formalize-spectrum-data-model.md b/2nd-gen/packages/swc/.storybook/guides/project-planning/workstreams/2nd-gen-component-migration/formalize-spectrum-data-model.mdx similarity index 73% rename from CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/03_formalize-spectrum-data-model.md rename to 2nd-gen/packages/swc/.storybook/guides/project-planning/workstreams/2nd-gen-component-migration/formalize-spectrum-data-model.mdx index 72089ac19f..43b3b87500 100644 --- a/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/03_formalize-spectrum-data-model.md +++ b/2nd-gen/packages/swc/.storybook/guides/project-planning/workstreams/2nd-gen-component-migration/formalize-spectrum-data-model.mdx @@ -1,13 +1,9 @@ - +import { Meta } from '@storybook/addon-docs/blocks'; -[CONTRIBUTOR-DOCS](../../../../README.md) / [Project planning](../../../README.md) / [Workstreams](../../README.md) / [2nd-gen Component Migration](../README.md) / Step By Step / Formalize Spectrum data model - - + # Formalize Spectrum data model - - - Create a `[Component].types.ts` file in the `core/components/[component]` directory - Define shared constants (e.g., semantic variants, size values) - Define S1-specific constants and type unions diff --git a/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/05_migrate-rendering-and-styles.md b/2nd-gen/packages/swc/.storybook/guides/project-planning/workstreams/2nd-gen-component-migration/migrate-rendering-and-styles-from-spectrum-css.mdx similarity index 89% rename from CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/05_migrate-rendering-and-styles.md rename to 2nd-gen/packages/swc/.storybook/guides/project-planning/workstreams/2nd-gen-component-migration/migrate-rendering-and-styles-from-spectrum-css.mdx index 8cfeb7a373..835c5a1968 100644 --- a/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/05_migrate-rendering-and-styles.md +++ b/2nd-gen/packages/swc/.storybook/guides/project-planning/workstreams/2nd-gen-component-migration/migrate-rendering-and-styles-from-spectrum-css.mdx @@ -1,24 +1,9 @@ - +import { Meta } from '@storybook/addon-docs/blocks'; -[CONTRIBUTOR-DOCS](../../../../README.md) / [Project planning](../../../README.md) / [Workstreams](../../README.md) / [2nd-gen Component Migration](../README.md) / Step By Step / Migrate rendering & styles from Spectrum CSS - - + # Migrate rendering & styles from Spectrum CSS - - -
-In this doc - -- [[ TODO: Integrate this content ]](#-todo-integrate-this-content-) -- [Bring over styles from Spectrum CSS](#bring-over-styles-from-spectrum-css) -- [Update styles in the 2nd-generation component](#update-styles-in-the-2nd-generation-component) - -
- - - ## [ TODO: Integrate this content ] The following bits from the top-level migration guide outline need to be integrated into this doc: diff --git a/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/02_move-base-class-to-2nd-gen-core.md b/2nd-gen/packages/swc/.storybook/guides/project-planning/workstreams/2nd-gen-component-migration/move-base-class-to-2nd-gen-code.mdx similarity index 58% rename from CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/02_move-base-class-to-2nd-gen-core.md rename to 2nd-gen/packages/swc/.storybook/guides/project-planning/workstreams/2nd-gen-component-migration/move-base-class-to-2nd-gen-code.mdx index 3335f5e4bf..653005b2db 100644 --- a/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/02_move-base-class-to-2nd-gen-core.md +++ b/2nd-gen/packages/swc/.storybook/guides/project-planning/workstreams/2nd-gen-component-migration/move-base-class-to-2nd-gen-code.mdx @@ -1,13 +1,9 @@ - +import { Meta } from '@storybook/addon-docs/blocks'; -[CONTRIBUTOR-DOCS](../../../../README.md) / [Project planning](../../../README.md) / [Workstreams](../../README.md) / [2nd-gen Component Migration](../README.md) / Step By Step / Move base class to 2nd-gen core - - + # Move base class to 2nd-gen core - - - Create a directory for the component under `core/components` - Move `[Component].base.ts` file from 1st-gen - Add `index.ts` file diff --git a/2nd-gen/packages/swc/.storybook/guides/project-planning/workstreams/2nd-gen-component-migration/overview.mdx b/2nd-gen/packages/swc/.storybook/guides/project-planning/workstreams/2nd-gen-component-migration/overview.mdx new file mode 100644 index 0000000000..de2dd3fb36 --- /dev/null +++ b/2nd-gen/packages/swc/.storybook/guides/project-planning/workstreams/2nd-gen-component-migration/overview.mdx @@ -0,0 +1,642 @@ +import { Meta } from '@storybook/addon-docs/blocks'; + + + +# Overview + +The tactical process of migrating individual components to the multi-generation architecture: + +- Refactoring 1st-gen components to separate core functionality from generation-specific rendering +- Moving base classes into 2nd-gen Core +- Building corresponding 2nd-gen implementations +- Migrating styles from the Spectrum CSS repository + +Because our 1st-gen components vary in complexity and quality—some have known issues (a11y and otherwise) that we believe will require substantial changes or rewrites—we will add classes to 2nd-gen Core incrementally, based on component-specific roadmaps we'll build in parallel with spinning up the 2nd-gen project. + +## Status + + + + Component + Factor component + Move to core + Add data model + Add 2nd-gen + Render & style + Add stories + + + + Accordion + + + + + + + + + Action Bar + + + + + + + + + Action Button + + + + + + + + + Action Group + + + + + + + + + Action Menu + + + + + + + + + Alert Banner + ✓ + + + + + + + + Alert Dialog + + + + + + + + + Asset + ✓ + + + + + + + + Avatar + + + + + + + + + Badge + ✓ + ✓ + ✓ + ✓ + ✓ + ✓ + + + Breadcrumbs + + + + + + + + + Button + + + + + + + + + Button Group + + + + + + + + + Card + + + + + + + + + Checkbox + + + + + + + + + Clear Button + + + + + + + + + Close Button + + + + + + + + + Coachmark + + + + + + + + + Color Area + + + + + + + + + Color Field + + + + + + + + + Color Handle + + + + + + + + + Color Loupe + + + + + + + + + Color Slider + + + + + + + + + Color Wheel + + + + + + + + + Combobox + + + + + + + + + Contextual Help + + + + + + + + + Dialog + + + + + + + + + Divider + ✓ + ✓ + ✓ + ✓ + ✓ + ✓ + + + Dropzone + + + + + + + + + Field Group + + + + + + + + + Field Label + + + + + + + + + Help Text + + + + + + + + + Icon + + + + + + + + + Icons + + + + + + + + + Icons UI + + + + + + + + + Icons Workflow + + + + + + + + + Iconset + + + + + + + + + Illustrated Message + + + + + + + + + Infield Button + + + + + + + + + Link + + + + + + + + + Menu + + + + + + + + + Meter + + + + + + + + + Modal + + + + + + + + + Number Field + + + + + + + + + Overlay + + + + + + + + + Picker + + + + + + + + + Picker Button + + + + + + + + + Popover + + + + + + + + + Progress Bar + + + + + + + + + Progress Circle + ✓ + ✓ + ✓ + ✓ + ✓ + ✓ + + + Radio + + + + + + + + + Search + + + + + + + + + Sidenav + + + + + + + + + Slider + + + + + + + + + Split View + + + + + + + + + Status Light + ✓ + ✓ + ✓ + ✓ + ✓ + ✓ + + + Swatch + + + + + + + + + Switch + + + + + + + + + Table + + + + + + + + + Tabs + + + + + + + + + Tags + + + + + + + + + Textfield + + + + + + + + + Thumbnail + + + + + + + + + Toast + + + + + + + + + Tooltip + + + + + + + + + Top Nav + + + + + + + + + Tray + + + + + + + + + Underlay + + + + + + + + + diff --git a/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/01_2nd-gen-definition-and-development/README.md b/2nd-gen/packages/swc/.storybook/guides/project-planning/workstreams/2nd-gen-defnition-and-development.mdx similarity index 62% rename from CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/01_2nd-gen-definition-and-development/README.md rename to 2nd-gen/packages/swc/.storybook/guides/project-planning/workstreams/2nd-gen-defnition-and-development.mdx index 1647600920..dc8864c4af 100644 --- a/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/01_2nd-gen-definition-and-development/README.md +++ b/2nd-gen/packages/swc/.storybook/guides/project-planning/workstreams/2nd-gen-defnition-and-development.mdx @@ -1,12 +1,8 @@ - +import { Meta } from '@storybook/addon-docs/blocks'; -[CONTRIBUTOR-DOCS](../../../README.md) / [Project planning](../../README.md) / [Workstreams](../README.md) / 2nd-gen Definition and Development + - - -# 2nd-gen Definition and Development - - +# 2nd-gen definition and development Building the 2nd-gen project from the ground up as a clean foundation for future work. This workstream encompasses multiple parallel efforts: diff --git a/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/README.md b/2nd-gen/packages/swc/.storybook/guides/project-planning/workstreams/about-workstreams.mdx similarity index 60% rename from CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/README.md rename to 2nd-gen/packages/swc/.storybook/guides/project-planning/workstreams/about-workstreams.mdx index aa788467cb..4911130886 100644 --- a/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/README.md +++ b/2nd-gen/packages/swc/.storybook/guides/project-planning/workstreams/about-workstreams.mdx @@ -1,37 +1,8 @@ - +import { Meta } from '@storybook/addon-docs/blocks'; -[CONTRIBUTOR-DOCS](../../README.md) / [Project planning](../README.md) / Workstreams + - - -# Workstreams - - - -
-In this doc - -- [About workstreams](#about-workstreams) -- [Active workstreams](#active-workstreams) - -
- -
-Beneath this doc - -- [2nd-gen Definition and Development](01_2nd-gen-definition-and-development/README.md) -- [2nd-gen Component Migration](02_2nd-gen-component-migration/README.md) - - [Status](02_2nd-gen-component-migration/01_status.md) - - Step By Step -- [Accessibility Improvements](03_accessibility-improvements/README.md) -- [Component Improvements](04_component-improvements/README.md) -- [1st-gen Spectrum 2 Enhancements](05_1st-gen-spectrum-2-enhancements/README.md) - -
- - - -## About workstreams +# About workstreams Workstreams represent our strategic objectives translated into actionable work. Each workstream defines a coherent body of work toward a specific goal, with its own scope, approach, and priorities. diff --git a/2nd-gen/packages/swc/.storybook/guides/project-planning/workstreams/accessibility-improvements.mdx b/2nd-gen/packages/swc/.storybook/guides/project-planning/workstreams/accessibility-improvements.mdx new file mode 100644 index 0000000000..f490145df3 --- /dev/null +++ b/2nd-gen/packages/swc/.storybook/guides/project-planning/workstreams/accessibility-improvements.mdx @@ -0,0 +1,11 @@ +import { Meta } from '@storybook/addon-docs/blocks'; + + + +# Accessibility Improvements + +Systematic work to maximize accessibility across all components: + +- Expanding documentation and examples +- Conducting comprehensive accessibility audits +- Addressing identified issues diff --git a/2nd-gen/packages/swc/.storybook/guides/project-planning/workstreams/component-improvements.mdx b/2nd-gen/packages/swc/.storybook/guides/project-planning/workstreams/component-improvements.mdx new file mode 100644 index 0000000000..ea5a2b7c5c --- /dev/null +++ b/2nd-gen/packages/swc/.storybook/guides/project-planning/workstreams/component-improvements.mdx @@ -0,0 +1,12 @@ +import { Meta } from '@storybook/addon-docs/blocks'; + + + +# Component Improvements + +Ongoing enhancements to components: + +- Bug fixes +- Feature additions +- API clarity and consistency improvements +- Major refactoring or replacement as needed diff --git a/2nd-gen/packages/swc/.storybook/preview.ts b/2nd-gen/packages/swc/.storybook/preview.ts index c55165b719..eb129dfe14 100644 --- a/2nd-gen/packages/swc/.storybook/preview.ts +++ b/2nd-gen/packages/swc/.storybook/preview.ts @@ -55,8 +55,8 @@ const preview = { page: DocumentTemplate, toc: { contentsSelector: '.sbdocs-content', - headingSelector: 'h2:not(.demo), h3:not(.demo), h4:not(.demo)', - ignoreSelector: '.sbdocs-subtitle', + headingSelector: 'h2, h3, h4', + ignoreSelector: '.sbdocs-subtitle, .sbdocs-preview', disable: false, unsafeTocbotOptions: { // orderedList: false, @@ -92,6 +92,28 @@ const preview = { ], 'Style guide', 'Project planning', + [ + 'Overview', + 'Components', + 'Milestones', + 'Workstreams', + [ + 'About workstreams', + '2nd-gen definition and development', + '2nd-gen component migration', + [ + 'Overview', + 'Factor rendering out of 1st-gen component', + 'Move base class to 2nd-gen core', + 'Formalize Spectrum data model', + 'Add 2nd-gen component', + 'Migrate rendering and styles', + ], + 'Accessibility improvements', + 'Component improvements', + '1st-gen Spectrum 2 enhancements', + ], + ], 'Accessibility guides', [ 'Overview', diff --git a/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/01_status.md b/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/01_status.md deleted file mode 100644 index cfe71e7e79..0000000000 --- a/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/01_status.md +++ /dev/null @@ -1,80 +0,0 @@ - - -[CONTRIBUTOR-DOCS](../../../README.md) / [Project planning](../../README.md) / [Workstreams](../README.md) / [2nd-gen Component Migration](README.md) / Status - - - -# Status - - - -| Component | [Factor Component](02_step-by-step/01_factor-rendering-out-of-1st-gen-component.md) | [Move to Core](02_step-by-step/02_move-base-class-to-2nd-gen-core.md) | [Add Data Model](02_step-by-step/03_formalize-spectrum-data-model.md) | [Add 2nd-Gen](02_step-by-step/04_implement-2nd-gen-component.md) | [Render & Style](02_step-by-step/05_migrate-rendering-and-styles.md) | [Add Stories](02_step-by-step/06_add-stories-for-2nd-gen-component.md) | -| ------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------- | -| Accordion | | | | | | | -| Action Bar | | | | | | | -| Action Button | | | | | | | -| Action Group | | | | | | | -| Action Menu | | | | | | | -| Alert Banner | ✓ | | | | | | -| Alert Dialog | | | | | | | -| Asset | ✓ | | | | | | -| Avatar | | | | | | | -| Badge | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Breadcrumbs | | | | | | | -| Button | | | | | | | -| Button Group | | | | | | | -| Card | | | | | | | -| Checkbox | | | | | | | -| Clear Button | | | | | | | -| Close Button | | | | | | | -| Coachmark | | | | | | | -| Color Area | | | | | | | -| Color Field | | | | | | | -| Color Handle | | | | | | | -| Color Loupe | | | | | | | -| Color Slider | | | | | | | -| Color Wheel | | | | | | | -| Combobox | | | | | | | -| Contextual Help | | | | | | | -| Dialog | | | | | | | -| Divider | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Dropzone | | | | | | | -| Field Group | | | | | | | -| Field Label | | | | | | | -| Help Text | | | | | | | -| Icon | | | | | | | -| Icons | | | | | | | -| Icons UI | | | | | | | -| Icons Workflow | | | | | | | -| Iconset | | | | | | | -| Illustrated Message | | | | | | | -| Infield Button | | | | | | | -| Link | | | | | | | -| Menu | | | | | | | -| Meter | | | | | | | -| Modal | | | | | | | -| Number Field | | | | | | | -| Overlay | | | | | | | -| Picker | | | | | | | -| Picker Button | | | | | | | -| Popover | | | | | | | -| Progress Bar | | | | | | | -| Progress Circle | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Radio | | | | | | | -| Search | | | | | | | -| Sidenav | | | | | | | -| Slider | | | | | | | -| Split View | | | | | | | -| Status Light | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Swatch | | | | | | | -| Switch | | | | | | | -| Table | | | | | | | -| Tabs | | | | | | | -| Tags | | | | | | | -| Textfield | | | | | | | -| Thumbnail | | | | | | | -| Toast | | | | | | | -| Tooltip | | | | | | | -| Top Nav | | | | | | | -| Tray | | | | | | | -| Underlay | | | | | | | diff --git a/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/README.md b/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/README.md deleted file mode 100644 index a37f2ef264..0000000000 --- a/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/README.md +++ /dev/null @@ -1,34 +0,0 @@ - - -[CONTRIBUTOR-DOCS](../../../README.md) / [Project planning](../../README.md) / [Workstreams](../README.md) / 2nd-gen Component Migration - - - -# 2nd-gen Component Migration - - - -
-Beneath this doc - -- [Status](01_status.md) -- Step By Step - - [Factor rendering out of 1st-gen component](02_step-by-step/01_factor-rendering-out-of-1st-gen-component.md) - - [Move base class to 2nd-gen core](02_step-by-step/02_move-base-class-to-2nd-gen-core.md) - - [Formalize Spectrum data model](02_step-by-step/03_formalize-spectrum-data-model.md) - - [Add 2nd-gen SWC component](02_step-by-step/04_implement-2nd-gen-component.md) - - [Migrate rendering & styles from Spectrum CSS](02_step-by-step/05_migrate-rendering-and-styles.md) - - [Add stories for 2nd-gen component](02_step-by-step/06_add-stories-for-2nd-gen-component.md) - -
- - - -The tactical process of migrating individual components to the multi-generation architecture: - -- Refactoring 1st-gen components to separate core functionality from generation-specific rendering -- Moving base classes into 2nd-gen Core -- Building corresponding 2nd-gen implementations -- Migrating styles from the Spectrum CSS repository - -Because our 1st-gen components vary in complexity and quality—some have known issues (a11y and otherwise) that we believe will require substantial changes or rewrites—we will add classes to 2nd-gen Core incrementally, based on component-specific roadmaps we'll build in parallel with spinning up the 2nd-gen project. diff --git a/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/03_accessibility-improvements/README.md b/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/03_accessibility-improvements/README.md deleted file mode 100644 index 9d831c237d..0000000000 --- a/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/03_accessibility-improvements/README.md +++ /dev/null @@ -1,15 +0,0 @@ - - -[CONTRIBUTOR-DOCS](../../../README.md) / [Project planning](../../README.md) / [Workstreams](../README.md) / Accessibility Improvements - - - -# Accessibility Improvements - - - -Systematic work to maximize accessibility across all components: - -- Expanding documentation and examples -- Conducting comprehensive accessibility audits -- Addressing identified issues diff --git a/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/04_component-improvements/README.md b/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/04_component-improvements/README.md deleted file mode 100644 index 92b366b1bf..0000000000 --- a/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/04_component-improvements/README.md +++ /dev/null @@ -1,16 +0,0 @@ - - -[CONTRIBUTOR-DOCS](../../../README.md) / [Project planning](../../README.md) / [Workstreams](../README.md) / Component Improvements - - - -# Component Improvements - - - -Ongoing enhancements to components: - -- Bug fixes -- Feature additions -- API clarity and consistency improvements -- Major refactoring or replacement as needed diff --git a/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/05_1st-gen-spectrum-2-enhancements/README.md b/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/05_1st-gen-spectrum-2-enhancements/README.md deleted file mode 100644 index 2e40cb29b5..0000000000 --- a/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/05_1st-gen-spectrum-2-enhancements/README.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[CONTRIBUTOR-DOCS](../../../README.md) / [Project planning](../../README.md) / [Workstreams](../README.md) / 1st-gen Spectrum 2 Enhancements - - - -# 1st-gen Spectrum 2 Enhancements - - - -Ongoing refinement of the `spectrum-two` theme in 1st-gen as needed to deliver production-quality Spectrum 2 support for customers using 1st-gen components. diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/README.md b/CONTRIBUTOR-DOCS/03_project-planning/03_components/README.md deleted file mode 100644 index 158eded19c..0000000000 --- a/CONTRIBUTOR-DOCS/03_project-planning/03_components/README.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[CONTRIBUTOR-DOCS](../../README.md) / [Project planning](../README.md) / Components - - - -# Components - - - -(Content to be added) diff --git a/CONTRIBUTOR-DOCS/03_project-planning/README.md b/CONTRIBUTOR-DOCS/03_project-planning/README.md deleted file mode 100644 index d81428d75b..0000000000 --- a/CONTRIBUTOR-DOCS/03_project-planning/README.md +++ /dev/null @@ -1,55 +0,0 @@ - - -[CONTRIBUTOR-DOCS](../README.md) / Project planning - - - -# Project planning - - - -
-In this doc - -- [Contents](#contents) - -
- -
-Beneath this doc - -- [Objectives and strategy](01_objectives-and-strategy.md) -- [Workstreams](02_workstreams/README.md) - - [2nd-gen Definition and Development](02_workstreams/01_2nd-gen-definition-and-development/README.md) - - [2nd-gen Component Migration](02_workstreams/02_2nd-gen-component-migration/README.md) - - [Accessibility Improvements](02_workstreams/03_accessibility-improvements/README.md) - - [Component Improvements](02_workstreams/04_component-improvements/README.md) - - [1st-gen Spectrum 2 Enhancements](02_workstreams/05_1st-gen-spectrum-2-enhancements/README.md) -- [Components](03_components/README.md) -- [Milestones](04_milestones/README.md) - -
- - - -This section contains strategic planning documentation for the Spectrum Web Components project, including objectives, workstreams, component roadmaps, and milestones. - -The documentation here helps us: - -- Understand the strategic context and goals driving our work -- Track progress across multiple workstreams -- Coordinate efforts that span multiple components -- Monitor individual component roadmaps and status -- Define and track project milestones - -## Contents - -- **[Objectives and Strategy](./01_objectives-and-strategy.md)** - Strategic context for the 1st-gen-to-2nd-gen transition, including our goals and approach. - -- **[Workstreams](./02_workstreams/README.md)** - Detailed information about our active workstreams, offering a workstream-centric view of cross-cutting work affecting many or all components. - -- **[Components](./03_components/README.md)** - Component-specific planning and status information, offering a component-centric view of how individual components are affected by multiple workstreams. - -- **[Milestones](./04_milestones/README.md)** - Information about project milestones and their goals. - -Together, these views help us manage the project roadmap, ensuring we make progress on strategic objectives while maintaining clarity about the state and evolution of individual components. From f3739e39dbf453e95072d5e01488047667d9afd7 Mon Sep 17 00:00:00 2001 From: Nikki Massaro Date: Tue, 9 Dec 2025 13:10:45 -0500 Subject: [PATCH 09/10] docs(project-planning): fixed typo --- .../.storybook/guides/contributor-guides/getting-involved.mdx | 4 ++-- 2nd-gen/packages/swc/.storybook/preview.ts | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/2nd-gen/packages/swc/.storybook/guides/contributor-guides/getting-involved.mdx b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/getting-involved.mdx index c7b225f396..0e2b83fea1 100644 --- a/2nd-gen/packages/swc/.storybook/guides/contributor-guides/getting-involved.mdx +++ b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/getting-involved.mdx @@ -1,8 +1,8 @@ import { Meta } from '@storybook/addon-docs/blocks'; - + -# Gettiing involved +# Getting involved ## Welcome diff --git a/2nd-gen/packages/swc/.storybook/preview.ts b/2nd-gen/packages/swc/.storybook/preview.ts index eb129dfe14..834ed8ba62 100644 --- a/2nd-gen/packages/swc/.storybook/preview.ts +++ b/2nd-gen/packages/swc/.storybook/preview.ts @@ -80,7 +80,7 @@ const preview = { 'Getting started guide', 'Contributor guides', [ - 'Gettiing involved', + 'Getting involved', 'Using the issue tracker', 'Working in the SWC repo', 'Making a pull request', From 9444ee56d3ad813bf4a669020f146634986794c7 Mon Sep 17 00:00:00 2001 From: Nikki Massaro Date: Tue, 9 Dec 2025 13:17:16 -0500 Subject: [PATCH 10/10] docs(guides): fixed links --- .../guides/accessibility-guides/overview.mdx | 4 ++-- .../contributor-guides/working-in-the-swc-repo.mdx | 2 +- .../workstreams/about-workstreams.mdx | 12 ++++++------ 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/overview.mdx b/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/overview.mdx index 45fe046371..07f3de2a73 100644 --- a/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/overview.mdx +++ b/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/overview.mdx @@ -34,7 +34,7 @@ Building accessible software is simply the right thing to do. Digital content ha Many jurisdictions have legal requirements for digital accessibility: -- **[Americans with Disabilities Act (ADA)](hhttps://www.ada.gov/topics/intro-to-ada/)** requires federal and state government entities as well as private entities that own, operate, lease, or lease to places of public accommodation must be accessible to people with disabilities +- **[Americans with Disabilities Act (ADA)](https://www.ada.gov/topics/intro-to-ada/)** requires federal and state government entities as well as private entities that own, operate, lease, or lease to places of public accommodation must be accessible to people with disabilities - **[Section 508](https://www.section508.gov/)** applies to US federal government entities but impacts any entity that does buisness with the US federal government - **[European Accessibility Act](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=COM%3A2015%3A0615%3AFINa)** establishes accessbility standards for the EU; applies to "applies to any business’s product or service that is sold or in use within the Eurozone, not just EU member state businesses" [deque blog post](https://www.deque.com/blog/eu-web-accessibility-compliance-and-legislation/) - **[Accessibility for Ontarians with Disabilities Act (AODA)](https://www.ontario.ca/laws/statute/05a11a)** "applies to every person or organization in the public and private sectors of the Province of Ontario, including the Legislative Assembly of Ontario" to comply with defined accessbility guidelines for EU member states @@ -84,7 +84,7 @@ Users interact with web components using various assistive technologies: - **[JAWS](https://www.freedomscientific.com/products/software/jaws/)**: Popular Windows screen reader, often used with Chrome or Edge browsers - **[NVDA](https://www.nvaccess.org/about-nvda/)**: Free, open-source Windows screen reader, often used with Firefox browsers -- **[VoiceOver](hhttps://support.apple.com/guide/voiceover/turn-voiceover-on-or-off-vo2682/mac)**: Built-in screen reader for macOS and iOS, often used with Safari browsers +- **[VoiceOver](https://support.apple.com/guide/voiceover/turn-voiceover-on-or-off-vo2682/mac)**: Built-in screen reader for macOS and iOS, often used with Safari browsers - **[TalkBack](https://support.google.com/accessibility/android/answer/6007100?hl=en)**: Built-in screen reader for Android, often used with Chrome browsers - **[Narrator](https://support.microsoft.com/en-us/windows/complete-guide-to-narrator-e4397a0d-ef4f-b386-d8ae-c172f109bdb1)**: Built-in Windows screen reader, often used with Edge browsers diff --git a/2nd-gen/packages/swc/.storybook/guides/contributor-guides/working-in-the-swc-repo.mdx b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/working-in-the-swc-repo.mdx index 3420b7a7ab..f284f4abeb 100644 --- a/2nd-gen/packages/swc/.storybook/guides/contributor-guides/working-in-the-swc-repo.mdx +++ b/2nd-gen/packages/swc/.storybook/guides/contributor-guides/working-in-the-swc-repo.mdx @@ -37,7 +37,7 @@ yarn install SWC is currently in transition from its first generation (**1st-gen**) to its second generation (**2nd-gen**). -> This transition is motivated by some important strategic goals. For more information, see [Objectives and Strategy](?path=/docs/guides-project-planning--docs). +> This transition is motivated by some important strategic goals. For more information, see [Objectives and Strategy](?path=/docs/project-planning-overview--docs). Instead of creating a separate branch or repo for 2nd-gen, we are working on the 1st-gen and 2nd-gen projects side-by-side in this repository, with some core functionality being shared between 1st- and 2nd-gen components. This strategy makes it easier for us to continue actively improving and supporting 1st-gen even as we devote much of our attention to defining and building 2nd-gen. diff --git a/2nd-gen/packages/swc/.storybook/guides/project-planning/workstreams/about-workstreams.mdx b/2nd-gen/packages/swc/.storybook/guides/project-planning/workstreams/about-workstreams.mdx index 4911130886..4c9aa97075 100644 --- a/2nd-gen/packages/swc/.storybook/guides/project-planning/workstreams/about-workstreams.mdx +++ b/2nd-gen/packages/swc/.storybook/guides/project-planning/workstreams/about-workstreams.mdx @@ -8,16 +8,16 @@ Workstreams represent our strategic objectives translated into actionable work. This section of the contributor docs contains detailed information about each of our active workstreams. -For more on how Workstreams (this section) and [Components](../03_components/README.md) provide complementary views of our work, see the [Project Planning overview](../README.md). +For more on how Workstreams (this section) and [Components](?path=/docs/project-planning-components--docs) provide complementary views of our work, see the [Project Planning overview](?path=/docs/project-planning-overview--docs). ## Active workstreams -- **[2nd-gen Definition and Development](./01_2nd-gen-definition-and-development/README.md)** - Building the 2nd-gen project from the ground up, including rendering layer, tooling, infrastructure, tests, Storybook, and documentation. +- **[2nd-gen Definition and Development](?path=/docs/project-planning-workstreams-2nd-gen-definition-and-development--docs)** - Building the 2nd-gen project from the ground up, including rendering layer, tooling, infrastructure, tests, Storybook, and documentation. -- **[2nd-gen Component Migration](./02_2nd-gen-component-migration/README.md)** - Tactical process of migrating individual components to enable core functionality sharing between 1st-gen and 2nd-gen. +- **[2nd-gen Component Migration](?path=/docs/project-planning-workstreams-2nd-gen-component-migration-overview--docs)** - Tactical process of migrating individual components to enable core functionality sharing between 1st-gen and 2nd-gen. -- **[Accessibility Improvements](./03_accessibility-improvements/README.md)** - Systematic work to maximize accessibility through expanded documentation, comprehensive audits, and issue remediation. +- **[Accessibility Improvements](?path=/docs/project-planning-workstreams-accessibility-improvements--docs)** - Systematic work to maximize accessibility through expanded documentation, comprehensive audits, and issue remediation. -- **[Component Improvements](./04_component-improvements/README.md)** - Ongoing enhancements including bug fixes, feature additions, API improvements, and refactoring. +- **[Component Improvements](?path=/docs/project-planning-workstreams-component-improvements--docs)** - Ongoing enhancements including bug fixes, feature additions, API improvements, and refactoring. -- **[1st-gen Spectrum 2 Enhancements](./05_1st-gen-spectrum-2-enhancements/README.md)** - Ongoing refinement of the `spectrum-two` theme for 1st-gen customers. +- **[1st-gen Spectrum 2 Enhancements](?path=/docs/project-planning-workstreams-1st-gen-spectrum-2-enhancements--docs)** - Ongoing refinement of the `spectrum-two` theme for 1st-gen customers.