Component Annotations

Mark reusable UI components in your codebase for design system tracking.

Overview #

Component annotations identify the atomic building blocks of your design system—buttons, inputs, cards, avatars, and other reusable elements. While patterns describe high-level UI workflows, components are the pieces that compose them.

Annotation Syntax #

Add component annotations using code comments:

Button.tsx

// uipool-component: button-primary
export function Button({ children, variant = 'primary' }) {
  return <button className={`btn btn-${variant}`}>{children}</button>;
}

The format is:

// uipool-component: component-id

Where to Place Annotations #

Place component annotations in these locations:

Component Definition

Best for tracking the source component file:

Avatar.tsx

// uipool-component: avatar
export function Avatar({ src, size = 'md', fallback }) {
  return (
    <div className={`avatar avatar-${size}`}>
      {src ? <img src={src} alt="" /> : <span>{fallback}</span>}
    </div>
  );
}

Component Usage

Track where components are used throughout your app:

UserCard.tsx

export function UserCard({ user }) {
  return (
    <div className="user-card">
      {/* uipool-component: avatar */}
      <Avatar src={user.avatar} fallback={user.initials} />
      
      {/* uipool-component: text-display */}
      <Text variant="heading">{user.name}</Text>
    </div>
  );
}

Vue Templates

Use HTML comments in Vue templates:

ProfileHeader.vue

<template>
  <div class="profile-header">
    <!-- uipool-component: avatar -->
    <Avatar :src="user.avatar" size="lg" />
    
    <!-- uipool-component: badge -->
    <Badge v-if="user.isPro" variant="success">Pro</Badge>
  </div>
</template>

Naming Conventions #

Use consistent, descriptive component IDs:

✓ Good	✗ Avoid	Why
button-primary	btn1	Be descriptive
text-input	TextInput	Use kebab-case
avatar	user-avatar-component	Keep it concise
modal-dialog	modal_dialog	Prefer hyphens for consistency

Match your component IDs to your design system's component library names for easier cross-referencing.

Annotating Variants #

For components with variants, annotate each variant separately:

Buttons.tsx

// Each variant gets its own annotation

// uipool-component: button-primary
<Button variant="primary">Submit</Button>

// uipool-component: button-secondary  
<Button variant="secondary">Cancel</Button>

// uipool-component: button-ghost
<Button variant="ghost">Learn more</Button>

// uipool-component: button-danger
<Button variant="danger">Delete</Button>

This provides granular tracking of which button variants are used across your codebase.

Adding Metadata #

Include additional metadata with your annotations (coming soon):

DataTable.tsx

// uipool-component: data-table
// @version: 2.0
// @status: stable
// @figma: https://figma.com/file/xxx
export function DataTable({ columns, data }) {
  // ...
}

Extended metadata support is planned for a future release. Currently, only the component ID is parsed.

Components vs Patterns #

Understanding when to use each annotation type:

uipool-component

• Reusable UI elements
• Buttons, inputs, cards
• Part of component library
• Atomic building blocks

uipool-pattern

• UI workflows & experiences
• Login flow, checkout, search
• Composed of components
• Full-page or section-level

Scanner Output #

Component annotations appear in your scan report under the components array:

uipool-report.json

{
  "components": [
    {
      "componentId": "button-primary",
      "count": 47,
      "files": [
        "src/components/Button.tsx",
        "src/pages/Checkout.tsx",
        "src/pages/Settings.tsx"
      ]
    },
    {
      "componentId": "avatar",
      "count": 23,
      "files": [
        "src/components/Avatar.tsx",
        "src/components/UserCard.tsx"
      ]
    }
  ]
}