Skip to content

CLAUDE.md

Latest commit

 

History

History
312 lines (232 loc) · 8.63 KB

CLAUDE.md

File metadata and controls

312 lines (232 loc) · 8.63 KB

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

// 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

// 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

# Preferred task structure
tasks:
  test:
    command: [pnpm, ava, test]
    platform: node
  build:
    command: [pnpm, build]
    platform: node
    deps: [test]

Commitlint Configuration

// 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

// 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

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
  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
⚡