ui-component-patterns（ui 组件模式）

UI Component Patterns

Use this skill when the job is to classify the reusable component problem, choose one primary component packet, and leave behind a short component-architecture brief instead of a giant React-pattern dump.

The job is not to catalog every possible component pattern. The job is to:

1. identify the reusable component pressure first,
2. choose one bounded packet,
3. keep shared-vs-local and parent-vs-component ownership visible,
4. separate alternate-root composition from broader system or accessibility work,
5. route neighboring frontend concerns honestly.

Read these support docs first:

• references/intake-packets-and-route-outs.md
• references/component-api-checklist.md
• references/handoff-boundaries.md

When to use this skill

• A team has too many similar buttons, cards, dialogs, field wrappers, or nav patterns and needs one shared primitive or component-family boundary.
• A request mixes variants, slots, controlled-vs-uncontrolled behavior, wrappers, and docs expectations and needs routing before implementation.
• You need to decide whether something should stay product-local, become a shared primitive, or split into primitive plus wrapper.
• A component API is growing escape hatches and someone needs to shrink it into one honest packet.
• The tricky part is alternate-root composition (button vs a/router Link, slotted child, custom wrapper) rather than pure styling.
• Storybook/examples exist, but the docs/verification packet for states, usage rules, or edge cases is still unclear.

When not to use this skill

• The main task is token governance, visual-language rules, primitive naming policy, or cross-product system direction → design-system
• The main task is keyboard/focus behavior, semantics, labels, announcements, contrast, or manual accessibility remediation → web-accessibility
• The main task is viewport/container adaptation, breakpoint strategy, reflow, or responsive media → responsive-design
• The main task is broader app/workflow state ownership, server/client boundaries, or cross-screen state coordination → state-management
• The main task is rerender churn, hydration, route performance, or bundle/runtime behavior → react-best-practices
• The reusable component boundary is already settled and the real job is just implementing it; in that case implement directly instead of reopening the architecture decision

Instructions

Step 1: Frame the reusable component job before naming props

Capture the minimum intake packet first.

component_intake:
  surface: button-action | form-field | dialog-overlay | nav-menu | card-list-item | table-toolbar | mixed | unknown
  workflow_type: new-primitive | duplicate-cleanup | api-review | wrapper-split | docs-verification | unknown
  primary_packet: primitive-boundary | slot-anatomy | controlled-ownership | alternate-root-composition | docs-verification | mixed | unknown
  ownership_pressure: shared-vs-local | parent-state | wrapper-proliferation | type-safety | docs-drift | mixed | unknown
  signal_source: repeated-components | bug-report | code-review | storybook-gap | design-review | migration | mixed | unknown
  confidence: high | medium | low

Rule: do not start with “add a prop.” First label the reusable component pressure.

Step 2: Choose exactly one primary component packet

Use the router in references/intake-packets-and-route-outs.md.

Primary packets:

1. primitive-boundary
2. slot-anatomy
3. controlled-ownership
4. alternate-root-composition
5. docs-verification

Pick the packet that resolves the current decision. List anything else as follow-up, not as equal co-owners.

Step 3: Keep the invariants visible

These rules survive every serious answer:

• shared components should solve repeated work, not invent a local framework for one screen
• product-specific copy, analytics, workflow rules, and layout quirks usually belong in wrappers, not the primitive
• variants should express stable meaning (tone, size, density, state) rather than one-off screen exceptions
• slots/subcomponents are for structured flexibility, not for hiding a confused API
• if both controlled and uncontrolled behavior are offered, the contract must be explicit and coherent
• alternate-root composition changes semantics and accessibility responsibility; keep that visible
• Storybook/examples are evidence surfaces, not proof that the component boundary is healthy

Step 4: Build the component packet

Return this structure:

# Component Architecture Packet

## Scope
- Surface:
- Workflow type:
- Primary packet:
- Confidence: high | medium | low

## Current signal
- Main symptom:
- Ownership pressure:
- What is already known:
- What still needs direct verification:

## Recommended first slice
1. ...
2. ...
3. ...

## Component decisions
- Shared vs local:
- Primitive / wrapper split:
- Variants or slots:
- Controlled vs uncontrolled:
- Alternate-root or wrapper rules:

## Docs and verification
- Stories/examples required:
- State / variant matrix:
- Accessibility follow-up:
- Responsive follow-up:

## Ownership and route-outs
- Primary owner:
- Adjacent skills / teams:

