diff --git a/.ai/README.md b/.ai/README.md index 101a2e82192..9d9079e324c 100644 --- a/.ai/README.md +++ b/.ai/README.md @@ -97,7 +97,7 @@ _Generated by `yarn ai:sync` from frontmatter. Do not edit this block by hand._ - **[`rules/stories-format.md`](./rules/stories-format.md)** (`gen2/packages/swc/components/*/stories/**`, `gen2/packages/swc/patterns/*/*/stories/**`, `gen2/packages/core/controllers/*/stories/**`): Enforces consistent file structure, section separators, meta configuration, story tags, and layout parameters for gen2 Storybook stories files. Story prose lives in per-unit MDX; the stories file is definitions-only. - **[`rules/styles.md`](./rules/styles.md)** (`**/*.css`): Rules for consistent styling in component CSS - **[`rules/text-formatting.md`](./rules/text-formatting.md)** (`**/*.md`, `**/*.txt`, `**/*.mdx`): Text formatting and capitalization rules for documentation and tickets -- **[`memory/agnostic-lessons.md`](./memory/agnostic-lessons.md)** (`**`; not used by code-review): Accumulated lessons for agents working in this repository, covering path depths, module format, repository layout, Storybook tag conventions, and documentation style. +- **[`memory/agnostic-lessons.md`](./memory/agnostic-lessons.md)** (`**`; not used by code-review): Accumulated lessons for agents working in this repository, covering path depths, module format, repository layout, the gen2 styling API prefix, generated build output, Storybook tag conventions, and documentation style. - **[`memory/css-styling-lessons.md`](./memory/css-styling-lessons.md)** (`**/*.css`): Accumulated CSS lessons for component styling in this repository, covering selector syntax, custom property consumption, shorthands and fallback chains, variant states, and linter rewrites. ### Skills diff --git a/.ai/memory/agnostic-lessons.md b/.ai/memory/agnostic-lessons.md index f0f5a30dcc2..3388c521b9a 100644 --- a/.ai/memory/agnostic-lessons.md +++ b/.ai/memory/agnostic-lessons.md @@ -1,5 +1,5 @@ --- -description: Accumulated lessons for agents working in this repository, covering path depths, module format, repository layout, Storybook tag conventions, and documentation style. +description: Accumulated lessons for agents working in this repository, covering path depths, module format, repository layout, the gen2 styling API prefix, generated build output, Storybook tag conventions, and documentation style. paths: - '**' excludeAgent: code-review @@ -32,6 +32,19 @@ Accumulated lessons from working sessions on this project. Grouped by category. --- +## Styling API + +- **gen2 components expose `--swc-*` custom properties**: A gen2 component's public styling API, meaning the custom properties it documents with `@cssprop` and that consumers set to override it, uses the `--swc-*` prefix (for example `--swc-badge-height`). `--mod-*` and `--spectrum-*` are 1st-gen and Spectrum CSS conventions. Use them in gen2 docs, examples, and JSDoc only when a 1st-gen to gen2 migration guide compares the two. Stylelint's `custom-property-pattern` doesn't enforce the prefix. + +--- + +## Generated files + +- **Keep regenerated build output**: When `yarn build` rewrites a generated file, such as `gen2/packages/swc/stylesheets/global/global-*.css` (built from component CSS by `gen2/packages/tools/vite-global-elements-css`), commit the regenerated file even if the diff looks unrelated, such as reordered properties. The committed copy was stale. Revert it only if the diff contradicts its source. + +--- + ## Documentation - **Contributor migration-analysis markdown**: Prefer plain sentences with backticks for roles, elements, and code. Bold is fine sparingly for scanning cues; follow `accessibility-migration-analysis` skill (≈30% cap on bold markup for body prose, single spans for multi-word emphasis). +- **Don't hard-wrap prose**: `.prettierrc.yaml` sets `printWidth: 80` but leaves `proseWrap` at its default, `preserve`, so Prettier never reflows Markdown prose. Write each paragraph on one line in `.md` and `.mdx` files, and break lines only for structure: list items, headings, tables, and code. Reviewers have flagged hand-wrapped prose as diff noise. diff --git a/.cursor/rules/memory-agnostic-lessons.mdc b/.cursor/rules/memory-agnostic-lessons.mdc index 4031f44a866..23f5123ac42 100644 --- a/.cursor/rules/memory-agnostic-lessons.mdc +++ b/.cursor/rules/memory-agnostic-lessons.mdc @@ -1,5 +1,5 @@ --- -description: Accumulated lessons for agents working in this repository, covering path depths, module format, repository layout, Storybook tag conventions, and documentation style. +description: Accumulated lessons for agents working in this repository, covering path depths, module format, repository layout, the gen2 styling API prefix, generated build output, Storybook tag conventions, and documentation style. globs: ** alwaysApply: false --- @@ -33,6 +33,19 @@ Accumulated lessons from working sessions on this project. Grouped by category. --- +## Styling API + +- **gen2 components expose `--swc-*` custom properties**: A gen2 component's public styling API, meaning the custom properties it documents with `@cssprop` and that consumers set to override it, uses the `--swc-*` prefix (for example `--swc-badge-height`). `--mod-*` and `--spectrum-*` are 1st-gen and Spectrum CSS conventions. Use them in gen2 docs, examples, and JSDoc only when a 1st-gen to gen2 migration guide compares the two. Stylelint's `custom-property-pattern` doesn't enforce the prefix. + +--- + +## Generated files + +- **Keep regenerated build output**: When `yarn build` rewrites a generated file, such as `gen2/packages/swc/stylesheets/global/global-*.css` (built from component CSS by `gen2/packages/tools/vite-global-elements-css`), commit the regenerated file even if the diff looks unrelated, such as reordered properties. The committed copy was stale. Revert it only if the diff contradicts its source. + +--- + ## Documentation - **Contributor migration-analysis markdown**: Prefer plain sentences with backticks for roles, elements, and code. Bold is fine sparingly for scanning cues; follow `accessibility-migration-analysis` skill (≈30% cap on bold markup for body prose, single spans for multi-word emphasis). +- **Don't hard-wrap prose**: `.prettierrc.yaml` sets `printWidth: 80` but leaves `proseWrap` at its default, `preserve`, so Prettier never reflows Markdown prose. Write each paragraph on one line in `.md` and `.mdx` files, and break lines only for structure: list items, headings, tables, and code. Reviewers have flagged hand-wrapped prose as diff noise. diff --git a/.github/instructions/memory-agnostic-lessons.instructions.md b/.github/instructions/memory-agnostic-lessons.instructions.md index 667fbe00945..21a113e7b3e 100644 --- a/.github/instructions/memory-agnostic-lessons.instructions.md +++ b/.github/instructions/memory-agnostic-lessons.instructions.md @@ -1,5 +1,5 @@ --- -description: Accumulated lessons for agents working in this repository, covering path depths, module format, repository layout, Storybook tag conventions, and documentation style. +description: Accumulated lessons for agents working in this repository, covering path depths, module format, repository layout, the gen2 styling API prefix, generated build output, Storybook tag conventions, and documentation style. applyTo: '**' excludeAgent: code-review --- @@ -33,6 +33,19 @@ Accumulated lessons from working sessions on this project. Grouped by category. --- +## Styling API + +- **gen2 components expose `--swc-*` custom properties**: A gen2 component's public styling API, meaning the custom properties it documents with `@cssprop` and that consumers set to override it, uses the `--swc-*` prefix (for example `--swc-badge-height`). `--mod-*` and `--spectrum-*` are 1st-gen and Spectrum CSS conventions. Use them in gen2 docs, examples, and JSDoc only when a 1st-gen to gen2 migration guide compares the two. Stylelint's `custom-property-pattern` doesn't enforce the prefix. + +--- + +## Generated files + +- **Keep regenerated build output**: When `yarn build` rewrites a generated file, such as `gen2/packages/swc/stylesheets/global/global-*.css` (built from component CSS by `gen2/packages/tools/vite-global-elements-css`), commit the regenerated file even if the diff looks unrelated, such as reordered properties. The committed copy was stale. Revert it only if the diff contradicts its source. + +--- + ## Documentation - **Contributor migration-analysis markdown**: Prefer plain sentences with backticks for roles, elements, and code. Bold is fine sparingly for scanning cues; follow `accessibility-migration-analysis` skill (≈30% cap on bold markup for body prose, single spans for multi-word emphasis). +- **Don't hard-wrap prose**: `.prettierrc.yaml` sets `printWidth: 80` but leaves `proseWrap` at its default, `preserve`, so Prettier never reflows Markdown prose. Write each paragraph on one line in `.md` and `.mdx` files, and break lines only for structure: list items, headings, tables, and code. Reviewers have flagged hand-wrapped prose as diff noise.