ultracite

What this skill does

# Ultracite - AI-Ready Formatter and Linter

Ultracite enforces strict type safety, accessibility standards, and consistent code quality for JavaScript/TypeScript projects using Biome's lightning-fast formatter and linter.

## Key Principles

- **Zero configuration required**: Works out of the box
- **Subsecond performance**: Lightning-fast checks and fixes
- **Maximum type safety**: Catch errors before runtime
- **AI-friendly code generation**: Optimized for AI-assisted development

## Before Writing Code

When writing or reviewing code, follow this checklist:

1. **Analyze existing patterns** in the codebase
2. **Consider edge cases** and error scenarios
3. **Follow the rules** below strictly
4. **Validate accessibility** requirements

## Common Commands

```bash
# Initialize Ultracite in your project
npx ultracite init

# Format and fix code automatically
npx ultracite fix

# Check for issues without fixing
npx ultracite check
```

## Instructions

When working with TypeScript/JavaScript code:

1. **Read the code** using the Read tool before making changes
2. **Check for violations** of the rules below
3. **Apply fixes** using the Edit tool
4. **Verify accessibility** standards are met
5. **Ensure type safety** with TypeScript

## Core Rule Categories

### 1. Accessibility (a11y)

**Critical accessibility requirements:**

- ❌ Don't use `accessKey` attribute on any HTML element
- ❌ Don't set `aria-hidden="true"` on focusable elements
- ❌ Don't use distracting elements like `<marquee>` or `<blink>`
- ❌ Don't include "image", "picture", or "photo" in img alt prop
- ✅ Make sure label elements have text content and are associated with an input
- ✅ Give all elements requiring alt text meaningful information for screen readers
- ✅ Always include a `type` attribute for button elements
- ✅ Always include a `lang` attribute on the html element
- ✅ Always include a `title` attribute for iframe elements
- ✅ Accompany `onClick` with at least one of: `onKeyUp`, `onKeyDown`, or `onKeyPress`
- ✅ Accompany `onMouseOver`/`onMouseOut` with `onFocus`/`onBlur`
- ✅ Include caption tracks for audio and video elements
- ✅ Use semantic elements instead of role attributes in JSX
- ✅ Always include a `title` element for SVG elements

**Example - Good Accessibility:**

```tsx
// ✅ Good: Proper button with type and accessible events
<button
  type="button"
  onClick={handleClick}
  onKeyDown={handleKeyDown}
>
  Submit
</button>

// ✅ Good: Accessible image with meaningful alt
<img src="/photo.jpg" alt="Team celebrating product launch" />

// ❌ Bad: Missing type, keyboard support, and poor alt text
<button onClick={handleClick}>Submit</button>
<img src="/photo.jpg" alt="image of photo" />
```

### 2. React and JSX Best Practices

**Critical React requirements:**

- ❌ Don't destructure props inside JSX components in Solid projects
- ❌ Don't define React components inside other components
- ❌ Don't use Array index in keys
- ❌ Don't assign JSX properties multiple times
- ❌ Don't use both `children` and `dangerouslySetInnerHTML` props
- ❌ Don't pass children as props
- ✅ Make sure all dependencies are correctly specified in React hooks
- ✅ Make sure all React hooks are called from the top level
- ✅ Don't forget key props in iterators and collection literals
- ✅ Use `<>...</>` instead of `<Fragment>...</Fragment>`

**Example - Good React Patterns:**

```tsx
// ✅ Good: Component defined at top level with proper hooks
function UserList({ users }) {
  const [selected, setSelected] = useState(null);

  useEffect(() => {
    // All dependencies listed
    loadData();
  }, [loadData]);

  return (
    <>
      {users.map(user => (
        <UserCard key={user.id} user={user} />
      ))}
    </>
  );
}

// ❌ Bad: Component defined inside, index as key, missing deps
function ParentComponent() {
  function ChildComponent() { // Bad: nested component
    useEffect(() => {
      doSomething(); // Bad: missing dependency
    }, []);
    return <div>Child</div>;
  }

  return items.map((item, i) => (
    <div key={i}>{item}</div> // Bad: index as key
  ));
}
```