Step 5: Use the packet, not a giant pattern gallery

Pull the packet from references/intake-packets-and-route-outs.md.

Packet rules:

• primitive-boundary → decide shared vs local scope, primitive vs wrapper split, and what absolutely stays outside the shared API
• slot-anatomy → define subcomponents/slots, variant boundaries, composition rules, and anatomy expectations for reusable structure
• controlled-ownership → decide whether parent state, workflow state, or component-local defaults own the lifecycle
• alternate-root-composition → handle asChild / component / wrapper-root behavior, prop spreading, refs, and semantic constraints when the primitive must compose onto another element
• docs-verification → define Storybook/examples, state matrix, anti-usage notes, and the smallest credible verification surface for the component family

Step 6: Keep mechanism choice separate from ownership choice

Use this split in serious answers:

• Mechanism — variants, slots, subcomponents, controlled props, polymorphic root, wrapper split, docs matrix
• Ownership — ui-component-patterns, design-system, web-accessibility, responsive-design, state-management, or react-best-practices

If the request starts from screenshots, Storybook drift, or a code diff, say explicitly that those artifacts are the signal, not the finished component decision.

Step 7: Route adjacent work explicitly

Use these route-outs when the problem crosses boundaries:

• token governance, primitive naming, contribution policy, or cross-product component standards → design-system
• keyboard/focus remediation, label/announcement issues, ARIA, contrast, reduced motion, or manual a11y verification → web-accessibility
• viewport/container adaptation, reflow, responsive media, or dense-data layout strategy → responsive-design
• app/workflow state ownership, server/client state boundaries, URL/form/global-store decisions → state-management
• rerender churn, hydration, bundle/runtime performance, or route-level performance behavior → react-best-practices

When mixed requests appear, keep ui-component-patterns on the reusable component packet and name the routed follow-up explicitly.

Step 8: Prefer honest boundaries over over-generalized props

When a component keeps accumulating booleans, escape hatches, or product-specific rules:

1. check whether the API should split into primitive plus wrapper,
2. collapse accidental variants into a smaller semantic set,
3. move layout- or workflow-specific behavior out of the primitive,
4. route systemic or remediation-heavy follow-ups outward instead of widening the skill.

Examples

Example 1: Button family drift

Input: “We have five button implementations and people keep adding one-off props.”

Good output direction:

• choose primitive-boundary as the primary packet
• keep one shared action primitive plus a narrower icon/button-group wrapper if needed
• collapse random booleans into a small variant/tone/size set
• keep analytics and screen-specific layout wrappers outside the primitive
• route token naming to design-system

Example 2: Modal state confusion

Input: “Should our modal manage its own state or always be controlled by the parent workflow?”

Good output direction:

• choose controlled-ownership as the primary packet
• classify the modal as a reusable composite pattern
• recommend controlled ownership when workflow state, routing, or async submit logic matters
• allow an uncontrolled convenience path only if the contract remains explicit
• route keyboard/focus remediation details to web-accessibility

Example 3: Link-button composition

Input: “Our design-system button sometimes needs to render as a router link. How should we support that without breaking types or semantics?”

Good output direction:

• choose alternate-root-composition as the primary packet
• make prop spreading, ref forwarding, and semantic/accessibility constraints explicit
• keep route-level navigation policy or token governance outside the primitive decision
• leave behind a bounded wrapper/root contract instead of a vague “just add an as prop” answer

Example 4: Storybook drift

Input: “The component exists, but teams keep using it differently and Storybook is missing the edge cases.”

Good output direction:

• choose docs-verification as the primary packet
• define the minimum state/variant matrix and example set
• add anti-usage notes and wrapper expectations
• route accessibility-only or responsive-only follow-up packets outward

Best practices

1. Prefer the smallest reusable primitive that removes repeated work without inventing a local framework.
2. Keep packet choice explicit; one component decision should not silently absorb governance, remediation, responsive strategy, and runtime tuning.
3. Treat slots and subcomponents as structured API tools, not as a way to dodge ownership decisions.
4. Make controlled vs uncontrolled behavior an explicit contract, not an accidental half-state hybrid.
5. Keep alternate-root composition honest about refs, prop spreading, and semantics.
6. Use Storybook/examples as part of the evidence surface, but still write down the docs/verification packet.
7. Revisit the abstraction when consumers repeatedly need escape hatches or app-specific wrappers to use it.

References

• Radix UI — Composition
• Material UI — Composition
• Storybook Docs
• shadcn/ui Docs