Skip to main content
rule CX Codex

definitions — Claude Code rule: UI terms and setup

definitions is a Claude Code rule that classifies UI artifacts and keeps names consistent across primitives, components, blocks, templates, and patterns.

Apache-2.0 ★ 141 updated 2026-11-17

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

What definitions does

The definitions rule separates UI artifacts by role. A primitive supplies behavior and accessibility without styling; a component adds visual treatment; a pattern documents a recurring UI solution; and a block combines pieces for a concrete interface case. A page is a single-route view, a template groups multiple pages with routing and providers, while a utility holds non-visual logic.

The rule includes a decision flow and React examples covering Props API, children or slots, render props, controlled and uncontrolled state, provider/context, portals, headless behavior, variants, and design tokens. It also flags a common naming error: a dialog with visual classes is a component rather than a primitive. For Claude Code, place the file at .claude/rules/definitions.md.

What it helps with

  • tell a primitive from a styled component
  • classify a UI artifact by its role
  • separate a block from a page or template
  • label non-visual logic as a utility

Example prompts for the agent

  • Classify this UI element as a primitive, component, block, page, or template.
  • Check whether the styled dialog in Dialog.tsx has the right category.
  • Identify which parts of this interface are patterns and utilities.

How to install definitions

Manually: put the files in place

.claude/rules/definitions.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 definitions

How do I install definitions in Claude Code?

Create the rule file at .claude/rules/definitions.md and place the definitions content there.

What does definitions do?

It defines terms for UI artifacts and separates primitives, components, patterns, blocks, pages, templates, and utilities by styling, behavior, and composition level.

How is a primitive different from a component in definitions?

A primitive provides behavior and accessibility without visual styling. A component adds styles or composes elements, so a dialog with visual classes belongs to the component category.

Source text

definitions.md · Apache-2.0
---
title: Component Artifact Definitions
impact: MEDIUM
impactDescription: Essential for correct component classification
tags: definitions, primitive, component, block, template, pattern, utility, terminology
---

## Component Artifact Definitions

Precise terminology for classifying and naming UI artifacts.

### Primitive (Unstyled Component)

The **lowest-level building block** providing behavior and accessibility without styling. Completely headless.

```tsx
// Primitive - behavior only, no styling
function DialogPrimitive({ open, onOpenChange, children }) {
  return (
    <Dialog.Root open={open} onOpenChange={onOpenChange}>
      {children}
    </Dialog.Root>
  );
}
```

**Examples:** Radix UI Primitives, React Aria Components, Headless UI

### Component

A **styled, reusable UI unit** that adds visual design to primitives or composes multiple elements.

```tsx
// Component - styled and reusable
function Button({ variant = "primary", size = "md", children, ...props }) {
  return (
    <button
      className={cn("base-button-styles", variants[variant], sizes[size])}
      {...props}
    >
      {children}
    </button>
  );
}
```

**Examples:** shadcn/ui components, Material UI, Ant Design

### Pattern

A **specific composition** solving a UI/UX problem. Documentation-focused, not a reusable component.

**Examples:** Form validation with inline errors, confirming destructive actions, typeahead search

### Block

An **opinionated, production-ready composition** solving a concrete interface use case.

```tsx
// Block - complete, opinionated composition
function PricingTable({ plans, onSelectPlan }) {
  return (
    <div className="pricing-table">
      {plans.map((plan) => (
        <Card key={plan.id}>
          <Card.Header>
            <Card.Title>{plan.name}</Card.Title>
          </Card.Header>
          <Card.Content>
            <div className="price">{plan.price}</div>
          </Card.Content>
          <Card.Footer>
            <Button onClick={() => onSelectPlan(plan.id)}>Select Plan</Button>
          </Card.Footer>
        </Card>
      ))}
    </div>
  );
}
```

**Examples:** Pricing table, auth screens, onboarding stepper, AI chat panel

### Page

A **complete, single-route view** composed of multiple blocks.

