redpanda-data Setup Registry Workflow
Hooks
- PostToolUse (
ui-registry-warn.sh): warn once/session when edit UI component dirs | prompt upstream PR - Stop (
registry-check.sh): block if redpanda-ui modified without updateregistry.json+ add changeset
Component Taxonomy (Atomic Design)
Classify every registry component one level. Drive test depth.
| Level | useState | Registry imports | Custom kbd handlers | Portal | Test count |
|---|---|---|---|---|---|
| Atom | 0-1 | 0 | 0 | No | 3-4 |
| Molecule | 2 | 1-2 | 1-10 lines | Maybe | 5-8 |
| Organism | 3+ | 3+ | 10+ lines | Often | 8-15 |
Tiebreaker: highest-scoring signal win. Radix-provided kbd nav no count.
Atom: Single-responsibility primitives | one semantic HTML element/Radix primitive | zero or one controlled/uncontrolled toggle. Examples: Button, Badge, Input, Label, Separator, Spinner, Skeleton, Checkbox, Switch
Molecule: Combine 2-3 atoms | limited local state (open/closed, selected index) | simple portals. Examples: CopyButton, InputGroup, ButtonGroup, Field, Accordion, Breadcrumb, Card, Tabs
Organism: Multiple molecules+atoms | significant state (3+ vars or useReducer) | custom kbd nav | portal rendering. Examples: Combobox, MultiSelect, DataTable, Dialog, DropdownMenu, Sheet, Sidebar, AutoForm
Component evolve between levels -> verify heuristics | expand tests new minimum | review FP compliance.
Consumer Drift Analysis
Compare consumer repo components against registry source. Run on upstream sync.
Process
- Discovery -- scan
packages/registry/src/components/| match against consumer dirs - Comparison --
git diff --no-index --ignore-all-spaceper component | skip empty diffs - Filtering -- apply rules below each non-empty diff
- Categorization -- assign one status per component
Filter Rules
| Rule | Detect | Action |
|---|---|---|
| Import noise | Only @/->../ path changes, 'use client' directives, biome comments |
Skip-Import-Only |
| Staleness | Registry changelog newer than consumer file | Skip-Outdated -- consumer sync FROM registry |
| Business logic | String equality (=== 'admin'), feature flags, API endpoints, route logic, analytics, env checks |
Skip-Business-Logic -- never upstream app-specific code |
Business Logic Red Flags
| Pattern | Example |
|---|---|
| String equality checks | title === 'Users' |
| Hard-coded business data | tier === 'enterprise' |
| Feature flags | featureFlagEnabled |
| API endpoints | fetch('/api/console/users') |
| Route-specific logic | pathname.includes('/dashboard') |
| Analytics/tracking | analytics.track(...) |
Safe: prop-based logic (variant === 'destructive', size === 'lg').
Output Statuses
| Status | Meaning |
|---|---|
| Upstream | Real functional diff, safe merge into registry |
| Skip-Import-Only | Only import path/directive noise |
| Skip-Outdated | Registry newer -- consumer pull, not push |
| Skip-Business-Logic | App-specific logic -- re-implement cleanly if needed |
Steps
- Copy
scripts/ui-registry-warn.sh+scripts/registry-check.sh->.claude/hooks/|chmod +x - Configure
.claude/settings.json:- PostToolUse (Edit|Write):
ui-registry-warn.sh - Stop:
registry-check.sh
- PostToolUse (Edit|Write):
Verify
- Both hooks executable
- Edit
components/ui/orredpanda-ui/trigger warning - Modify
redpanda-ui/withoutregistry.jsonupdate -> Stop block - Modify
redpanda-ui/withregistry.jsonbut no changeset -> Stop block