chore: clean up patterns

.cursor/rules/stories-format.mdc

@@ -1,10 +1,12 @@
 ---
-description: 2nd-gen/packages/swc/components/*/stories/**
-alwaysApply: false
+globs: 2nd-gen/packages/swc/components/*/stories/**
+alwaysApply: true
 ---
 # Storybook stories format standards
 
-Enforce consistent formatting and structure for Storybook stories files in 2nd-gen components.
+Enforce consistent formatting and technical structure for Storybook stories files in 2nd-gen components.
+
+**See also**: `.cursor/rules/stories-documentation.mdc` for comprehensive guidance on WHAT to document (content, patterns, examples).
 
 ## Scope
 
@@ -19,13 +21,13 @@ Required structure with visual separators between sections:
 1. **Copyright header** (lines 1-11)
 2. **Imports**
 3. **METADATA** - Meta object with component configuration
-4. **AUTODOCS STORY** - Playground story
-5. **ANATOMY STORIES** - Component structure (if applicable)
-6. **OPTIONS STORIES** - Variants, sizes, styles
-7. **STATES STORIES** - Component states (if applicable)
-8. **BEHAVIORS STORIES** - Built-in functionality (if applicable)
-9. **ACCESSIBILITY STORIES** - A11y demonstration
-10. **HELPER FUNCTIONS** - Utilities like size label mappers (if needed)
+4. **HELPERS** - Shared label mappings and utilities (if needed)
+5. **AUTODOCS STORY** - Playground story
+6. **ANATOMY STORIES** - Component structure (if applicable)
+7. **OPTIONS STORIES** - Variants, sizes, styles
+8. **STATES STORIES** - Component states (if applicable)
+9. **BEHAVIORS STORIES** - Built-in functionality (if applicable)
+10. **ACCESSIBILITY STORIES** - A11y demonstration
 
 #### Visual separators
 
@@ -34,6 +36,10 @@ Required structure with visual separators between sections:
 //    METADATA
 // ────────────────
 
+// ────────────────────
+//    HELPERS
+// ────────────────────
+
 // ────────────────────
 //    AUTODOCS STORY
 // ────────────────────
@@ -57,23 +63,68 @@ Required structure with visual separators between sections:
 // ────────────────────────────────
 //    ACCESSIBILITY STORIES
 // ────────────────────────────────
+```
+
+## Key Principles
+
+### Always Pass Args Through
+
+When using custom `render` functions, **always** spread `...args` into template calls:
+
+```typescript
+// ✅ Good - args are passed through
+export const MyStory: Story = {
+    render: (args) => html`
+        ${template({ ...args, size: 's' })}
+    `,
+};
 
-// ────────────────────────
-//    HELPER FUNCTIONS
-// ────────────────────────
+// ❌ Bad - args are lost
+export const MyStory: Story = {
+    render: (args) => html`
+        ${template({ size: 's' })}
+    `,
+};
+```
+
+This ensures:
+
+- Storybook controls work correctly
+- Args from the Playground/global level are respected
+- Component defaults can be overridden
+
+### When to Use render vs args
+
+- **Use `args` directly**: When the default render is sufficient (single component, no wrapper)
+- **Use `render: (args) =>`**: When you need multiple instances, custom HTML structure, or conditional rendering
+
+```typescript
+// ✅ Good - simple case uses args
+export const Overview: Story = {
+    args: { size: 'm', label: 'Example' },
+    tags: ['overview'],
+};
+
+// ✅ Good - complex case uses render with args
+export const Sizes: Story = {
+    render: (args) => html`
+        ${template({ ...args, size: 's' })}
+        ${template({ ...args, size: 'm' })}
+        ${template({ ...args, size: 'l' })}
+    `,
+    tags: ['options'],
+};
 ```
 
 ### Usage file (`.usage.mdx`)
 
-Keep minimal—use `<SpectrumStories />` to pull in stories by tag. Only include sections with corresponding stories, except Installation which is written directly in MDX.
+Keep minimal—use `<SpectrumStories />` to pull in stories by tag. Only include sections with corresponding stories.
+
+**Note**: Installation instructions are programmatically generated by `DocumentTemplate.mdx` and should not be manually added.
 
 ```mdx
 import { SpectrumStories } from '../../../.storybook/blocks';
 
-## Installation
-
-Package name, npm install command, and import statements go here directly (not as a story).
-
 ## Anatomy
 
 <SpectrumStories tag="anatomy" hideTitle />
@@ -96,9 +147,11 @@ Package name, npm install command, and import statements go here directly (not a
 ```
 
 **Section rules**:
+
 - Use `hideTitle` for Anatomy and Accessibility only
 - Follow this section order, skipping inapplicable sections
 - Use sentence case for headings
+- Do not include an Installation section (it's auto-generated)
 
 ## Meta configuration
 
@@ -107,6 +160,11 @@ Package name, npm install command, and import statements go here directly (not a
 ```typescript
 /**
  * Component description explaining its purpose and key features.
+ * 
+ * This description is displayed in the Overview story. It should provide context about
+ * what the component does and when to use it. If referencing other components, link to
+ * their Storybook paths using relative URLs (e.g., `<swc-badge>` becomes 
+ * `[Badge](../?path=/docs/badge--overview)`).
  */
 const meta: Meta = {
     title: 'Component name',
@@ -116,14 +174,23 @@ const meta: Meta = {
     render: (args) => template(args),
     parameters: {
         actions: { handles: events },      // If events exist
-        docs: { subtitle: `Component description` }, // Required
+        docs: { 
+            subtitle: `Component description` // Required - displayed in Overview, cannot include links
+        },
         design: { type: 'figma', url: 'https://www.figma.com/...'},     // Recommended
         stackblitz: { url: 'https://stackblitz.com/...'},                // Recommended
     },
     tags: ['migrated'],
 };
 ```
 
+**Important notes:**
+
+- **JSDoc description above meta**: Displayed in the Overview story. Can include markdown links to other components.
+- **`parameters.docs.subtitle`**: Displayed as the subtitle in the Overview story. Cannot include links (plain text only).
+- **Avoid repetition**: The subtitle and JSDoc description should complement each other, not duplicate content. The subtitle is a brief summary; the JSDoc provides fuller context.
+- **Component links**: When referencing other components in the JSDoc description, use relative Storybook paths: `[ComponentName](../?path=/docs/component-name--overview)`
+
 ## Layout and decorators
 
 Use `flexLayout: true` for stories displaying multiple items (sizes, variants, states). This applies flex layout with consistent spacing.
@@ -208,6 +275,7 @@ export const StaticColors: Story = {
 | Tag | Usage |
 |-----|-------|
 | `'autodocs'`, `'dev'` | Playground story only |
+| `'overview'` | Overview story |
 | `'anatomy'` | Anatomy stories |
 | `'options'` | Variant, size, and style stories |
 | `'states'` | State demonstration stories |
@@ -233,6 +301,8 @@ export const Playground: Story = {
 };
 ```
 
+**Note**: Use `args` directly (not `render`) when the default render is sufficient. Only use `render: (args) => html` when you need custom rendering.
+
 Include comprehensive JSDoc comment above the meta object explaining what the component does.
 
 Every story export must have a JSDoc comment explaining:
@@ -241,7 +311,7 @@ Every story export must have a JSDoc comment explaining:
 - Any important context or usage notes
 - Best practices if relevant
 
-**Exception**: Do NOT add JSDoc comments above the Playground story.
+**Exceptions**: Do NOT add JSDoc comments above the Playground or Overview stories.
 
 Use markdown formatting within JSDoc:
 
@@ -259,10 +329,27 @@ export const Playground: Story = {
 };
 ```
 
+### Overview
+
+Quick introduction showing the component in its most common use case. No JSDoc comment needed.
+
+```typescript
+export const Overview: Story = {
+    args: {
+        // Most common/representative configuration
+    },
+    tags: ['overview'],
+};
+```
+
+**Note**: Use `args` directly when possible. Only use `render: (args) =>` if you need custom HTML structure around the component.
+
 ### Anatomy
 
 Document all slots and content-rendering properties (e.g., `label`, `icon`, `src`). Combine variations into one story.
 
+**Important**: When using `render: (args) =>`, **always** spread `...args` into template calls to ensure Storybook controls work correctly.
+
 ```typescript
 /**
  * A component-name consists of:
@@ -455,6 +542,7 @@ export const Accessibility: Story = {
 Every story export requires a JSDoc comment explaining what it demonstrates, **except Playground**.
 
 Use markdown formatting:
+
 - `**Bold**` for emphasis
 - Bullet lists for multiple points
 - Backticks for code
@@ -561,7 +649,7 @@ See `asset.stories.ts` for complete examples.
 
 ### ❌ Don't
 
-- Add JSDoc to Playground story
+- Add JSDoc to Playground or Overview story
 - Use 'usage' tag (deprecated)
 - Omit `subtitle` in meta parameters
 - Use placeholder text
@@ -572,14 +660,17 @@ See `asset.stories.ts` for complete examples.
 - Use `<SpectrumStories />` in usage.mdx
 - Use `flexLayout: true` for multi-item stories
 - Tag stories correctly: `anatomy`, `options`, `states`, `behaviors`, `a11y`
-- Include comprehensive JSDoc (except Playground)
+- Include comprehensive JSDoc (except Playground and Overview)
 - Use meaningful, realistic content
 
 ## Checklist
 
 - [ ] Copyright header (2025)
 - [ ] Visual separators between sections
 - [ ] Meta: title, component, args, argTypes, render, `parameters.docs.subtitle`, `tags: ['migrated']`
+- [ ] Meta JSDoc description above meta object (with component links if applicable)
+- [ ] Subtitle is concise and non-repetitive (plain text only, no links)
+- [ ] Overview: `['overview']` tag, common use case args, no JSDoc on story itself
 - [ ] Playground: `['autodocs', 'dev']` tags, no JSDoc, common use case args
 - [ ] Anatomy: all slots + content properties, `['anatomy']` tag, `flexLayout: true`
 - [ ] Options: all uncovered attributes, `['options']` tag, `flexLayout: true`

2nd-gen/packages/core/components/badge/Badge.types.ts

@@ -10,30 +10,33 @@
  * governing permissions and limitations under the License.
  */
 
+import type { ElementSize } from '@spectrum-web-components/core/shared/base/index.js';
+
 /*
  * @todo The S1 types can be removed once we are no longer maintaining 1st-gen.
  */
 
-import type { ElementSize } from '@spectrum-web-components/core/shared/base/index.js';
-
-export const VALID_SIZES: ElementSize[] = ['s', 'm', 'l'] as const;
-
 export const FIXED_VALUES = [
-    'inline-start',
-    'inline-end',
     'block-start',
     'block-end',
+    'inline-start',
+    'inline-end',
 ] as const;
 
-export type FixedValues = (typeof FIXED_VALUES)[number];
+export const BADGE_VALID_SIZES = [
+    's',
+    'm',
+    'l',
+    'xl',
+] as const satisfies readonly ElementSize[];
 
 export const BADGE_VARIANTS_SEMANTIC = [
     'accent',
-    'neutral',
     'informative',
+    'neutral',
     'positive',
-    'negative',
     'notice',
+    'negative',
 ] as const;
 
 export const BADGE_VARIANTS_COLOR_S1 = [
@@ -72,6 +75,11 @@ export const BADGE_VARIANTS_S2 = [
     ...BADGE_VARIANTS_COLOR_S2,
 ] as const;
 
+export type FixedValues = (typeof FIXED_VALUES)[number];
+export type BadgeSize = (typeof BADGE_VALID_SIZES)[number];
+export type BadgeSemanticVariant = (typeof BADGE_VARIANTS_SEMANTIC)[number];
+export type BadgeColorVariantS1 = (typeof BADGE_VARIANTS_COLOR_S1)[number];
+export type BadgeColorVariantS2 = (typeof BADGE_VARIANTS_COLOR_S2)[number];
 export type BadgeVariantS1 = (typeof BADGE_VARIANTS_S1)[number];
 export type BadgeVariantS2 = (typeof BADGE_VARIANTS_S2)[number];
 export type BadgeVariant = BadgeVariantS1 | BadgeVariantS2;

2nd-gen/packages/core/components/divider/Divider.base.ts

@@ -29,6 +29,7 @@ import {
  */
 export abstract class DividerBase extends SizedMixin(SpectrumElement, {
     validSizes: DIVIDER_VALID_SIZES,
+    /**@todo the design spec says the default size is small but we declare no default size */
     noDefaultSize: true,
 }) {
     /**

2nd-gen/packages/core/components/divider/Divider.types.ts

@@ -12,7 +12,11 @@
 
 import type { ElementSize } from '@spectrum-web-components/core/shared/base/index.js';
 
-export const DIVIDER_VALID_SIZES: ElementSize[] = ['s', 'm', 'l'] as const;
+export const DIVIDER_VALID_SIZES = [
+    's',
+    'm',
+    'l',
+] as const satisfies ElementSize[];
 export const DIVIDER_STATIC_COLORS = ['white', 'black'] as const;
 
 export type DividerStaticColor = (typeof DIVIDER_STATIC_COLORS)[number];

2nd-gen/packages/core/components/progress-circle/ProgressCircle.base.ts

@@ -20,7 +20,6 @@ import { getLabelFromSlot } from '@spectrum-web-components/core/shared/get-label
 
 import {
     PROGRESS_CIRCLE_VALID_SIZES,
-    ProgressCircleSize,
     ProgressCircleStaticColor,
 } from './ProgressCircle.types.js';
 
@@ -37,11 +36,9 @@ import {
  * @slot - Accessible label for the progress circle.
  *
  *   Used to provide context about what is loading or progressing.
- *
- * @fires progress-change - Dispatched when the progress value changes
  */
 export abstract class ProgressCircleBase extends SizedMixin(SpectrumElement, {
-    validSizes: PROGRESS_CIRCLE_VALID_SIZES as ProgressCircleSize[],
+    validSizes: PROGRESS_CIRCLE_VALID_SIZES,
 }) {
     // ─────────────────────────
     //     API TO OVERRIDE
@@ -90,7 +87,6 @@ export abstract class ProgressCircleBase extends SizedMixin(SpectrumElement, {
      * Accessible label for the progress circle.
      *
      * Used to provide context about what is loading or progressing.
-     * @required for accessibility
      */
     @property({ type: String })
     public label = '';

2nd-gen/packages/core/components/progress-circle/ProgressCircle.types.ts

@@ -16,7 +16,7 @@ export const PROGRESS_CIRCLE_VALID_SIZES: ElementSize[] = [
     's',
     'm',
     'l',
-] as const;
+] as const satisfies ElementSize[];
 export const PROGRESS_CIRCLE_STATIC_COLORS_S1 = ['white'] as const;
 export const PROGRESS_CIRCLE_STATIC_COLORS_S2 = [
     ...PROGRESS_CIRCLE_STATIC_COLORS_S1,
@@ -30,4 +30,3 @@ export type ProgressCircleStaticColorS2 =
 export type ProgressCircleStaticColor =
     | ProgressCircleStaticColorS1
     | ProgressCircleStaticColorS2;
-export type ProgressCircleSize = (typeof PROGRESS_CIRCLE_VALID_SIZES)[number];