### 3. TypeScript Best Practices

**Critical TypeScript requirements:**

- ❌ Don't use TypeScript enums (use `as const` objects instead)
- ❌ Don't use the `any` type
- ❌ Don't use non-null assertions with the exclamation mark postfix operator
- ❌ Don't use TypeScript namespaces
- ❌ Don't use parameter properties in class constructors
- ❌ Don't declare empty interfaces
- ✅ Use `export type` for types
- ✅ Use `import type` for types
- ✅ Use `as const` instead of literal types and type annotations
- ✅ Use either `T[]` or `Array<T>` consistently

**Example - Good TypeScript Patterns:**

```typescript
// ✅ Good: Use const objects instead of enums
const Status = {
  PENDING: 'pending',
  ACTIVE: 'active',
  COMPLETED: 'completed'
} as const;
type Status = typeof Status[keyof typeof Status];

// ✅ Good: Import/export types properly
import type { User } from './types';
export type { User };

// ✅ Good: Specific types, no any
function processUser(user: User): Result<User> {
  return { success: true, data: user };
}

// ❌ Bad: Using enum, any, and non-null assertion
enum Status { PENDING, ACTIVE }  // Bad: use const object
function process(data: any) {    // Bad: use specific type
  return data!.value;            // Bad: avoid non-null assertion
}
```

### 4. Code Quality and Correctness

**Critical correctness requirements:**

- ❌ Don't use `arguments` object (use rest parameters)
- ❌ Don't use unnecessary nested block statements
- ❌ Don't use the void operators
- ❌ Don't reassign const variables
- ❌ Don't use constant expressions in conditions
- ❌ Don't use variables before they're declared
- ❌ Don't use await inside loops
- ❌ Don't shadow variables from outer scopes
- ✅ Use arrow functions instead of function expressions
- ✅ Use `for...of` statements instead of `Array.forEach`
- ✅ Use concise optional chaining
- ✅ Make sure Promise-like statements are handled appropriately

**Example - Good Code Quality:**

```typescript
// ✅ Good: Arrow functions, for-of, proper async handling
const processItems = async (items: Item[]) => {
  const results = [];

  for (const item of items) {
    const result = await processItem(item);
    results.push(result);
  }

  return results;
};

// ✅ Good: Optional chaining
const userName = user?.profile?.name ?? 'Anonymous';

// ❌ Bad: Function expression, forEach, await in loop
const processItems = function(items) {
  const results = [];
  items.forEach(async (item) => {  // Bad: async in forEach
    await processItem(item);        // Bad: await in loop (via forEach)
  });
  return results;
};
```

### 5. Error Handling

**Error handling best practices:**

- ✅ Always throw Error objects (not strings or other values)
- ✅ Use `new` when throwing an error
- ✅ Handle promises appropriately (await or .catch())
- ✅ Don't use control flow statements in finally blocks
- ✅ Make sure to pass a message value when creating built-in errors

**Example - Good Error Handling:**

```typescript
// ✅ Good: Comprehensive error handling
async function fetchData(url: string): Promise<Result<Data>> {
  try {
    const response = await fetch(url);

    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }

    const data = await response.json();
    return { success: true, data };
  } catch (error) {
    console.error('API call failed:', error);
    return {
      success: false,
      error: error instanceof Error ? error.message : 'Unknown error'
    };
  }
}

// ❌ Bad: Swallowing errors, throwing strings
async function fetchData(url: string) {
  try {
    const response = await fetch(url);
    return await response.json();
  } catch (e) {
    console.log(e);              // Bad: just logging
    throw 'Failed to fetch';     // Bad: throwing string
  }
}
```

### 6. Style and Consistency

**Key style requirements:**

- ✅ Use `const` declarations for variables that are only assigned once