Categorization

Components can be organized using status, kind, tags, and hierarchy. These properties enable filtering, searching, and logical grouping in the catalogue.

Status

Indicates the component’s maturity level.

Status	Description	Use When
`stable`	Production-ready	API is finalized, fully tested
`beta`	Nearly ready	API may change, needs feedback
`deprecated`	Being phased out	Replacement available, avoid for new code

{
  "id": "button",
  "status": "stable"
}

Visual Indicators

Stable: Green badge
Beta: Yellow badge
Deprecated: Red badge

Kind

Defines the component’s role in the hierarchy.

Kind	Description	Landing Page
`standalone`	Independent component	✅ Shown
`subcomponent`	Part of a parent component	❌ Hidden (shown under parent)
`feature`	Feature enhancement	✅ Shown

{
  "id": "table-row",
  "kind": "subcomponent",
  "parentId": "data-table"
}

Standalone Components

Independent components that can be used on their own.

{
  "id": "button",
  "kind": "standalone"
}

Subcomponents

Components that are part of a larger component. Must specify parentId.

{
  "id": "tab-panel",
  "kind": "subcomponent",
  "parentId": "tabs"
}

Parent component can list its subcomponents:

{
  "id": "tabs",
  "kind": "standalone",
  "subcomponents": ["tab-panel", "tab-list", "tab-trigger"]
}

Feature Components

Enhancements or utilities that augment other components.

{
  "id": "tooltip",
  "kind": "feature"
}

Category	Examples
Function	`form`, `navigation`, `layout`, `display`
Interaction	`interactive`, `static`, `animated`
Content	`text`, `media`, `data`, `icon`
Domain	`auth`, `commerce`, `social`

Component Hierarchy

Parent-Child Relationships

Define relationships using parentId and subcomponents:

Parent (data-table/component.json):

{
  "id": "data-table",
  "kind": "standalone",
  "subcomponents": ["table-header", "table-row", "table-cell"]
}

Child (table-row/component.json):

{
  "id": "table-row",
  "kind": "subcomponent",
  "parentId": "data-table"
}

Hierarchy Display

Landing page shows only standalone and feature components
Subcomponents appear on their parent’s detail page
Breadcrumbs show parent > child navigation

Filtering in the Catalogue

Landing Page Filters

Users can filter by:

Status: Checkboxes for stable/beta/deprecated
Kind: Checkboxes for standalone/feature
Search: Text search across id, title, description, tags

URL Parameters

Filters can be set via URL:

/#/?status=stable&kind=standalone&q=button

Organization Strategies

By Domain

registry/components/
├── auth/
│   ├── login-form/
│   └── signup-form/
├── commerce/
│   ├── product-card/
│   └── cart-item/
└── common/
    ├── button/
    └── input/

Use tags to group: ["auth", "form"]

By Atomic Design

// Atoms
{ "id": "button", "tags": ["atom"] }
{ "id": "icon", "tags": ["atom"] }

// Molecules
{ "id": "search-input", "tags": ["molecule"] }
{ "id": "card", "tags": ["molecule"] }

// Organisms
{ "id": "header", "tags": ["organism"] }
{ "id": "product-grid", "tags": ["organism"] }

By Feature Area

{ "id": "date-picker", "tags": ["forms", "input", "date"] }
{ "id": "data-table", "tags": ["data", "display", "table"] }
{ "id": "modal", "tags": ["overlay", "dialog"] }

Best Practices

Consistent Status Usage
- New components start as beta
- Promote to stable after API stabilizes
- Mark deprecated when replacement exists
Clear Hierarchy
- Use subcomponent for tightly coupled children
- Use feature for optional enhancements
- Keep hierarchy shallow (max 2 levels)
Meaningful Tags
- Use lowercase, singular words
- Limit to 3-5 tags per component
- Establish a tag vocabulary for your team
Validation
- Run catalogue validate to check references
- Ensures parentId points to existing component
- Verifies subcomponents array matches actual components

Component Catalogue