diff --git a/.ai/README.md b/.ai/README.md index 53f3cca0c4f..00c2cc3ea03 100644 --- a/.ai/README.md +++ b/.ai/README.md @@ -192,7 +192,7 @@ Skills are used on-demand. When a task matches a skill’s purpose, the agent re - **purpose**: Create accessibility migration analysis docs for the "analyze accessibility" step of 2nd-gen component migration - **How to invoke**: Say "create accessibility analysis for [component]", "analyze accessibility for [component]", or "accessibility migration for [component]". Also invoked when you refer to the "analyze accessibility" step in the 2nd-gen component migration workstream. -- Use when: On the analyze-accessibility step for one or more components; creating one markdown file per component at `CONTRIBUTOR-DOCS/03_project-planning/03_components/[component-name]/accessibility-migration-analysis.md` +- Use when: On the analyze-accessibility step for one or more components; creating one markdown file per component at `CONTRIBUTOR-DOCS/project-planning/03_components/[component-name]/accessibility-migration-analysis.md` - Applies to: `CONTRIBUTOR-DOCS/**/accessibility-migration-analysis.md` - Provides: Required section order, ARIA recommendations structure, Shadow DOM guidance, keyboard and focus conventions, testing table format, reference examples @@ -221,8 +221,8 @@ Skills are used on-demand. When a task matches a skill’s purpose, the agent re - **purpose**: Create rendering-and-styling migration analysis docs for the “analyze rendering and styling” step of 2nd-gen component migration - **How to invoke**: Say “create migration analysis for [component]”, “analyze rendering and styling for [component]”, or “rendering and styling migration for [component]”. Also invoked when you refer to the “analyze rendering and styling” step in the 2nd-gen component migration workstream. -- Use when: On the analyze-rendering-and-styling step for one or more components; creating one markdown file per component at `CONTRIBUTOR-DOCS/03_project-planning/03_components/[component-name]/rendering-and-styling-migration-analysis.md` -- Provides: Workflow summary (specs from CSS + SWC, three-way DOM comparison, CSS⇒SWC mapping table, summary). Full instructions in `CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_analyze-rendering-and-styling/cursor_prompt.md` +- Use when: On the analyze-rendering-and-styling step for one or more components; creating one markdown file per component at `CONTRIBUTOR-DOCS/project-planning/03_components/[component-name]/rendering-and-styling-migration-analysis.md` +- Provides: Workflow summary (specs from CSS + SWC, three-way DOM comparison, CSS⇒SWC mapping table, summary). Full instructions in `CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_analyze-rendering-and-styling/cursor_prompt.md` #### Consumer migration guide diff --git a/.ai/rules/contributor-doc-update.md b/.ai/rules/contributor-doc-update.md index dc83ef1e952..00f486c1677 100644 --- a/.ai/rules/contributor-doc-update.md +++ b/.ai/rules/contributor-doc-update.md @@ -25,7 +25,7 @@ alwaysApply: false 1. **Run the nav script** from the contributor docs script folder (from project root): ```bash - cd CONTRIBUTOR-DOCS/01_contributor-guides/07_authoring-contributor-docs + cd CONTRIBUTOR-DOCS/for-contributors/authoring-contributor-docs node update-nav.js ``` 2. **Confirm** the script completes without errors. diff --git a/.ai/rules/github-description.md b/.ai/rules/github-description.md index 219b003ff0c..b4e688e075c 100644 --- a/.ai/rules/github-description.md +++ b/.ai/rules/github-description.md @@ -227,7 +227,7 @@ Common additional labels include: **Required:** Complete each applicable item and document your testing steps (replace the placeholders with your component-specific instructions). diff --git a/.ai/rules/storybook-mdx-conversion.md b/.ai/rules/storybook-mdx-conversion.md index 12d86c72955..fdbe4ce1b58 100644 --- a/.ai/rules/storybook-mdx-conversion.md +++ b/.ai/rules/storybook-mdx-conversion.md @@ -25,7 +25,7 @@ yarn generate:contributor-docs It is wired into `yarn storybook` and `yarn storybook:build`, so a normal dev loop regenerates on every start. The script: - Walks `CONTRIBUTOR-DOCS/` and emits one `.mdx` per `.md` under `.storybook/contributor-docs/` -- Emits mirrored copies for files configured in `MIRROR_EMITS` (currently: `00_get-started/for-consumers.md` → `.storybook/get-started/index.mdx` with title `Get started`) +- Emits mirrored copies for files configured in `MIRROR_EMITS` (currently: `for-consumers/get-started.md` → `.storybook/get-started/index.mdx` with title `Get started`) - Strips the auto-generated breadcrumbs + TOC blocks (they belong on GitHub, not Storybook) - Rewrites `.md` links to Storybook `/docs/...` paths and source-file links to GitHub URLs - Sanitizes HTML for MDX (self-closes void elements, converts `` to `mailto:` links) diff --git a/.ai/rules/styles.md b/.ai/rules/styles.md index 4b45c735a97..21c177ad723 100644 --- a/.ai/rules/styles.md +++ b/.ai/rules/styles.md @@ -4,7 +4,7 @@ globs: *.css alwaysApply: true --- -1. Follow rules outlined in the `CONTRIBUTOR-DOCS/02_style-guide` style guide directory. +1. Follow rules outlined in the `CONTRIBUTOR-DOCS/for-contributors/style-guide` style guide directory. 2. Auto-fix results based on settings defined by the `../../stylelint.config.js` unless it requires rewriting more than 30% of the line. Changes that impact more than 30% of the original content should prompt for update. 3. Copyrights should reflect the current year. 4. Comments added should always use sentence, never title case. diff --git a/.ai/skills/accessibility-migration-analysis/SKILL.md b/.ai/skills/accessibility-migration-analysis/SKILL.md index 00a3f09b86b..d95d6fdc8c6 100644 --- a/.ai/skills/accessibility-migration-analysis/SKILL.md +++ b/.ai/skills/accessibility-migration-analysis/SKILL.md @@ -29,18 +29,18 @@ You are an accessibility auditor, not a documenter. Your job is to verify what t ### Output - **One markdown file per component** at: - `CONTRIBUTOR-DOCS/03_project-planning/03_components/[component-name]/accessibility-migration-analysis.md` + `CONTRIBUTOR-DOCS/project-planning/03_components/[component-name]/accessibility-migration-analysis.md` - **Pairing:** Link to `./rendering-and-styling-migration-analysis.md` from **Overview → Also read** -- **Nav:** After adding the file or changing `##` / `###` headings, run `node update-nav.js` from `CONTRIBUTOR-DOCS/01_contributor-guides/07_authoring-contributor-docs`. Register the doc in `03_components/README.md` when introducing a new component folder. +- **Nav:** After adding the file or changing `##` / `###` headings, run `node update-nav.js` from `CONTRIBUTOR-DOCS/for-contributors/authoring-contributor-docs`. Register the doc in `03_components/README.md` when introducing a new component folder. ### Reference examples (consistency) Use these existing docs when matching structure, headings, tables, and phrasing: -- `CONTRIBUTOR-DOCS/03_project-planning/03_components/badge/accessibility-migration-analysis.md` -- `CONTRIBUTOR-DOCS/03_project-planning/03_components/divider/accessibility-migration-analysis.md` -- `CONTRIBUTOR-DOCS/03_project-planning/03_components/progress-circle/accessibility-migration-analysis.md` -- `CONTRIBUTOR-DOCS/03_project-planning/03_components/status-light/accessibility-migration-analysis.md` +- `CONTRIBUTOR-DOCS/project-planning/03_components/badge/accessibility-migration-analysis.md` +- `CONTRIBUTOR-DOCS/project-planning/03_components/divider/accessibility-migration-analysis.md` +- `CONTRIBUTOR-DOCS/project-planning/03_components/progress-circle/accessibility-migration-analysis.md` +- `CONTRIBUTOR-DOCS/project-planning/03_components/status-light/accessibility-migration-analysis.md` ### Important diff --git a/.ai/skills/component-migration-analysis/SKILL.md b/.ai/skills/component-migration-analysis/SKILL.md index f3aa55d889f..f5004cce965 100644 --- a/.ai/skills/component-migration-analysis/SKILL.md +++ b/.ai/skills/component-migration-analysis/SKILL.md @@ -27,7 +27,7 @@ You are a code archaeologist. Read existing code without judgment — your job i ### Output - **One markdown file per component** at: - `CONTRIBUTOR-DOCS/03_project-planning/03_components/[component-name]/rendering-and-styling-migration-analysis.md` + `CONTRIBUTOR-DOCS/project-planning/03_components/[component-name]/rendering-and-styling-migration-analysis.md` - **Structure**: Component specifications (CSS from spectrum-css `spectrum-two` metadata.json; SWC from spectrum-web-components `main` render/slots) → Comparison (DOM structure changes: SWC + CSS main + CSS spectrum-two; CSS⇒SWC mapping table) → Summary of changes → Resources ### Sources and branches diff --git a/.ai/skills/component-migration-analysis/references/migration-analysis-prompt.md b/.ai/skills/component-migration-analysis/references/migration-analysis-prompt.md index 89f48a90b60..09923f46b39 100644 --- a/.ai/skills/component-migration-analysis/references/migration-analysis-prompt.md +++ b/.ai/skills/component-migration-analysis/references/migration-analysis-prompt.md @@ -2,7 +2,7 @@ # Spectrum Migration Documentation Prompt -For the **[COMPONENT_NAME]** component(s), create comprehensive migration documentation in individual markdown files under CONTRIBUTOR-DOCS: one file per component in `CONTRIBUTOR-DOCS/03_project-planning/03_components/[component-name]/rendering-and-styling-migration-analysis.md`, following this exact structure: +For the **[COMPONENT_NAME]** component(s), create comprehensive migration documentation in individual markdown files under CONTRIBUTOR-DOCS: one file per component in `CONTRIBUTOR-DOCS/project-planning/03_components/[component-name]/rendering-and-styling-migration-analysis.md`, following this exact structure: **IMPORTANT**: All files must be created on the original spectrum-web-components branch where the session started. @@ -23,8 +23,8 @@ For additional context on goals and common pitfalls, reference `migration-roadma - **One markdown file per component** - Use the component/package name from the spectrum-web-components repository: -- File path format: `CONTRIBUTOR-DOCS/03_project-planning/03_components/[component-name]/rendering-and-styling-migration-analysis.md` -- Example: `CONTRIBUTOR-DOCS/03_project-planning/03_components/alert-banner/rendering-and-styling-migration-analysis.md`, `.../dialog/rendering-and-styling-migration-analysis.md` +- File path format: `CONTRIBUTOR-DOCS/project-planning/03_components/[component-name]/rendering-and-styling-migration-analysis.md` +- Example: `CONTRIBUTOR-DOCS/project-planning/03_components/alert-banner/rendering-and-styling-migration-analysis.md`, `.../dialog/rendering-and-styling-migration-analysis.md` ## Component Documentation Structure @@ -350,7 +350,7 @@ Under this heading, add a placeholder section for resources with a bulleted list ## Output format notes -- Create one markdown file per component at `CONTRIBUTOR-DOCS/03_project-planning/03_components/[component-name]/rendering-and-styling-migration-analysis.md` (use the component's kebab-case folder name from spectrum-web-components) +- Create one markdown file per component at `CONTRIBUTOR-DOCS/project-planning/03_components/[component-name]/rendering-and-styling-migration-analysis.md` (use the component's kebab-case folder name from spectrum-web-components) - The filename is always `rendering-and-styling-migration-analysis.md`; the folder name is the component name - Use proper markdown formatting with Level 1 heading for component name - Ensure all
elements are properly closed diff --git a/.ai/skills/consumer-migration-guide/SKILL.md b/.ai/skills/consumer-migration-guide/SKILL.md index c9705627423..2834c02d6d1 100644 --- a/.ai/skills/consumer-migration-guide/SKILL.md +++ b/.ai/skills/consumer-migration-guide/SKILL.md @@ -41,7 +41,7 @@ Create per-component migration guidance for application developers upgrading app - Consumer migration guides live alongside the Spectrum 2 component source so the doc ships with the component code. Do **not** add them to `CONTRIBUTOR-DOCS/`. - **Do not link to project-planning / `CONTRIBUTOR-DOCS` docs** from the guide. Those are maintainer-facing; consumers don't need them. Link only to public consumer docs (e.g. the Spectrum 1 README on npm or the Spectrum 2 component Storybook page) when a link genuinely helps. -- **Nav:** The guide lives in the component directory, so the `CONTRIBUTOR-DOCS` `update-nav.js` script does not manage it. Do not register it in `CONTRIBUTOR-DOCS/03_project-planning/03_components/README.md`, and do not include auto-generated breadcrumbs or TOC markers intended for that script. +- **Nav:** The guide lives in the component directory, so the `CONTRIBUTOR-DOCS` `update-nav.js` script does not manage it. Do not register it in `CONTRIBUTOR-DOCS/project-planning/03_components/README.md`, and do not include auto-generated breadcrumbs or TOC markers intended for that script. - **MDX gotchas:** Keep bare tag names (``, ``, etc.) wrapped in backticks in prose, and keep HTML/JS examples inside fenced code blocks. Avoid loose `{` / `}` outside code blocks; MDX parses them as JS expressions. ### Required source inputs diff --git a/.ai/skills/consumer-migration-guide/references/consumer-migration-guide-prompt.md b/.ai/skills/consumer-migration-guide/references/consumer-migration-guide-prompt.md index ec2664a6d06..c7bc66f3f56 100644 --- a/.ai/skills/consumer-migration-guide/references/consumer-migration-guide-prompt.md +++ b/.ai/skills/consumer-migration-guide/references/consumer-migration-guide-prompt.md @@ -50,7 +50,7 @@ If a claim is not confirmed by source, omit it. When sources disagree, follow this order of authority: 1. **The shipped Spectrum 2 source** (`2nd-gen/packages/swc/components/[component-name]/` and `2nd-gen/packages/core/components/[component-name]/`) — ground truth for what the component actually does. -2. **The CSS style guide** (`CONTRIBUTOR-DOCS/02_style-guide/` and `.ai/rules/styles.md`) — recommendations here **outweigh** anything in a component's `rendering-and-styling-migration-analysis.md`. The analysis docs are early, component-specific planning artifacts; the style guide is the canonical, cross-component rule set and supersedes them when they conflict (for example on custom-property naming, prefixing, and public-vs-private boundaries). +2. **The CSS style guide** (`CONTRIBUTOR-DOCS/for-contributors/style-guide/` and `.ai/rules/styles.md`) — recommendations here **outweigh** anything in a component's `rendering-and-styling-migration-analysis.md`. The analysis docs are early, component-specific planning artifacts; the style guide is the canonical, cross-component rule set and supersedes them when they conflict (for example on custom-property naming, prefixing, and public-vs-private boundaries). 3. **`rendering-and-styling-migration-analysis.md`** and other maintainer-facing analysis docs — use only for context and rationale. If an analysis doc suggests a public API shape that the Spectrum 2 source or the CSS style guide contradicts, trust the source and the style guide, not the analysis. ## File and heading format diff --git a/.ai/skills/contributor-docs-nav/SKILL.md b/.ai/skills/contributor-docs-nav/SKILL.md index de08f35a70c..600fe049d83 100644 --- a/.ai/skills/contributor-docs-nav/SKILL.md +++ b/.ai/skills/contributor-docs-nav/SKILL.md @@ -30,7 +30,7 @@ You are a documentation maintainer. Broken links and stale navigation are bugs, 1. **When to run**: File/folder add/remove/rename/move; heading changes; folder structure changes; or user request. 2. **How to run** (from project root): ```bash - cd CONTRIBUTOR-DOCS/01_contributor-guides/07_authoring-contributor-docs + cd CONTRIBUTOR-DOCS/for-contributors/authoring-contributor-docs node update-nav.js ``` 3. **After running**: Verify success, report results (files updated, link counts). Fix straightforward link errors automatically; ask the user when the fix is ambiguous (e.g. target file removed, multiple anchor matches). diff --git a/.ai/skills/contributor-docs-nav/references/ai-agent-instructions.md b/.ai/skills/contributor-docs-nav/references/ai-agent-instructions.md index be0f8e090da..c683996f4eb 100644 --- a/.ai/skills/contributor-docs-nav/references/ai-agent-instructions.md +++ b/.ai/skills/contributor-docs-nav/references/ai-agent-instructions.md @@ -54,7 +54,7 @@ Execute the script when: ### How to run ```bash -cd CONTRIBUTOR-DOCS/01_contributor-guides/07_authoring-contributor-docs +cd CONTRIBUTOR-DOCS/for-contributors/authoring-contributor-docs node update-nav.js ``` @@ -127,7 +127,7 @@ The script automatically verifies all internal markdown links after updating nav ``` Script reports: "File not found: ../migration/overview.md" → Search metadata for files matching "migration" or "overview" -→ Find: "03_project-planning/01_migration-status.md" +→ Find: "project-planning/01_migration-status.md" → Update link with correct relative path → Report: "Fixed broken link: updated path to migration status doc" ``` diff --git a/.ai/skills/migration-a11y/SKILL.md b/.ai/skills/migration-a11y/SKILL.md index 059dd5ac50d..dabfc44e0f2 100644 --- a/.ai/skills/migration-a11y/SKILL.md +++ b/.ai/skills/migration-a11y/SKILL.md @@ -3,9 +3,9 @@ name: migration-a11y description: Phase 5 of 1st-gen to 2nd-gen component migration. Use to implement WCAG-aligned semantics, ARIA, keyboard support, and focus management, and document accessibility behavior. --- -# Migration a11y ([Phase 5](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/README.md)) +# Migration a11y ([Phase 5](../../../CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/README.md)) -[Phase 5](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/README.md) of the 1st-gen → 2nd-gen component migration. The goal is to implement WCAG-aligned behavior — semantics, ARIA, keyboard support, and focus management — and verify it with assistive technology and automated tests. +[Phase 5](../../../CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/README.md) of the 1st-gen → 2nd-gen component migration. The goal is to implement WCAG-aligned behavior — semantics, ARIA, keyboard support, and focus management — and verify it with assistive technology and automated tests. See also: [`accessibility-compliance`](../accessibility-compliance/SKILL.md) for general WCAG 2.2 patterns, ARIA reference, and testing tools. @@ -35,4 +35,4 @@ You are an implementer working from evidence, not assumptions. Read the accessib ## Workflow -Follow **[Phase 5: Accessibility](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_washing-machine-workflow.md#phase-5-accessibility)** in the washing machine workflow doc — it covers what to do, what to check, common problems, and the quality gate for this phase. +Follow **[Phase 5: Accessibility](../../../CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_washing-machine-workflow.md#phase-5-accessibility)** in the washing machine workflow doc — it covers what to do, what to check, common problems, and the quality gate for this phase. diff --git a/.ai/skills/migration-api/SKILL.md b/.ai/skills/migration-api/SKILL.md index 21e041013d2..08f91bfd134 100644 --- a/.ai/skills/migration-api/SKILL.md +++ b/.ai/skills/migration-api/SKILL.md @@ -3,9 +3,9 @@ name: migration-api description: Phase 3 of 1st-gen to 2nd-gen component migration. Use to move properties, methods, and types from 1st-gen to 2nd-gen while maintaining a clear public API. --- -# Migration API ([Phase 3](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/README.md)) +# Migration API ([Phase 3](../../../CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/README.md)) -[Phase 3](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/README.md) of the 1st-gen → 2nd-gen component migration. The goal is to migrate properties, methods, and types from 1st-gen to 2nd-gen — keeping the public API clear, types in core, and internal helpers marked appropriately. +[Phase 3](../../../CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/README.md) of the 1st-gen → 2nd-gen component migration. The goal is to migrate properties, methods, and types from 1st-gen to 2nd-gen — keeping the public API clear, types in core, and internal helpers marked appropriately. ## Mindset @@ -33,4 +33,4 @@ You are defining a contract, not writing logic. Every property and type you plac ## Workflow -Follow **[Phase 3: API Migration](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_washing-machine-workflow.md#phase-3-api-migration)** in the washing machine workflow doc — it covers what to do, what to check, common problems, and the quality gate for this phase. +Follow **[Phase 3: API Migration](../../../CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_washing-machine-workflow.md#phase-3-api-migration)** in the washing machine workflow doc — it covers what to do, what to check, common problems, and the quality gate for this phase. diff --git a/.ai/skills/migration-documentation/SKILL.md b/.ai/skills/migration-documentation/SKILL.md index 183a201aadb..5f4c4f907a9 100644 --- a/.ai/skills/migration-documentation/SKILL.md +++ b/.ai/skills/migration-documentation/SKILL.md @@ -3,9 +3,9 @@ name: migration-documentation description: Phase 7 of 1st-gen to 2nd-gen component migration. Use to write JSDoc, Storybook stories, and usage docs so the component is usable and understandable by others. --- -# Migration documentation ([Phase 7](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/README.md)) +# Migration documentation ([Phase 7](../../../CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/README.md)) -[Phase 7](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/README.md) of the 1st-gen → 2nd-gen component migration. The goal is JSDoc on the public API, Storybook stories covering the main use cases, and migration notes where the API diverges from 1st-gen. +[Phase 7](../../../CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/README.md) of the 1st-gen → 2nd-gen component migration. The goal is JSDoc on the public API, Storybook stories covering the main use cases, and migration notes where the API diverges from 1st-gen. See also: [`documentation`](../documentation/SKILL.md) for Adobe content writing standards to follow when writing usage docs and migration notes. @@ -35,4 +35,4 @@ You are writing for the next contributor, not for yourself. Every story, JSDoc l ## Workflow -Follow **[Phase 7: Documentation](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_washing-machine-workflow.md#phase-7-documentation)** in the washing machine workflow doc — it covers what to do, what to check, common problems, and the quality gate for this phase. +Follow **[Phase 7: Documentation](../../../CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_washing-machine-workflow.md#phase-7-documentation)** in the washing machine workflow doc — it covers what to do, what to check, common problems, and the quality gate for this phase. diff --git a/.ai/skills/migration-prep/SKILL.md b/.ai/skills/migration-prep/SKILL.md index 09f386bf854..3851594272f 100644 --- a/.ai/skills/migration-prep/SKILL.md +++ b/.ai/skills/migration-prep/SKILL.md @@ -5,7 +5,7 @@ description: Phase 1 of 1st-gen to 2nd-gen component migration. Use to understan # Migration prep (Phase 1) -[Phase 1](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/README.md) of the 1st-gen → 2nd-gen component migration. The goal is to thoroughly understand the component and produce a written migration plan—covering API surface, breaking changes, file layout, and naming decisions—before any code is moved or refactored. +[Phase 1](../../../CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/README.md) of the 1st-gen → 2nd-gen component migration. The goal is to thoroughly understand the component and produce a written migration plan—covering API surface, breaking changes, file layout, and naming decisions—before any code is moved or refactored. ## Mindset @@ -31,4 +31,4 @@ You are a planner, not an implementer. Your job is to produce a written plan the ## Workflow -Follow **[Phase 1: Preparation](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_washing-machine-workflow.md#phase-1-preparation)** in the washing machine workflow doc — it covers what to do, what to check, common problems, and the quality gate for this phase. +Follow **[Phase 1: Preparation](../../../CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_washing-machine-workflow.md#phase-1-preparation)** in the washing machine workflow doc — it covers what to do, what to check, common problems, and the quality gate for this phase. diff --git a/.ai/skills/migration-review/SKILL.md b/.ai/skills/migration-review/SKILL.md index f7d8aa56f42..eb376643bb2 100644 --- a/.ai/skills/migration-review/SKILL.md +++ b/.ai/skills/migration-review/SKILL.md @@ -3,13 +3,13 @@ name: migration-review description: Phase 8 of 1st-gen to 2nd-gen component migration. Use to run final checks, verify lint/tests/build/Storybook, update the workstream status table, and open a PR. --- -# Migration review ([Phase 8](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/README.md)) +# Migration review ([Phase 8](../../../CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/README.md)) -[Phase 8](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/README.md) of the 1st-gen → 2nd-gen component migration. The goal is final checks — lint, tests, build, and Storybook — then updating the workstream status table and opening a PR. +[Phase 8](../../../CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/README.md) of the 1st-gen → 2nd-gen component migration. The goal is final checks — lint, tests, build, and Storybook — then updating the workstream status table and opening a PR. ## Mindset -You are a gatekeeper, not a rubber stamp. A passing build and green tests are the minimum expectations. Read the diff as if you are a reviewer who did not write this code. Look for missing edge cases, inconsistent conventions, and anything the automated checks cannot catch. Use the style guides in `CONTRIBUTOR-DOCS/02_style-guide` when enforcing code styles. +You are a gatekeeper, not a rubber stamp. A passing build and green tests are the minimum expectations. Read the diff as if you are a reviewer who did not write this code. Look for missing edge cases, inconsistent conventions, and anything the automated checks cannot catch. Use the style guides in `CONTRIBUTOR-DOCS/for-contributors/style-guide` when enforcing code styles. ## When to use this skill @@ -32,4 +32,4 @@ You are a gatekeeper, not a rubber stamp. A passing build and green tests are th ## Workflow -Follow **[Phase 8: Review](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_washing-machine-workflow.md#phase-8-review)** in the washing machine workflow doc — it covers what to do, what to check, common problems, and the quality gate for this phase. +Follow **[Phase 8: Review](../../../CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_washing-machine-workflow.md#phase-8-review)** in the washing machine workflow doc — it covers what to do, what to check, common problems, and the quality gate for this phase. diff --git a/.ai/skills/migration-setup/SKILL.md b/.ai/skills/migration-setup/SKILL.md index a7aa2eba798..5385ca79e21 100644 --- a/.ai/skills/migration-setup/SKILL.md +++ b/.ai/skills/migration-setup/SKILL.md @@ -5,7 +5,7 @@ description: Phase 2 of 1st-gen to 2nd-gen component migration. Use to create th # Migration setup (Phase 2) -[Phase 2](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/README.md) of the 1st-gen → 2nd-gen component migration. The goal is to create the core and SWC directory structure, stub out the required files, and confirm the component is importable before any implementation work begins. +[Phase 2](../../../CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/README.md) of the 1st-gen → 2nd-gen component migration. The goal is to create the core and SWC directory structure, stub out the required files, and confirm the component is importable before any implementation work begins. ## Mindset @@ -34,4 +34,4 @@ You are building a foundation, not a feature. Every file you create here is a co ## Workflow -Follow **[Phase 2: Setup](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_washing-machine-workflow.md#phase-2-setup)** in the washing machine workflow doc — it covers what to do, what to check, common problems, and the quality gate for this phase. +Follow **[Phase 2: Setup](../../../CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_washing-machine-workflow.md#phase-2-setup)** in the washing machine workflow doc — it covers what to do, what to check, common problems, and the quality gate for this phase. diff --git a/.ai/skills/migration-styling/SKILL.md b/.ai/skills/migration-styling/SKILL.md index 083aae65f3c..06dcdd9fbe0 100644 --- a/.ai/skills/migration-styling/SKILL.md +++ b/.ai/skills/migration-styling/SKILL.md @@ -3,13 +3,13 @@ name: migration-styling description: Phase 4 of 1st-gen to 2nd-gen component migration. Use to migrate CSS to the 2nd-gen structure, apply Spectrum 2 tokens, and ensure stylelint passes. --- -# Migration styling ([Phase 4](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/README.md)) +# Migration styling ([Phase 4](../../../CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/README.md)) -[Phase 4](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/README.md) of the 1st-gen → 2nd-gen component migration. The goal is to migrate CSS to the 2nd-gen structure, replace hard-coded values with tokens, and ensure the component's CSS passes stylelint with no errors. +[Phase 4](../../../CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/README.md) of the 1st-gen → 2nd-gen component migration. The goal is to migrate CSS to the 2nd-gen structure, replace hard-coded values with tokens, and ensure the component's CSS passes stylelint with no errors. ## Mindset -You are translating, not redesigning. Your job is not to invent new visual decisions. Use the `rendering-and-styling-migration-analysis.md` file that corresponds to the component you are migrating. When the token you need does not exist, use the `ask-questions` skill to flag it with the user. Refer to the CSS styling guides in `CONTRIBUTOR-DOCS/02_style-guide/` when refactoring the CSS (i.e. change `--spectrum` prefixes to `--swc`; `.spectrum*` classes to `.swc*`; `--mod` prefixes should not exist). The CSS style guides are the preferred way to write the CSS, as opposed to any recommendations you find in the rendering analysis doc. +You are translating, not redesigning. Your job is not to invent new visual decisions. Use the `rendering-and-styling-migration-analysis.md` file that corresponds to the component you are migrating. When the token you need does not exist, use the `ask-questions` skill to flag it with the user. Refer to the CSS styling guides in `CONTRIBUTOR-DOCS/for-contributors/style-guide/` when refactoring the CSS (i.e. change `--spectrum` prefixes to `--swc`; `.spectrum*` classes to `.swc*`; `--mod` prefixes should not exist). The CSS style guides are the preferred way to write the CSS, as opposed to any recommendations you find in the rendering analysis doc. ## When to use this skill @@ -33,4 +33,4 @@ You are translating, not redesigning. Your job is not to invent new visual decis ## Workflow -Follow **[Phase 4: Styling](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_washing-machine-workflow.md#phase-4-styling)** in the washing machine workflow doc — it covers what to do, what to check, common problems, and the quality gate for this phase. +Follow **[Phase 4: Styling](../../../CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_washing-machine-workflow.md#phase-4-styling)** in the washing machine workflow doc — it covers what to do, what to check, common problems, and the quality gate for this phase. diff --git a/.ai/skills/migration-testing/SKILL.md b/.ai/skills/migration-testing/SKILL.md index f2547b9745f..d556a855a9f 100644 --- a/.ai/skills/migration-testing/SKILL.md +++ b/.ai/skills/migration-testing/SKILL.md @@ -3,9 +3,9 @@ name: migration-testing description: Phase 6 of 1st-gen to 2nd-gen component migration. Use to write unit tests, accessibility tests, and Storybook play functions for a migrated component. --- -# Migration testing ([Phase 6](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/README.md)) +# Migration testing ([Phase 6](../../../CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/README.md)) -[Phase 6](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/README.md) of the 1st-gen → 2nd-gen component migration. The goal is automated test coverage for behavior and accessibility — unit tests via Vitest, a11y tests via Playwright, and Storybook play functions. +[Phase 6](../../../CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/README.md) of the 1st-gen → 2nd-gen component migration. The goal is automated test coverage for behavior and accessibility — unit tests via Vitest, a11y tests via Playwright, and Storybook play functions. ## Mindset @@ -33,4 +33,4 @@ You are a skeptic. Tests that always pass are not tests — they are documentati ## Workflow -Follow **[Phase 6: Testing](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_washing-machine-workflow.md#phase-6-testing)** in the washing machine workflow doc — it covers what to do, what to check, common problems, and the quality gate for this phase. +Follow **[Phase 6: Testing](../../../CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_washing-machine-workflow.md#phase-6-testing)** in the washing machine workflow doc — it covers what to do, what to check, common problems, and the quality gate for this phase. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 278cf4f8718..e98d4188917 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -78,7 +78,7 @@ **Required:** Complete each applicable item and document your testing steps (replace the placeholders with your component-specific instructions). diff --git a/.husky/pre-commit b/.husky/pre-commit index e67fb3a5f1d..1dedb7225fa 100755 --- a/.husky/pre-commit +++ b/.husky/pre-commit @@ -2,6 +2,6 @@ yarn lint-staged --allow-empty # If any CONTRIBUTOR-DOCS files are staged, regenerate navigation and verify links if git diff --cached --name-only | grep -q "^CONTRIBUTOR-DOCS/"; then - node CONTRIBUTOR-DOCS/01_contributor-guides/07_authoring-contributor-docs/update-nav.js "$(pwd)/CONTRIBUTOR-DOCS" + node CONTRIBUTOR-DOCS/for-contributors/authoring-contributor-docs/update-nav.js "$(pwd)/CONTRIBUTOR-DOCS" git add CONTRIBUTOR-DOCS/ fi diff --git a/1st-gen/AGENTS.md b/1st-gen/AGENTS.md index a1ccb0090e7..3064fb9bba8 100644 --- a/1st-gen/AGENTS.md +++ b/1st-gen/AGENTS.md @@ -22,4 +22,4 @@ If a change belongs in both generations, make it in `2nd-gen/packages/core/` so - [`tools/AGENTS.md`](./tools/AGENTS.md) — shared tooling - [`projects/AGENTS.md`](./projects/AGENTS.md) — non-component workspaces - [`2nd-gen/AGENTS.md`](../2nd-gen/AGENTS.md) — the future direction -- [Migration workstream docs](../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/README.md) +- [Migration workstream docs](../CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/README.md) diff --git a/2nd-gen/AGENTS.md b/2nd-gen/AGENTS.md index bf5819b4cc5..614d50da317 100644 --- a/2nd-gen/AGENTS.md +++ b/2nd-gen/AGENTS.md @@ -18,4 +18,4 @@ - [`packages/core/AGENTS.md`](./packages/core/AGENTS.md) — base classes, mixins, types - [`packages/swc/AGENTS.md`](./packages/swc/AGENTS.md) — rendering, CSS, stories, tests - [`1st-gen/AGENTS.md`](../1st-gen/AGENTS.md) — the generation being replaced -- [Migration workstream docs](../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/README.md) +- [Migration workstream docs](../CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/README.md) diff --git a/2nd-gen/README.md b/2nd-gen/README.md index 9990888e5df..0073d7ba612 100644 --- a/2nd-gen/README.md +++ b/2nd-gen/README.md @@ -9,7 +9,7 @@ This workspace contains the second generation of Spectrum Web Components (SWC), ## Documentation -- **[Get started (for consumers)](../CONTRIBUTOR-DOCS/00_get-started/for-consumers.md)** — install and render your first component. The same content renders interactively under **Get started** in Storybook. +- **[Get started (for consumers)](../CONTRIBUTOR-DOCS/for-consumers/get-started.md)** — install and render your first component. The same content renders interactively under **Get started** in Storybook. - **[Contributor docs](../CONTRIBUTOR-DOCS/README.md)** — architecture, development workflows, migration guides, and project planning. ## Local development diff --git a/2nd-gen/packages/swc/.storybook/main.ts b/2nd-gen/packages/swc/.storybook/main.ts index e1e0671c135..56761bdf210 100644 --- a/2nd-gen/packages/swc/.storybook/main.ts +++ b/2nd-gen/packages/swc/.storybook/main.ts @@ -94,7 +94,7 @@ if (storybookMode !== 'ci-a11y') { // Local `yarn dev` / `yarn storybook` still shows the full tree. files: storybookMode === 'build' - ? '{*.mdx,!(03_project-planning)/**/*.mdx}' + ? '{*.mdx,!(project-planning)/**/*.mdx}' : '**/*.mdx', titlePrefix: 'Contribute', } diff --git a/2nd-gen/packages/swc/.storybook/preview.ts b/2nd-gen/packages/swc/.storybook/preview.ts index 6991ce54790..406c7779cdd 100644 --- a/2nd-gen/packages/swc/.storybook/preview.ts +++ b/2nd-gen/packages/swc/.storybook/preview.ts @@ -264,74 +264,77 @@ const preview = { // GENERATED:CONTRIBUTOR-DOCS-SORT - Do not edit manually. Run `yarn generate:contributor-docs` to update. [ 'Contributor documentation', - 'Get started', - ['Component matrix', 'For consumers'], - 'Contributor guides', + 'For agents', + 'For consumers', + ['Customization cheatsheet', 'Get started'], + 'For contributors', [ - 'Getting involved', - 'Using the issue tracker', - 'Working in the SWC repo', - 'Making a pull request', - 'Participating in PR reviews', - 'Releasing SWC', + '2nd-gen testing', + 'Accessibility testing', 'Authoring contributor docs', [ 'Templates', ['Consumer quickstart'], ], - 'Patching dependencies', - 'Accessibility testing', - 'Using stackblitz', - '2nd-gen testing', - 'Tools vs packages', 'Focus management', - ], - 'Style guide', - [ - 'CSS', - [ - 'Component CSS', - 'Custom properties', - 'Component CSS PR checklist', - 'Spectrum SWC migration', - 'Anti patterns', - 'Property order quick reference', - ], - 'TypeScript', - [ - 'File organization', - 'Class structure', - 'TypeScript modifiers', - 'Lit decorators', - 'Property patterns', - 'Method patterns', - 'JSDoc standards', - 'Component types', - 'Rendering patterns', - 'Naming conventions', - 'Base vs concrete', - 'Composition patterns', - 'Mixin composition', - 'Controller composition', - 'Directive composition', - 'Interface composition', - 'Debug validation', - ], - 'Linting tools', - 'Testing', + 'Getting involved', + 'Making a pull request', + 'Participating in PR reviews', + 'Patching dependencies', + 'Releasing SWC', + 'Style guide', [ - 'Testing overview', - 'Storybook testing', - 'Playwright accessbility testing', - 'Visual regresssion testing', - 'Testing utilities', - 'Code coverage', - 'Avoiding flaky tests', - 'Running tests.', - 'PR review checklist', - 'Resources', + 'CSS', + [ + 'Anti patterns', + 'Component CSS PR checklist', + 'Component CSS', + 'Custom properties', + 'Property order quick reference', + 'Spectrum SWC migration', + ], + 'Linting tools', + 'Testing', + [ + 'Avoiding flaky tests', + 'Code coverage', + 'Playwright accessbility testing', + 'PR review checklist', + 'Resources', + 'Running tests', + 'Storybook testing', + 'Testing overview', + 'Testing utilities', + 'Visual regresssion testing', + ], + 'TypeScript', + [ + 'Base vs concrete', + 'Class structure', + 'Component types', + 'Composition patterns', + 'Controller composition', + 'Debug validation', + 'Directive composition', + 'File organization', + 'Interface composition', + 'JSDoc standards', + 'Lit decorators', + 'Method patterns', + 'Mixin composition', + 'Naming conventions', + 'Property patterns', + 'Rendering patterns', + 'TypeScript modifiers', + ], ], + 'Tools vs packages', + 'Using stackblitz', + 'Using the issue tracker', + 'Working in the SWC repo', ], + 'For internals', + 'For maintainers', 'Project planning', [ 'Objectives and strategy', @@ -460,8 +463,20 @@ const preview = { ['Rendering and styling migration analysis'], ], 'Milestones', - 'Strategies', - ['Focus management strategy rfc'], + ], + 'Reference', + ['Component status'], + 'Rfcs', + [ + 'Accepted', + ['2026 03 31 focus management strategy'], + 'Proposed', + [ + '2026 04 22 docs overhaul v2', + '2026 04 22 focus management strategy', + ], + 'Superseded', + 'Template', ], ], // GENERATED:CONTRIBUTOR-DOCS-SORT-END diff --git a/2nd-gen/packages/swc/.storybook/scripts/generate-component-matrix.mjs b/2nd-gen/packages/swc/.storybook/scripts/generate-component-matrix.mjs index b87e1c8f921..7d83e7537c5 100644 --- a/2nd-gen/packages/swc/.storybook/scripts/generate-component-matrix.mjs +++ b/2nd-gen/packages/swc/.storybook/scripts/generate-component-matrix.mjs @@ -11,7 +11,7 @@ */ /** - * Generates CONTRIBUTOR-DOCS/00_get-started/component-matrix.md — a single + * Generates CONTRIBUTOR-DOCS/reference/component-status.md — a single * at-a-glance view of every 2nd-gen component's migration status, React * Spectrum 2 parity, and design/sandbox links. * @@ -22,7 +22,7 @@ * Inputs: * - CEM (.storybook/custom-elements.json) — tag, status, since (row set + three columns) * - Per-component story files — Figma and Stackblitz URLs - * - component-matrix.data.yml — optional RSP parity override + notes + * - component-status.data.yml — optional RSP parity override + notes * * RSP parity is a human judgment today (set via the YAML, defaulting to * `partial` for every component). Once MVP-5 lands, the CEM plugin will parse @@ -49,11 +49,11 @@ const REPO_ROOT = resolve(STORYBOOK_DIR, '../../../..'); const CONTRIBUTOR_DOCS_DIR = resolve(REPO_ROOT, 'CONTRIBUTOR-DOCS'); const DATA_FILE = resolve( CONTRIBUTOR_DOCS_DIR, - '00_get-started/component-matrix.data.yml' + 'reference/component-status.data.yml' ); const OUTPUT_FILE = resolve( CONTRIBUTOR_DOCS_DIR, - '00_get-started/component-matrix.md' + 'reference/component-status.md' ); const GITHUB_REPO_URL = 'https://github.com/adobe/spectrum-web-components/tree/main'; @@ -62,7 +62,7 @@ const GENERATED_HEADER = ``; @@ -225,7 +225,7 @@ function renderMarkdown(rows) { '- **Since** — first 2nd-gen package version to ship the component. Derived from CEM (`@since` JSDoc tag).' ); lines.push( - '- **RSP 2 parity** — whether the 2nd-gen component reaches feature parity with the equivalent React Spectrum 2 component. Values: `full`, `partial`, `none`, or a short note. Currently a human judgment set in `component-matrix.data.yml`; defaults to `partial` while per-component RSP tracking is being designed. Will move to an `@RSPparity` JSDoc tag parsed by CEM once the MVP-5 plugin lands.' + '- **RSP 2 parity** — whether the 2nd-gen component reaches feature parity with the equivalent React Spectrum 2 component. Values: `full`, `partial`, `none`, or a short note. Currently a human judgment set in `component-status.data.yml`; defaults to `partial` while per-component RSP tracking is being designed. Will move to an `@RSPparity` JSDoc tag parsed by CEM once the MVP-5 plugin lands.' ); lines.push(''); diff --git a/2nd-gen/packages/swc/.storybook/scripts/generate-contributor-docs.mjs b/2nd-gen/packages/swc/.storybook/scripts/generate-contributor-docs.mjs index c58f2de3f69..3ef9bf496cf 100644 --- a/2nd-gen/packages/swc/.storybook/scripts/generate-contributor-docs.mjs +++ b/2nd-gen/packages/swc/.storybook/scripts/generate-contributor-docs.mjs @@ -55,7 +55,7 @@ const GITHUB_REPO_URL = */ const MIRROR_EMITS = [ { - source: '00_get-started/for-consumers.md', + source: 'for-consumers/get-started.md', outputDir: GET_STARTED_OUTPUT_DIR, outputFile: 'index.mdx', title: 'Get started', @@ -65,7 +65,7 @@ const MIRROR_EMITS = [ heading: 'Get started', }, { - source: '00_get-started/component-matrix.md', + source: 'reference/component-status.md', outputDir: LEARN_OUTPUT_DIR, outputFile: 'component-status.mdx', title: 'Component status', diff --git a/CONTRIBUTOR-DOCS/00_get-started/README.md b/CONTRIBUTOR-DOCS/00_get-started/README.md deleted file mode 100644 index 7a164880f2b..00000000000 --- a/CONTRIBUTOR-DOCS/00_get-started/README.md +++ /dev/null @@ -1,27 +0,0 @@ - - -[CONTRIBUTOR-DOCS](../README.md) / Get started - - - -# Get started - - - -
-Beneath this doc - -- [Component status](component-matrix.md) -- [Customization cheatsheet](customization-cheatsheet.md) -- [Get started (for consumers)](for-consumers.md) - -
- - - -Quick-start guides for people new to Spectrum Web Components. - -Start here if you are: - -- **A consumer** building an application with SWC — see [Get started (for consumers)](./for-consumers.md). -- **A contributor** working on the SWC codebase itself — see [Contributor guides](../01_contributor-guides/README.md). diff --git a/CONTRIBUTOR-DOCS/01_contributor-guides/README.md b/CONTRIBUTOR-DOCS/01_contributor-guides/README.md deleted file mode 100644 index fa1eaa6106b..00000000000 --- a/CONTRIBUTOR-DOCS/01_contributor-guides/README.md +++ /dev/null @@ -1,33 +0,0 @@ - - -[CONTRIBUTOR-DOCS](../README.md) / Contributor guides - - - -# Contributor guides - - - -
-Beneath this doc - -- [Getting involved](01_getting-involved.md) -- [Using the issue tracker](02_using-the-issue-tracker.md) -- [Working in the SWC repo](03_working-in-the-swc-repo.md) -- [Making a pull request](04_making-a-pull-request.md) -- [Participating in PR reviews](05_participating-in-pr-reviews.md) -- [Releasing SWC](06_releasing-swc.md) -- [Authoring contributor docs](07_authoring-contributor-docs/README.md) - - Templates -- [Patching dependencies](08_patching-dependencies.md) -- [Accessibility testing](09_accessibility-testing.md) -- [Maintaining StackBlitz examples for Spectrum Web Components](10_using-stackblitz.md) -- [2nd gen testing](11_2ndgen_testing.md) -- [Tools vs packages: where code lives](12_tools-vs-packages.md) -- [Focus management](13_focus-management.md) - -
- - - -(Content to be added) diff --git a/CONTRIBUTOR-DOCS/02_style-guide/01_css/README.md b/CONTRIBUTOR-DOCS/02_style-guide/01_css/README.md deleted file mode 100644 index 7aac2c06737..00000000000 --- a/CONTRIBUTOR-DOCS/02_style-guide/01_css/README.md +++ /dev/null @@ -1,25 +0,0 @@ - - -[CONTRIBUTOR-DOCS](../../README.md) / [Style guide](../README.md) / 2nd-Gen CSS - - - -# 2nd-Gen CSS - - - -
-Beneath this doc - -- [Component CSS](01_component-css.md) -- [Custom Properties](02_custom-properties.md) -- [Component CSS PR Checklist](03_component-css-pr-checklist.md) -- [Spectrum CSS to SWC Migration](04_spectrum-swc-migration.md) -- [Styling Anti-Patterns (What to Avoid)](05_anti-patterns.md) -- [Property order quick reference](06_property-order-quick-reference.md) - -
- - - -This section contains style guides for CSS authoring and maintenance for **2nd-gen** component styles. diff --git a/CONTRIBUTOR-DOCS/02_style-guide/02_typescript/README.md b/CONTRIBUTOR-DOCS/02_style-guide/02_typescript/README.md deleted file mode 100644 index f63be4d9ca7..00000000000 --- a/CONTRIBUTOR-DOCS/02_style-guide/02_typescript/README.md +++ /dev/null @@ -1,78 +0,0 @@ - - -[CONTRIBUTOR-DOCS](../../README.md) / [Style guide](../README.md) / 2nd-gen TypeScript - - - -# 2nd-gen TypeScript - - - -
-In this doc - -- [Guides](#guides) -- [External references](#external-references) - -
- -
-Beneath this doc - -- [File organization](01_file-organization.md) -- [Class structure](02_class-structure.md) -- [TypeScript modifier keywords](03_typescript-modifiers.md) -- [Lit decorators and modifiers](04_lit-decorators.md) -- [Property patterns](05_property-patterns.md) -- [Method patterns](06_method-patterns.md) -- [JSDoc standards](07_jsdoc-standards.md) -- [Component types](08_component-types.md) -- [Rendering patterns](09_rendering-patterns.md) -- [Naming conventions](10_naming-conventions.md) -- [Base class vs concrete class](11_base-vs-concrete.md) -- [Composition patterns](12_composition-patterns.md) -- [Mixin composition](13_mixin-composition.md) -- [Controller composition](14_controller-composition.md) -- [Directive composition](15_directive-composition.md) -- [Interface composition](16_interface-composition.md) -- [Debug and validation](17_debug-validation.md) - -
- - - -This section covers the TypeScript coding conventions for **2nd-gen** component development. These guides explain how to organize files, structure classes, use decorators, write JSDoc, define types, and compose behavior using mixins, controllers, directives, and interfaces. - -The guides are written for both human contributors and AI agents. They use simple language, clear examples, and consistent formatting so anyone can follow them. - -> **Reference implementation:** The [Badge](../../../2nd-gen/packages/core/components/badge/Badge.base.ts) component is the primary example throughout these guides. Other 2nd-gen components (Status Light, Progress Circle, Divider, Asset) are used where they show different patterns. - -## Guides - -- **[File organization](01_file-organization.md)** — Copyright headers, import grouping and order, export patterns, and where types files live. -- **[Class structure](02_class-structure.md)** — Base vs concrete class layout, section comments, and how to order properties and methods within sections. -- **[TypeScript modifier keywords](03_typescript-modifiers.md)** — When and how to use `static`, `override`, `public`, `protected`, and `private`. -- **[Lit decorators and modifiers](04_lit-decorators.md)** — `@property`, `@state`, `@query`, `@queryAssignedNodes`, `@eventOptions`, and other Lit decorators. -- **[Property patterns](05_property-patterns.md)** — Property ordering, reactive property decorators, and when to use custom getters/setters vs Lit defaults. -- **[Method patterns](06_method-patterns.md)** — Method ordering, lifecycle method names, event handler naming, ARIA role assignment, and the `override` keyword. -- **[JSDoc standards](07_jsdoc-standards.md)** — When JSDoc is required, what to include, and how to use tags like `@internal`, `@attribute`, `@slot`, `@element`, and `@example`. -- **[Component types](08_component-types.md)** — Patterns for `*.types.ts` files: constant arrays, type derivation, S1/S2 split, naming, and removal strategy. -- **[Rendering patterns](09_rendering-patterns.md)** — Helper functions, inline SVG, size transformations, and classMap patterns. -- **[Naming conventions](10_naming-conventions.md)** — Rules for class names, property names, method names, type names, constant names, CSS class names, and file names. -- **[Base class vs concrete class](11_base-vs-concrete.md)** — What belongs in core (base) vs SWC (concrete) and how to decide. -- **[Composition patterns](12_composition-patterns.md)** — When to use a mixin, controller, directive, or interface, and how to choose. -- **[Mixin composition](13_mixin-composition.md)** — How to compose mixins: order, options, depth limits, and patterns. -- **[Controller composition](14_controller-composition.md)** — How to create and attach Lit controllers to host components. -- **[Directive composition](15_directive-composition.md)** — How to use built-in Lit directives and author custom ones. -- **[Interface composition](16_interface-composition.md)** — When to use `interface` vs `type`, and how to define and consume interfaces. -- **[Debug and validation](17_debug-validation.md)** — Debug-mode validation, warning patterns, and the `window.__swc` API. - -## External references - -- [TypeScript documentation](https://www.typescriptlang.org/docs/) -- [Lit documentation](https://lit.dev/docs/) -- [Lit — Reactive properties](https://lit.dev/docs/components/properties/) -- [Lit — Decorators](https://lit.dev/docs/components/decorators/) -- [Lit — Controllers](https://lit.dev/docs/composition/controllers/) -- [Lit — Directives](https://lit.dev/docs/templates/directives/) -- [JSDoc reference](https://jsdoc.app/) diff --git a/CONTRIBUTOR-DOCS/02_style-guide/README.md b/CONTRIBUTOR-DOCS/02_style-guide/README.md deleted file mode 100644 index 0f6548ef408..00000000000 --- a/CONTRIBUTOR-DOCS/02_style-guide/README.md +++ /dev/null @@ -1,60 +0,0 @@ - - -[CONTRIBUTOR-DOCS](../README.md) / Style guide - - - -# Style guide - - - -
-Beneath this doc - -- [2nd-Gen CSS](01_css/README.md) - - [Component CSS](01_css/01_component-css.md) - - [Custom Properties](01_css/02_custom-properties.md) - - [Component CSS PR Checklist](01_css/03_component-css-pr-checklist.md) - - [Spectrum CSS to SWC Migration](01_css/04_spectrum-swc-migration.md) - - [Styling Anti-Patterns (What to Avoid)](01_css/05_anti-patterns.md) - - [Property order quick reference](01_css/06_property-order-quick-reference.md) -- [2nd-gen TypeScript](02_typescript/README.md) - - [File organization](02_typescript/01_file-organization.md) - - [Class structure](02_typescript/02_class-structure.md) - - [TypeScript modifier keywords](02_typescript/03_typescript-modifiers.md) - - [Lit decorators and modifiers](02_typescript/04_lit-decorators.md) - - [Property patterns](02_typescript/05_property-patterns.md) - - [Method patterns](02_typescript/06_method-patterns.md) - - [JSDoc standards](02_typescript/07_jsdoc-standards.md) - - [Component types](02_typescript/08_component-types.md) - - [Rendering patterns](02_typescript/09_rendering-patterns.md) - - [Naming conventions](02_typescript/10_naming-conventions.md) - - [Base class vs concrete class](02_typescript/11_base-vs-concrete.md) - - [Composition patterns](02_typescript/12_composition-patterns.md) - - [Mixin composition](02_typescript/13_mixin-composition.md) - - [Controller composition](02_typescript/14_controller-composition.md) - - [Directive composition](02_typescript/15_directive-composition.md) - - [Interface composition](02_typescript/16_interface-composition.md) - - [Debug and validation](02_typescript/17_debug-validation.md) -- [Linting tools](03_linting-tools.md) -- [Testing guide](04_testing/README.md) - - [Testing overview](04_testing/01_testing-overview.md) - - [Storybook testing](04_testing/02_storybook-testing.md) - - [Playwright accessibility testing](04_testing/03_playwright-accessbility-testing.md) - - [Visual regression testing](04_testing/04_visual-regresssion-testing.md) - - [Testing utilities](04_testing/05_testing-utilities.md) - - [Code coverage](04_testing/06_code-coverage.md) - - [Avoiding flaky tests](04_testing/07_avoiding-flaky-tests.md) - - [Running tests](04_testing/08_running-tests..md) - - [PR review checklist](04_testing/09_pr_review-checklist.md) - - [Resources](04_testing/10_resources.md) - -
- - - -This section covers the coding conventions and authoring patterns used across Spectrum Web Components. Following these guides keeps the codebase consistent, reviewable, and accessible. - -- **[2nd-gen CSS](01_css/README.md)** — Property ordering, class naming, custom properties, selector patterns, and forced-colors requirements for component stylesheets. -- **[2nd-gen TypeScript](02_typescript/README.md)** — File organization, class structure, decorators, JSDoc, type definitions, naming, and composition patterns for component TypeScript. -- **[Linting tools](03_linting-tools.md)** — How automated linting enforces these conventions and how to configure or extend the rules. diff --git a/CONTRIBUTOR-DOCS/README.md b/CONTRIBUTOR-DOCS/README.md index 4786a82bd8c..cbcc1ca59ea 100644 --- a/CONTRIBUTOR-DOCS/README.md +++ b/CONTRIBUTOR-DOCS/README.md @@ -16,34 +16,34 @@
Beneath this doc -- [Get started](00_get-started/README.md) - - [Component status](00_get-started/component-matrix.md) - - [Customization cheatsheet](00_get-started/customization-cheatsheet.md) - - [Get started (for consumers)](00_get-started/for-consumers.md) -- [Contributor guides](01_contributor-guides/README.md) - - [Getting involved](01_contributor-guides/01_getting-involved.md) - - [Using the issue tracker](01_contributor-guides/02_using-the-issue-tracker.md) - - [Working in the SWC repo](01_contributor-guides/03_working-in-the-swc-repo.md) - - [Making a pull request](01_contributor-guides/04_making-a-pull-request.md) - - [Participating in PR reviews](01_contributor-guides/05_participating-in-pr-reviews.md) - - [Releasing SWC](01_contributor-guides/06_releasing-swc.md) - - [Authoring contributor docs](01_contributor-guides/07_authoring-contributor-docs/README.md) - - [Patching dependencies](01_contributor-guides/08_patching-dependencies.md) - - [Accessibility testing](01_contributor-guides/09_accessibility-testing.md) - - [Maintaining StackBlitz examples for Spectrum Web Components](01_contributor-guides/10_using-stackblitz.md) - - [2nd gen testing](01_contributor-guides/11_2ndgen_testing.md) - - [Tools vs packages: where code lives](01_contributor-guides/12_tools-vs-packages.md) - - [Focus management](01_contributor-guides/13_focus-management.md) -- [Style guide](02_style-guide/README.md) - - [2nd-Gen CSS](02_style-guide/01_css/README.md) - - [2nd-gen TypeScript](02_style-guide/02_typescript/README.md) - - [Linting tools](02_style-guide/03_linting-tools.md) - - [Testing guide](02_style-guide/04_testing/README.md) -- [Project planning](03_project-planning/README.md) - - [Objectives and strategy](03_project-planning/01_objectives-and-strategy.md) - - [Workstreams](03_project-planning/02_workstreams/README.md) - - [Components](03_project-planning/03_components/README.md) - - [Milestones](03_project-planning/04_milestones/README.md) +- For Agents +- For Consumers + - [Customization cheatsheet](for-consumers/customization-cheatsheet.md) + - [Get started (for consumers)](for-consumers/get-started.md) +- [Contributor guides](for-contributors/README.md) + - [2nd gen testing](for-contributors/2ndgen-testing.md) + - [Accessibility testing](for-contributors/accessibility-testing.md) + - [Authoring contributor docs](for-contributors/authoring-contributor-docs/README.md) + - [Focus management](for-contributors/focus-management.md) + - [Getting involved](for-contributors/getting-involved.md) + - [Making a pull request](for-contributors/making-a-pull-request.md) + - [Participating in PR reviews](for-contributors/participating-in-pr-reviews.md) + - [Patching dependencies](for-contributors/patching-dependencies.md) + - [Releasing SWC](for-contributors/releasing-swc.md) + - [Style guide](for-contributors/style-guide/README.md) + - [Tools vs packages: where code lives](for-contributors/tools-vs-packages.md) + - [Maintaining StackBlitz examples for Spectrum Web Components](for-contributors/using-stackblitz.md) + - [Using the issue tracker](for-contributors/using-the-issue-tracker.md) + - [Working in the SWC repo](for-contributors/working-in-the-swc-repo.md) +- For Internals +- For Maintainers +- [Project planning](project-planning/README.md) + - [Objectives and strategy](project-planning/01_objectives-and-strategy.md) + - [Workstreams](project-planning/02_workstreams/README.md) + - [Components](project-planning/03_components/README.md) + - [Milestones](project-planning/04_milestones/README.md) +- Reference + - [Component status](reference/component-status.md) - [RFCs](rfcs/README.md) - Accepted - Proposed @@ -66,8 +66,8 @@ SWC is developed by a core team in Adobe Design Engineering, but we welcome cont Spectrum Web Components is currently in transition from its first generation (1st-gen) to its second generation (2nd-gen). -- To understand how this transition affects the SWC code base, see [Repository Structure](./01_contributor-guides/03_working-in-the-swc-repo.md#repository-structure). -- To understand the motivation for this transition, see [Objectives and Strategy](./03_project-planning/01_objectives-and-strategy.md). +- To understand how this transition affects the SWC code base, see [Repository Structure](./for-contributors/working-in-the-swc-repo.md#repository-structure). +- To understand the motivation for this transition, see [Objectives and Strategy](./project-planning/01_objectives-and-strategy.md). ## About these docs @@ -75,22 +75,22 @@ These docs contain essential information about the SWC project for both maintain The docs are organized into sections to help you find the information you need: -**[Get started](./00_get-started/README.md)** - Quick-start guides for people new to SWC. Start here if you're a consumer installing SWC in your application; the same content renders interactively under **Get started** in Storybook. +**[Get started](./for-consumers/get-started.md)** - Quick-start guide for people new to SWC. Start here if you're a consumer installing SWC in your application; the same content renders interactively under **Get started** in Storybook. -**[Contributor Guides](./01_contributor-guides/README.md)** - Topical guides for working on the project. This section includes guides for getting started, understanding processes, and accomplishing specific tasks like adding new components or editing these contributor docs themselves. When you change doc structure or headings, see [Authoring contributor docs](./01_contributor-guides/07_authoring-contributor-docs/README.md) to regenerate navigation and verify links. +**[Contributor Guides](./for-contributors/README.md)** - Topical guides for working on the project. This section includes guides for getting started, understanding processes, and accomplishing specific tasks like adding new components or editing these contributor docs themselves. When you change doc structure or headings, see [Authoring contributor docs](./for-contributors/authoring-contributor-docs/README.md) to regenerate navigation and verify links. -**[Style Guide](./02_style-guide/README.md)** - Comprehensive style guide covering project-wide conventions and area-specific rules. This section is useful for human reference and for AI-assisted work, documenting our approaches to linting, JSDoc conventions, component structure, and other coding standards. +**[Style Guide](./for-contributors/style-guide/README.md)** - Comprehensive style guide covering project-wide conventions and area-specific rules. This section is useful for human reference and for AI-assisted work, documenting our approaches to linting, JSDoc conventions, component structure, and other coding standards. -**[Accessibility testing](./01_contributor-guides/09_accessibility-testing.md)** - Automated accessibility testing, snapshots, and manual testing expectations for pull requests. +**[Accessibility testing](./for-contributors/accessibility-testing.md)** - Automated accessibility testing, snapshots, and manual testing expectations for pull requests. -**[Project Planning](./03_project-planning/README.md)** - Strategic planning documentation including objectives, workstreams, component roadmaps, and milestones. This section contains: +**[Project Planning](./project-planning/README.md)** - Strategic planning documentation including objectives, workstreams, component roadmaps, and milestones. This section contains: -- **[Objectives and Strategy](./03_project-planning/01_objectives-and-strategy.md)** - Strategic context for the 1st-gen-to-2nd-gen transition, including our goals and approach. +- **[Objectives and Strategy](./project-planning/01_objectives-and-strategy.md)** - Strategic context for the 1st-gen-to-2nd-gen transition, including our goals and approach. -- **[Workstreams](./03_project-planning/02_workstreams/README.md)** - Workstream-centric view of cross-cutting work affecting many or all components, helping us work toward specific objectives and coordinate efforts. +- **[Workstreams](./project-planning/02_workstreams/README.md)** - Workstream-centric view of cross-cutting work affecting many or all components, helping us work toward specific objectives and coordinate efforts. -- **[Components](./03_project-planning/03_components/README.md)** - Component-centric view of individual components and how they're affected by multiple workstreams, useful for understanding each component's roadmap and status. +- **[Components](./project-planning/03_components/README.md)** - Component-centric view of individual components and how they're affected by multiple workstreams, useful for understanding each component's roadmap and status. -- **[Milestones](./03_project-planning/04_milestones/README.md)** - Information about project milestones and their goals. +- **[Milestones](./project-planning/04_milestones/README.md)** - Information about project milestones and their goals. Together, the Workstreams and Components 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. diff --git a/CONTRIBUTOR-DOCS/00_get-started/customization-cheatsheet.md b/CONTRIBUTOR-DOCS/for-consumers/customization-cheatsheet.md similarity index 98% rename from CONTRIBUTOR-DOCS/00_get-started/customization-cheatsheet.md rename to CONTRIBUTOR-DOCS/for-consumers/customization-cheatsheet.md index 34e47052b1e..6452630ee0a 100644 --- a/CONTRIBUTOR-DOCS/00_get-started/customization-cheatsheet.md +++ b/CONTRIBUTOR-DOCS/for-consumers/customization-cheatsheet.md @@ -1,6 +1,6 @@ -[CONTRIBUTOR-DOCS](../README.md) / [Get started](README.md) / Customization cheatsheet +[CONTRIBUTOR-DOCS](../README.md) / For Consumers / Customization cheatsheet @@ -41,7 +41,7 @@ One scannable reference for the four customization surfaces consumers reach for most: the application stylesheet, the `--swc-*` override pattern, theme/scale modifiers, and Adobe Clean Spectrum VF font loading. -For a gentler introduction, start with [Get started (for consumers)](for-consumers.md). Deep-dive topics link out from each section below. +For a gentler introduction, start with [Get started (for consumers)](get-started.md). Deep-dive topics link out from each section below. ## Install the stylesheet diff --git a/CONTRIBUTOR-DOCS/00_get-started/for-consumers.md b/CONTRIBUTOR-DOCS/for-consumers/get-started.md similarity index 89% rename from CONTRIBUTOR-DOCS/00_get-started/for-consumers.md rename to CONTRIBUTOR-DOCS/for-consumers/get-started.md index 489cd8a8c12..3228c3f53a9 100644 --- a/CONTRIBUTOR-DOCS/00_get-started/for-consumers.md +++ b/CONTRIBUTOR-DOCS/for-consumers/get-started.md @@ -1,6 +1,6 @@ -[CONTRIBUTOR-DOCS](../README.md) / [Get started](README.md) / Get started (for consumers) +[CONTRIBUTOR-DOCS](../README.md) / For Consumers / Get started (for consumers) @@ -59,4 +59,4 @@ React wrappers are planned. No plans for Vue or Svelte support at this time. For - **Components** — browse the component catalog in the **Components** section of the sidebar - **Customization** — override tokens, themes, and fonts in [Customization guides](/docs/learn-customization-getting-started--docs) - **Accessibility** — review [accessibility guidance](/docs/learn-accessibility-guides-overview--docs) for consumers -- **Contributing** — see [Contributor guides](../01_contributor-guides/README.md) if you want to contribute upstream +- **Contributing** — see [Contributor guides](../for-contributors/README.md) if you want to contribute upstream diff --git a/CONTRIBUTOR-DOCS/01_contributor-guides/11_2ndgen_testing.md b/CONTRIBUTOR-DOCS/for-contributors/2ndgen-testing.md similarity index 91% rename from CONTRIBUTOR-DOCS/01_contributor-guides/11_2ndgen_testing.md rename to CONTRIBUTOR-DOCS/for-contributors/2ndgen-testing.md index 258ec1748dc..20280063ea6 100644 --- a/CONTRIBUTOR-DOCS/01_contributor-guides/11_2ndgen_testing.md +++ b/CONTRIBUTOR-DOCS/for-contributors/2ndgen-testing.md @@ -20,7 +20,7 @@ ## Overview -2nd gen components use three types of tests: Storybook play functions for interaction tests, Playwright for accessibility tests, and visual regression testing through stories. The full testing guide — including file structure, test patterns, assertion conventions, accessibility testing, coverage thresholds, flaky test prevention, and more — lives in the [Testing guide](../02_style-guide/04_testing/README.md). +2nd gen components use three types of tests: Storybook play functions for interaction tests, Playwright for accessibility tests, and visual regression testing through stories. The full testing guide — including file structure, test patterns, assertion conventions, accessibility testing, coverage thresholds, flaky test prevention, and more — lives in the [Testing guide](../for-contributors/style-guide/testing/README.md). ## Where to put tests diff --git a/CONTRIBUTOR-DOCS/for-contributors/README.md b/CONTRIBUTOR-DOCS/for-contributors/README.md new file mode 100644 index 00000000000..4d62704d17e --- /dev/null +++ b/CONTRIBUTOR-DOCS/for-contributors/README.md @@ -0,0 +1,38 @@ + + +[CONTRIBUTOR-DOCS](../README.md) / Contributor guides + + + +# Contributor guides + + + +
+Beneath this doc + +- [2nd gen testing](2ndgen-testing.md) +- [Accessibility testing](accessibility-testing.md) +- [Authoring contributor docs](authoring-contributor-docs/README.md) + - Templates +- [Focus management](focus-management.md) +- [Getting involved](getting-involved.md) +- [Making a pull request](making-a-pull-request.md) +- [Participating in PR reviews](participating-in-pr-reviews.md) +- [Patching dependencies](patching-dependencies.md) +- [Releasing SWC](releasing-swc.md) +- [Style guide](style-guide/README.md) + - [2nd-Gen CSS](style-guide/css/README.md) + - [Linting tools](style-guide/linting-tools.md) + - [Testing guide](style-guide/testing/README.md) + - [2nd-gen TypeScript](style-guide/typescript/README.md) +- [Tools vs packages: where code lives](tools-vs-packages.md) +- [Maintaining StackBlitz examples for Spectrum Web Components](using-stackblitz.md) +- [Using the issue tracker](using-the-issue-tracker.md) +- [Working in the SWC repo](working-in-the-swc-repo.md) + +
+ + + +(Content to be added) diff --git a/CONTRIBUTOR-DOCS/01_contributor-guides/09_accessibility-testing.md b/CONTRIBUTOR-DOCS/for-contributors/accessibility-testing.md similarity index 99% rename from CONTRIBUTOR-DOCS/01_contributor-guides/09_accessibility-testing.md rename to CONTRIBUTOR-DOCS/for-contributors/accessibility-testing.md index 24b567e11f7..dd24517ea84 100644 --- a/CONTRIBUTOR-DOCS/01_contributor-guides/09_accessibility-testing.md +++ b/CONTRIBUTOR-DOCS/for-contributors/accessibility-testing.md @@ -456,7 +456,7 @@ spectrum-web-components/ ├── playwright.a11y.config.ts # Playwright config (both gens) ├── playwright.a11y.2ndgen.config.ts # Playwright config (2nd-gen only) ├── CONTRIBUTOR-DOCS/ -│ └── 01_contributor-guides/ +│ └── for-contributors/ │ └── 09_accessibility-testing.md # This guide ├── 1st-gen/ │ ├── package.json # Test scripts (points to root config) diff --git a/CONTRIBUTOR-DOCS/01_contributor-guides/07_authoring-contributor-docs/README.md b/CONTRIBUTOR-DOCS/for-contributors/authoring-contributor-docs/README.md similarity index 98% rename from CONTRIBUTOR-DOCS/01_contributor-guides/07_authoring-contributor-docs/README.md rename to CONTRIBUTOR-DOCS/for-contributors/authoring-contributor-docs/README.md index 5ef8a3c8b37..8e1a679996f 100644 --- a/CONTRIBUTOR-DOCS/01_contributor-guides/07_authoring-contributor-docs/README.md +++ b/CONTRIBUTOR-DOCS/for-contributors/authoring-contributor-docs/README.md @@ -113,8 +113,8 @@ Each doc file has the following structure, with markers clearly separating auto- - 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/)` + - Correct: `[Workstreams](../../project-planning/02_workstreams/README.md)` + - Incorrect: `[Workstreams](../../project-planning/02_workstreams/)` ## Organizing docs diff --git a/CONTRIBUTOR-DOCS/01_contributor-guides/07_authoring-contributor-docs/templates/consumer-quickstart.md b/CONTRIBUTOR-DOCS/for-contributors/authoring-contributor-docs/templates/consumer-quickstart.md similarity index 100% rename from CONTRIBUTOR-DOCS/01_contributor-guides/07_authoring-contributor-docs/templates/consumer-quickstart.md rename to CONTRIBUTOR-DOCS/for-contributors/authoring-contributor-docs/templates/consumer-quickstart.md diff --git a/CONTRIBUTOR-DOCS/01_contributor-guides/07_authoring-contributor-docs/update-nav.js b/CONTRIBUTOR-DOCS/for-contributors/authoring-contributor-docs/update-nav.js similarity index 100% rename from CONTRIBUTOR-DOCS/01_contributor-guides/07_authoring-contributor-docs/update-nav.js rename to CONTRIBUTOR-DOCS/for-contributors/authoring-contributor-docs/update-nav.js diff --git a/CONTRIBUTOR-DOCS/01_contributor-guides/07_authoring-contributor-docs/verify-links.js b/CONTRIBUTOR-DOCS/for-contributors/authoring-contributor-docs/verify-links.js similarity index 98% rename from CONTRIBUTOR-DOCS/01_contributor-guides/07_authoring-contributor-docs/verify-links.js rename to CONTRIBUTOR-DOCS/for-contributors/authoring-contributor-docs/verify-links.js index 55352f356cd..60f3240946b 100644 --- a/CONTRIBUTOR-DOCS/01_contributor-guides/07_authoring-contributor-docs/verify-links.js +++ b/CONTRIBUTOR-DOCS/for-contributors/authoring-contributor-docs/verify-links.js @@ -144,7 +144,8 @@ function extractLinksFromContent(filepath, content) { if ( linkHref.startsWith('http://') || linkHref.startsWith('https://') || - linkHref.startsWith('//') + linkHref.startsWith('//') || + linkHref.startsWith('/docs/') // Stable Storybook paths pass through; see .ai/rules/storybook-mdx-conversion.md ) { continue; // Skip external URLs } diff --git a/CONTRIBUTOR-DOCS/01_contributor-guides/13_focus-management.md b/CONTRIBUTOR-DOCS/for-contributors/focus-management.md similarity index 99% rename from CONTRIBUTOR-DOCS/01_contributor-guides/13_focus-management.md rename to CONTRIBUTOR-DOCS/for-contributors/focus-management.md index 1aaa9338b0d..c3aa46a4334 100644 --- a/CONTRIBUTOR-DOCS/01_contributor-guides/13_focus-management.md +++ b/CONTRIBUTOR-DOCS/for-contributors/focus-management.md @@ -635,4 +635,4 @@ When submitting a PR that affects focus management, you must verify: - [Open UI Focusgroup Explainer](https://open-ui.org/components/focusgroup.explainer/) — The emerging standard the controller aligns with - [Shadow DOM delegatesFocus](https://frontendmasters.com/blog/shadow-dom-focus-delegation-getting-delegatesfocus-right/) — Implementation deep-dive - [On disabled and aria-disabled](https://kittygiraudel.com/2024/03/29/on-disabled-and-aria-disabled-attributes/) — Why `DisabledMixin` uses `aria-disabled` -- [Accessibility Testing Guide](09_accessibility-testing.md) — Automated and manual a11y testing +- [Accessibility Testing Guide](accessibility-testing.md) — Automated and manual a11y testing diff --git a/CONTRIBUTOR-DOCS/01_contributor-guides/01_getting-involved.md b/CONTRIBUTOR-DOCS/for-contributors/getting-involved.md similarity index 97% rename from CONTRIBUTOR-DOCS/01_contributor-guides/01_getting-involved.md rename to CONTRIBUTOR-DOCS/for-contributors/getting-involved.md index ea3cbe952bb..119a1cd1ab2 100644 --- a/CONTRIBUTOR-DOCS/01_contributor-guides/01_getting-involved.md +++ b/CONTRIBUTOR-DOCS/for-contributors/getting-involved.md @@ -80,7 +80,7 @@ Should any behavior fall short of these expectations, please report it to + +[CONTRIBUTOR-DOCS](../../README.md) / [Contributor guides](../README.md) / Style guide + + + +# Style guide + + + +
+Beneath this doc + +- [2nd-Gen CSS](css/README.md) + - [Styling Anti-Patterns (What to Avoid)](css/anti-patterns.md) + - [Component CSS PR Checklist](css/component-css-pr-checklist.md) + - [Component CSS](css/component-css.md) + - [Custom Properties](css/custom-properties.md) + - [Property order quick reference](css/property-order-quick-reference.md) + - [Spectrum CSS to SWC Migration](css/spectrum-swc-migration.md) +- [Linting tools](linting-tools.md) +- [Testing guide](testing/README.md) + - [Avoiding flaky tests](testing/avoiding-flaky-tests.md) + - [Code coverage](testing/code-coverage.md) + - [Playwright accessibility testing](testing/playwright-accessbility-testing.md) + - [PR review checklist](testing/pr-review-checklist.md) + - [Resources](testing/resources.md) + - [Running tests](testing/running-tests.md) + - [Storybook testing](testing/storybook-testing.md) + - [Testing overview](testing/testing-overview.md) + - [Testing utilities](testing/testing-utilities.md) + - [Visual regression testing](testing/visual-regresssion-testing.md) +- [2nd-gen TypeScript](typescript/README.md) + - [Base class vs concrete class](typescript/base-vs-concrete.md) + - [Class structure](typescript/class-structure.md) + - [Component types](typescript/component-types.md) + - [Composition patterns](typescript/composition-patterns.md) + - [Controller composition](typescript/controller-composition.md) + - [Debug and validation](typescript/debug-validation.md) + - [Directive composition](typescript/directive-composition.md) + - [File organization](typescript/file-organization.md) + - [Interface composition](typescript/interface-composition.md) + - [JSDoc standards](typescript/jsdoc-standards.md) + - [Lit decorators and modifiers](typescript/lit-decorators.md) + - [Method patterns](typescript/method-patterns.md) + - [Mixin composition](typescript/mixin-composition.md) + - [Naming conventions](typescript/naming-conventions.md) + - [Property patterns](typescript/property-patterns.md) + - [Rendering patterns](typescript/rendering-patterns.md) + - [TypeScript modifier keywords](typescript/typescript-modifiers.md) + +
+ + + +This section covers the coding conventions and authoring patterns used across Spectrum Web Components. Following these guides keeps the codebase consistent, reviewable, and accessible. + +- **[2nd-gen CSS](css/README.md)** — Property ordering, class naming, custom properties, selector patterns, and forced-colors requirements for component stylesheets. +- **[2nd-gen TypeScript](typescript/README.md)** — File organization, class structure, decorators, JSDoc, type definitions, naming, and composition patterns for component TypeScript. +- **[Linting tools](linting-tools.md)** — How automated linting enforces these conventions and how to configure or extend the rules. diff --git a/CONTRIBUTOR-DOCS/for-contributors/style-guide/css/README.md b/CONTRIBUTOR-DOCS/for-contributors/style-guide/css/README.md new file mode 100644 index 00000000000..407d167fdfb --- /dev/null +++ b/CONTRIBUTOR-DOCS/for-contributors/style-guide/css/README.md @@ -0,0 +1,25 @@ + + +[CONTRIBUTOR-DOCS](../../../README.md) / [Contributor guides](../../README.md) / [Style guide](../README.md) / 2nd-Gen CSS + + + +# 2nd-Gen CSS + + + +
+Beneath this doc + +- [Styling Anti-Patterns (What to Avoid)](anti-patterns.md) +- [Component CSS PR Checklist](component-css-pr-checklist.md) +- [Component CSS](component-css.md) +- [Custom Properties](custom-properties.md) +- [Property order quick reference](property-order-quick-reference.md) +- [Spectrum CSS to SWC Migration](spectrum-swc-migration.md) + +
+ + + +This section contains style guides for CSS authoring and maintenance for **2nd-gen** component styles. diff --git a/CONTRIBUTOR-DOCS/02_style-guide/01_css/05_anti-patterns.md b/CONTRIBUTOR-DOCS/for-contributors/style-guide/css/anti-patterns.md similarity index 89% rename from CONTRIBUTOR-DOCS/02_style-guide/01_css/05_anti-patterns.md rename to CONTRIBUTOR-DOCS/for-contributors/style-guide/css/anti-patterns.md index 485090733b0..e414e26ef83 100644 --- a/CONTRIBUTOR-DOCS/02_style-guide/01_css/05_anti-patterns.md +++ b/CONTRIBUTOR-DOCS/for-contributors/style-guide/css/anti-patterns.md @@ -1,6 +1,6 @@ -[CONTRIBUTOR-DOCS](../../README.md) / [Style guide](../README.md) / [2nd-Gen CSS](README.md) / Styling Anti-Patterns (What to Avoid) +[CONTRIBUTOR-DOCS](../../../README.md) / [Contributor guides](../../README.md) / [Style guide](../README.md) / [2nd-Gen CSS](README.md) / Styling Anti-Patterns (What to Avoid) @@ -66,7 +66,7 @@ This appendix lists **common mistakes encountered when adopting the 2nd-gen SWC Each anti-pattern is grounded in real Spectrum source patterns. **Badge** and **Status Light** are reference implementations for correct patterns. -📖 **Reference implementations**: [Badge](../../../2nd-gen/packages/swc/components/badge/badge.css) · [Status Light](../../../2nd-gen/packages/swc/components/status-light/status-light.css) · [Reference Migration: Badge](04_spectrum-swc-migration.md#reference-migration-badge) +📖 **Reference implementations**: [Badge](../../../../2nd-gen/packages/swc/components/badge/badge.css) · [Status Light](../../../../2nd-gen/packages/swc/components/status-light/status-light.css) · [Reference Migration: Badge](spectrum-swc-migration.md#reference-migration-badge) ## 1. Leaving Visual Styles on `:host` @@ -105,7 +105,7 @@ Each anti-pattern is grounded in real Spectrum source patterns. **Badge** and ** 🔎 **Badge reference:** See the migrated Badge where `:host` is limited to layout (`display`, `place-self`, `vertical-align`) and all visual styling lives on `.swc-Badge`. -📖 See: *Component CSS Style Guide → [Rule order](01_component-css.md#rule-order)* +📖 See: *Component CSS Style Guide → [Rule order](component-css.md#rule-order)* ## 2. Preserving `--mod-*` as an Extra Indirection Layer @@ -167,7 +167,7 @@ min-block-size: var(--swc-mod-badge-height, token('component-height-100')); 🔎 **Badge reference:** See the Badge migration where all `--mod-* → spectrum → property` chains are collapsed into intentional `--swc-badge-*` properties. -📖 See: *Custom Properties Style Guide → [Component custom property exposure](02_custom-properties.md#component-custom-property-exposure)* +📖 See: *Custom Properties Style Guide → [Component custom property exposure](custom-properties.md#component-custom-property-exposure)* ## 3. Excess Variant Classes in `render()` @@ -204,7 +204,7 @@ classMap({ 🔎 **Badge reference:** Badge size, variant, subtle, and outline states are all expressed via `:host()` selectors and custom property updates. -📖 See: *Component CSS Style Guide → [Variant implementation patterns](01_component-css.md#variant-implementation-patterns)* +📖 See: *Component CSS Style Guide → [Variant implementation patterns](component-css.md#variant-implementation-patterns)* ## 4. Increasing Selector Specificity to Force Overrides @@ -253,9 +253,9 @@ Badge size, variant, subtle, and outline states are all expressed via `:host()` ``` 🔎 **Badge reference:** -[badge.css](../../../2nd-gen/packages/swc/components/badge/badge.css) uses `.swc-Badge--subtle:where(.swc-Badge--gray)` for compounded variants. [Divider](../../../2nd-gen/packages/swc/components/divider/divider.css) uses the same pattern for static color + size. +[badge.css](../../../../2nd-gen/packages/swc/components/badge/badge.css) uses `.swc-Badge--subtle:where(.swc-Badge--gray)` for compounded variants. [Divider](../../../../2nd-gen/packages/swc/components/divider/divider.css) uses the same pattern for static color + size. -📖 See: *Component CSS Style Guide → [Managing Specificity](01_component-css.md#managing-specificity)* +📖 See: *Component CSS Style Guide → [Managing Specificity](component-css.md#managing-specificity)* ## 5. Using `:where()` Inside `:host()` for Custom Property Updates @@ -288,7 +288,7 @@ Badge size, variant, subtle, and outline states are all expressed via `:host()` 🔎 **Badge reference:** Badge safely compounds attributes within `:host()` when updating custom properties only. -📖 See: *Component CSS Style Guide → [Shadow DOM specificity and custom property inheritance](01_component-css.md#shadow-dom-specificity-and-custom-property-inheritance)* +📖 See: *Component CSS Style Guide → [Shadow DOM specificity and custom property inheritance](component-css.md#shadow-dom-specificity-and-custom-property-inheritance)* ## 6. Exposing Too Many Custom Properties “Just in Case” @@ -319,7 +319,7 @@ Badge safely compounds attributes within `:host()` when updating custom properti 🔎 **Badge reference:** Badge exposes a minimal, intentional surface and uses `_swc-*` properties for derived calculations. -📖 See: *Custom Properties Style Guide → [Private properties](02_custom-properties.md#private-properties)* +📖 See: *Custom Properties Style Guide → [Private properties](custom-properties.md#private-properties)* ## 7. Treating Forced-Colors as a Variant @@ -356,9 +356,9 @@ Badge exposes a minimal, intentional surface and uses `_swc-*` properties for de ``` 🔎 **Status Light reference:** -[status-light.css](../../../2nd-gen/packages/swc/components/status-light/status-light.css) overrides `--swc-statuslight-content-color` and adds a border to the dot pseudo-element so it stays visible in high-contrast mode. +[status-light.css](../../../../2nd-gen/packages/swc/components/status-light/status-light.css) overrides `--swc-statuslight-content-color` and adds a border to the dot pseudo-element so it stays visible in high-contrast mode. -📖 See: *Component CSS Style Guide → [Forced colors requirements](01_component-css.md#forced-colors-requirements)* +📖 See: *Component CSS Style Guide → [Forced colors requirements](component-css.md#forced-colors-requirements)* ## 8. Leaving Spectrum-Era Classes After Migration @@ -388,7 +388,7 @@ Badge exposes a minimal, intentional surface and uses `_swc-*` properties for de 🔎 **Badge reference:** After migration, Badge relies solely on `.swc-Badge` and attributes. -📖 See: *Spectrum CSS to SWC Migration → [Validation step: removing legacy classes](04_spectrum-swc-migration.md#5-validation-step-removing-legacy-classes)* +📖 See: *Spectrum CSS to SWC Migration → [Validation step: removing legacy classes](spectrum-swc-migration.md#5-validation-step-removing-legacy-classes)* ## Before/after refactoring examples diff --git a/CONTRIBUTOR-DOCS/02_style-guide/01_css/03_component-css-pr-checklist.md b/CONTRIBUTOR-DOCS/for-contributors/style-guide/css/component-css-pr-checklist.md similarity index 92% rename from CONTRIBUTOR-DOCS/02_style-guide/01_css/03_component-css-pr-checklist.md rename to CONTRIBUTOR-DOCS/for-contributors/style-guide/css/component-css-pr-checklist.md index 63c34fae82d..e7e3084e5b8 100644 --- a/CONTRIBUTOR-DOCS/02_style-guide/01_css/03_component-css-pr-checklist.md +++ b/CONTRIBUTOR-DOCS/for-contributors/style-guide/css/component-css-pr-checklist.md @@ -1,6 +1,6 @@ -[CONTRIBUTOR-DOCS](../../README.md) / [Style guide](../README.md) / [2nd-Gen CSS](README.md) / Component CSS PR Checklist +[CONTRIBUTOR-DOCS](../../../README.md) / [Contributor guides](../../README.md) / [Style guide](../README.md) / [2nd-Gen CSS](README.md) / Component CSS PR Checklist diff --git a/CONTRIBUTOR-DOCS/02_style-guide/01_css/01_component-css.md b/CONTRIBUTOR-DOCS/for-contributors/style-guide/css/component-css.md similarity index 93% rename from CONTRIBUTOR-DOCS/02_style-guide/01_css/01_component-css.md rename to CONTRIBUTOR-DOCS/for-contributors/style-guide/css/component-css.md index 6105ccf247b..38ccc8c42ae 100644 --- a/CONTRIBUTOR-DOCS/02_style-guide/01_css/01_component-css.md +++ b/CONTRIBUTOR-DOCS/for-contributors/style-guide/css/component-css.md @@ -1,6 +1,6 @@ -[CONTRIBUTOR-DOCS](../../README.md) / [Style guide](../README.md) / [2nd-Gen CSS](README.md) / Component CSS +[CONTRIBUTOR-DOCS](../../../README.md) / [Contributor guides](../../README.md) / [Style guide](../README.md) / [2nd-Gen CSS](README.md) / Component CSS @@ -42,7 +42,7 @@ The following are high-level guidelines for the CSS creation for components. ## Contributor TL;DR -> For examples of all of these rules in practice, review [Badge](../../../2nd-gen/packages/swc/components/badge/badge.css) and [Status Light](../../../2nd-gen/packages/swc/components/status-light/status-light.css) as reference implementations, the [reference migration for Badge](04_spectrum-swc-migration.md#reference-migration-badge), and the [anti-patterns guide](05_anti-patterns.md). +> For examples of all of these rules in practice, review [Badge](../../../../2nd-gen/packages/swc/components/badge/badge.css) and [Status Light](../../../../2nd-gen/packages/swc/components/status-light/status-light.css) as reference implementations, the [reference migration for Badge](spectrum-swc-migration.md#reference-migration-badge), and the [anti-patterns guide](anti-patterns.md). - `:host` is for defining how the container participates in the global layout, not the core component styles - Follow the prescribed rule order @@ -85,7 +85,7 @@ Follow this outline for ordering rulesets within component stylesheets. This wil - If needed, this media query should *always* be at the end of the stylesheet to take priority over other styles. - Use direct internal selectors, not host selectors, to enforce the style and prevent accidental consumer overrides. -Sizes, variants, and states should primarily modify the component via updating component custom property values. Refer to the [custom properties style guide](02_custom-properties.md). +Sizes, variants, and states should primarily modify the component via updating component custom property values. Refer to the [custom properties style guide](custom-properties.md). ## CSS property ordering @@ -113,9 +113,9 @@ Inside each ruleset, order properties in a consistent way. This makes stylesheet
-For the full list and annotated examples, see the [property order quick reference](06_property-order-quick-reference.md). +For the full list and annotated examples, see the [property order quick reference](property-order-quick-reference.md). -**Example from [Badge](../../../2nd-gen/packages/swc/components/badge/badge.css)**: +**Example from [Badge](../../../../2nd-gen/packages/swc/components/badge/badge.css)**: ```css .swc-Badge { @@ -147,7 +147,7 @@ Use these patterns so class names are predictable across components. > **Note**: Classes are not the only way to apply variants and states — attribute selectors (e.g., `:host([variant="positive"])`) are preferred when exposing a customization surface. See [Variant implementation patterns](#variant-implementation-patterns) for guidance on when to use classes vs. attributes. -**Example from [Badge](../../../2nd-gen/packages/swc/components/badge/badge.css)**: +**Example from [Badge](../../../../2nd-gen/packages/swc/components/badge/badge.css)**: ```css .swc-Badge { /* base */ } @@ -157,7 +157,7 @@ Use these patterns so class names are predictable across components. .swc-Badge--gray { /* color variant */ } ``` -**Example from [Status Light](../../../2nd-gen/packages/swc/components/status-light/status-light.css)**: +**Example from [Status Light](../../../../2nd-gen/packages/swc/components/status-light/status-light.css)**: ```css .swc-StatusLight { /* base */ } @@ -180,7 +180,7 @@ Use comments to explain non-obvious choices. Keep them short and use sentence ca - Use `/* NOTE: */` for important caveats - Avoid comments that repeat what the code does -**Example from [Badge](../../../2nd-gen/packages/swc/components/badge/badge.css)**: +**Example from [Badge](../../../../2nd-gen/packages/swc/components/badge/badge.css)**: ```css /* NOTE: `accent` is the default color */ @@ -206,7 +206,7 @@ Use `:host` only for layout participation. Do not put visual styles here. } ``` -**Why**: `:host` is part of the public styling API. Visual styles here are harder to override. See [anti-pattern #1](05_anti-patterns.md#1-leaving-visual-styles-on-host). +**Why**: `:host` is part of the public styling API. Visual styles here are harder to override. See [anti-pattern #1](anti-patterns.md#1-leaving-visual-styles-on-host). ### When to use `:host([attribute])` @@ -224,7 +224,7 @@ See [Managing Specificity](#managing-specificity) for full guidance. In short: w ## Variant implementation patterns -Variants change how the component looks. Use the right selector based on customization intent of [custom property exposure](02_custom-properties.md#component-custom-property-exposure). +Variants change how the component looks. Use the right selector based on customization intent of [custom property exposure](custom-properties.md#component-custom-property-exposure). | Variant type | Selector | Example | | ------------------ | ---------------------------------------- | -------------------------------------- | @@ -234,7 +234,7 @@ Variants change how the component looks. Use the right selector based on customi | Static color | `.swc-ComponentName--staticWhite` | No exposure; ensures contrast | | Geometric | `.swc-ComponentName--fixed-inline-start` | No exposure; layout modifier | -**Example from [Badge](../../../2nd-gen/packages/swc/components/badge/badge.css)**: +**Example from [Badge](../../../../2nd-gen/packages/swc/components/badge/badge.css)**: ```css :host([variant="positive"]) { @@ -265,7 +265,7 @@ States reflect user interaction or component condition. Attach them to `:host` w Size variants (s, m, l, xl) use `:host([size="..."])` and update custom properties. Do not add size classes to `render()`. -**Example from [Status Light](../../../2nd-gen/packages/swc/components/status-light/status-light.css)**: +**Example from [Status Light](../../../../2nd-gen/packages/swc/components/status-light/status-light.css)**: ```css :host([size="s"]) { @@ -300,7 +300,7 @@ Use `@keyframes` at the top of the file. Apply animations via custom properties } ``` -**Example from [Progress Circle](../../../2nd-gen/packages/swc/components/progress-circle/progress-circle.css)**. +**Example from [Progress Circle](../../../../2nd-gen/packages/swc/components/progress-circle/progress-circle.css)**. **Transitions**: Prefer design tokens for duration and easing. Use `transition` in the Transitions/Animations category of the property order. @@ -315,7 +315,7 @@ Forced colors mode (Windows High Contrast, etc.) replaces colors with system val 3. **Use internal selectors**: Target `.swc-ComponentName` or internal elements, not `:host`. This prevents accidental consumer overrides from breaking accessibility. 4. **Reuse custom properties**: Override component custom properties (e.g. `--swc-statuslight-content-color`) so the rest of the stylesheet still works. -**Example from [Status Light](../../../2nd-gen/packages/swc/components/status-light/status-light.css)**: +**Example from [Status Light](../../../../2nd-gen/packages/swc/components/status-light/status-light.css)**: ```css @media (forced-colors: active) { @@ -442,7 +442,7 @@ However: - If you need to modify a direct CSS property (not a custom property), - or there is no corresponding custom property available, -then the change should be made on the base component or subcomponent selector, as described in the [custom properties style guide](02_custom-properties.md). +then the change should be made on the base component or subcomponent selector, as described in the [custom properties style guide](custom-properties.md). ### Using Cascade Layers (`@layer`) diff --git a/CONTRIBUTOR-DOCS/02_style-guide/01_css/02_custom-properties.md b/CONTRIBUTOR-DOCS/for-contributors/style-guide/css/custom-properties.md similarity index 90% rename from CONTRIBUTOR-DOCS/02_style-guide/01_css/02_custom-properties.md rename to CONTRIBUTOR-DOCS/for-contributors/style-guide/css/custom-properties.md index 86dd5389ac6..2053164e8e9 100644 --- a/CONTRIBUTOR-DOCS/02_style-guide/01_css/02_custom-properties.md +++ b/CONTRIBUTOR-DOCS/for-contributors/style-guide/css/custom-properties.md @@ -1,6 +1,6 @@ -[CONTRIBUTOR-DOCS](../../README.md) / [Style guide](../README.md) / [2nd-Gen CSS](README.md) / Custom Properties +[CONTRIBUTOR-DOCS](../../../README.md) / [Contributor guides](../../README.md) / [Style guide](../README.md) / [2nd-Gen CSS](README.md) / Custom Properties @@ -53,7 +53,7 @@ This guide explains how to manage **private, internal, and exposed custom proper CSS custom properties *normally* can't actually be "private". However, due to shadow DOM encapsulation, we can (partially*) enforce them as private by defining them on a nested wrapper within the component instead of on :host. -**Example from [Badge](../../../2nd-gen/packages/swc/components/badge/badge.css)** — private properties for internal calculations, with exposed properties consumed inline via `var()`: +**Example from [Badge](../../../../2nd-gen/packages/swc/components/badge/badge.css)** — private properties for internal calculations, with exposed properties consumed inline via `var()`: ```css .swc-Badge { @@ -68,7 +68,7 @@ CSS custom properties *normally* can't actually be "private". However, due to sh } ``` -**Example from [Status Light](../../../2nd-gen/packages/swc/components/status-light/status-light.css)** — private properties as passthroughs for size variants: +**Example from [Status Light](../../../../2nd-gen/packages/swc/components/status-light/status-light.css)** — private properties as passthroughs for size variants: ```css .swc-StatusLight { @@ -88,7 +88,7 @@ _*"partially" due to possible eventual exposure when we introduce parts_ - Only expose component properties when needed by the component itself or for passthrough (nested) styling - Exposed singularly based on CSS *property type*, and no longer based on states or variants - - This distinction directly affects which selector type is used (`:host()` vs internal class selectors). See [Variant Selectors and Inheritance](01_component-css.md#shadow-dom-specificity-and-custom-property-inheritance). + - This distinction directly affects which selector type is used (`:host()` vs internal class selectors). See [Variant Selectors and Inheritance](component-css.md#shadow-dom-specificity-and-custom-property-inheritance). - May be exposed via inclusion in private property, or inline with CSS property - Include in private property if value has repeated usage throughout base (non-variant) component styles - In migrated components, legacy `--mod-*` properties should not be preserved; instead, collapse the chain into a single component-level property. @@ -152,7 +152,7 @@ flowchart TD For examples of exposed vs internal properties applied via selectors, see: - [Selector Conventions](#selector-conventions) -- [Variant Selectors and Inheritance](01_component-css.md#shadow-dom-specificity-and-custom-property-inheritance) +- [Variant Selectors and Inheritance](component-css.md#shadow-dom-specificity-and-custom-property-inheritance) ### Exclusions for Custom Property Overrides @@ -166,7 +166,7 @@ There are some exclusions as to what should be exposed for overrides: - certain geometric variants (e.g. fixed-edge Badge) intentionally override exposed properties, such as corner radius - properties modified for forced-colors mode - ensures forced-colors related overrides take precedence over consumer overrides for base component - - forced-colors overrides are applied at the end of the component stylesheet. See the forced-colors section in the [Component CSS Style Guide](01_component-css.md). + - forced-colors overrides are applied at the end of the component stylesheet. See the forced-colors section in the [Component CSS Style Guide](component-css.md). Use internal selectors (ex. `.swc-Badge--magenta` ) to pass library overrides for these exclusions. @@ -190,7 +190,7 @@ swc-button:focus-visible ### Variant Selectors and Inheritance -Refer to the [Component CSS Style Guide](01_component-css.md#shadow-dom-specificity-and-custom-property-inheritance) for more details about variant selectors and how they are impacted by custom property inheritance. +Refer to the [Component CSS Style Guide](component-css.md#shadow-dom-specificity-and-custom-property-inheritance) for more details about variant selectors and how they are impacted by custom property inheritance. ## Using `token()` diff --git a/CONTRIBUTOR-DOCS/02_style-guide/01_css/06_property-order-quick-reference.md b/CONTRIBUTOR-DOCS/for-contributors/style-guide/css/property-order-quick-reference.md similarity index 89% rename from CONTRIBUTOR-DOCS/02_style-guide/01_css/06_property-order-quick-reference.md rename to CONTRIBUTOR-DOCS/for-contributors/style-guide/css/property-order-quick-reference.md index e2c3d56e8ab..04075c5b022 100644 --- a/CONTRIBUTOR-DOCS/02_style-guide/01_css/06_property-order-quick-reference.md +++ b/CONTRIBUTOR-DOCS/for-contributors/style-guide/css/property-order-quick-reference.md @@ -1,6 +1,6 @@ -[CONTRIBUTOR-DOCS](../../README.md) / [Style guide](../README.md) / [2nd-Gen CSS](README.md) / Property order quick reference +[CONTRIBUTOR-DOCS](../../../README.md) / [Contributor guides](../../README.md) / [Style guide](../README.md) / [2nd-Gen CSS](README.md) / Property order quick reference @@ -20,9 +20,9 @@ -Use this guide when writing or reviewing component CSS. Consistent property order makes stylesheets easier to scan and reduces merge conflicts. This order is enforced via `stylelint-order` and the property groups defined in [`linters/stylelint-property-order.js`](../../../linters/stylelint-property-order.js). The table below is a condensed summary — see that file for the full list. +Use this guide when writing or reviewing component CSS. Consistent property order makes stylesheets easier to scan and reduces merge conflicts. This order is enforced via `stylelint-order` and the property groups defined in [`linters/stylelint-property-order.js`](../../../../linters/stylelint-property-order.js). The table below is a condensed summary — see that file for the full list. -For full context, see [Component CSS](01_component-css.md#rule-order). +For full context, see [Component CSS](component-css.md#rule-order). ## Why property order matters @@ -55,7 +55,7 @@ This is the expected order as enforced by `stylelint-order`: ## Example from Badge -From [badge.css](../../../2nd-gen/packages/swc/components/badge/badge.css): +From [badge.css](../../../../2nd-gen/packages/swc/components/badge/badge.css): ```css .swc-Badge { @@ -90,7 +90,7 @@ From [badge.css](../../../2nd-gen/packages/swc/components/badge/badge.css): ## Example from Status Light -From [status-light.css](../../../2nd-gen/packages/swc/components/status-light/status-light.css): +From [status-light.css](../../../../2nd-gen/packages/swc/components/status-light/status-light.css): ```css .swc-StatusLight::before { @@ -115,4 +115,4 @@ From [status-light.css](../../../2nd-gen/packages/swc/components/status-light/st --- -**Reference implementations**: [Badge](../../../2nd-gen/packages/swc/components/badge/badge.css) · [Status Light](../../../2nd-gen/packages/swc/components/status-light/status-light.css) +**Reference implementations**: [Badge](../../../../2nd-gen/packages/swc/components/badge/badge.css) · [Status Light](../../../../2nd-gen/packages/swc/components/status-light/status-light.css) diff --git a/CONTRIBUTOR-DOCS/02_style-guide/01_css/04_spectrum-swc-migration.md b/CONTRIBUTOR-DOCS/for-contributors/style-guide/css/spectrum-swc-migration.md similarity index 94% rename from CONTRIBUTOR-DOCS/02_style-guide/01_css/04_spectrum-swc-migration.md rename to CONTRIBUTOR-DOCS/for-contributors/style-guide/css/spectrum-swc-migration.md index 0750eecbec8..15bbd721bb4 100644 --- a/CONTRIBUTOR-DOCS/02_style-guide/01_css/04_spectrum-swc-migration.md +++ b/CONTRIBUTOR-DOCS/for-contributors/style-guide/css/spectrum-swc-migration.md @@ -1,6 +1,6 @@ -[CONTRIBUTOR-DOCS](../../README.md) / [Style guide](../README.md) / [2nd-Gen CSS](README.md) / Spectrum CSS to SWC Migration +[CONTRIBUTOR-DOCS](../../../README.md) / [Contributor guides](../../README.md) / [Style guide](../README.md) / [2nd-Gen CSS](README.md) / Spectrum CSS to SWC Migration @@ -28,7 +28,7 @@ This guide outlines the high-level mechanical steps for migrating existing Spect ## Core Migration Steps -For concrete before/after examples of each of these steps, review the [reference migration](#reference-migration-badge) as well as examples for avoiding issues in the [anti-patterns guide](05_anti-patterns.md). +For concrete before/after examples of each of these steps, review the [reference migration](#reference-migration-badge) as well as examples for avoiding issues in the [anti-patterns guide](anti-patterns.md). > _The order after #1 & #2 isn’t important, but individual steps must be completed when applicable._ @@ -44,11 +44,11 @@ For concrete before/after examples of each of these steps, review the [reference - update class and custom property prefixes from `.spectrum` to `.swc` - you will refine custom properties more in step #4, but this will re-enable the initial visual styles since the prefix for design tokens has changed 3. Update from the base `:host` selector to use the component wrapper class name _unless_ determined to be a critical style best left on `:host` - - Visual styling should generally move off of `:host` and onto the component wrapper class. Styles left on `:host` should be limited to layout participation or defensive defaults (see `:host` guidance in the [Component CSS Style Guide](01_component-css.md)). -4. Remove `--mod` properties, and migrate behavior using exposed or internal custom properties, plus upgrade to `token()`, as described in the [Custom Properties style guide](02_custom-properties.md) + - Visual styling should generally move off of `:host` and onto the component wrapper class. Styles left on `:host` should be limited to layout participation or defensive defaults (see `:host` guidance in the [Component CSS Style Guide](component-css.md)). +4. Remove `--mod` properties, and migrate behavior using exposed or internal custom properties, plus upgrade to `token()`, as described in the [Custom Properties style guide](custom-properties.md) - during migration, collapse `--mod-*` fallback chains into a single, intentional component custom property 5. Remove any extra override CSS files after combination is complete -6. After applying custom properties guidance and the additional [Component CSS Style Guide](01_component-css.md) rules, revisit the `render()` and remove any unused classes +6. After applying custom properties guidance and the additional [Component CSS Style Guide](component-css.md) rules, revisit the `render()` and remove any unused classes - this often indicates successful consolidation of variant and state logic into CSS > **Tip:** If a migration feels unusually complex, it often indicates that legacy Spectrum styles encoded behavior that should now be expressed via custom properties or layout primitives. Visit the style guides to help guide refactoring decisions. diff --git a/CONTRIBUTOR-DOCS/02_style-guide/03_linting-tools.md b/CONTRIBUTOR-DOCS/for-contributors/style-guide/linting-tools.md similarity index 97% rename from CONTRIBUTOR-DOCS/02_style-guide/03_linting-tools.md rename to CONTRIBUTOR-DOCS/for-contributors/style-guide/linting-tools.md index a26cf0ec672..eba5d6e3645 100644 --- a/CONTRIBUTOR-DOCS/02_style-guide/03_linting-tools.md +++ b/CONTRIBUTOR-DOCS/for-contributors/style-guide/linting-tools.md @@ -1,6 +1,6 @@ -[CONTRIBUTOR-DOCS](../README.md) / [Style guide](README.md) / Linting tools +[CONTRIBUTOR-DOCS](../../README.md) / [Contributor guides](../README.md) / [Style guide](README.md) / Linting tools @@ -227,7 +227,7 @@ Import groups are ordered as: ### CSS property ordering -CSS properties are sorted in a custom logical order by `stylelint-order`, defined in [`stylelint-property-order.js`](../../linters/stylelint-property-order.js). Run `yarn format:styles` to sort properties. +CSS properties are sorted in a custom logical order by `stylelint-order`, defined in [`stylelint-property-order.js`](../../../linters/stylelint-property-order.js). Run `yarn format:styles` to sort properties. ### Design tokens (2nd-gen only) diff --git a/CONTRIBUTOR-DOCS/02_style-guide/04_testing/README.md b/CONTRIBUTOR-DOCS/for-contributors/style-guide/testing/README.md similarity index 60% rename from CONTRIBUTOR-DOCS/02_style-guide/04_testing/README.md rename to CONTRIBUTOR-DOCS/for-contributors/style-guide/testing/README.md index 9d295ea920a..f914268ab3d 100644 --- a/CONTRIBUTOR-DOCS/02_style-guide/04_testing/README.md +++ b/CONTRIBUTOR-DOCS/for-contributors/style-guide/testing/README.md @@ -1,6 +1,6 @@ -[CONTRIBUTOR-DOCS](../../README.md) / [Style guide](../README.md) / Testing guide +[CONTRIBUTOR-DOCS](../../../README.md) / [Contributor guides](../../README.md) / [Style guide](../README.md) / Testing guide @@ -11,16 +11,16 @@
Beneath this doc -- [Testing overview](01_testing-overview.md) -- [Storybook testing](02_storybook-testing.md) -- [Playwright accessibility testing](03_playwright-accessbility-testing.md) -- [Visual regression testing](04_visual-regresssion-testing.md) -- [Testing utilities](05_testing-utilities.md) -- [Code coverage](06_code-coverage.md) -- [Avoiding flaky tests](07_avoiding-flaky-tests.md) -- [Running tests](08_running-tests..md) -- [PR review checklist](09_pr_review-checklist.md) -- [Resources](10_resources.md) +- [Avoiding flaky tests](avoiding-flaky-tests.md) +- [Code coverage](code-coverage.md) +- [Playwright accessibility testing](playwright-accessbility-testing.md) +- [PR review checklist](pr-review-checklist.md) +- [Resources](resources.md) +- [Running tests](running-tests.md) +- [Storybook testing](storybook-testing.md) +- [Testing overview](testing-overview.md) +- [Testing utilities](testing-utilities.md) +- [Visual regression testing](visual-regresssion-testing.md)
diff --git a/CONTRIBUTOR-DOCS/02_style-guide/04_testing/07_avoiding-flaky-tests.md b/CONTRIBUTOR-DOCS/for-contributors/style-guide/testing/avoiding-flaky-tests.md similarity index 94% rename from CONTRIBUTOR-DOCS/02_style-guide/04_testing/07_avoiding-flaky-tests.md rename to CONTRIBUTOR-DOCS/for-contributors/style-guide/testing/avoiding-flaky-tests.md index bc0f866043f..7efbbc532ac 100644 --- a/CONTRIBUTOR-DOCS/02_style-guide/04_testing/07_avoiding-flaky-tests.md +++ b/CONTRIBUTOR-DOCS/for-contributors/style-guide/testing/avoiding-flaky-tests.md @@ -1,6 +1,6 @@ -[CONTRIBUTOR-DOCS](../../README.md) / [Style guide](../README.md) / [Testing guide](README.md) / Avoiding flaky tests +[CONTRIBUTOR-DOCS](../../../README.md) / [Contributor guides](../../README.md) / [Style guide](../README.md) / [Testing guide](README.md) / Avoiding flaky tests diff --git a/CONTRIBUTOR-DOCS/02_style-guide/04_testing/06_code-coverage.md b/CONTRIBUTOR-DOCS/for-contributors/style-guide/testing/code-coverage.md similarity index 91% rename from CONTRIBUTOR-DOCS/02_style-guide/04_testing/06_code-coverage.md rename to CONTRIBUTOR-DOCS/for-contributors/style-guide/testing/code-coverage.md index 01ef9d768ad..98f3fc92e28 100644 --- a/CONTRIBUTOR-DOCS/02_style-guide/04_testing/06_code-coverage.md +++ b/CONTRIBUTOR-DOCS/for-contributors/style-guide/testing/code-coverage.md @@ -1,6 +1,6 @@ -[CONTRIBUTOR-DOCS](../../README.md) / [Style guide](../README.md) / [Testing guide](README.md) / Code coverage +[CONTRIBUTOR-DOCS](../../../README.md) / [Contributor guides](../../README.md) / [Style guide](../README.md) / [Testing guide](README.md) / Code coverage diff --git a/CONTRIBUTOR-DOCS/02_style-guide/04_testing/03_playwright-accessbility-testing.md b/CONTRIBUTOR-DOCS/for-contributors/style-guide/testing/playwright-accessbility-testing.md similarity index 98% rename from CONTRIBUTOR-DOCS/02_style-guide/04_testing/03_playwright-accessbility-testing.md rename to CONTRIBUTOR-DOCS/for-contributors/style-guide/testing/playwright-accessbility-testing.md index 9c8487e7cb8..ad89c1775b8 100644 --- a/CONTRIBUTOR-DOCS/02_style-guide/04_testing/03_playwright-accessbility-testing.md +++ b/CONTRIBUTOR-DOCS/for-contributors/style-guide/testing/playwright-accessbility-testing.md @@ -1,6 +1,6 @@ -[CONTRIBUTOR-DOCS](../../README.md) / [Style guide](../README.md) / [Testing guide](README.md) / Playwright accessibility testing +[CONTRIBUTOR-DOCS](../../../README.md) / [Contributor guides](../../README.md) / [Style guide](../README.md) / [Testing guide](README.md) / Playwright accessibility testing diff --git a/CONTRIBUTOR-DOCS/02_style-guide/04_testing/09_pr_review-checklist.md b/CONTRIBUTOR-DOCS/for-contributors/style-guide/testing/pr-review-checklist.md similarity index 87% rename from CONTRIBUTOR-DOCS/02_style-guide/04_testing/09_pr_review-checklist.md rename to CONTRIBUTOR-DOCS/for-contributors/style-guide/testing/pr-review-checklist.md index bbe04b8d76a..c434e0f3e1a 100644 --- a/CONTRIBUTOR-DOCS/02_style-guide/04_testing/09_pr_review-checklist.md +++ b/CONTRIBUTOR-DOCS/for-contributors/style-guide/testing/pr-review-checklist.md @@ -1,6 +1,6 @@ -[CONTRIBUTOR-DOCS](../../README.md) / [Style guide](../README.md) / [Testing guide](README.md) / PR review checklist +[CONTRIBUTOR-DOCS](../../../README.md) / [Contributor guides](../../README.md) / [Style guide](../README.md) / [Testing guide](README.md) / PR review checklist diff --git a/CONTRIBUTOR-DOCS/02_style-guide/04_testing/10_resources.md b/CONTRIBUTOR-DOCS/for-contributors/style-guide/testing/resources.md similarity index 76% rename from CONTRIBUTOR-DOCS/02_style-guide/04_testing/10_resources.md rename to CONTRIBUTOR-DOCS/for-contributors/style-guide/testing/resources.md index 1c52144f00b..f2c45d5d7fa 100644 --- a/CONTRIBUTOR-DOCS/02_style-guide/04_testing/10_resources.md +++ b/CONTRIBUTOR-DOCS/for-contributors/style-guide/testing/resources.md @@ -1,6 +1,6 @@ -[CONTRIBUTOR-DOCS](../../README.md) / [Style guide](../README.md) / [Testing guide](README.md) / Resources +[CONTRIBUTOR-DOCS](../../../README.md) / [Contributor guides](../../README.md) / [Style guide](../README.md) / [Testing guide](README.md) / Resources @@ -18,5 +18,5 @@ - [UI testing best practices](https://dev.to/bryce/ui-testing-best-practices-4ke4) - [Red Hat Design System testing conventions](https://github.com/RedHat-UX/red-hat-design-system/wiki/Testing) - [WCAG 2.1 quick reference](https://www.w3.org/WAI/WCAG21/quickref/) -- [Accessibility testing guide](../../01_contributor-guides/09_accessibility-testing.md) (project-specific) -- [2nd gen testing guide](../../01_contributor-guides/11_2ndgen_testing.md) (project-specific) +- [Accessibility testing guide](../../accessibility-testing.md) (project-specific) +- [2nd gen testing guide](../../2ndgen-testing.md) (project-specific) diff --git a/CONTRIBUTOR-DOCS/02_style-guide/04_testing/08_running-tests..md b/CONTRIBUTOR-DOCS/for-contributors/style-guide/testing/running-tests.md similarity index 94% rename from CONTRIBUTOR-DOCS/02_style-guide/04_testing/08_running-tests..md rename to CONTRIBUTOR-DOCS/for-contributors/style-guide/testing/running-tests.md index 2415dd763bb..2fa2a7b7690 100644 --- a/CONTRIBUTOR-DOCS/02_style-guide/04_testing/08_running-tests..md +++ b/CONTRIBUTOR-DOCS/for-contributors/style-guide/testing/running-tests.md @@ -1,6 +1,6 @@ -[CONTRIBUTOR-DOCS](../../README.md) / [Style guide](../README.md) / [Testing guide](README.md) / Running tests +[CONTRIBUTOR-DOCS](../../../README.md) / [Contributor guides](../../README.md) / [Style guide](../README.md) / [Testing guide](README.md) / Running tests diff --git a/CONTRIBUTOR-DOCS/02_style-guide/04_testing/02_storybook-testing.md b/CONTRIBUTOR-DOCS/for-contributors/style-guide/testing/storybook-testing.md similarity index 99% rename from CONTRIBUTOR-DOCS/02_style-guide/04_testing/02_storybook-testing.md rename to CONTRIBUTOR-DOCS/for-contributors/style-guide/testing/storybook-testing.md index 4638f2d85bb..6698bff3aa5 100644 --- a/CONTRIBUTOR-DOCS/02_style-guide/04_testing/02_storybook-testing.md +++ b/CONTRIBUTOR-DOCS/for-contributors/style-guide/testing/storybook-testing.md @@ -1,6 +1,6 @@ -[CONTRIBUTOR-DOCS](../../README.md) / [Style guide](../README.md) / [Testing guide](README.md) / Storybook testing +[CONTRIBUTOR-DOCS](../../../README.md) / [Contributor guides](../../README.md) / [Style guide](../README.md) / [Testing guide](README.md) / Storybook testing diff --git a/CONTRIBUTOR-DOCS/02_style-guide/04_testing/01_testing-overview.md b/CONTRIBUTOR-DOCS/for-contributors/style-guide/testing/testing-overview.md similarity index 90% rename from CONTRIBUTOR-DOCS/02_style-guide/04_testing/01_testing-overview.md rename to CONTRIBUTOR-DOCS/for-contributors/style-guide/testing/testing-overview.md index 47c538d6117..4023ba41d6f 100644 --- a/CONTRIBUTOR-DOCS/02_style-guide/04_testing/01_testing-overview.md +++ b/CONTRIBUTOR-DOCS/for-contributors/style-guide/testing/testing-overview.md @@ -1,6 +1,6 @@ -[CONTRIBUTOR-DOCS](../../README.md) / [Style guide](../README.md) / [Testing guide](README.md) / Testing overview +[CONTRIBUTOR-DOCS](../../../README.md) / [Contributor guides](../../README.md) / [Style guide](../README.md) / [Testing guide](README.md) / Testing overview diff --git a/CONTRIBUTOR-DOCS/02_style-guide/04_testing/05_testing-utilities.md b/CONTRIBUTOR-DOCS/for-contributors/style-guide/testing/testing-utilities.md similarity index 96% rename from CONTRIBUTOR-DOCS/02_style-guide/04_testing/05_testing-utilities.md rename to CONTRIBUTOR-DOCS/for-contributors/style-guide/testing/testing-utilities.md index 6c4b4b034e2..51f762f6a4f 100644 --- a/CONTRIBUTOR-DOCS/02_style-guide/04_testing/05_testing-utilities.md +++ b/CONTRIBUTOR-DOCS/for-contributors/style-guide/testing/testing-utilities.md @@ -1,6 +1,6 @@ -[CONTRIBUTOR-DOCS](../../README.md) / [Style guide](../README.md) / [Testing guide](README.md) / Testing utilities +[CONTRIBUTOR-DOCS](../../../README.md) / [Contributor guides](../../README.md) / [Style guide](../README.md) / [Testing guide](README.md) / Testing utilities diff --git a/CONTRIBUTOR-DOCS/02_style-guide/04_testing/04_visual-regresssion-testing.md b/CONTRIBUTOR-DOCS/for-contributors/style-guide/testing/visual-regresssion-testing.md similarity index 89% rename from CONTRIBUTOR-DOCS/02_style-guide/04_testing/04_visual-regresssion-testing.md rename to CONTRIBUTOR-DOCS/for-contributors/style-guide/testing/visual-regresssion-testing.md index 371b9a796f1..1300a88f8f1 100644 --- a/CONTRIBUTOR-DOCS/02_style-guide/04_testing/04_visual-regresssion-testing.md +++ b/CONTRIBUTOR-DOCS/for-contributors/style-guide/testing/visual-regresssion-testing.md @@ -1,6 +1,6 @@ -[CONTRIBUTOR-DOCS](../../README.md) / [Style guide](../README.md) / [Testing guide](README.md) / Visual regression testing +[CONTRIBUTOR-DOCS](../../../README.md) / [Contributor guides](../../README.md) / [Style guide](../README.md) / [Testing guide](README.md) / Visual regression testing diff --git a/CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/README.md b/CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/README.md new file mode 100644 index 00000000000..c4c9512d0eb --- /dev/null +++ b/CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/README.md @@ -0,0 +1,78 @@ + + +[CONTRIBUTOR-DOCS](../../../README.md) / [Contributor guides](../../README.md) / [Style guide](../README.md) / 2nd-gen TypeScript + + + +# 2nd-gen TypeScript + + + +
+In this doc + +- [Guides](#guides) +- [External references](#external-references) + +
+ +
+Beneath this doc + +- [Base class vs concrete class](base-vs-concrete.md) +- [Class structure](class-structure.md) +- [Component types](component-types.md) +- [Composition patterns](composition-patterns.md) +- [Controller composition](controller-composition.md) +- [Debug and validation](debug-validation.md) +- [Directive composition](directive-composition.md) +- [File organization](file-organization.md) +- [Interface composition](interface-composition.md) +- [JSDoc standards](jsdoc-standards.md) +- [Lit decorators and modifiers](lit-decorators.md) +- [Method patterns](method-patterns.md) +- [Mixin composition](mixin-composition.md) +- [Naming conventions](naming-conventions.md) +- [Property patterns](property-patterns.md) +- [Rendering patterns](rendering-patterns.md) +- [TypeScript modifier keywords](typescript-modifiers.md) + +
+ + + +This section covers the TypeScript coding conventions for **2nd-gen** component development. These guides explain how to organize files, structure classes, use decorators, write JSDoc, define types, and compose behavior using mixins, controllers, directives, and interfaces. + +The guides are written for both human contributors and AI agents. They use simple language, clear examples, and consistent formatting so anyone can follow them. + +> **Reference implementation:** The [Badge](../../../../2nd-gen/packages/core/components/badge/Badge.base.ts) component is the primary example throughout these guides. Other 2nd-gen components (Status Light, Progress Circle, Divider, Asset) are used where they show different patterns. + +## Guides + +- **[File organization](file-organization.md)** — Copyright headers, import grouping and order, export patterns, and where types files live. +- **[Class structure](class-structure.md)** — Base vs concrete class layout, section comments, and how to order properties and methods within sections. +- **[TypeScript modifier keywords](typescript-modifiers.md)** — When and how to use `static`, `override`, `public`, `protected`, and `private`. +- **[Lit decorators and modifiers](lit-decorators.md)** — `@property`, `@state`, `@query`, `@queryAssignedNodes`, `@eventOptions`, and other Lit decorators. +- **[Property patterns](property-patterns.md)** — Property ordering, reactive property decorators, and when to use custom getters/setters vs Lit defaults. +- **[Method patterns](method-patterns.md)** — Method ordering, lifecycle method names, event handler naming, ARIA role assignment, and the `override` keyword. +- **[JSDoc standards](jsdoc-standards.md)** — When JSDoc is required, what to include, and how to use tags like `@internal`, `@attribute`, `@slot`, `@element`, and `@example`. +- **[Component types](component-types.md)** — Patterns for `*.types.ts` files: constant arrays, type derivation, S1/S2 split, naming, and removal strategy. +- **[Rendering patterns](rendering-patterns.md)** — Helper functions, inline SVG, size transformations, and classMap patterns. +- **[Naming conventions](naming-conventions.md)** — Rules for class names, property names, method names, type names, constant names, CSS class names, and file names. +- **[Base class vs concrete class](base-vs-concrete.md)** — What belongs in core (base) vs SWC (concrete) and how to decide. +- **[Composition patterns](composition-patterns.md)** — When to use a mixin, controller, directive, or interface, and how to choose. +- **[Mixin composition](mixin-composition.md)** — How to compose mixins: order, options, depth limits, and patterns. +- **[Controller composition](controller-composition.md)** — How to create and attach Lit controllers to host components. +- **[Directive composition](directive-composition.md)** — How to use built-in Lit directives and author custom ones. +- **[Interface composition](interface-composition.md)** — When to use `interface` vs `type`, and how to define and consume interfaces. +- **[Debug and validation](debug-validation.md)** — Debug-mode validation, warning patterns, and the `window.__swc` API. + +## External references + +- [TypeScript documentation](https://www.typescriptlang.org/docs/) +- [Lit documentation](https://lit.dev/docs/) +- [Lit — Reactive properties](https://lit.dev/docs/components/properties/) +- [Lit — Decorators](https://lit.dev/docs/components/decorators/) +- [Lit — Controllers](https://lit.dev/docs/composition/controllers/) +- [Lit — Directives](https://lit.dev/docs/templates/directives/) +- [JSDoc reference](https://jsdoc.app/) diff --git a/CONTRIBUTOR-DOCS/02_style-guide/02_typescript/11_base-vs-concrete.md b/CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/base-vs-concrete.md similarity index 97% rename from CONTRIBUTOR-DOCS/02_style-guide/02_typescript/11_base-vs-concrete.md rename to CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/base-vs-concrete.md index 70b8817812a..691bb226481 100644 --- a/CONTRIBUTOR-DOCS/02_style-guide/02_typescript/11_base-vs-concrete.md +++ b/CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/base-vs-concrete.md @@ -1,6 +1,6 @@ -[CONTRIBUTOR-DOCS](../../README.md) / [Style guide](../README.md) / [2nd-gen TypeScript](README.md) / Base class vs concrete class +[CONTRIBUTOR-DOCS](../../../README.md) / [Contributor guides](../../README.md) / [Style guide](../README.md) / [2nd-gen TypeScript](README.md) / Base class vs concrete class diff --git a/CONTRIBUTOR-DOCS/02_style-guide/02_typescript/02_class-structure.md b/CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/class-structure.md similarity index 97% rename from CONTRIBUTOR-DOCS/02_style-guide/02_typescript/02_class-structure.md rename to CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/class-structure.md index ba6e0b8a816..8244729f529 100644 --- a/CONTRIBUTOR-DOCS/02_style-guide/02_typescript/02_class-structure.md +++ b/CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/class-structure.md @@ -1,6 +1,6 @@ -[CONTRIBUTOR-DOCS](../../README.md) / [Style guide](../README.md) / [2nd-gen TypeScript](README.md) / Class structure +[CONTRIBUTOR-DOCS](../../../README.md) / [Contributor guides](../../README.md) / [Style guide](../README.md) / [2nd-gen TypeScript](README.md) / Class structure @@ -34,7 +34,7 @@ This guide explains how to organize a component class in 2nd-gen. Every componen The base class holds behavior and API. The concrete class holds styles, rendering, and anything specific to the visual layer. This separation keeps logic testable and reusable independently of rendering. -> **Reference implementation:** [Badge.base.ts](../../../2nd-gen/packages/core/components/badge/Badge.base.ts) (base) and [Badge.ts](../../../2nd-gen/packages/swc/components/badge/Badge.ts) (concrete). +> **Reference implementation:** [Badge.base.ts](../../../../2nd-gen/packages/core/components/badge/Badge.base.ts) (base) and [Badge.ts](../../../../2nd-gen/packages/swc/components/badge/Badge.ts) (concrete). ## Two classes per component diff --git a/CONTRIBUTOR-DOCS/02_style-guide/02_typescript/08_component-types.md b/CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/component-types.md similarity index 97% rename from CONTRIBUTOR-DOCS/02_style-guide/02_typescript/08_component-types.md rename to CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/component-types.md index 6d4caf546eb..6de7e82c766 100644 --- a/CONTRIBUTOR-DOCS/02_style-guide/02_typescript/08_component-types.md +++ b/CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/component-types.md @@ -1,6 +1,6 @@ -[CONTRIBUTOR-DOCS](../../README.md) / [Style guide](../README.md) / [2nd-gen TypeScript](README.md) / Component types +[CONTRIBUTOR-DOCS](../../../README.md) / [Contributor guides](../../README.md) / [Style guide](../README.md) / [2nd-gen TypeScript](README.md) / Component types @@ -46,7 +46,7 @@ This guide defines patterns for the `*.types.ts` files in `core/components/*/`. These files contain the constants and types that 2nd-gen component classes consume. -> **Note:** This guide was migrated from `02_style-guide/03_component-types.md`. The original file has been removed. +> **Note:** This guide was migrated from `for-contributors/style-guide/03_component-types.md`. The original file has been removed. ## Purpose @@ -66,7 +66,7 @@ Types files serve three goals: ## Naming conventions -> **See also:** [Naming conventions](10_naming-conventions.md) for the full naming rules, including CSS class names and the rationale for underscore-separated prefixes. +> **See also:** [Naming conventions](naming-conventions.md) for the full naming rules, including CSS class names and the rationale for underscore-separated prefixes. ### Constant prefixes diff --git a/CONTRIBUTOR-DOCS/02_style-guide/02_typescript/12_composition-patterns.md b/CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/composition-patterns.md similarity index 88% rename from CONTRIBUTOR-DOCS/02_style-guide/02_typescript/12_composition-patterns.md rename to CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/composition-patterns.md index 453e4175727..217396d89a0 100644 --- a/CONTRIBUTOR-DOCS/02_style-guide/02_typescript/12_composition-patterns.md +++ b/CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/composition-patterns.md @@ -1,6 +1,6 @@ -[CONTRIBUTOR-DOCS](../../README.md) / [Style guide](../README.md) / [2nd-gen TypeScript](README.md) / Composition patterns +[CONTRIBUTOR-DOCS](../../../README.md) / [Contributor guides](../../README.md) / [Style guide](../README.md) / [2nd-gen TypeScript](README.md) / Composition patterns @@ -106,7 +106,7 @@ Use an interface when you need to define the **shape** of an object without addi **Mixin depth limit:** -Components should have a maximum mixin depth of 2. If more behavior is needed, use controllers instead of additional mixins. See [Mixin composition](13_mixin-composition.md#mixin-depth-limit) for the rationale. +Components should have a maximum mixin depth of 2. If more behavior is needed, use controllers instead of additional mixins. See [Mixin composition](mixin-composition.md#mixin-depth-limit) for the rationale. Use this flowchart to choose the right pattern: @@ -133,7 +133,7 @@ Does the behavior add properties or lifecycle to the component? Each composition pattern has its own detailed guide: -- **[Mixin composition](13_mixin-composition.md)** — How to compose mixins, ordering, options, and patterns -- **[Controller composition](14_controller-composition.md)** — How to create and attach controllers -- **[Directive composition](15_directive-composition.md)** — How to use built-in directives and author custom ones -- **[Interface composition](16_interface-composition.md)** — When to use interfaces and how to define them +- **[Mixin composition](mixin-composition.md)** — How to compose mixins, ordering, options, and patterns +- **[Controller composition](controller-composition.md)** — How to create and attach controllers +- **[Directive composition](directive-composition.md)** — How to use built-in directives and author custom ones +- **[Interface composition](interface-composition.md)** — When to use interfaces and how to define them diff --git a/CONTRIBUTOR-DOCS/02_style-guide/02_typescript/14_controller-composition.md b/CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/controller-composition.md similarity index 98% rename from CONTRIBUTOR-DOCS/02_style-guide/02_typescript/14_controller-composition.md rename to CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/controller-composition.md index 9a33804bc21..01199d12fca 100644 --- a/CONTRIBUTOR-DOCS/02_style-guide/02_typescript/14_controller-composition.md +++ b/CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/controller-composition.md @@ -1,6 +1,6 @@ -[CONTRIBUTOR-DOCS](../../README.md) / [Style guide](../README.md) / [2nd-gen TypeScript](README.md) / Controller composition +[CONTRIBUTOR-DOCS](../../../README.md) / [Contributor guides](../../README.md) / [Style guide](../README.md) / [2nd-gen TypeScript](README.md) / Controller composition diff --git a/CONTRIBUTOR-DOCS/02_style-guide/02_typescript/17_debug-validation.md b/CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/debug-validation.md similarity index 97% rename from CONTRIBUTOR-DOCS/02_style-guide/02_typescript/17_debug-validation.md rename to CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/debug-validation.md index c5ee6fed9d6..e898662c0d5 100644 --- a/CONTRIBUTOR-DOCS/02_style-guide/02_typescript/17_debug-validation.md +++ b/CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/debug-validation.md @@ -1,6 +1,6 @@ -[CONTRIBUTOR-DOCS](../../README.md) / [Style guide](../README.md) / [2nd-gen TypeScript](README.md) / Debug and validation +[CONTRIBUTOR-DOCS](../../../README.md) / [Contributor guides](../../README.md) / [Style guide](../README.md) / [2nd-gen TypeScript](README.md) / Debug and validation diff --git a/CONTRIBUTOR-DOCS/02_style-guide/02_typescript/15_directive-composition.md b/CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/directive-composition.md similarity index 97% rename from CONTRIBUTOR-DOCS/02_style-guide/02_typescript/15_directive-composition.md rename to CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/directive-composition.md index 92437241f84..78006641327 100644 --- a/CONTRIBUTOR-DOCS/02_style-guide/02_typescript/15_directive-composition.md +++ b/CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/directive-composition.md @@ -1,6 +1,6 @@ -[CONTRIBUTOR-DOCS](../../README.md) / [Style guide](../README.md) / [2nd-gen TypeScript](README.md) / Directive composition +[CONTRIBUTOR-DOCS](../../../README.md) / [Contributor guides](../../README.md) / [Style guide](../README.md) / [2nd-gen TypeScript](README.md) / Directive composition diff --git a/CONTRIBUTOR-DOCS/02_style-guide/02_typescript/01_file-organization.md b/CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/file-organization.md similarity index 94% rename from CONTRIBUTOR-DOCS/02_style-guide/02_typescript/01_file-organization.md rename to CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/file-organization.md index 3e002c271ae..e48ef7407cd 100644 --- a/CONTRIBUTOR-DOCS/02_style-guide/02_typescript/01_file-organization.md +++ b/CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/file-organization.md @@ -1,6 +1,6 @@ -[CONTRIBUTOR-DOCS](../../README.md) / [Style guide](../README.md) / [2nd-gen TypeScript](README.md) / File organization +[CONTRIBUTOR-DOCS](../../../README.md) / [Contributor guides](../../README.md) / [Style guide](../README.md) / [2nd-gen TypeScript](README.md) / File organization @@ -34,7 +34,7 @@ This guide explains how to organize files in 2nd-gen components. It covers the c ## Copyright header -Every TypeScript file starts with the Apache 2.0 copyright header. The template lives at [`linters/HEADER.js`](../../../linters/HEADER.js) and the `<%= YEAR %>` placeholder is replaced with the current year. The linter automatically adds this header to new files, so you do not need to copy it manually. Do not change the wording. +Every TypeScript file starts with the Apache 2.0 copyright header. The template lives at [`linters/HEADER.js`](../../../../linters/HEADER.js) and the `<%= YEAR %>` placeholder is replaced with the current year. The linter automatically adds this header to new files, so you do not need to copy it manually. Do not change the wording. ## Import grouping and order @@ -248,4 +248,4 @@ declare global { defineElement('swc-badge', Badge); ``` -For more on type file patterns (naming, structure, S1/S2 split), see [Component types](08_component-types.md). +For more on type file patterns (naming, structure, S1/S2 split), see [Component types](component-types.md). diff --git a/CONTRIBUTOR-DOCS/02_style-guide/02_typescript/16_interface-composition.md b/CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/interface-composition.md similarity index 96% rename from CONTRIBUTOR-DOCS/02_style-guide/02_typescript/16_interface-composition.md rename to CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/interface-composition.md index 0c6a5197baf..7597b8d4010 100644 --- a/CONTRIBUTOR-DOCS/02_style-guide/02_typescript/16_interface-composition.md +++ b/CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/interface-composition.md @@ -1,6 +1,6 @@ -[CONTRIBUTOR-DOCS](../../README.md) / [Style guide](../README.md) / [2nd-gen TypeScript](README.md) / Interface composition +[CONTRIBUTOR-DOCS](../../../README.md) / [Contributor guides](../../README.md) / [Style guide](../README.md) / [2nd-gen TypeScript](README.md) / Interface composition diff --git a/CONTRIBUTOR-DOCS/02_style-guide/02_typescript/07_jsdoc-standards.md b/CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/jsdoc-standards.md similarity index 98% rename from CONTRIBUTOR-DOCS/02_style-guide/02_typescript/07_jsdoc-standards.md rename to CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/jsdoc-standards.md index 10ae22fc219..80520ebcb4c 100644 --- a/CONTRIBUTOR-DOCS/02_style-guide/02_typescript/07_jsdoc-standards.md +++ b/CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/jsdoc-standards.md @@ -1,6 +1,6 @@ -[CONTRIBUTOR-DOCS](../../README.md) / [Style guide](../README.md) / [2nd-gen TypeScript](README.md) / JSDoc standards +[CONTRIBUTOR-DOCS](../../../README.md) / [Contributor guides](../../README.md) / [Style guide](../README.md) / [2nd-gen TypeScript](README.md) / JSDoc standards diff --git a/CONTRIBUTOR-DOCS/02_style-guide/02_typescript/04_lit-decorators.md b/CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/lit-decorators.md similarity index 96% rename from CONTRIBUTOR-DOCS/02_style-guide/02_typescript/04_lit-decorators.md rename to CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/lit-decorators.md index ed7dc82b3b4..8e2cad26d96 100644 --- a/CONTRIBUTOR-DOCS/02_style-guide/02_typescript/04_lit-decorators.md +++ b/CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/lit-decorators.md @@ -1,6 +1,6 @@ -[CONTRIBUTOR-DOCS](../../README.md) / [Style guide](../README.md) / [2nd-gen TypeScript](README.md) / Lit decorators and modifiers +[CONTRIBUTOR-DOCS](../../../README.md) / [Contributor guides](../../README.md) / [Style guide](../README.md) / [2nd-gen TypeScript](README.md) / Lit decorators and modifiers @@ -258,4 +258,4 @@ The `@property()` decorator feeds the **Custom Elements Manifest** (CEM). Proper `@state()` properties are **not** included in the CEM because they are internal. -JSDoc tags on the class (like `@attribute`, `@slot`, `@element`) also feed CEM. See [JSDoc standards](07_jsdoc-standards.md) for details on which tags CEM consumes. +JSDoc tags on the class (like `@attribute`, `@slot`, `@element`) also feed CEM. See [JSDoc standards](jsdoc-standards.md) for details on which tags CEM consumes. diff --git a/CONTRIBUTOR-DOCS/02_style-guide/02_typescript/06_method-patterns.md b/CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/method-patterns.md similarity index 94% rename from CONTRIBUTOR-DOCS/02_style-guide/02_typescript/06_method-patterns.md rename to CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/method-patterns.md index 8daee6e48cb..20a2612ab33 100644 --- a/CONTRIBUTOR-DOCS/02_style-guide/02_typescript/06_method-patterns.md +++ b/CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/method-patterns.md @@ -1,6 +1,6 @@ -[CONTRIBUTOR-DOCS](../../README.md) / [Style guide](../README.md) / [2nd-gen TypeScript](README.md) / Method patterns +[CONTRIBUTOR-DOCS](../../../README.md) / [Contributor guides](../../README.md) / [Style guide](../README.md) / [2nd-gen TypeScript](README.md) / Method patterns @@ -27,7 +27,7 @@ This guide explains how to order and name methods in 2nd-gen component classes. ## Method ordering -Within the [IMPLEMENTATION section](02_class-structure.md#section-implementation) of a base class, or the [RENDERING & STYLING section](02_class-structure.md#section-rendering-and-styling) of a concrete class, order methods by access level: +Within the [IMPLEMENTATION section](class-structure.md#section-implementation) of a base class, or the [RENDERING & STYLING section](class-structure.md#section-rendering-and-styling) of a concrete class, order methods by access level: 1. **public** methods first 2. **protected** methods second (including lifecycle) @@ -193,7 +193,7 @@ protected override firstUpdated(changed: PropertyValues): void { ## The override keyword -Always use the `override` keyword when overriding lifecycle methods or any method from the parent class. This tells TypeScript the method must exist in the parent. See [TypeScript modifier keywords](03_typescript-modifiers.md#override) for more. +Always use the `override` keyword when overriding lifecycle methods or any method from the parent class. This tells TypeScript the method must exist in the parent. See [TypeScript modifier keywords](typescript-modifiers.md#override) for more. ```ts // ✅ Good diff --git a/CONTRIBUTOR-DOCS/02_style-guide/02_typescript/13_mixin-composition.md b/CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/mixin-composition.md similarity index 98% rename from CONTRIBUTOR-DOCS/02_style-guide/02_typescript/13_mixin-composition.md rename to CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/mixin-composition.md index 256f3c51485..2ffcb261ce5 100644 --- a/CONTRIBUTOR-DOCS/02_style-guide/02_typescript/13_mixin-composition.md +++ b/CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/mixin-composition.md @@ -1,6 +1,6 @@ -[CONTRIBUTOR-DOCS](../../README.md) / [Style guide](../README.md) / [2nd-gen TypeScript](README.md) / Mixin composition +[CONTRIBUTOR-DOCS](../../../README.md) / [Contributor guides](../../README.md) / [Style guide](../README.md) / [2nd-gen TypeScript](README.md) / Mixin composition diff --git a/CONTRIBUTOR-DOCS/02_style-guide/02_typescript/10_naming-conventions.md b/CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/naming-conventions.md similarity index 92% rename from CONTRIBUTOR-DOCS/02_style-guide/02_typescript/10_naming-conventions.md rename to CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/naming-conventions.md index bec7d88edd9..7d4fda39be9 100644 --- a/CONTRIBUTOR-DOCS/02_style-guide/02_typescript/10_naming-conventions.md +++ b/CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/naming-conventions.md @@ -1,6 +1,6 @@ -[CONTRIBUTOR-DOCS](../../README.md) / [Style guide](../README.md) / [2nd-gen TypeScript](README.md) / Naming conventions +[CONTRIBUTOR-DOCS](../../../README.md) / [Contributor guides](../../README.md) / [Style guide](../README.md) / [2nd-gen TypeScript](README.md) / Naming conventions @@ -77,7 +77,7 @@ public static_color?: ProgressCircleStaticColor; public _isOpen = false; // should be: private _isOpen = false; ``` -The one exception for underscores is backing fields that pair with a custom getter/setter (see [Property patterns](05_property-patterns.md#backing-fields)). +The one exception for underscores is backing fields that pair with a custom getter/setter (see [Property patterns](property-patterns.md#backing-fields)). ## Type names @@ -90,7 +90,7 @@ Use **PascalCase** matching the component class name. No `I` prefix for interfac | Static color | `ProgressCircleStaticColor`, `DividerStaticColor` | | Semantic variant | `BadgeSemanticVariant` | -See [Component types](08_component-types.md#type-names) for detailed naming and suffixing rules. +See [Component types](component-types.md#type-names) for detailed naming and suffixing rules. ```ts // ✅ Good @@ -115,7 +115,7 @@ Use **UPPER_SNAKE_CASE** with an underscore-separated component prefix. Multi-word component names use underscores: `STATUS_LIGHT_`, not `STATUSLIGHT_`. -See [Component types](08_component-types.md#constant-prefixes) for the full prefix rules. +See [Component types](component-types.md#constant-prefixes) for the full prefix rules. ```ts // ✅ Good @@ -144,7 +144,7 @@ PROGRESSCIRCLE_VALID_SIZES ACTIONBUTTON_VARIANTS ``` -If existing code uses merged prefixes, rename to the underscore-separated form (see [Component types](08_component-types.md#constant-prefixes)). +If existing code uses merged prefixes, rename to the underscore-separated form (see [Component types](component-types.md#constant-prefixes)). ## CSS class names diff --git a/CONTRIBUTOR-DOCS/02_style-guide/02_typescript/05_property-patterns.md b/CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/property-patterns.md similarity index 95% rename from CONTRIBUTOR-DOCS/02_style-guide/02_typescript/05_property-patterns.md rename to CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/property-patterns.md index 6e9405edfbf..0029f52ccc8 100644 --- a/CONTRIBUTOR-DOCS/02_style-guide/02_typescript/05_property-patterns.md +++ b/CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/property-patterns.md @@ -1,6 +1,6 @@ -[CONTRIBUTOR-DOCS](../../README.md) / [Style guide](../README.md) / [2nd-gen TypeScript](README.md) / Property patterns +[CONTRIBUTOR-DOCS](../../../README.md) / [Contributor guides](../../README.md) / [Style guide](../README.md) / [2nd-gen TypeScript](README.md) / Property patterns @@ -26,7 +26,7 @@ This guide explains how to declare and order properties in 2nd-gen component cla ## Property ordering -Within each [class section](02_class-structure.md), order properties by access level: +Within each [class section](class-structure.md), order properties by access level: 1. **public** properties first 2. **protected** properties second @@ -91,7 +91,7 @@ static override readonly VARIANTS_COLOR = BADGE_VARIANTS_COLOR; ## Reactive properties with @property() -Use the `@property()` decorator for properties that are part of the component's public API. See [Lit decorators](04_lit-decorators.md) for full decorator options. +Use the `@property()` decorator for properties that are part of the component's public API. See [Lit decorators](lit-decorators.md) for full decorator options. Key rules: diff --git a/CONTRIBUTOR-DOCS/02_style-guide/02_typescript/09_rendering-patterns.md b/CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/rendering-patterns.md similarity index 97% rename from CONTRIBUTOR-DOCS/02_style-guide/02_typescript/09_rendering-patterns.md rename to CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/rendering-patterns.md index b8a13f5a417..7df58b18319 100644 --- a/CONTRIBUTOR-DOCS/02_style-guide/02_typescript/09_rendering-patterns.md +++ b/CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/rendering-patterns.md @@ -1,6 +1,6 @@ -[CONTRIBUTOR-DOCS](../../README.md) / [Style guide](../README.md) / [2nd-gen TypeScript](README.md) / Rendering patterns +[CONTRIBUTOR-DOCS](../../../README.md) / [Contributor guides](../../README.md) / [Style guide](../README.md) / [2nd-gen TypeScript](README.md) / Rendering patterns diff --git a/CONTRIBUTOR-DOCS/02_style-guide/02_typescript/03_typescript-modifiers.md b/CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/typescript-modifiers.md similarity index 97% rename from CONTRIBUTOR-DOCS/02_style-guide/02_typescript/03_typescript-modifiers.md rename to CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/typescript-modifiers.md index 02f8a3616e0..c648f73709a 100644 --- a/CONTRIBUTOR-DOCS/02_style-guide/02_typescript/03_typescript-modifiers.md +++ b/CONTRIBUTOR-DOCS/for-contributors/style-guide/typescript/typescript-modifiers.md @@ -1,6 +1,6 @@ -[CONTRIBUTOR-DOCS](../../README.md) / [Style guide](../README.md) / [2nd-gen TypeScript](README.md) / TypeScript modifier keywords +[CONTRIBUTOR-DOCS](../../../README.md) / [Contributor guides](../../README.md) / [Style guide](../README.md) / [2nd-gen TypeScript](README.md) / TypeScript modifier keywords diff --git a/CONTRIBUTOR-DOCS/01_contributor-guides/12_tools-vs-packages.md b/CONTRIBUTOR-DOCS/for-contributors/tools-vs-packages.md similarity index 100% rename from CONTRIBUTOR-DOCS/01_contributor-guides/12_tools-vs-packages.md rename to CONTRIBUTOR-DOCS/for-contributors/tools-vs-packages.md diff --git a/CONTRIBUTOR-DOCS/01_contributor-guides/10_using-stackblitz.md b/CONTRIBUTOR-DOCS/for-contributors/using-stackblitz.md similarity index 100% rename from CONTRIBUTOR-DOCS/01_contributor-guides/10_using-stackblitz.md rename to CONTRIBUTOR-DOCS/for-contributors/using-stackblitz.md diff --git a/CONTRIBUTOR-DOCS/01_contributor-guides/02_using-the-issue-tracker.md b/CONTRIBUTOR-DOCS/for-contributors/using-the-issue-tracker.md similarity index 100% rename from CONTRIBUTOR-DOCS/01_contributor-guides/02_using-the-issue-tracker.md rename to CONTRIBUTOR-DOCS/for-contributors/using-the-issue-tracker.md diff --git a/CONTRIBUTOR-DOCS/01_contributor-guides/03_working-in-the-swc-repo.md b/CONTRIBUTOR-DOCS/for-contributors/working-in-the-swc-repo.md similarity index 93% rename from CONTRIBUTOR-DOCS/01_contributor-guides/03_working-in-the-swc-repo.md rename to CONTRIBUTOR-DOCS/for-contributors/working-in-the-swc-repo.md index 80f73433a43..5b8b545cfb4 100644 --- a/CONTRIBUTOR-DOCS/01_contributor-guides/03_working-in-the-swc-repo.md +++ b/CONTRIBUTOR-DOCS/for-contributors/working-in-the-swc-repo.md @@ -71,7 +71,7 @@ This setting uses the `.git-blame-ignore-revs` file in the repository root. 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](../03_project-planning/01_objectives-and-strategy.md). +> This transition is motivated by some important strategic goals. For more information, see [Objectives and Strategy](../project-planning/01_objectives-and-strategy.md). Instead of creating a separate branch or repo for 2nd-gen, we are working on both projects side-by-side in this repository. The two generations are **independent** — there is no runtime dependency between them. Code in 2nd-gen does not affect 1st-gen, and vice versa. @@ -86,9 +86,9 @@ Reflecting this structure, the repository is organized into two top-level worksp - The 2nd-gen SWC library (`packages/swc/`). -Within both 1st-gen and 2nd-gen, the repo separates **components** (user-facing UI that matches Spectrum design) from **tools/utilities** (base classes, theme, grid, tokens, reactive controllers, etc.). For how we decide where new or existing code belongs, see [Tools vs packages](12_tools-vs-packages.md). +Within both 1st-gen and 2nd-gen, the repo separates **components** (user-facing UI that matches Spectrum design) from **tools/utilities** (base classes, theme, grid, tokens, reactive controllers, etc.). For how we decide where new or existing code belongs, see [Tools vs packages](tools-vs-packages.md). -During this transition, depending on what you're trying to accomplish, you may end up working in `[1st-gen](/1st-gen/README.md)`, `[2nd-gen](/2nd-gen/README.md)`, or both. If you have any questions, [please ask](./01_getting-involved.md#community--support)—we're happy to help. +During this transition, depending on what you're trying to accomplish, you may end up working in `[1st-gen](/1st-gen/README.md)`, `[2nd-gen](/2nd-gen/README.md)`, or both. If you have any questions, [please ask](./getting-involved.md#community--support)—we're happy to help. ## Development workflow @@ -159,4 +159,4 @@ Here are the most frequently used commands available from the repository root: | `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](./09_accessibility-testing.md) for detailed information about writing and running accessibility tests. +For more specific workflows and advanced topics, refer to the other contributor guides, especially [Accessibility testing](./accessibility-testing.md) for detailed information about writing and running accessibility tests. diff --git a/CONTRIBUTOR-DOCS/03_project-planning/01_objectives-and-strategy.md b/CONTRIBUTOR-DOCS/project-planning/01_objectives-and-strategy.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/01_objectives-and-strategy.md rename to CONTRIBUTOR-DOCS/project-planning/01_objectives-and-strategy.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/01_2nd-gen-definition-and-development/README.md b/CONTRIBUTOR-DOCS/project-planning/02_workstreams/01_2nd-gen-definition-and-development/README.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/01_2nd-gen-definition-and-development/README.md rename to CONTRIBUTOR-DOCS/project-planning/02_workstreams/01_2nd-gen-definition-and-development/README.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/01_status.md b/CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/01_status.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/01_status.md rename to CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/01_status.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_analyze-rendering-and-styling/README.md b/CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_analyze-rendering-and-styling/README.md similarity index 98% rename from CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_analyze-rendering-and-styling/README.md rename to CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_analyze-rendering-and-styling/README.md index 8d8db316df7..b3eb0ce2b20 100644 --- a/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_analyze-rendering-and-styling/README.md +++ b/CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_analyze-rendering-and-styling/README.md @@ -206,7 +206,7 @@ The prompt template lives in the component-migration-analysis skill at `.cursor/ ### Adding new components 1. Use the component-migration-analysis skill with the target component name (or follow the full prompt in the skill's references folder). -2. Generate the markdown file in `CONTRIBUTOR-DOCS/03_project-planning/03_components/[component-name]/rendering-and-styling-migration-analysis.md` +2. Generate the markdown file in `CONTRIBUTOR-DOCS/project-planning/03_components/[component-name]/rendering-and-styling-migration-analysis.md` 3. Review and validate all sections for accuracy 4. Submit a PR diff --git a/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_washing-machine-workflow.md b/CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_washing-machine-workflow.md similarity index 93% rename from CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_washing-machine-workflow.md rename to CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_washing-machine-workflow.md index 35aa0337bb7..10f1bda30db 100644 --- a/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_washing-machine-workflow.md +++ b/CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_washing-machine-workflow.md @@ -336,27 +336,27 @@ If you are renaming or removing a public prop or attribute, confirm with the tea ## Phase 4: Styling -**Goal:** Migrate CSS to 2nd-gen structure and follow the CSS style guide. Follow the [full migration steps](../../../../02_style-guide/01_css/04_spectrum-swc-migration.md); see also [Step 6: Migrate rendering & styles from Spectrum CSS](06_migrate-rendering-and-styles.md) for workstream context. Requires a local **spectrum-css** checkout next to this repo—see [Workspace setup](#workspace-setup). +**Goal:** Migrate CSS to 2nd-gen structure and follow the CSS style guide. Follow the [full migration steps](../../../../for-contributors/style-guide/css/spectrum-swc-migration.md); see also [Step 6: Migrate rendering & styles from Spectrum CSS](06_migrate-rendering-and-styles.md) for workstream context. Requires a local **spectrum-css** checkout next to this repo—see [Workspace setup](#workspace-setup). ### What to do -1. **Follow the migration steps** — [Step 6](06_migrate-rendering-and-styles.md) and the [full migration steps](../../../../02_style-guide/01_css/04_spectrum-swc-migration.md). Use [03_components/](../../../03_components/) for spectrum-two alignment. Copy S2 styles from your **spectrum-css** clone, **`spectrum-two`** branch, component `index.css` (not `dist`). -2. **Use tokens** — Replace hard-coded values with `token(...)`. Follow [component CSS](../../../../02_style-guide/01_css/01_component-css.md) and [custom properties](../../../../02_style-guide/01_css/02_custom-properties.md). +1. **Follow the migration steps** — [Step 6](06_migrate-rendering-and-styles.md) and the [full migration steps](../../../../for-contributors/style-guide/css/spectrum-swc-migration.md). Use [03_components/](../../../03_components/) for spectrum-two alignment. Copy S2 styles from your **spectrum-css** clone, **`spectrum-two`** branch, component `index.css` (not `dist`). +2. **Use tokens** — Replace hard-coded values with `token(...)`. Follow [component CSS](../../../../for-contributors/style-guide/css/component-css.md) and [custom properties](../../../../for-contributors/style-guide/css/custom-properties.md). 3. **Run stylelint** — After updating CSS, run `nx run swc:lint`. Fix all errors. The 2nd-gen config enforces: **property order** (see `linters/stylelint-property-order.js`); **no descending specificity** (e.g. `:host([disabled])` before `:host([checked][disabled])`); **declaration empty line** (empty line between groups); **token usage** (`token("...")` for color, font-size, etc.). -For templates, `render()`, icons (inline SVG), and detailed examples, see [Step 6](06_migrate-rendering-and-styles.md) and the [full migration steps](../../../../02_style-guide/01_css/04_spectrum-swc-migration.md). +For templates, `render()`, icons (inline SVG), and detailed examples, see [Step 6](06_migrate-rendering-and-styles.md) and the [full migration steps](../../../../for-contributors/style-guide/css/spectrum-swc-migration.md). ### What to check - [ ] No inline styles for theme/size; use CSS and classes. - [ ] Tokens and custom properties align with Spectrum 2. -- [ ] Follows the [full migration steps](../../../../02_style-guide/01_css/04_spectrum-swc-migration.md). -- [ ] Adheres to the [component styling guidelines](../../../../02_style-guide/01_css/01_component-css.md). +- [ ] Follows the [full migration steps](../../../../for-contributors/style-guide/css/spectrum-swc-migration.md). +- [ ] Adheres to the [component styling guidelines](../../../../for-contributors/style-guide/css/component-css.md). - [ ] **2nd-gen CSS passes stylelint:** No `order/properties-order`, `no-descending-specificity`, `declaration-empty-line-before`, or token-usage errors in the component’s `.css` file (run `nx run swc:lint` or the repo’s lint command). ### Common problems and solutions -For troubleshooting and detailed patterns (e.g. 1st-gen Constructable Stylesheets vs plain `.css`, variant classes, size/density), see the [full migration steps](../../../../02_style-guide/01_css/04_spectrum-swc-migration.md) and [component styling guidelines](../../../../02_style-guide/01_css/01_component-css.md). +For troubleshooting and detailed patterns (e.g. 1st-gen Constructable Stylesheets vs plain `.css`, variant classes, size/density), see the [full migration steps](../../../../for-contributors/style-guide/css/spectrum-swc-migration.md) and [component styling guidelines](../../../../for-contributors/style-guide/css/component-css.md). | Problem | Solution | |--------|----------| @@ -366,19 +366,19 @@ For troubleshooting and detailed patterns (e.g. 1st-gen Constructable Stylesheet ### Quality gate -- [ ] Follows the [full migration steps](../../../../02_style-guide/01_css/04_spectrum-swc-migration.md). -- [ ] Adheres to the [component styling guidelines](../../../../02_style-guide/01_css/01_component-css.md). +- [ ] Follows the [full migration steps](../../../../for-contributors/style-guide/css/spectrum-swc-migration.md). +- [ ] Adheres to the [component styling guidelines](../../../../for-contributors/style-guide/css/component-css.md). - [ ] Stylelint passes for the component’s CSS (no 2nd-gen CSS lint errors). --- ## Phase 5: Accessibility -**Goal:** Implement WCAG-aligned behavior and document it. Follow the repo’s [Accessibility testing](https://github.com/adobe/spectrum-web-components/blob/main/CONTRIBUTOR-DOCS/01_contributor-guides/09_accessibility-testing.md) guide and the PR template’s accessibility checklist; for public-facing usage, refer to the [public docs site](https://opensource.adobe.com/spectrum-web-components/) accessibility guidance where applicable. +**Goal:** Implement WCAG-aligned behavior and document it. Follow the repo’s [Accessibility testing](https://github.com/adobe/spectrum-web-components/blob/main/CONTRIBUTOR-DOCS/for-contributors/accessibility-testing.md) guide and the PR template’s accessibility checklist; for public-facing usage, refer to the [public docs site](https://opensource.adobe.com/spectrum-web-components/) accessibility guidance where applicable. ### What to do -1. **Follow the [Accessibility testing](https://github.com/adobe/spectrum-web-components/blob/main/CONTRIBUTOR-DOCS/01_contributor-guides/09_accessibility-testing.md) guide** and the PR template checklist. +1. **Follow the [Accessibility testing](https://github.com/adobe/spectrum-web-components/blob/main/CONTRIBUTOR-DOCS/for-contributors/accessibility-testing.md) guide** and the PR template checklist. 2. **Use 2nd-gen Storybook accessibility guides:** `2nd-gen/packages/swc/.storybook/guides/accessibility-guides/` — codebase-specific a11y patterns and docs surfaced in Storybook (complement the contributor guide and APG). 3. **Identify the APG pattern** for your component type (e.g. button, combobox) — [WCAG ARIA Authoring Practices Guide (APG)](https://www.w3.org/WAI/ARIA/apg/patterns/). 4. **Implement:** Semantics (prefer native HTML), ARIA where needed, keyboard support, focus management (trap in overlays), screen reader exposure. Test with assistive tech; document in JSDoc. @@ -425,14 +425,14 @@ Prefer native events when they give the right semantics (e.g. `click`). Add cust 3. **Storybook play functions:** Add play functions for defaults, variants, keyboard. 4. **Coverage:** Main props, variants, user actions. -Follow the two-file layout (`test/.test.ts`, `test/.a11y.spec.ts`). See the [2nd gen testing conventions](../../../../01_contributor-guides/11_2ndgen_testing.md) and reference implementations in `link/test/`, `checkbox/test/`, `badge/test/`, etc. +Follow the two-file layout (`test/.test.ts`, `test/.a11y.spec.ts`). See the [2nd gen testing conventions](../../../../for-contributors/2ndgen-testing.md) and reference implementations in `link/test/`, `checkbox/test/`, `badge/test/`, etc. ### What to check - [ ] `test/.test.ts` and `test/.a11y.spec.ts` are present and follow the structure described above (test stories under *Component/Tests*, a11y spec with `gotoStory` and `toMatchAriaSnapshot`). - [ ] Unit tests pass; a11y tests pass. - [ ] Critical paths (render, props, slots, events) are covered. -- [ ] Tests follow the project [testing conventions](../../../../01_contributor-guides/11_2ndgen_testing.md) (Ticket 10). +- [ ] Tests follow the project [testing conventions](../../../../for-contributors/2ndgen-testing.md) (Ticket 10). ### Common problems and solutions @@ -584,8 +584,8 @@ Use Badge as the reference implementation: - **Workspace:** [spectrum-css](https://github.com/adobe/spectrum-css) cloned **next to** this repo—see [Workspace setup](#workspace-setup). - **TypeScript:** Team conventions; for 2nd-gen API patterns (static `readonly`, `window.__swc.warn`), see Phase 3 [API patterns](#api-patterns-statics-and-warnings) and 2nd-gen Badge (`core` + `swc`). -- **CSS:** [2nd-gen CSS style guide (CONTRIBUTOR-DOCS)](../../../../02_style-guide/01_css/README.md) — component CSS, custom properties, Spectrum→SWC migration, anti-patterns, property order -- **Testing:** [2nd gen testing conventions](../../../../01_contributor-guides/11_2ndgen_testing.md) +- **CSS:** [2nd-gen CSS style guide (CONTRIBUTOR-DOCS)](../../../../for-contributors/style-guide/css/README.md) — component CSS, custom properties, Spectrum→SWC migration, anti-patterns, property order +- **Testing:** [2nd gen testing conventions](../../../../for-contributors/2ndgen-testing.md) - **WCAG APG:** [https://www.w3.org/WAI/ARIA/apg/patterns/](https://www.w3.org/WAI/ARIA/apg/patterns/) - **Component analysis:** [03_components/](../../../03_components/) — Step 1 [Cursor prompt](01_analyze-rendering-and-styling/README.md); optional **component-migration-analysis** Cursor skill alongside that flow. - **2nd-gen Storybook guides:** [2nd-gen/packages/swc/.storybook/guides/](../../../../../2nd-gen/packages/swc/.storybook/guides/) diff --git a/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/02_factor-rendering-out-of-1st-gen-component.md b/CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/02_factor-rendering-out-of-1st-gen-component.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/02_factor-rendering-out-of-1st-gen-component.md rename to CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/02_factor-rendering-out-of-1st-gen-component.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/03_move-base-class-to-2nd-gen-core.md b/CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/03_move-base-class-to-2nd-gen-core.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/03_move-base-class-to-2nd-gen-core.md rename to CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/03_move-base-class-to-2nd-gen-core.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/04_formalize-spectrum-data-model.md b/CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/04_formalize-spectrum-data-model.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/04_formalize-spectrum-data-model.md rename to CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/04_formalize-spectrum-data-model.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/05_implement-2nd-gen-component.md b/CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/05_implement-2nd-gen-component.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/05_implement-2nd-gen-component.md rename to CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/05_implement-2nd-gen-component.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/06_migrate-rendering-and-styles.md b/CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/06_migrate-rendering-and-styles.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/06_migrate-rendering-and-styles.md rename to CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/06_migrate-rendering-and-styles.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/07_add-stories-for-2nd-gen-component.md b/CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/07_add-stories-for-2nd-gen-component.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/07_add-stories-for-2nd-gen-component.md rename to CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/07_add-stories-for-2nd-gen-component.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/03_migration-project-planning.md b/CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/03_migration-project-planning.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/03_migration-project-planning.md rename to CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/03_migration-project-planning.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/README.md b/CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/README.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/README.md rename to CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/README.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/03_accessibility-improvements/README.md b/CONTRIBUTOR-DOCS/project-planning/02_workstreams/03_accessibility-improvements/README.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/03_accessibility-improvements/README.md rename to CONTRIBUTOR-DOCS/project-planning/02_workstreams/03_accessibility-improvements/README.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/04_component-improvements/README.md b/CONTRIBUTOR-DOCS/project-planning/02_workstreams/04_component-improvements/README.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/04_component-improvements/README.md rename to CONTRIBUTOR-DOCS/project-planning/02_workstreams/04_component-improvements/README.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/05_1st-gen-spectrum-2-enhancements/README.md b/CONTRIBUTOR-DOCS/project-planning/02_workstreams/05_1st-gen-spectrum-2-enhancements/README.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/05_1st-gen-spectrum-2-enhancements/README.md rename to CONTRIBUTOR-DOCS/project-planning/02_workstreams/05_1st-gen-spectrum-2-enhancements/README.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/README.md b/CONTRIBUTOR-DOCS/project-planning/02_workstreams/README.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/README.md rename to CONTRIBUTOR-DOCS/project-planning/02_workstreams/README.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/README.md b/CONTRIBUTOR-DOCS/project-planning/03_components/README.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/03_components/README.md rename to CONTRIBUTOR-DOCS/project-planning/03_components/README.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/action-button/rendering-and-styling-migration-analysis.md b/CONTRIBUTOR-DOCS/project-planning/03_components/action-button/rendering-and-styling-migration-analysis.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/03_components/action-button/rendering-and-styling-migration-analysis.md rename to CONTRIBUTOR-DOCS/project-planning/03_components/action-button/rendering-and-styling-migration-analysis.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/action-group/rendering-and-styling-migration-analysis.md b/CONTRIBUTOR-DOCS/project-planning/03_components/action-group/rendering-and-styling-migration-analysis.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/03_components/action-group/rendering-and-styling-migration-analysis.md rename to CONTRIBUTOR-DOCS/project-planning/03_components/action-group/rendering-and-styling-migration-analysis.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/alert-banner/rendering-and-styling-migration-analysis.md b/CONTRIBUTOR-DOCS/project-planning/03_components/alert-banner/rendering-and-styling-migration-analysis.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/03_components/alert-banner/rendering-and-styling-migration-analysis.md rename to CONTRIBUTOR-DOCS/project-planning/03_components/alert-banner/rendering-and-styling-migration-analysis.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/asset/rendering-and-styling-migration-analysis.md b/CONTRIBUTOR-DOCS/project-planning/03_components/asset/rendering-and-styling-migration-analysis.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/03_components/asset/rendering-and-styling-migration-analysis.md rename to CONTRIBUTOR-DOCS/project-planning/03_components/asset/rendering-and-styling-migration-analysis.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/avatar/accessibility-migration-analysis.md b/CONTRIBUTOR-DOCS/project-planning/03_components/avatar/accessibility-migration-analysis.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/03_components/avatar/accessibility-migration-analysis.md rename to CONTRIBUTOR-DOCS/project-planning/03_components/avatar/accessibility-migration-analysis.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/avatar/migration-plan.md b/CONTRIBUTOR-DOCS/project-planning/03_components/avatar/migration-plan.md similarity index 98% rename from CONTRIBUTOR-DOCS/03_project-planning/03_components/avatar/migration-plan.md rename to CONTRIBUTOR-DOCS/project-planning/03_components/avatar/migration-plan.md index b6d8a840533..9f11ae408e2 100644 --- a/CONTRIBUTOR-DOCS/03_project-planning/03_components/avatar/migration-plan.md +++ b/CONTRIBUTOR-DOCS/project-planning/03_components/avatar/migration-plan.md @@ -191,6 +191,6 @@ All `--mod-avatar-*` customization properties removed. Consumers must migrate to ## 7. Reference - Reference implementation: `2nd-gen/packages/core/components/badge/Badge.base.ts` -- CSS migration guide: `CONTRIBUTOR-DOCS/02_style-guide/01_css/04_spectrum-swc-migration.md` -- 2nd-gen testing guide: `CONTRIBUTOR-DOCS/01_contributor-guides/11_2ndgen_testing.md` +- CSS migration guide: `CONTRIBUTOR-DOCS/for-contributors/style-guide/css/spectrum-swc-migration.md` +- 2nd-gen testing guide: `CONTRIBUTOR-DOCS/for-contributors/2ndgen-testing.md` - 2nd-gen core mixins: `2nd-gen/packages/core/mixins/` diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/avatar/rendering-and-styling-migration-analysis.md b/CONTRIBUTOR-DOCS/project-planning/03_components/avatar/rendering-and-styling-migration-analysis.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/03_components/avatar/rendering-and-styling-migration-analysis.md rename to CONTRIBUTOR-DOCS/project-planning/03_components/avatar/rendering-and-styling-migration-analysis.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/badge/accessibility-migration-analysis.md b/CONTRIBUTOR-DOCS/project-planning/03_components/badge/accessibility-migration-analysis.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/03_components/badge/accessibility-migration-analysis.md rename to CONTRIBUTOR-DOCS/project-planning/03_components/badge/accessibility-migration-analysis.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/badge/rendering-and-styling-migration-analysis.md b/CONTRIBUTOR-DOCS/project-planning/03_components/badge/rendering-and-styling-migration-analysis.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/03_components/badge/rendering-and-styling-migration-analysis.md rename to CONTRIBUTOR-DOCS/project-planning/03_components/badge/rendering-and-styling-migration-analysis.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/button-group/rendering-and-styling-migration-analysis.md b/CONTRIBUTOR-DOCS/project-planning/03_components/button-group/rendering-and-styling-migration-analysis.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/03_components/button-group/rendering-and-styling-migration-analysis.md rename to CONTRIBUTOR-DOCS/project-planning/03_components/button-group/rendering-and-styling-migration-analysis.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/button/rendering-and-styling-migration-analysis.md b/CONTRIBUTOR-DOCS/project-planning/03_components/button/rendering-and-styling-migration-analysis.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/03_components/button/rendering-and-styling-migration-analysis.md rename to CONTRIBUTOR-DOCS/project-planning/03_components/button/rendering-and-styling-migration-analysis.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/checkbox/rendering-and-styling-migration-analysis.md b/CONTRIBUTOR-DOCS/project-planning/03_components/checkbox/rendering-and-styling-migration-analysis.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/03_components/checkbox/rendering-and-styling-migration-analysis.md rename to CONTRIBUTOR-DOCS/project-planning/03_components/checkbox/rendering-and-styling-migration-analysis.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/color-field/rendering-and-styling-migration-analysis.md b/CONTRIBUTOR-DOCS/project-planning/03_components/color-field/rendering-and-styling-migration-analysis.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/03_components/color-field/rendering-and-styling-migration-analysis.md rename to CONTRIBUTOR-DOCS/project-planning/03_components/color-field/rendering-and-styling-migration-analysis.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/color-loupe/accessibility-migration-analysis.md b/CONTRIBUTOR-DOCS/project-planning/03_components/color-loupe/accessibility-migration-analysis.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/03_components/color-loupe/accessibility-migration-analysis.md rename to CONTRIBUTOR-DOCS/project-planning/03_components/color-loupe/accessibility-migration-analysis.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/divider/accessibility-migration-analysis.md b/CONTRIBUTOR-DOCS/project-planning/03_components/divider/accessibility-migration-analysis.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/03_components/divider/accessibility-migration-analysis.md rename to CONTRIBUTOR-DOCS/project-planning/03_components/divider/accessibility-migration-analysis.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/divider/rendering-and-styling-migration-analysis.md b/CONTRIBUTOR-DOCS/project-planning/03_components/divider/rendering-and-styling-migration-analysis.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/03_components/divider/rendering-and-styling-migration-analysis.md rename to CONTRIBUTOR-DOCS/project-planning/03_components/divider/rendering-and-styling-migration-analysis.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/dropzone/rendering-and-styling-migration-analysis.md b/CONTRIBUTOR-DOCS/project-planning/03_components/dropzone/rendering-and-styling-migration-analysis.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/03_components/dropzone/rendering-and-styling-migration-analysis.md rename to CONTRIBUTOR-DOCS/project-planning/03_components/dropzone/rendering-and-styling-migration-analysis.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/field-group/rendering-and-styling-migration-analysis.md b/CONTRIBUTOR-DOCS/project-planning/03_components/field-group/rendering-and-styling-migration-analysis.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/03_components/field-group/rendering-and-styling-migration-analysis.md rename to CONTRIBUTOR-DOCS/project-planning/03_components/field-group/rendering-and-styling-migration-analysis.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/field-label/rendering-and-styling-migration-analysis.md b/CONTRIBUTOR-DOCS/project-planning/03_components/field-label/rendering-and-styling-migration-analysis.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/03_components/field-label/rendering-and-styling-migration-analysis.md rename to CONTRIBUTOR-DOCS/project-planning/03_components/field-label/rendering-and-styling-migration-analysis.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/help-text/rendering-and-styling-migration-analysis.md b/CONTRIBUTOR-DOCS/project-planning/03_components/help-text/rendering-and-styling-migration-analysis.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/03_components/help-text/rendering-and-styling-migration-analysis.md rename to CONTRIBUTOR-DOCS/project-planning/03_components/help-text/rendering-and-styling-migration-analysis.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/illustrated-message/accessibility-migration-analysis.md b/CONTRIBUTOR-DOCS/project-planning/03_components/illustrated-message/accessibility-migration-analysis.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/03_components/illustrated-message/accessibility-migration-analysis.md rename to CONTRIBUTOR-DOCS/project-planning/03_components/illustrated-message/accessibility-migration-analysis.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/illustrated-message/rendering-and-styling-migration-analysis.md b/CONTRIBUTOR-DOCS/project-planning/03_components/illustrated-message/rendering-and-styling-migration-analysis.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/03_components/illustrated-message/rendering-and-styling-migration-analysis.md rename to CONTRIBUTOR-DOCS/project-planning/03_components/illustrated-message/rendering-and-styling-migration-analysis.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/infield-button/rendering-and-styling-migration-analysis.md b/CONTRIBUTOR-DOCS/project-planning/03_components/infield-button/rendering-and-styling-migration-analysis.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/03_components/infield-button/rendering-and-styling-migration-analysis.md rename to CONTRIBUTOR-DOCS/project-planning/03_components/infield-button/rendering-and-styling-migration-analysis.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/infield-progress-circle/rendering-and-styling-migration-analysis.md b/CONTRIBUTOR-DOCS/project-planning/03_components/infield-progress-circle/rendering-and-styling-migration-analysis.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/03_components/infield-progress-circle/rendering-and-styling-migration-analysis.md rename to CONTRIBUTOR-DOCS/project-planning/03_components/infield-progress-circle/rendering-and-styling-migration-analysis.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/link/rendering-and-styling-migration-analysis.md b/CONTRIBUTOR-DOCS/project-planning/03_components/link/rendering-and-styling-migration-analysis.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/03_components/link/rendering-and-styling-migration-analysis.md rename to CONTRIBUTOR-DOCS/project-planning/03_components/link/rendering-and-styling-migration-analysis.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/meter/rendering-and-styling-migration-analysis.md b/CONTRIBUTOR-DOCS/project-planning/03_components/meter/rendering-and-styling-migration-analysis.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/03_components/meter/rendering-and-styling-migration-analysis.md rename to CONTRIBUTOR-DOCS/project-planning/03_components/meter/rendering-and-styling-migration-analysis.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/number-field/rendering-and-styling-migration-analysis.md b/CONTRIBUTOR-DOCS/project-planning/03_components/number-field/rendering-and-styling-migration-analysis.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/03_components/number-field/rendering-and-styling-migration-analysis.md rename to CONTRIBUTOR-DOCS/project-planning/03_components/number-field/rendering-and-styling-migration-analysis.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/opacity-checkerboard/rendering-and-styling-migration-analysis.md b/CONTRIBUTOR-DOCS/project-planning/03_components/opacity-checkerboard/rendering-and-styling-migration-analysis.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/03_components/opacity-checkerboard/rendering-and-styling-migration-analysis.md rename to CONTRIBUTOR-DOCS/project-planning/03_components/opacity-checkerboard/rendering-and-styling-migration-analysis.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/picker-button/rendering-and-styling-migration-analysis.md b/CONTRIBUTOR-DOCS/project-planning/03_components/picker-button/rendering-and-styling-migration-analysis.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/03_components/picker-button/rendering-and-styling-migration-analysis.md rename to CONTRIBUTOR-DOCS/project-planning/03_components/picker-button/rendering-and-styling-migration-analysis.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/progress-bar/accessibility-migration-analysis.md b/CONTRIBUTOR-DOCS/project-planning/03_components/progress-bar/accessibility-migration-analysis.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/03_components/progress-bar/accessibility-migration-analysis.md rename to CONTRIBUTOR-DOCS/project-planning/03_components/progress-bar/accessibility-migration-analysis.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/progress-bar/rendering-and-styling-migration-analysis.md b/CONTRIBUTOR-DOCS/project-planning/03_components/progress-bar/rendering-and-styling-migration-analysis.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/03_components/progress-bar/rendering-and-styling-migration-analysis.md rename to CONTRIBUTOR-DOCS/project-planning/03_components/progress-bar/rendering-and-styling-migration-analysis.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/progress-circle/accessibility-migration-analysis.md b/CONTRIBUTOR-DOCS/project-planning/03_components/progress-circle/accessibility-migration-analysis.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/03_components/progress-circle/accessibility-migration-analysis.md rename to CONTRIBUTOR-DOCS/project-planning/03_components/progress-circle/accessibility-migration-analysis.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/progress-circle/rendering-and-styling-migration-analysis.md b/CONTRIBUTOR-DOCS/project-planning/03_components/progress-circle/rendering-and-styling-migration-analysis.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/03_components/progress-circle/rendering-and-styling-migration-analysis.md rename to CONTRIBUTOR-DOCS/project-planning/03_components/progress-circle/rendering-and-styling-migration-analysis.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/radio/rendering-and-styling-migration-analysis.md b/CONTRIBUTOR-DOCS/project-planning/03_components/radio/rendering-and-styling-migration-analysis.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/03_components/radio/rendering-and-styling-migration-analysis.md rename to CONTRIBUTOR-DOCS/project-planning/03_components/radio/rendering-and-styling-migration-analysis.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/search/rendering-and-styling-migration-analysis.md b/CONTRIBUTOR-DOCS/project-planning/03_components/search/rendering-and-styling-migration-analysis.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/03_components/search/rendering-and-styling-migration-analysis.md rename to CONTRIBUTOR-DOCS/project-planning/03_components/search/rendering-and-styling-migration-analysis.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/slider/rendering-and-styling-migration-analysis.md b/CONTRIBUTOR-DOCS/project-planning/03_components/slider/rendering-and-styling-migration-analysis.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/03_components/slider/rendering-and-styling-migration-analysis.md rename to CONTRIBUTOR-DOCS/project-planning/03_components/slider/rendering-and-styling-migration-analysis.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/status-light/accessibility-migration-analysis.md b/CONTRIBUTOR-DOCS/project-planning/03_components/status-light/accessibility-migration-analysis.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/03_components/status-light/accessibility-migration-analysis.md rename to CONTRIBUTOR-DOCS/project-planning/03_components/status-light/accessibility-migration-analysis.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/status-light/rendering-and-styling-migration-analysis.md b/CONTRIBUTOR-DOCS/project-planning/03_components/status-light/rendering-and-styling-migration-analysis.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/03_components/status-light/rendering-and-styling-migration-analysis.md rename to CONTRIBUTOR-DOCS/project-planning/03_components/status-light/rendering-and-styling-migration-analysis.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/swatch-group/rendering-and-styling-migration-analysis.md b/CONTRIBUTOR-DOCS/project-planning/03_components/swatch-group/rendering-and-styling-migration-analysis.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/03_components/swatch-group/rendering-and-styling-migration-analysis.md rename to CONTRIBUTOR-DOCS/project-planning/03_components/swatch-group/rendering-and-styling-migration-analysis.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/swatch/rendering-and-styling-migration-analysis.md b/CONTRIBUTOR-DOCS/project-planning/03_components/swatch/rendering-and-styling-migration-analysis.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/03_components/swatch/rendering-and-styling-migration-analysis.md rename to CONTRIBUTOR-DOCS/project-planning/03_components/swatch/rendering-and-styling-migration-analysis.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/switch/rendering-and-styling-migration-analysis.md b/CONTRIBUTOR-DOCS/project-planning/03_components/switch/rendering-and-styling-migration-analysis.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/03_components/switch/rendering-and-styling-migration-analysis.md rename to CONTRIBUTOR-DOCS/project-planning/03_components/switch/rendering-and-styling-migration-analysis.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/tag/rendering-and-styling-migration-analysis.md b/CONTRIBUTOR-DOCS/project-planning/03_components/tag/rendering-and-styling-migration-analysis.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/03_components/tag/rendering-and-styling-migration-analysis.md rename to CONTRIBUTOR-DOCS/project-planning/03_components/tag/rendering-and-styling-migration-analysis.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/tags/rendering-and-styling-migration-analysis.md b/CONTRIBUTOR-DOCS/project-planning/03_components/tags/rendering-and-styling-migration-analysis.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/03_components/tags/rendering-and-styling-migration-analysis.md rename to CONTRIBUTOR-DOCS/project-planning/03_components/tags/rendering-and-styling-migration-analysis.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/textfield/rendering-and-styling-migration-analysis.md b/CONTRIBUTOR-DOCS/project-planning/03_components/textfield/rendering-and-styling-migration-analysis.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/03_components/textfield/rendering-and-styling-migration-analysis.md rename to CONTRIBUTOR-DOCS/project-planning/03_components/textfield/rendering-and-styling-migration-analysis.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/thumbnail/rendering-and-styling-migration-analysis.md b/CONTRIBUTOR-DOCS/project-planning/03_components/thumbnail/rendering-and-styling-migration-analysis.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/03_components/thumbnail/rendering-and-styling-migration-analysis.md rename to CONTRIBUTOR-DOCS/project-planning/03_components/thumbnail/rendering-and-styling-migration-analysis.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/03_components/tooltip/rendering-and-styling-migration-analysis.md b/CONTRIBUTOR-DOCS/project-planning/03_components/tooltip/rendering-and-styling-migration-analysis.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/03_components/tooltip/rendering-and-styling-migration-analysis.md rename to CONTRIBUTOR-DOCS/project-planning/03_components/tooltip/rendering-and-styling-migration-analysis.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/04_milestones/README.md b/CONTRIBUTOR-DOCS/project-planning/04_milestones/README.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/04_milestones/README.md rename to CONTRIBUTOR-DOCS/project-planning/04_milestones/README.md diff --git a/CONTRIBUTOR-DOCS/03_project-planning/README.md b/CONTRIBUTOR-DOCS/project-planning/README.md similarity index 100% rename from CONTRIBUTOR-DOCS/03_project-planning/README.md rename to CONTRIBUTOR-DOCS/project-planning/README.md diff --git a/CONTRIBUTOR-DOCS/00_get-started/component-matrix.data.yml b/CONTRIBUTOR-DOCS/reference/component-status.data.yml similarity index 100% rename from CONTRIBUTOR-DOCS/00_get-started/component-matrix.data.yml rename to CONTRIBUTOR-DOCS/reference/component-status.data.yml diff --git a/CONTRIBUTOR-DOCS/00_get-started/component-matrix.md b/CONTRIBUTOR-DOCS/reference/component-status.md similarity index 94% rename from CONTRIBUTOR-DOCS/00_get-started/component-matrix.md rename to CONTRIBUTOR-DOCS/reference/component-status.md index 1a76da9ca20..7d182bf7632 100644 --- a/CONTRIBUTOR-DOCS/00_get-started/component-matrix.md +++ b/CONTRIBUTOR-DOCS/reference/component-status.md @@ -1,6 +1,6 @@ -[CONTRIBUTOR-DOCS](../README.md) / [Get started](README.md) / Component status +[CONTRIBUTOR-DOCS](../README.md) / Reference / Component status @@ -21,7 +21,7 @@ Regenerate with: yarn generate:component-matrix Rows + status + since come from CEM (`.storybook/custom-elements.json`). Figma + Stackblitz URLs come from each component's `stories/*.stories.ts`. -RSP 2 parity is a human judgment set in `component-matrix.data.yml` (defaults +RSP 2 parity is a human judgment set in `component-status.data.yml` (defaults to `partial`). It will move to an `@RSPparity` JSDoc tag parsed by CEM once the MVP-5 CEM plugin lands. --> @@ -43,4 +43,4 @@ slots, events, CSS parts) lives on each component's Storybook page. - **Status** — `Preview` (API may change), `Stable` (public), `Internal` (not for consumers), `Deprecated`, `Unsupported`. Derived from CEM (`@status` JSDoc tag). - **Since** — first 2nd-gen package version to ship the component. Derived from CEM (`@since` JSDoc tag). -- **RSP 2 parity** — whether the 2nd-gen component reaches feature parity with the equivalent React Spectrum 2 component. Values: `full`, `partial`, `none`, or a short note. Currently a human judgment set in `component-matrix.data.yml`; defaults to `partial` while per-component RSP tracking is being designed. Will move to an `@RSPparity` JSDoc tag parsed by CEM once the MVP-5 plugin lands. +- **RSP 2 parity** — whether the 2nd-gen component reaches feature parity with the equivalent React Spectrum 2 component. Values: `full`, `partial`, `none`, or a short note. Currently a human judgment set in `component-status.data.yml`; defaults to `partial` while per-component RSP tracking is being designed. Will move to an `@RSPparity` JSDoc tag parsed by CEM once the MVP-5 plugin lands. diff --git a/CONTRIBUTOR-DOCS/rfcs/proposed/2026-04-22-docs-overhaul-v2.md b/CONTRIBUTOR-DOCS/rfcs/proposed/2026-04-22-docs-overhaul-v2.md index 9e2085c012b..6cf9ab79344 100644 --- a/CONTRIBUTOR-DOCS/rfcs/proposed/2026-04-22-docs-overhaul-v2.md +++ b/CONTRIBUTOR-DOCS/rfcs/proposed/2026-04-22-docs-overhaul-v2.md @@ -453,7 +453,7 @@ Spectrum 2 design system, web components. Full docs at Note: 2nd-gen's canonical docs URL is . The legacy `opensource.adobe.com/spectrum-web-components/` URL continues to serve the 1st-gen site; links in v2 assets point to the new host. +> Note: 2nd-gen's canonical docs URL is [spectrum-web-components.adobe.com](https://spectrum-web-components.adobe.com/). The legacy `opensource.adobe.com/spectrum-web-components/` URL continues to serve the 1st-gen site; links in v2 assets point to the new host. - Update all `2nd-gen/packages/*/README.md` to the stub pattern - Script it where possible (generated stubs); hand-authored where necessary @@ -731,8 +731,8 @@ Remaining verification items (not "open questions" in the RFC sense; tracked as - No file contains content for more than one audience — `grep -l "for contributors:" for-consumers/` returns nothing; same check in reverse. - `generate-contributor-docs.mjs` produces a working Storybook from the new tree; no dead links. - The customization cheatsheet is gone from the codebase; its content is distributed across five+ audience-specific files with zero content loss. -- Package READMEs are all ≤30 lines and point to . -- `public/llms.txt` exists and is <5K tokens; `public/llms-full.txt` exists and is <1M tokens; both regenerate on every `yarn storybook` / `yarn storybook:build`. +- Package READMEs are all ≤30 lines and point to [spectrum-web-components.adobe.com](https://spectrum-web-components.adobe.com/). +- `public/llms.txt` exists and is under 5K tokens; `public/llms-full.txt` exists and is under 1M tokens; both regenerate on every `yarn storybook` / `yarn storybook:build`. - `rfcs/` contains at minimum: `template.md`, `README.md`, `proposed/2026-04-22-docs-overhaul-v2.md` (this RFC), `proposed/2026-04-22-focus-management-strategy.md` (migrated). After this RFC is accepted, it moves to `rfcs/accepted/`. - `CONTRIBUTOR-DOCS/README.md` has an auto-generated "Components" section between marker comments (no manual maintenance). - `.ai/skills/*` are each tagged `internal` or `public`; only `public` skills are referenced from `for-agents/skill-install.md`.