Skip to main content
rule CX Codex

principles — Claude Code rule: what it does, how to install

The principles rule for Claude Code establishes six core standards for component design. It guides agents during component creation, refactoring, and evaluation.

Apache-2.0 ★ 141 updated 2026-11-17

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/rules/principles.md
Open on GitHub

What principles does

The rule enforces design standards focused on composability, accessibility, and performance. It mandates the use of native semantic HTML while discouraging heavy dependencies to keep bundle sizes lean. Every architectural decision is evaluated against code transparency, ease of styling via CSS variables, and the inclusion of JSDoc documentation.

Applying this rule prevents the development of monolithic structures or obscured black-box components. Agents reference this file during UI development to ensure that all interactive elements support keyboard navigation and remain maintainable by the development team.

What it helps with

  • prevent the creation of monolithic components
  • ensure UI accessibility by default
  • simplify code maintenance and styling
  • minimize unnecessary bundle dependencies

Example prompts for the agent

  • Apply the core principles when refactoring the login form.
  • Evaluate this component against the composability guidelines.
  • Ensure the modal follows the accessibility standards defined in principles.

How to install principles

Manually: put the files in place

.claude/rules/principles.md

The paths frontmatter field limits the files

Step by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use

Questions about principles

How to install principles in Claude Code?

Create a file at .claude/rules/principles.md and add the rule content there.

What does principles do?

It provides a framework for architectural decisions to ensure components are modular, performant, and well-documented.

What is required to use principles?

The rule relies on semantic HTML usage, avoiding overly complex Higher-Order Components, and keeping documentation clear.

Source text

principles.md · Apache-2.0
---
title: Core Component Principles
impact: HIGH
impactDescription: Foundation of component architecture decisions
tags: principles, composability, accessibility, customization, performance, transparency, dx
---

## Core Component Principles

These six principles guide all component design decisions. Apply them consistently when building, refactoring, or evaluating components.

### 1. Composability and Reusability

Favor composition over inheritance. Build components that combine and nest to create complex UIs.

**Incorrect (monolithic, hard to customize):**

```tsx
<Accordion data={data} />
```

**Correct (composable, each layer customizable):**

```tsx
<Accordion.Root open={open} onOpenChange={setOpen}>
  {items.map((item) => (
    <Accordion.Item key={item.id}>
      <Accordion.Trigger>{item.title}</Accordion.Trigger>
      <Accordion.Content>{item.content}</Accordion.Content>
    </Accordion.Item>
  ))}
</Accordion.Root>
```

### 2. Accessible by Default

Components must be usable by all users. Accessibility is not optional—it's a baseline feature.

**Incorrect (generic div with click handler):**

```tsx
<div onClick={handleClick} className="button">
  Click me
</div>
```

**Correct (semantic button element):**

```tsx
<button onClick={handleClick}>Click me</button>
```

Best practices:

- Use semantic HTML (`<button>`, `<ul>/<li>`, `<nav>`, etc.)
- Provide proper ARIA roles, states, and properties
- Support keyboard navigation for all interactive elements
- Ensure focus management in modals, dropdowns, and overlays

### 3. Customizability and Theming

Components should be easy to restyle or adapt to different design requirements.

**Correct (design tokens and className override):**

```tsx
export function Button({ className, ...props }: ButtonProps) {
  return <button className={cn("base-button-styles", className)} {...props} />;
}
```

Best practices:

- Use CSS variables (design tokens) for colors, spacing, typography
- Always allow `className` prop for style overrides
- Provide sensible default styling
- Avoid hard-coded colors, fonts, or spacing values

### 4. Lightweight and Performant

Components should be lean in terms of assets and dependencies.

**Incorrect (heavy dependency for simple task):**

```tsx
import { entireDateLibrary } from "heavy-date-lib";
```

**Correct (native APIs or lightweight alternatives):**

```tsx
const formatDate = (date: Date) => date.toLocaleDateString();
```

Best practices:

- Keep bundle size minimal
- Use tree-shaking friendly imports
- Lazy load heavy features when possible
- Optimize for initial render performance

### 5. Transparency and Code Ownership

Components should not be black boxes. Developers should be able to inspect and modify them.

**Correct (clear, readable implementation):**

```tsx
export function Button({ children, onClick, ...props }: ButtonProps) {
  return (
    <button onClick={onClick} {...props}>
      {children}
    </button>
  );
}
```

**Incorrect (obfuscated or overly complex):**

```tsx
export const Button = compose(withHOC1, withHOC2, withHOC3)(BaseButton);
```

### 6. Well-documented and DX-Friendly

Components should come with clear documentation and examples.

**Correct (comprehensive JSDoc):**

```tsx
/**
 * Button component for primary actions.
 *
 * @example
 * <Button variant="primary" onClick={handleClick}>Click me</Button>
 *
 * @remarks
 * - Supports keyboard navigation (Enter/Space)
 * - Accessible by default with proper ARIA attributes
 */
export function Button({ ... }: ButtonProps) { }
```

A well-designed component applies all six principles together: **Composes** with other components, **works for everyone** with proper accessibility, **adapts** to different designs via theming, **performs** efficiently, **can be inspected** and modified, and **is easy to learn** through documentation.

© maxtrigify · Apache-2.0 · maxtrigify/Otto

Similar IDE rules

All IDE rules for Frontend and UI →

From the same set18

The whole set →
composition The composition rule for Claude Code guides the breakdown of complex UI components into small, focused parts. It serves when building component libraries or flexible interfaces. CX Codex +1 ★ 141repo stars overview overview is a Claude Code rule for designing accessible, composable UI components. It comes into play while shaping component APIs and shared patterns. CX Codex +1 ★ 141repo stars types The types rule for Claude Code standardizes component prop definitions in TypeScript. It provides a framework for building flexible, type-safe interfaces across React projects. CX Codex +1 ★ 141repo stars data-attributes data-attributes is a Claude Code rule for styling component states and targeting nested parts with data-state and data-slot. CX Codex +1 ★ 141repo stars as-child as-child is a Claude Code rule for merging a component’s props and handlers into a custom child without an extra DOM wrapper. It applies to composable React triggers. CX Codex +1 ★ 141repo stars documentation documentation is a Claude Code rule that standardizes UI component documentation. It enforces consistent sections for props, runnable examples, and accessibility guidelines. CX Codex +1 ★ 141repo stars state state is a Claude Code rule for controlled and uncontrolled React component state. It applies while designing component APIs and state props. CX Codex +1 ★ 141repo stars accessibility accessibility is a Claude Code rule that enforces accessible frontend patterns. It triggers when generating UI components, dialogs, and navigation menus. CX Codex +1 ★ 141repo stars

Project sponsors

Companies that keep this analytics open