Skip to content

CLAUDE.md

Latest commit

 

History

History
283 lines (219 loc) · 9.73 KB

CLAUDE.md

File metadata and controls

283 lines (219 loc) · 9.73 KB

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 <number> --body "..."
  • List issues: gh issue list
  • View issue: gh issue view <number>
  • Comment on issues: gh issue comment <number> --body "..."
  • Close issues: gh issue close <number>
  • Create PRs: gh pr create

Issue Management

  • Update issue descriptions/checklists, NOT just comments
  • When completing a task, use: gh issue edit <number> --body "$(gh issue view <number> -c | sed 's/- \[ \] Task/- [x] Task/')"
  • Keep issue bodies as single source of truth
  • Use tasklist format: - [ ] for tasks
  • Link related issues with #<number> in descriptions
  • Use labels appropriately: enhancement, bug, documentation

Commit Messages

  • REQUIRED: Follow conventional commits format (enforced by commitlint)
  • Format: <type>(<scope>): <Subject starting with capital letter>
  • 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 <number>
    • Create feature branch from dev: git checkout dev && git pull && git checkout -b feature/issue-<number>-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 <files>
    • 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 <number>
    • 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