```tsx
function LandingPage() {
  return (
    <Layout>
      <HeroBlock />
      <FeaturesBlock />
      <PricingBlock />
      <FooterBlock />
    </Layout>
  );
}
```

### Template

A **multi-page collection** or full-site scaffold bundling pages, routing, layouts, and providers.

**Examples:** SaaS starter, e-commerce template, dashboard starter

### Utility (Non-visual)

A **helper** for developer ergonomics or composition; not rendered UI.

```tsx
function useControllableState({ prop, defaultProp, onChange }) {
  const [state, setState] = useState(defaultProp);
  const value = prop !== undefined ? prop : state;
  const setValue = (newValue) => {
    if (prop === undefined) setState(newValue);
    onChange?.(newValue);
  };
  return [value, setValue];
}
```

**Examples:** React hooks, class utilities, keybinding helpers, focus scopes

### Classification Decision Flow

1. **Behavior/a11y only, no styling?** → **Primitive**
2. **Styled, reusable UI element?** → **Component**
3. **Concrete product use case with opinionated composition?** → **Block**
4. **Multi-page scaffold with routing/providers?** → **Template**
5. **Documentation of recurring solution?** → **Pattern**
6. **Non-visual logic?** → **Utility**

### Common Classification Mistakes

**Incorrect (mislabeling a styled component as a primitive):**

```tsx
// Wrong: This is styled, so it's a Component, not a Primitive
function DialogPrimitive({ open, onOpenChange, children }) {
  return (
    <Dialog.Root open={open} onOpenChange={onOpenChange}>
      <Dialog.Content className="rounded-lg border bg-white p-6 shadow-lg">
        {children}
      </Dialog.Content>
    </Dialog.Root>
  );
}
```

**Correct (proper classification based on styling presence):**

```tsx
// Primitive - behavior only, no styling
function DialogPrimitive({ open, onOpenChange, children }) {
  return (
    <Dialog.Root open={open} onOpenChange={onOpenChange}>
      {children}
    </Dialog.Root>
  );
}

// Component - styled wrapper around primitive
function Dialog({ open, onOpenChange, children }) {
  return (
    <DialogPrimitive open={open} onOpenChange={onOpenChange}>
      <Dialog.Content
        className={cn("rounded-lg border bg-white p-6 shadow-lg")}
      >
        {children}
      </Dialog.Content>
    </DialogPrimitive>
  );
}
```

### Key Vocabulary

- **Props API** - Public configuration surface, typed and documented
- **Children/Slots** - Placeholders for caller-provided structure
- **Render Prop** - Function child delegating rendering
- **Controlled** - Value driven by props (parent is source of truth)
- **Uncontrolled** - Internal state with optional `defaultValue`
- **Provider/Context** - Supplies shared state to subtree
- **Portal** - Rendering outside DOM hierarchy for layering
- **Headless** - Behavior without styling
- **Styled** - Ships with default visual design
- **Variants** - Style/behavior permutations via props
- **Design Tokens** - Named values for theming

© maxtrigify · Apache-2.0 · maxtrigify/Otto

Similar IDE rules

All IDE rules for Frontend and UI →

From the same set18

The whole set →
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 polymorphism polymorphism is a Claude Code rule for React components that keep their styles and behavior across element types. The as prop selects the rendered element. CX Codex +1 ★ 141repo stars styling styling is a Claude Code rule that enforces Tailwind CSS patterns. Guides the agent to combine classes with tailwind-merge, clsx, and CVA. CX Codex +1 ★ 141repo stars components-build components-build is a Claude Code skill for building, reviewing, and refactoring reusable React components with the components.build specification. It activates for work on component APIs, accessibility, styling, and TypeScript props. CX Codex +1 ★ 141repo stars otto-design otto-design is a Claude Code skill that enforces UI mockup creation in Paper before building SwiftUI views. It triggers on redesigns, mockups, or any visual changes to Otto surfaces. CX Codex +1 ★ 141repo stars

Project sponsors

Companies that keep this analytics open