From 130bca3a9e6542068498b85a276c4ada3e1e8fd5 Mon Sep 17 00:00:00 2001 From: Garth Braithwaite Date: Fri, 27 Mar 2026 12:37:03 -0600 Subject: [PATCH 1/2] chore: migrate cursor config to claude code Replace Cursor-specific configuration with Claude Code equivalents: - Delete .cursorrules (root and component-options-editor) - Delete .cursor/rules and .cursor/mcp.json - Move .cursor/plans/ and .cursor/skills/ to .claude/ - Create CLAUDE.md at root and tools/component-options-editor/ - Add .claude/settings.local.json to .gitignore Co-Authored-By: Claude Opus 4.6 (1M context) --- .../plans/size-property-analysis.md | 0 .../plans/token-options-mapping-analysis.md | 0 .../skills/enhance-sync-pr/SKILL.md | 20 +- .cursor/mcp.json | 3 - .cursor/rules | 265 ---------------- .cursorrules | 271 ---------------- .gitignore | 3 + CLAUDE.md | 297 ++++++++++++++++++ tools/component-options-editor/.cursorrules | 259 --------------- tools/component-options-editor/CLAUDE.md | 283 +++++++++++++++++ 10 files changed, 593 insertions(+), 808 deletions(-) rename {.cursor => .claude}/plans/size-property-analysis.md (100%) rename {.cursor => .claude}/plans/token-options-mapping-analysis.md (100%) rename {.cursor => .claude}/skills/enhance-sync-pr/SKILL.md (90%) delete mode 100644 .cursor/mcp.json delete mode 100644 .cursor/rules delete mode 100644 .cursorrules create mode 100644 CLAUDE.md delete mode 100644 tools/component-options-editor/.cursorrules create mode 100644 tools/component-options-editor/CLAUDE.md diff --git a/.cursor/plans/size-property-analysis.md b/.claude/plans/size-property-analysis.md similarity index 100% rename from .cursor/plans/size-property-analysis.md rename to .claude/plans/size-property-analysis.md diff --git a/.cursor/plans/token-options-mapping-analysis.md b/.claude/plans/token-options-mapping-analysis.md similarity index 100% rename from .cursor/plans/token-options-mapping-analysis.md rename to .claude/plans/token-options-mapping-analysis.md diff --git a/.cursor/skills/enhance-sync-pr/SKILL.md b/.claude/skills/enhance-sync-pr/SKILL.md similarity index 90% rename from .cursor/skills/enhance-sync-pr/SKILL.md rename to .claude/skills/enhance-sync-pr/SKILL.md index 806f9ab1..30cb362c 100644 --- a/.cursor/skills/enhance-sync-pr/SKILL.md +++ b/.claude/skills/enhance-sync-pr/SKILL.md @@ -58,14 +58,14 @@ Or full graph: `moon ci` (same as GitHub Actions). ### Failure map (what to suggest) -| Symptom | Likely cause | Suggestion | | | -| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | --------------- | -| `checkComponentProps` lists token names | Missing or wrong `component` on entries in `color-component.json`, `layout-component.json`, or `icons.json` | Set `component` to match token name prefix (see [`packages/tokens/test/checkComponentProps.js`](../../../packages/tokens/test/checkComponentProps.js)). | | | -| Schema / `color-set` errors | `sets` missing `light`, `dark`, or **`wireframe`** | Align with [`schemas/token-types/color-set.json`](../../../packages/tokens/schemas/token-types/color-set.json). | | | -| `verifyDesignDataSnapshot` / snapshot mismatch | Validation report changed vs golden file | Paths in the snapshot are relative to `packages/tokens/`. After `moon run sdk:build`, run **`migrate snapshot` from `packages/tokens/`** so paths match `moon run tokens:verifyDesignDataSnapshot`: `cd packages/tokens && ../../sdk/target/debug/design-data migrate snapshot ./src --output ./snapshots/validation-snapshot.json --schema-path ./schemas --exceptions-path ./naming-exceptions.json`. | | | -| Token file / `$schema` / `uuid` | Invalid token shape | Fix per [`token-file.json`](../../../packages/tokens/schemas/token-file.json) and failing AVA tests. | | | -| Alias / renamed / manifest | Broken refs or manifest drift | Fix aliases; run `moon run tokens:buildManifest`. | | | -| Changeset lint on PR | Bad frontmatter | Valid `---` / \`"[**@adobe/spectrum-tokens**](https://github.com/adobe/spectrum-tokens)": patch | minor | major\` / body. | +| Symptom | Likely cause | Suggestion | | | +| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | - | +| `checkComponentProps` lists token names | Missing or wrong `component` on entries in `color-component.json`, `layout-component.json`, or `icons.json` | Set `component` to match token name prefix (see [`packages/tokens/test/checkComponentProps.js`](../../../packages/tokens/test/checkComponentProps.js)). | | | +| Schema / `color-set` errors | `sets` missing `light`, `dark`, or **`wireframe`** | Align with [`schemas/token-types/color-set.json`](../../../packages/tokens/schemas/token-types/color-set.json). | | | +| `verifyDesignDataSnapshot` / snapshot mismatch | Validation report changed vs golden file | Paths in the snapshot are relative to `packages/tokens/`. After `moon run sdk:build`, run **`migrate snapshot` from `packages/tokens/`** so paths match `moon run tokens:verifyDesignDataSnapshot`: `cd packages/tokens && ../../sdk/target/debug/design-data migrate snapshot ./src --output ./snapshots/validation-snapshot.json --schema-path ./schemas --exceptions-path ./naming-exceptions.json`. | | | +| Token file / `$schema` / `uuid` | Invalid token shape | Fix per [`token-file.json`](../../../packages/tokens/schemas/token-file.json) and failing AVA tests. | | | +| Alias / renamed / manifest | Broken refs or manifest drift | Fix aliases; run `moon run tokens:buildManifest`. | | | +| Changeset lint on PR | Bad frontmatter | Valid `---` / `"@adobe/spectrum-tokens": patch \| minor \| major` / body. | | | Re-run targeted tasks after each fix until green. @@ -108,7 +108,7 @@ GITHUB_TOKEN=... node src/cli.js generate \ Bump type is inferred from diff (e.g. deletions → major, additions → minor). -Commit using the **source implementer’s** git identity so changelog “Thanks @…” matches design work: +Commit using the **source implementer’s** git identity so changelog "Thanks @…" matches design work: ```bash git config user.email '' @@ -132,4 +132,4 @@ Push the branch; confirm CI and changeset-bot on the PR. ## Reference: prior manual PRs -Well-formed examples: merged sync PRs with `token-changeset-generator`-style changesets and enriched bodies (e.g. [#615](https://github.com/adobe/spectrum-design-data/issues/615), [#593](https://github.com/adobe/spectrum-design-data/issues/593)). Early PRs used hand-written “Design motivation” + “Token diff” in the changeset body — the generator now standardizes that shape. +Well-formed examples: merged sync PRs with `token-changeset-generator`-style changesets and enriched bodies (e.g. [#615](https://github.com/adobe/spectrum-design-data/issues/615), [#593](https://github.com/adobe/spectrum-design-data/issues/593)). Early PRs used hand-written "Design motivation" + "Token diff" in the changeset body — the generator now standardizes that shape. diff --git a/.cursor/mcp.json b/.cursor/mcp.json deleted file mode 100644 index da39e4ff..00000000 --- a/.cursor/mcp.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "mcpServers": {} -} diff --git a/.cursor/rules b/.cursor/rules deleted file mode 100644 index 0d86e18c..00000000 --- a/.cursor/rules +++ /dev/null @@ -1,265 +0,0 @@ -# Spectrum Tokens - Cursor Rules - -## Project Overview -This is the Spectrum Tokens project, a monorepo containing design tokens, component schemas, and related tooling for Adobe's Spectrum Design System. - -## Required Tools & Standards -- **Testing**: AVA (required for all JavaScript/TypeScript testing) -- **Package Management**: pnpm@10.17.1 (never use npm or yarn) -- **Monorepo Management**: moon (for task management and CI/CD) -- **Release Management**: changesets (for version bumps and releases) -- **Commit Messages**: commitlint with conventional commits (required for all git commits) -- **Node.js Version**: ~20.12 - -## Architecture -- **Monorepo Structure**: Uses pnpm workspaces with packages/, docs/, and tools/ -- **Task Management**: All tasks defined in moon.yml files -- **Testing**: AVA with specific configuration requirements -- **ESM**: Project uses ES modules (type: "module") - -## Coding Standards - -### JavaScript/TypeScript -- Use ES modules (import/export syntax) -- Prefer const over let, never use var -- Use async/await over Promise chains -- Use template literals for string interpolation -- Follow ESLint configuration where present - -### Testing Guidelines -- All tests must use AVA framework -- Test files must follow pattern: `test/**/*.test.js` -- Each package must have `ava.config.js` configuration -- Use descriptive test names -- Set up proper test environment variables - -### Commit Message Guidelines -- All commits must follow conventional commit format -- Use format: `type(scope): description` -- Available types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore` -- Scope is optional but recommended for clarity -- Description should be present tense and lowercase -- Breaking changes must include `!` after type/scope or `BREAKING CHANGE:` in footer -- Examples: `feat(tokens): add new color palette`, `fix(diff): handle edge case` - -### Package Management -- Always use pnpm commands (never npm or yarn) -- Use exact versions for critical dependencies -- Keep pnpm-lock.yaml in version control -- Add new packages to pnpm-workspace.yaml when needed - -### File Structure -- Follow existing patterns in packages/, docs/, tools/ -- Include moon.yml for task definitions -- Include proper package.json with correct fields -- Include commitlint.config.cjs for commit message validation -- Use conventional file naming - -## Development Workflow - -### Adding New Packages -1. Create package directory under packages/, docs/, or tools/ -2. Add package.json with proper configuration -3. Add moon.yml with task definitions -4. Add ava.config.js for testing -5. Update pnpm-workspace.yaml if needed - -### Testing -- Use `moon run test` to run tests -- Tests should be thorough and descriptive -- Mock external dependencies appropriately -- Use AVA's built-in assertions - -### Version Management -- Use changesets for all version bumps -- Create changesets with `pnpm changeset` -- Never manually edit version numbers -- Follow semantic versioning - -### Commit Message Management -- Use conventional commit format for all commits -- Commit messages are validated by commitlint -- Use appropriate commit types and scopes -- Include breaking change indicators when needed -- Follow the format: `type(scope): description` - -### Task Execution -- Use moon for all defined tasks -- Define tasks in moon.yml files -- Use pnpm commands within moon tasks -- Set appropriate platform (node) for Node.js tasks - -## Code Suggestions - -### Preferred Patterns -```javascript -// Preferred: ES modules -import { readFileSync } from 'fs'; -export default function myFunction() {} - -// Preferred: Async/await -async function fetchData() { - try { - const response = await fetch(url); - return await response.json(); - } catch (error) { - console.error('Error fetching data:', error); - } -} - -// Preferred: Template literals -const message = `Hello, ${name}!`; - -// Preferred: Destructuring -const { name, version } = packageJson; -``` - -### AVA Test Patterns -```javascript -// Preferred test structure -import test from 'ava'; -import { myFunction } from '../src/index.js'; - -test('myFunction should return expected result', t => { - const result = myFunction(input); - t.is(result, expected); -}); - -test('myFunction should handle errors gracefully', async t => { - const error = await t.throwsAsync(async () => { - await myFunction(invalidInput); - }); - t.is(error.message, 'Expected error message'); -}); -``` - -### Moon Task Definitions -```yaml -# Preferred task structure -tasks: - test: - command: [pnpm, ava, test] - platform: node - build: - command: [pnpm, build] - platform: node - deps: [test] -``` - -### Commitlint Configuration -```javascript -// commitlint.config.cjs -module.exports = { - extends: ["@commitlint/config-conventional"], - ignores: [ - (message) => message.includes("[create-pull-request] automated change"), - ], -}; -``` - -## File-Specific Guidelines - -### package.json -- Include "type": "module" for ESM -- Specify Node.js version in engines -- Use pnpm in packageManager field -- Include proper repository, author, license fields - -### ava.config.js -- Use export default syntax -- Include standard configuration options -- Set NODE_ENV to "test" -- Use verbose output for debugging - -### moon.yml -- Define clear task names -- Use pnpm commands -- Set platform: node for Node.js tasks -- Include proper dependencies between tasks - -## Anti-Patterns to Avoid - -### Prohibited Commands -- `npm install` or `yarn install` (use `pnpm install`) -- `npm run` or `yarn run` (use `pnpm run` or `moon run`) -- Manual version bumps (use changesets) -- Non-conventional commit messages (use proper format) - -### Prohibited Patterns -```javascript -// Avoid: CommonJS in new code -const fs = require('fs'); -module.exports = function() {}; - -// Avoid: var declarations -var message = 'Hello'; - -// Avoid: Promise chains when async/await is cleaner -fetch(url) - .then(response => response.json()) - .then(data => console.log(data)) - .catch(error => console.error(error)); -``` - -## Dependencies -- Manage all tool dependencies at root level -- Use specific versions for critical tools -- Keep dependencies up to date -- Prefer established, well-maintained packages - -## Documentation -- Include README.md for each package -- Document complex functions and modules -- Keep CHANGELOG.md updated via changesets -- Reference TOOLING_STANDARDS.md for tool usage - -## JSON Schema -- Use proper JSON schema validation -- Include $schema references where applicable -- Follow established schema patterns in the project -- Validate schemas in tests - -## License & Copyright -- All files must include proper Adobe copyright -- Use Apache-2.0 license -- Include copyright headers in source files -- Follow existing copyright patterns -- **New files** must use the **current calendar year** (the year the file is created) in the copyright line, e.g. `Copyright YYYY Adobe. All rights reserved.` Use the same comment style as neighboring files (`//` in Rust, `#` in YAML/moon.yml, block or line comments in JS/TS, etc.) - -## Performance Considerations -- Use efficient algorithms for token processing -- Cache expensive operations when possible -- Minimize file I/O operations -- Use streaming for large datasets - -## Security -- Validate all inputs -- Use secure defaults -- Avoid eval() and similar dangerous functions -- Keep dependencies updated for security fixes - -## Error Handling -- Use descriptive error messages -- Handle edge cases gracefully -- Log errors appropriately -- Use try/catch blocks for async operations - -## Code Style -- Use 2-space indentation -- Use single quotes for strings (follow existing patterns) -- Include trailing commas in multiline objects/arrays -- Use meaningful variable and function names -- Keep functions focused and small - -## When Making Changes -1. Run tests with `moon run test` -2. Use conventional commit message format (e.g., `feat(tokens): add new color system`) -3. Create changesets for version bumps -4. Update documentation as needed -5. Follow the established patterns in the codebase - -## IDE Integration -- Use the project's ESLint configuration -- Enable Prettier for consistent formatting -- Use the project's TypeScript configuration where applicable -- Respect the project's .gitignore patterns \ No newline at end of file diff --git a/.cursorrules b/.cursorrules deleted file mode 100644 index da308a1b..00000000 --- a/.cursorrules +++ /dev/null @@ -1,271 +0,0 @@ -# Spectrum Tokens - Cursor Rules - -## Project Overview -This is the Spectrum Tokens project, a monorepo containing design tokens, component schemas, and related tooling for Adobe's Spectrum Design System. - -## Required Tools & Standards -- **Testing**: AVA (required for all JavaScript/TypeScript testing) -- **Package Management**: pnpm@10.17.1 (never use npm or yarn) -- **Monorepo Management**: moon (for task management and CI/CD) -- **Release Management**: changesets (for version bumps and releases) -- **Commit Messages**: commitlint with conventional commits (required for all git commits) -- **Node.js Version**: ~20.12 - -## Architecture -- **Monorepo Structure**: Uses pnpm workspaces with packages/, docs/, and tools/ -- **Task Management**: All tasks defined in moon.yml files -- **Testing**: AVA with specific configuration requirements -- **ESM**: Project uses ES modules (type: "module") - -## Coding Standards - -### JavaScript/TypeScript -- Use ES modules (import/export syntax) -- Prefer const over let, never use var -- Use async/await over Promise chains -- Use template literals for string interpolation -- Follow ESLint configuration where present - -### Testing Guidelines -- All tests must use AVA framework -- Test files must follow pattern: `test/**/*.test.js` -- Each package must have `ava.config.js` configuration -- Use descriptive test names -- Set up proper test environment variables - -### Commit Message Guidelines -- All commits must follow conventional commit format -- Use format: `type(scope): description` -- Available types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore` -- Scope is optional but recommended for clarity -- Description should be present tense and lowercase -- Breaking changes must include `!` after type/scope or `BREAKING CHANGE:` in footer -- Examples: `feat(tokens): add new color palette`, `fix(diff): handle edge case` - -### Package Management -- Always use pnpm commands (never npm or yarn) -- Use exact versions for critical dependencies -- Keep pnpm-lock.yaml in version control -- Add new packages to pnpm-workspace.yaml when needed - -### File Structure -- Follow existing patterns in packages/, docs/, tools/ -- Include moon.yml for task definitions -- Include proper package.json with correct fields -- Include commitlint.config.cjs for commit message validation -- Use conventional file naming - -## Development Workflow - -### Adding New Packages -1. Create package directory under packages/, docs/, or tools/ -2. Add package.json with proper configuration -3. Add moon.yml with task definitions -4. Add ava.config.js for testing -5. Update pnpm-workspace.yaml if needed - -### Testing -- Use `moon run test` to run tests -- Tests should be thorough and descriptive -- Mock external dependencies appropriately -- Use AVA's built-in assertions - -### Version Management -- Use changesets for all version bumps -- Create changesets with `pnpm changeset` -- Never manually edit version numbers -- Follow semantic versioning - -### Commit Message Management -- Use conventional commit format for all commits -- Commit messages are validated by commitlint -- Use appropriate commit types and scopes -- Include breaking change indicators when needed -- Follow the format: `type(scope): description` - -### Task Execution -- Use moon for all defined tasks -- Define tasks in moon.yml files -- Use pnpm commands within moon tasks -- Set appropriate platform (node) for Node.js tasks - -## Code Suggestions - -### Preferred Patterns -```javascript -// Preferred: ES modules -import { readFileSync } from 'fs'; -export default function myFunction() {} - -// Preferred: Async/await -async function fetchData() { - try { - const response = await fetch(url); - return await response.json(); - } catch (error) { - console.error('Error fetching data:', error); - } -} - -// Preferred: Template literals -const message = `Hello, ${name}!`; - -// Preferred: Destructuring -const { name, version } = packageJson; -``` - -### AVA Test Patterns -```javascript -// Preferred test structure -import test from 'ava'; -import { myFunction } from '../src/index.js'; - -test('myFunction should return expected result', t => { - const result = myFunction(input); - t.is(result, expected); -}); - -test('myFunction should handle errors gracefully', async t => { - const error = await t.throwsAsync(async () => { - await myFunction(invalidInput); - }); - t.is(error.message, 'Expected error message'); -}); -``` - -### Moon Task Definitions -```yaml -# Preferred task structure -tasks: - test: - command: [pnpm, ava, test] - platform: node - build: - command: [pnpm, build] - platform: node - deps: [test] -``` - -### Commitlint Configuration -```javascript -// commitlint.config.cjs -module.exports = { - extends: ["@commitlint/config-conventional"], - ignores: [ - (message) => message.includes("[create-pull-request] automated change"), - ], -}; -``` - -## File-Specific Guidelines - -### package.json -- Include "type": "module" for ESM -- Specify Node.js version in engines -- Use pnpm in packageManager field -- Include proper repository, author, license fields - -### ava.config.js -- Use export default syntax -- Include standard configuration options -- Set NODE_ENV to "test" -- Use verbose output for debugging - -### moon.yml -- Define clear task names -- Use pnpm commands -- Set platform: node for Node.js tasks -- Include proper dependencies between tasks - -## Anti-Patterns to Avoid - -### Prohibited Commands -- `npm install` or `yarn install` (use `pnpm install`) -- `npm run` or `yarn run` (use `pnpm run` or `moon run`) -- Manual version bumps (use changesets) -- Non-conventional commit messages (use proper format) - -### Prohibited Patterns -```javascript -// Avoid: CommonJS in new code -const fs = require('fs'); -module.exports = function() {}; - -// Avoid: var declarations -var message = 'Hello'; - -// Avoid: Promise chains when async/await is cleaner -fetch(url) - .then(response => response.json()) - .then(data => console.log(data)) - .catch(error => console.error(error)); -``` - -## Dependencies -- Manage all tool dependencies at root level -- Use specific versions for critical tools -- Keep dependencies up to date -- Prefer established, well-maintained packages - -## Documentation -- Include README.md for each package -- Document complex functions and modules -- Keep CHANGELOG.md updated via changesets -- Reference TOOLING_STANDARDS.md for tool usage - -## JSON Schema -- Use proper JSON schema validation -- Include $schema references where applicable -- Follow established schema patterns in the project -- Validate schemas in tests - -## License & Copyright -- Use Apache-2.0 license for this project (see root `LICENSE`). -- **Copyright headers (Adobe OSPO / open-source practice):** Add the standard Apache 2.0 file header to **human-authored source files** you create or substantially edit—not to every file in the repo. -- **Include copyright headers in** (examples): - - Code: `.js`, `.ts`, `.jsx`, `.tsx`, and similar - - Scripts: `.sh`, `.bash`, etc. - - Human-edited config/templates: `.yaml`/`.yml`, `.json` (when not machine-generated dumps) -- **Do not add copyright headers to**: - - Markdown: `.md` (READMEs, changesets, docs, `CONTRIBUTING.md`, etc.) - - Clearly auto-generated or bundled output (lockfiles, build artifacts) - - Top-level project metadata (`LICENSE`, `.gitignore`, CI config, etc.) unless the project’s own standards say otherwise -- Follow existing header patterns in nearby files when editing. - -## Performance Considerations -- Use efficient algorithms for token processing -- Cache expensive operations when possible -- Minimize file I/O operations -- Use streaming for large datasets - -## Security -- Validate all inputs -- Use secure defaults -- Avoid eval() and similar dangerous functions -- Keep dependencies updated for security fixes - -## Error Handling -- Use descriptive error messages -- Handle edge cases gracefully -- Log errors appropriately -- Use try/catch blocks for async operations - -## Code Style -- Use 2-space indentation -- Use single quotes for strings (follow existing patterns) -- Include trailing commas in multiline objects/arrays -- Use meaningful variable and function names -- Keep functions focused and small - -## When Making Changes -1. Run tests with `moon run test` -2. Use conventional commit message format (e.g., `feat(tokens): add new color system`) -3. Create changesets for version bumps -4. Update documentation as needed -5. Follow the established patterns in the codebase - -## IDE Integration -- Use the project's ESLint configuration -- Enable Prettier for consistent formatting -- Use the project's TypeScript configuration where applicable -- Respect the project's .gitignore patterns \ No newline at end of file diff --git a/.gitignore b/.gitignore index cbef6e01..f0fb4cd5 100644 --- a/.gitignore +++ b/.gitignore @@ -119,6 +119,9 @@ sdk/target/ # visual studio code .vscode/ +# Claude Code local settings (machine-specific) +.claude/settings.local.json + # test temporary directories temp-* **/test/temp-* diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..0f9f7bd0 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,297 @@ +# Spectrum Tokens - Claude Code Rules + +## Project Overview + +This is the Spectrum Tokens project, a monorepo containing design tokens, component schemas, and related tooling for Adobe's Spectrum Design System. + +## Required Tools & Standards + +* **Testing**: AVA (required for all JavaScript/TypeScript testing) +* **Package Management**: pnpm\@10.17.1 (never use npm or yarn) +* **Monorepo Management**: moon (for task management and CI/CD) +* **Release Management**: changesets (for version bumps and releases) +* **Commit Messages**: commitlint with conventional commits (required for all git commits) +* **Node.js Version**: \~20.12 + +## Architecture + +* **Monorepo Structure**: Uses pnpm workspaces with packages/, docs/, and tools/ +* **Task Management**: All tasks defined in moon.yml files +* **Testing**: AVA with specific configuration requirements +* **ESM**: Project uses ES modules (type: "module") + +## Coding Standards + +### JavaScript/TypeScript + +* Use ES modules (import/export syntax) +* Prefer const over let, never use var +* Use async/await over Promise chains +* Use template literals for string interpolation +* Follow ESLint configuration where present + +### Testing Guidelines + +* All tests must use AVA framework +* Test files must follow pattern: `test/**/*.test.js` +* Each package must have `ava.config.js` configuration +* Use descriptive test names +* Set up proper test environment variables + +### Commit Message Guidelines + +* All commits must follow conventional commit format +* Use format: `type(scope): description` +* Available types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore` +* Scope is optional but recommended for clarity +* Description should be present tense and lowercase +* Breaking changes must include `!` after type/scope or `BREAKING CHANGE:` in footer +* Examples: `feat(tokens): add new color palette`, `fix(diff): handle edge case` + +### Package Management + +* Always use pnpm commands (never npm or yarn) +* Use exact versions for critical dependencies +* Keep pnpm-lock.yaml in version control +* Add new packages to pnpm-workspace.yaml when needed + +### File Structure + +* Follow existing patterns in packages/, docs/, tools/ +* Include moon.yml for task definitions +* Include proper package.json with correct fields +* Include commitlint.config.cjs for commit message validation +* Use conventional file naming + +## Development Workflow + +### Adding New Packages + +1. Create package directory under packages/, docs/, or tools/ +2. Add package.json with proper configuration +3. Add moon.yml with task definitions +4. Add ava.config.js for testing +5. Update pnpm-workspace.yaml if needed + +### Testing + +* Use `moon run test` to run tests +* Tests should be thorough and descriptive +* Mock external dependencies appropriately +* Use AVA's built-in assertions + +### Version Management + +* Use changesets for all version bumps +* Create changesets with `pnpm changeset` +* Never manually edit version numbers +* Follow semantic versioning + +### Commit Message Management + +* Use conventional commit format for all commits +* Commit messages are validated by commitlint +* Use appropriate commit types and scopes +* Include breaking change indicators when needed +* Follow the format: `type(scope): description` + +### Task Execution + +* Use moon for all defined tasks +* Define tasks in moon.yml files +* Use pnpm commands within moon tasks +* Set appropriate platform (node) for Node.js tasks + +## Code Suggestions + +### Preferred Patterns + +```javascript +// Preferred: ES modules +import { readFileSync } from 'fs'; +export default function myFunction() {} + +// Preferred: Async/await +async function fetchData() { + try { + const response = await fetch(url); + return await response.json(); + } catch (error) { + console.error('Error fetching data:', error); + } +} + +// Preferred: Template literals +const message = `Hello, ${name}!`; + +// Preferred: Destructuring +const { name, version } = packageJson; +``` + +### AVA Test Patterns + +```javascript +// Preferred test structure +import test from 'ava'; +import { myFunction } from '../src/index.js'; + +test('myFunction should return expected result', t => { + const result = myFunction(input); + t.is(result, expected); +}); + +test('myFunction should handle errors gracefully', async t => { + const error = await t.throwsAsync(async () => { + await myFunction(invalidInput); + }); + t.is(error.message, 'Expected error message'); +}); +``` + +### Moon Task Definitions + +```yaml +# Preferred task structure +tasks: + test: + command: [pnpm, ava, test] + platform: node + build: + command: [pnpm, build] + platform: node + deps: [test] +``` + +### Commitlint Configuration + +```javascript +// commitlint.config.cjs +module.exports = { + extends: ["@commitlint/config-conventional"], + ignores: [ + (message) => message.includes("[create-pull-request] automated change"), + ], +}; +``` + +## File-Specific Guidelines + +### package.json + +* Include "type": "module" for ESM +* Specify Node.js version in engines +* Use pnpm in packageManager field +* Include proper repository, author, license fields + +### ava.config.js + +* Use export default syntax +* Include standard configuration options +* Set NODE\_ENV to "test" +* Use verbose output for debugging + +### moon.yml + +* Define clear task names +* Use pnpm commands +* Set platform: node for Node.js tasks +* Include proper dependencies between tasks + +## Anti-Patterns to Avoid + +### Prohibited Commands + +* `npm install` or `yarn install` (use `pnpm install`) +* `npm run` or `yarn run` (use `pnpm run` or `moon run`) +* Manual version bumps (use changesets) +* Non-conventional commit messages (use proper format) + +### Prohibited Patterns + +```javascript +// Avoid: CommonJS in new code +const fs = require('fs'); +module.exports = function() {}; + +// Avoid: var declarations +var message = 'Hello'; + +// Avoid: Promise chains when async/await is cleaner +fetch(url) + .then(response => response.json()) + .then(data => console.log(data)) + .catch(error => console.error(error)); +``` + +## Dependencies + +* Manage all tool dependencies at root level +* Use specific versions for critical tools +* Keep dependencies up to date +* Prefer established, well-maintained packages + +## Documentation + +* Include README.md for each package +* Document complex functions and modules +* Keep CHANGELOG.md updated via changesets +* Reference TOOLING\_STANDARDS.md for tool usage + +## JSON Schema + +* Use proper JSON schema validation +* Include $schema references where applicable +* Follow established schema patterns in the project +* Validate schemas in tests + +## License & Copyright + +* All files must include proper Adobe copyright +* Use Apache-2.0 license +* Include copyright headers in source files +* Follow existing copyright patterns +* **New files** must use the **current calendar year** (the year the file is created) in the copyright line, e.g. `Copyright YYYY Adobe. All rights reserved.` Use the same comment style as neighboring files (`//` in Rust, `#` in YAML/moon.yml, block or line comments in JS/TS, etc.) + +## Performance Considerations + +* Use efficient algorithms for token processing +* Cache expensive operations when possible +* Minimize file I/O operations +* Use streaming for large datasets + +## Security + +* Validate all inputs +* Use secure defaults +* Avoid eval() and similar dangerous functions +* Keep dependencies updated for security fixes + +## Error Handling + +* Use descriptive error messages +* Handle edge cases gracefully +* Log errors appropriately +* Use try/catch blocks for async operations + +## Code Style + +* Use 2-space indentation +* Use single quotes for strings (follow existing patterns) +* Include trailing commas in multiline objects/arrays +* Use meaningful variable and function names +* Keep functions focused and small + +## When Making Changes + +1. Run tests with `moon run test` +2. Use conventional commit message format (e.g., `feat(tokens): add new color system`) +3. Create changesets for version bumps +4. Update documentation as needed +5. Follow the established patterns in the codebase + +## IDE Integration + +* Use the project's ESLint configuration +* Enable Prettier for consistent formatting +* Use the project's TypeScript configuration where applicable +* Respect the project's .gitignore patterns diff --git a/tools/component-options-editor/.cursorrules b/tools/component-options-editor/.cursorrules deleted file mode 100644 index 0563e789..00000000 --- a/tools/component-options-editor/.cursorrules +++ /dev/null @@ -1,259 +0,0 @@ -# Component Options Editor - Cursor Rules - -## Project Context -This is a Figma plugin built with TypeScript, Lit, and Spectrum Web Components. The plugin helps author component option schemas for Adobe Spectrum Design System components. - -## Technology Stack -- **Framework**: Lit (Web Components) -- **UI Library**: Spectrum Web Components (@spectrum-web-components/*) -- **Language**: TypeScript -- **Build**: Webpack -- **Figma**: Plugin API -- **Version Control**: Git with GitHub CLI - -## Code Quality Standards - -### TypeScript -- Always use explicit types, avoid `any` -- Use interfaces for data structures (see `src/index.d.ts`) -- Enable strict mode compliance -- Use type guards where appropriate -- Document complex types with JSDoc comments - -### Lit Components -- Use `@customElement` decorator for all custom elements -- Use `@property` and `@query` decorators appropriately -- Implement reactive properties with proper types -- Use `html` template literals for rendering -- Follow Lit lifecycle methods (connectedCallback, disconnectedCallback) -- Clean up event listeners in disconnectedCallback - -### Spectrum Web Components -- **ALWAYS use Spectrum Web Components for UI elements** -- Prefer Spectrum components over native HTML elements -- Import from `@spectrum-web-components/*` packages -- Common components to use: - - `sp-button`, `sp-button-group` - - `sp-textfield`, `sp-field-label`, `sp-field-group` - - `sp-picker`, `sp-menu`, `sp-menu-item` - - `sp-checkbox`, `sp-radio`, `sp-radio-group` - - `sp-table` and related table elements - - `sp-action-button`, `sp-action-group` - - `sp-tabs`, `sp-tab`, `sp-tab-panel` - - `sp-icon` with workflow icons -- Follow Spectrum design patterns and sizing (s, m, l, xl) -- Use Spectrum color tokens and theming - -### Code Organization -- One component per file -- Place components in appropriate directories: - - `src/ui/app/` - main app components - - `src/ui/app/templates/` - reusable template components - - `src/ui/app/events/` - custom events - - `src/plugin/` - Figma plugin backend code -- Keep files under 300 lines when possible -- Extract reusable logic into helper functions - -### Naming Conventions -- Components: PascalCase (e.g., `OptionForm`, `LitAppElement`) -- Files: camelCase.ts (e.g., `optionForm.ts`, `litAppElement.ts`) -- Properties: camelCase (e.g., `componentName`, `optionType`) -- Events: kebab-case (e.g., `save-option`, `update-component`) -- Constants: UPPER_SNAKE_CASE - -### Event Handling -- Create custom events extending Event class (see `SaveOptionEvent`) -- Use type-safe event dispatching -- Document event payloads with interfaces -- Clean up listeners properly - -### State Management -- Use Lit reactive properties (`@property`) -- Keep state as high as needed, as low as possible -- Communicate between components via events -- Store plugin data in Figma's plugin storage (`figma.currentPage.getPluginData`) - -## GitHub Integration - -### Using GitHub CLI -- **ALWAYS use `gh` CLI for GitHub operations** -- Update issues: `gh issue edit --body "..."` -- List issues: `gh issue list` -- View issue: `gh issue view ` -- Comment on issues: `gh issue comment --body "..."` -- Close issues: `gh issue close ` -- Create PRs: `gh pr create` - -### Issue Management -- **Update issue descriptions/checklists, NOT just comments** -- When completing a task, use: `gh issue edit --body "$(gh issue view -c | sed 's/- \[ \] Task/- [x] Task/')"` -- Keep issue bodies as single source of truth -- Use tasklist format: `- [ ]` for tasks -- Link related issues with `#` in descriptions -- Use labels appropriately: `enhancement`, `bug`, `documentation` - -### Commit Messages -- **REQUIRED**: Follow conventional commits format (enforced by commitlint) -- Format: `(): ` -- Types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore` -- Scopes: `metadata`, `options`, `preview`, `json`, `edit`, `variants`, `ui`, `plugin`, `build`, `deps` -- Subject must be sentence-case (capital first letter) -- Reference issues: `feat(metadata): Add category picker (#1)` -- Keep first line under 72 characters -- Add detailed description in body when needed - -### Pre-commit Automation -- **Husky pre-commit hook** runs automatically before each commit -- **lint-staged** runs ESLint and Prettier on staged files only -- Auto-fixes issues when possible -- Commit will be rejected if linting fails -- Commit message format is validated by commitlint - -### CI/CD & Branch Protection -- **GitHub Actions CI** runs on all pushes and PRs - - Checks: ESLint, Prettier, TypeScript compilation, Build, Copyright - - Must pass before merging to main -- **PR title validation** enforces conventional format -- **Branch protection active on main and dev**: - - Main: Requires status checks, conversation resolution, linear history - - Dev: Requires status checks, allows force pushes for rebasing - -## Plugin-Specific Guidelines - -### Figma Plugin Backend (src/plugin/) -- Keep plugin code minimal and focused on data persistence -- Use `figma.ui.postMessage` for plugin → UI communication -- Use `figma.ui.onmessage` for UI → plugin communication -- Handle errors gracefully with try-catch -- Log important operations with `cout` helper - -### UI Code (src/ui/) -- All UI logic runs in iframe sandbox -- Use `parent.postMessage` to communicate with plugin -- Listen for messages with `window.addEventListener('message')` -- Keep UI responsive and reactive -- Show loading states when appropriate - -### Data Validation -- Validate component metadata (required fields, URL format) -- Validate option data before saving -- Provide clear error messages to users -- Match JSON schema from `component-options.json` - -### Build Process -- Run `npm run build` before testing in Figma -- Build outputs to `dist/` directory -- Manifest paths in dist are relative (not `dist/...`) -- Test changes in Figma's development mode - -## Development Workflow - -### Git Flow Strategy -``` -main (protected, production) - └── dev (protected, development) - └── feature/issue-X-description (feature branches) -``` - -1. **Before starting work**: - - Check issue details: `gh issue view ` - - Create feature branch from dev: `git checkout dev && git pull && git checkout -b feature/issue--description` - -2. **During development**: - - Write clean, typed TypeScript - - Use Spectrum components - - Commit frequently with conventional commits (hooks will auto-fix formatting) - - Test in Figma frequently - - Keep commits atomic and well-described - -3. **Committing (automated checks run)**: - - Stage files: `git add ` - - Commit: `git commit -m "feat(scope): Description with capital letter"` - - **Pre-commit hook automatically runs**: ESLint --fix, Prettier --write - - **Commit-msg hook validates**: Conventional commit format - - Commit rejected if checks fail - fix issues and try again - - No need to run lint/prettier manually - hooks handle it! - -4. **Before pushing**: - - Optional: Run full validation: `npm run validate` - - Optional: Test build: `npm run build` - - Test plugin in Figma - - Push: `git push origin feature/issue-X-description` - -5. **Creating PRs**: - - Use `gh pr create --base dev` (merge to dev first, not main) - - PR title must follow conventional format: `feat(scope): Description` - - Reference issue: "Closes #" - - Describe changes and testing done - - Wait for CI checks to pass (automated) - - Squash and merge when ready - -6. **After completing tasks**: - - Update issue checklist using `gh issue edit ` - - Delete feature branch after merge - -7. **Releases to Main**: - - Create PR from dev to main when ready for release - - More stringent checks apply on main branch - - Tag releases appropriately - -## npm Scripts Reference - -### Quality & Validation -- `npm run lint` - Check TypeScript files with ESLint -- `npm run lint:fix` - Auto-fix ESLint issues -- `npm run prettier` - Check code formatting -- `npm run prettier:fix` - Auto-format code -- `npm run type-check` - Run TypeScript compiler without emitting files -- `npm run validate` - Run all checks (type-check, lint, prettier) -- `npm test` - Full validation + build (used in CI) -- `npm run lint-staged` - Run on staged files (used by Husky) - -### Build & Development -- `npm run build` - Full build (pack + assets) -- `npm run pack` - Webpack build + inline -- `npm run assets` - Copy assets to dist -- `npm run clean` - Remove build/dist directories -- `npm start` - Watch mode for development - -### Other -- `npm run copyright` - Check copyright headers -- `npm run format` - Run copyright + prettier + lint fixes - -## File References -- Main app: `src/ui/app/litAppElement.ts` -- Plugin backend: `src/plugin/plugin.ts` -- Type definitions: `src/index.d.ts` -- Schema reference: `component-options.json` -- Build config: `webpack.config.js` -- Package info: `package.json` -- Cursor rules: `.cursorrules` (this file) -- Branch protection plan: `.github/BRANCH_PROTECTION_PLAN.md` - -## Testing Checklist -- [ ] TypeScript compiles without errors -- [ ] Linter passes -- [ ] Plugin builds successfully -- [ ] Plugin loads in Figma without errors -- [ ] UI renders correctly -- [ ] Data persists after closing plugin -- [ ] All Spectrum components function properly -- [ ] Responsive to user interactions - -## Common Pitfalls to Avoid -- ❌ Using native HTML inputs instead of Spectrum components -- ❌ Forgetting to build before testing in Figma -- ❌ Not cleaning up event listeners -- ❌ Using `any` type -- ❌ Commenting on issues instead of updating descriptions -- ❌ Not referencing issues in commits -- ❌ Hardcoding values that should be configurable -- ❌ Forgetting to handle edge cases (empty arrays, null values) - -## Resources -- [Lit Documentation](https://lit.dev/) -- [Spectrum Web Components](https://opensource.adobe.com/spectrum-web-components/) -- [Figma Plugin API](https://www.figma.com/plugin-docs/) -- [TypeScript Handbook](https://www.typescriptlang.org/docs/) -- [GitHub CLI Manual](https://cli.github.com/manual/) - diff --git a/tools/component-options-editor/CLAUDE.md b/tools/component-options-editor/CLAUDE.md new file mode 100644 index 00000000..8f8d4915 --- /dev/null +++ b/tools/component-options-editor/CLAUDE.md @@ -0,0 +1,283 @@ +# Component Options Editor - Claude Code Rules + +## Project Context + +This is a Figma plugin built with TypeScript, Lit, and Spectrum Web Components. The plugin helps author component option schemas for Adobe Spectrum Design System components. + +## Technology Stack + +* **Framework**: Lit (Web Components) +* **UI Library**: Spectrum Web Components (@spectrum-web-components/\*) +* **Language**: TypeScript +* **Build**: Webpack +* **Figma**: Plugin API +* **Version Control**: Git with GitHub CLI + +## Code Quality Standards + +### TypeScript + +* Always use explicit types, avoid `any` +* Use interfaces for data structures (see `src/index.d.ts`) +* Enable strict mode compliance +* Use type guards where appropriate +* Document complex types with JSDoc comments + +### Lit Components + +* Use `@customElement` decorator for all custom elements +* Use `@property` and `@query` decorators appropriately +* Implement reactive properties with proper types +* Use `html` template literals for rendering +* Follow Lit lifecycle methods (connectedCallback, disconnectedCallback) +* Clean up event listeners in disconnectedCallback + +### Spectrum Web Components + +* **ALWAYS use Spectrum Web Components for UI elements** +* Prefer Spectrum components over native HTML elements +* Import from `@spectrum-web-components/*` packages +* Common components to use: + * `sp-button`, `sp-button-group` + * `sp-textfield`, `sp-field-label`, `sp-field-group` + * `sp-picker`, `sp-menu`, `sp-menu-item` + * `sp-checkbox`, `sp-radio`, `sp-radio-group` + * `sp-table` and related table elements + * `sp-action-button`, `sp-action-group` + * `sp-tabs`, `sp-tab`, `sp-tab-panel` + * `sp-icon` with workflow icons +* Follow Spectrum design patterns and sizing (s, m, l, xl) +* Use Spectrum color tokens and theming + +### Code Organization + +* One component per file +* Place components in appropriate directories: + * `src/ui/app/` - main app components + * `src/ui/app/templates/` - reusable template components + * `src/ui/app/events/` - custom events + * `src/plugin/` - Figma plugin backend code +* Keep files under 300 lines when possible +* Extract reusable logic into helper functions + +### Naming Conventions + +* Components: PascalCase (e.g., `OptionForm`, `LitAppElement`) +* Files: camelCase.ts (e.g., `optionForm.ts`, `litAppElement.ts`) +* Properties: camelCase (e.g., `componentName`, `optionType`) +* Events: kebab-case (e.g., `save-option`, `update-component`) +* Constants: UPPER\_SNAKE\_CASE + +### Event Handling + +* Create custom events extending Event class (see `SaveOptionEvent`) +* Use type-safe event dispatching +* Document event payloads with interfaces +* Clean up listeners properly + +### State Management + +* Use Lit reactive properties (`@property`) +* Keep state as high as needed, as low as possible +* Communicate between components via events +* Store plugin data in Figma's plugin storage (`figma.currentPage.getPluginData`) + +## GitHub Integration + +### Using GitHub CLI + +* **ALWAYS use `gh` CLI for GitHub operations** +* Update issues: `gh issue edit --body "..."` +* List issues: `gh issue list` +* View issue: `gh issue view ` +* Comment on issues: `gh issue comment --body "..."` +* Close issues: `gh issue close ` +* Create PRs: `gh pr create` + +### Issue Management + +* **Update issue descriptions/checklists, NOT just comments** +* When completing a task, use: `gh issue edit --body "$(gh issue view -c | sed 's/- \[ \] Task/- [x] Task/')"` +* Keep issue bodies as single source of truth +* Use tasklist format: `- [ ]` for tasks +* Link related issues with `#` in descriptions +* Use labels appropriately: `enhancement`, `bug`, `documentation` + +### Commit Messages + +* **REQUIRED**: Follow conventional commits format (enforced by commitlint) +* Format: `(): ` +* Types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore` +* Scopes: `metadata`, `options`, `preview`, `json`, `edit`, `variants`, `ui`, `plugin`, `build`, `deps` +* Subject must be sentence-case (capital first letter) +* Reference issues: `feat(metadata): Add category picker (#1)` +* Keep first line under 72 characters +* Add detailed description in body when needed + +### Pre-commit Automation + +* **Husky pre-commit hook** runs automatically before each commit +* **lint-staged** runs ESLint and Prettier on staged files only +* Auto-fixes issues when possible +* Commit will be rejected if linting fails +* Commit message format is validated by commitlint + +### CI/CD & Branch Protection + +* **GitHub Actions CI** runs on all pushes and PRs + * Checks: ESLint, Prettier, TypeScript compilation, Build, Copyright + * Must pass before merging to main +* **PR title validation** enforces conventional format +* **Branch protection active on main and dev**: + * Main: Requires status checks, conversation resolution, linear history + * Dev: Requires status checks, allows force pushes for rebasing + +## Plugin-Specific Guidelines + +### Figma Plugin Backend (src/plugin/) + +* Keep plugin code minimal and focused on data persistence +* Use `figma.ui.postMessage` for plugin -> UI communication +* Use `figma.ui.onmessage` for UI -> plugin communication +* Handle errors gracefully with try-catch +* Log important operations with `cout` helper + +### UI Code (src/ui/) + +* All UI logic runs in iframe sandbox +* Use `parent.postMessage` to communicate with plugin +* Listen for messages with `window.addEventListener('message')` +* Keep UI responsive and reactive +* Show loading states when appropriate + +### Data Validation + +* Validate component metadata (required fields, URL format) +* Validate option data before saving +* Provide clear error messages to users +* Match JSON schema from `component-options.json` + +### Build Process + +* Run `npm run build` before testing in Figma +* Build outputs to `dist/` directory +* Manifest paths in dist are relative (not `dist/...`) +* Test changes in Figma's development mode + +## Development Workflow + +### Git Flow Strategy + +``` +main (protected, production) + -> dev (protected, development) + -> feature/issue-X-description (feature branches) +``` + +1. **Before starting work**: + * Check issue details: `gh issue view ` + * Create feature branch from dev: `git checkout dev && git pull && git checkout -b feature/issue--description` + +2. **During development**: + * Write clean, typed TypeScript + * Use Spectrum components + * Commit frequently with conventional commits (hooks will auto-fix formatting) + * Test in Figma frequently + * Keep commits atomic and well-described + +3. **Committing (automated checks run)**: + * Stage files: `git add ` + * Commit: `git commit -m "feat(scope): Description with capital letter"` + * **Pre-commit hook automatically runs**: ESLint --fix, Prettier --write + * **Commit-msg hook validates**: Conventional commit format + * Commit rejected if checks fail - fix issues and try again + * No need to run lint/prettier manually - hooks handle it! + +4. **Before pushing**: + * Optional: Run full validation: `npm run validate` + * Optional: Test build: `npm run build` + * Test plugin in Figma + * Push: `git push origin feature/issue-X-description` + +5. **Creating PRs**: + * Use `gh pr create --base dev` (merge to dev first, not main) + * PR title must follow conventional format: `feat(scope): Description` + * Reference issue: "Closes #" + * Describe changes and testing done + * Wait for CI checks to pass (automated) + * Squash and merge when ready + +6. **After completing tasks**: + * Update issue checklist using `gh issue edit ` + * Delete feature branch after merge + +7. **Releases to Main**: + * Create PR from dev to main when ready for release + * More stringent checks apply on main branch + * Tag releases appropriately + +## npm Scripts Reference + +### Quality & Validation + +* `npm run lint` - Check TypeScript files with ESLint +* `npm run lint:fix` - Auto-fix ESLint issues +* `npm run prettier` - Check code formatting +* `npm run prettier:fix` - Auto-format code +* `npm run type-check` - Run TypeScript compiler without emitting files +* `npm run validate` - Run all checks (type-check, lint, prettier) +* `npm test` - Full validation + build (used in CI) +* `npm run lint-staged` - Run on staged files (used by Husky) + +### Build & Development + +* `npm run build` - Full build (pack + assets) +* `npm run pack` - Webpack build + inline +* `npm run assets` - Copy assets to dist +* `npm run clean` - Remove build/dist directories +* `npm start` - Watch mode for development + +### Other + +* `npm run copyright` - Check copyright headers +* `npm run format` - Run copyright + prettier + lint fixes + +## File References + +* Main app: `src/ui/app/litAppElement.ts` +* Plugin backend: `src/plugin/plugin.ts` +* Type definitions: `src/index.d.ts` +* Schema reference: `component-options.json` +* Build config: `webpack.config.js` +* Package info: `package.json` +* Branch protection plan: `.github/BRANCH_PROTECTION_PLAN.md` + +## Testing Checklist + +* [ ] TypeScript compiles without errors +* [ ] Linter passes +* [ ] Plugin builds successfully +* [ ] Plugin loads in Figma without errors +* [ ] UI renders correctly +* [ ] Data persists after closing plugin +* [ ] All Spectrum components function properly +* [ ] Responsive to user interactions + +## Common Pitfalls to Avoid + +* Using native HTML inputs instead of Spectrum components +* Forgetting to build before testing in Figma +* Not cleaning up event listeners +* Using `any` type +* Commenting on issues instead of updating descriptions +* Not referencing issues in commits +* Hardcoding values that should be configurable +* Forgetting to handle edge cases (empty arrays, null values) + +## Resources + +* [Lit Documentation](https://lit.dev/) +* [Spectrum Web Components](https://opensource.adobe.com/spectrum-web-components/) +* [Figma Plugin API](https://www.figma.com/plugin-docs/) +* [TypeScript Handbook](https://www.typescriptlang.org/docs/) +* [GitHub CLI Manual](https://cli.github.com/manual/) From bb7a203141d31e93a8535c2316aa657ea100af97 Mon Sep 17 00:00:00 2001 From: Garth Braithwaite Date: Fri, 27 Mar 2026 12:39:23 -0600 Subject: [PATCH 2/2] chore: add gh cli and pr template instructions to CLAUDE.md Co-Authored-By: Claude Opus 4.6 (1M context) --- CLAUDE.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 0f9f7bd0..f88d3eb2 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -281,6 +281,21 @@ fetch(url) * Use meaningful variable and function names * Keep functions focused and small +## GitHub CLI + +* **Always use `gh` CLI** for GitHub operations (issues, PRs, checks, releases) +* View PR/issue details: `gh pr view`, `gh issue view` +* Check CI status: `gh pr checks` + +## Pull Requests + +* When creating PRs, **use the repo's PR template** at `.github/PULL_REQUEST_TEMPLATE.md` as the body structure +* Read the template with `cat .github/PULL_REQUEST_TEMPLATE.md`, fill in each section, and pass it via `gh pr create --body-file` +* Fill in the checklist — check boxes that apply, leave others unchecked +* Link related issues in the "Related Issue" section +* Always include a motivation/context explanation +* Describe how changes were tested + ## When Making Changes 1. Run tests with `moon run test`