Discover reusable components

Component Inventory & Pattern Discovery

Before creating a new design-system primitive or adding another variant prop, map what already exists across the codebase. A design system succeeds by reducing arbitrary UI drift while respecting genuine domain-specific needs.

1. Auditing Existing UI & Component Usage

When inspecting a feature area or planning a shared component change:

1. Catalog existing primitives: locate the project's shared UI directories (components/ui, packages/ui, design-system, shared stylesheets, token files and workbench stories).
2. Trace real call sites: search where buttons, inputs, modals, badges, tables, cards and layout primitives are rendered across screens, noting:
   • Which variants, sizes and states are actually used in production.
   • Where consumers pass ad-hoc class overrides (className, :class, [ngClass], inline style) or wrapper <div> hacks to work around missing or rigid component behavior.
   • Where multiple near-identical one-off components exist for the same purpose (e.g., three different modal wrappers or four badge implementations).

2. Shared System Primitive vs. Product-Specific Component

Follow Alla Kholmatova's and Nathan Curtis's criteria to decide what belongs in the shared system:

• Promote to the shared design system when:
  • The pattern recurs across three or more independent screens or workflows with the same semantic purpose and interaction contract (e.g., Button, TextField, Select, Dialog, Tabs, Toast, Badge, DataTable, EmptyState).
  • Centralizing its states (hover, :focus-visible, active, disabled, loading, invalid), keyboard handling and token usage eliminates repeated bugs.
• Keep in the feature/domain layer when:
  • Two components only look superficially similar today (e.g., a PricingTierCard and a UserProfileSummaryCard) but represent distinct domain concepts that evolve independently.
  • Extracting them into a single component would require domain-specific mode flags (isPricing, showBillingBadge, forSidebar).
  • Instead, build the domain component by composing shared design-system primitives (Card, Stack, Badge, Button) and semantic tokens.

3. Diagnosing Design–Code Drift

Compare the visual direction defined by the UI/UX designer against the running code:

• Token drift: hardcoded hex/RGB colors, arbitrary pixel spacing (margin: 13px), ad-hoc font sizes (15px), inconsistent border radii or raw box-shadows bypassing semantic tokens.
• State gaps: components built only for the happy path with missing :focus-visible, :hover, :active, disabled, readonly, loading/pending, error/invalid, empty or long-text overflow states.
• Content fragility: layouts that break when translated into longer languages (such as German or Hungarian), when user-generated names wrap across lines, or when zoomed to 200%/400%.