Skip to content

apuya/react-basics-ui / .claude/skills/component

component

Unverified

Builds and audits reusable presentational UI components in Storybook — props in, events out, no fetching, routing, global state, or domain types. Designs minimal prop APIs (controlled/uncontrolled, ref forwarding, native prop passthrough), enumerates visual variants and interaction states, writes stories per variant and per state plus interaction stories with play functions, and audits components for business-logic leaks, API smells, and missing story coverage. Use when authoring a presentational component, organizing Storybook stories, refactoring a prop API, extracting logic out of a UI primitive, or auditing a component library. Triggers on "storybook", "story", "presentational component", "dumb component", "ui component", "reusable component", "component api", "component props", "component variants", "component states", "controlled component", "extract logic", "business logic in component", "ref forwarding", "play function", "interaction story", "component audit".

Component Engineer

Build presentational components that render pixels from props and emit events. Nothing else.

Mode router

ModeUse whenOutput
AuthorA new component is neededFile scaffold, prop API, variant matrix, state plan, story plan
AuditAn existing component or library needs reviewSeverity-ranked findings with file:line
StoriesA component lacks coverageStory file with default + variant matrix + per-state + interaction stories

If the mode is ambiguous, ask.

How components are built in this library

Every component in react-basics-ui follows the same shape. Match it — the generic guidance further down is the why; this is the how, here.

Folder layout

Components live under src/components/<category>/, with forms/ further split into inputs/ selection/ date-time/ advanced/ structure/. A folder holds:

Button/
  Button.tsx          root component — forwardRef + memo
  Button.types.ts     props and unions (the public type surface)
  Button.styles.ts    class-map constants (BASE_CLASSES, SIZE_STYLES, …)
  ButtonBase.tsx      shared internals, when siblings need them
  ButtonGroupContext.ts   context, when a compound part needs it (.ts, no JSX)
  Button.stories.tsx  CSF3 stories
  Button.test.tsx     behaviour tests (see /test for the suffix conventions)
  index.ts            the public barrel for this folder

Then export the folder from the category barrel (src/components/forms/index.ts), which the root src/index.ts re-exports. Everything ships from the package root.

Building blocks to reach for first

NeedUseWhere
Merge class stringscn()@/lib/cn
Compound-component contextcreateComponentContext()@/lib/createComponentContext
Controlled/uncontrolled valueuseControlledState@/hooks
Merge a forwarded ref with a local oneuseMergedRefs@/hooks
Stable form/aria idsgenerateFormId@/lib/generateFormId
Focus ring, disabled, transition classesFOCUS_RING, DISABLED_CLASSES, TRANSITION_COLORS@/components/shared/styles
Shared prop contractsComponentSize, GranularSize, OverlaySize, StatusVariant, AlertVariant, SelectOption@/components/shared/types

Six Base* primitives already carry the hard parts — compose, don't re-implement: BaseInputField (input chrome, tone, slots), BaseSelectionControl (checkbox/radio/switch mechanics), BaseOverlayDialog (portal, focus trap, scroll lock, escape), BaseCardContainer, BaseText, BaseAlertBox.

Size and tone scales — use the shared unions

This library does not use "sm" | "md" | "lg" for component sizes. Import the canonical scale instead of inventing one:

import type { ComponentSize } from '@/components/shared/types/size';
// ComponentSize  = 'small' | 'default' | 'large'   ← form controls, buttons, badges
// GranularSize   = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'  ← icons, avatars, spinners
// OverlaySize    = 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'full' ← modals, drawers

Composition patterns in use

  • forwardRef + memo on essentially every component (143 and 154 files respectively).
  • Compound components via Object.assign (28 components): export const Card = Object.assign(CardRoot, { Header, Content, Footer }).
  • Context via createComponentContext (26 components) rather than hand-rolled createContext + null checks.

Story titles

meta.title is '<Category>/<Component>', matching the folder category: Forms/, Data Display/, Layout/, Overlays/, Navigation/, Feedback/, Typography/, Utility/, Theme/. Nested form folders still title as Forms/X. Keep the title in step with the folder — a drifting title makes the Storybook sidebar disagree with the source tree.

The contract

A presentational component must:

  • Take props and render. Emit events for state changes the parent owns.
  • Be deterministic — same props → same output.
  • Reference named visual tokens, not raw values.
  • Meet a keyboard-and-screen-reader baseline.
  • Render correctly without context providers it does not itself supply.

It must not:

  • Fetch, mutate, subscribe, or poll.
  • Read from a router, store, query client, or auth context.
  • Import domain types or models. Nothing in src/components may know about a consuming application.
  • Hold business rules — it does not know why it is being used.
  • Read environment, time, or random sources unless an explicit prop opts in.

Component API design

Apply each rule when shaping the public API.

RuleReason
Prefer children or named slots over items arraysComposition keeps the API small as needs grow
Pick controlled or uncontrolled; if both, pair value + defaultValue (and onChange)Mixed conventions cause double-source-of-truth bugs
Variants are discriminated unions, not parallel booleanstone="danger" beats isDanger + isWarning that can collide
Sizes and tones are enums from shared/types, not numbers or ad-hoc stringsNumbers leak implementation detail; ad-hoc scales fragment the library
Forward refs on inputs, buttons, and anything a parent may focus, scroll to, or measureRef access is a public contract
Spread remaining native HTML props through to the underlying elementConsumers need aria-*, data-*, id, onBlur, etc. without re-declaring each
Default to required props; opt into optional only when there is a real default"Optional with no default" is a hidden invariant
Cap props at ~12; past that, decompose into sub-componentsA swollen API signals a component doing two jobs

Sub-components vs monolithic

Expose sub-parts (Dialog.Header, Dialog.Footer) when consumers legitimately rearrange the parts. Otherwise keep a single closed surface — sub-components are public API and cost more to evolve.

State coverage

Every interactive component addresses each applicable state. Mark N/A explicitly.

StateQuestion
DefaultResting state with normal props?
HoverCursor over (or none, for touch-only)?
Focus-visibleKeyboard focus ring?
Active / pressedMid-click / mid-touch?
DisabledAffordance shows why unavailable?
LoadingAsync action in flight — what is reversible, what is not?
ErrorValidation or async failure — message location, role="alert" semantics?
SuccessPost-action confirmation?
EmptyNo data / placeholder content?
Read-onlySame shape, no edit affordance, not styled as broken?
IndeterminateTri-state controls (checkbox, progress)?
SelectedItem is part of a selection set?

Style discipline

Components must not contain raw hex, rgb, hsl, px values, font families, or magic durations. Reference named tokens. If a needed token does not exist, propose a name and surface it as an Open Question — do not hardcode the value and move on.

Accessibility baseline

  • Correct semantic element first; ARIA only to fill gaps the element cannot.
  • Role, accessible name, and value verifiable from the rendered DOM.
  • Keyboard reachable; Tab order matches visual order; focus-visible ring is a token.
  • Hit target ≥ 44×44 logical pixels for primary interactive elements.
  • No information by color alone — pair with icon, text, or shape.
  • Honor reduced-motion: non-essential motion is suppressed, not just slowed.
  • Status changes from async actions announce via live region or moved focus.

Storybook stories

One story file per component

Co-locate the story file beside the component. meta.title is '<Category>/<Component>' matching the folder category (e.g. Forms/Button, Data Display/Table).

What to write

Story typeWhenNotes
DefaultAlwaysCanonical use with realistic args
Variants matrixPer variant axis (size, tone, density)One story per axis, or a single story rendering the matrix
StateOne per state from the coverage tableStory name = state name
InteractionOne per behavior (open, submit, navigate keys)Use play with userEvent + expect
Edge contentLong strings, RTL, narrow widths, dense dataCatches layout fragility

Story shape

  • args define defaults users tweak via controls.
  • argTypes constrain controls — disable controls for props that should not be tweaked.
  • parameters.a11y enables the a11y addon and turns rules on for the component's pattern.
  • parameters.docs.description.story gives one-sentence intent per story.
  • Mock everything the component would not have in production — but if the component needs mocks to render, that is a business-logic leak. Fix the component, not the story.

What does not belong in stories

  • Real network calls. Real router. Real auth.
  • Application-specific theme wrappers — register the theme in .storybook/preview.ts once.
  • Snapshot tests masquerading as stories — stories are documentation + interactive playground; assertions live in play or sibling test files.

Audit dimensions

Run in order. Each finding: location, observation, impact, suggestion.

1. Business-logic leaks

Search the component file for imports and calls that signal non-presentational behavior:

grep -nE "useQuery|useMutation|useSwr|useRouter|useNavigate|useStore|useSelector|useDispatch|fetch\(|axios|/api/|features/" <component>

Each hit moves out. In a library there is no container layer to hide it in — either lift it to a prop/callback the consumer supplies, or extract it into a co-located hook that takes plain arguments.

2. State coverage gaps

For each component, confirm a story exists per applicable state. Missing states are findings.

3. Token leaks

grep -nE "#[0-9a-fA-F]{3,8}\b|rgb\(|hsl\(" <component>
grep -nE "(padding|margin|gap|font-size|line-height|border-radius)\s*:\s*[0-9]" <component>

Each hit: replace with a token, or — if no token exists — propose one.

4. Prop API smells

SmellFix
Parallel booleans that can collide (isPrimary, isDanger, isGhost)Single discriminated union prop
> 12 propsDecompose into sub-components or compose primitives
Optional props with no defined defaultMake required or document the default
Same concept named differently across siblings (open vs isOpen vs visible)Pick one and align the library
Props that take JSX and objects for the same slotPick one shape per slot

5. Reachability

  • Native HTML props pass through? (Ref a small test: does aria-label, data-*, id, onBlur reach the underlying element?)
  • Refs forward? (Try wrapping in a focus-management helper.)

Severity

  • Critical — component cannot be reused (business-logic import, broken keyboard path, no focus ring, missing role).
  • High — state gap a real user hits; visible token drift; API collision.
  • Medium — polish gap, naming inconsistency, missing edge-content story.
  • Low — taste call.

Author workflow

  1. Justify existence. Why does no existing primitive (or composition of primitives) satisfy this?
  2. Define the API. Props table with types, defaults, and notes. Events with payloads. Slots. Refs.
  3. Enumerate variants. Size × tone × density (whatever axes apply).
  4. Cover states. Walk the State Coverage table; mark each applicable or N/A.
  5. A11y contract. Role, keyboard map, focus behavior, announcements.
  6. Tokens. Name every visual token the component consumes; flag any that need to be added.
  7. Story plan. Default, variants matrix, one story per state, interaction stories per behavior, edge-content story.
  8. Open questions. Tag [blocker], [clarify], [nice-to-have].
  9. Definition of Done. Label the spec Ready / Iterate / Blocked.

Definition of Done

Apply at the end of every mode.

- 0 business-logic imports in the component file
- 0 raw hex / rgb / hsl / px values
- 1 story per applicable state + 1 per variant axis
- ≥ 1 interaction story per public behavior
- A11y addon clean on every story (or known violation explicitly waived with rationale)
- Ref forwarded; native props spread through
- Public API typed and exported; defaults documented

If any item fails, label Iterate and list the gap. If a blocker is unresolved, label Blocked.

Output templates

Component spec

# Component: <Name>

## Why this exists
<Reuse walk-through — what was tried, why it didn't fit>

## API
| Prop | Type | Default | Notes |
|------|------|---------|-------|
| ... | ... | ... | ... |

Events: <list with payloads>
Slots: <list>
Ref: <forwarded to which element>

## Variants
- size: sm | md | lg
- tone: neutral | success | danger | ...
- density: comfortable | compact

## States
<one row per applicable state with visual + behavior + a11y note>

## A11y contract
- Role: ...
- Keyboard: ...
- Focus: ...
- Announcements: ...

## Tokens consumed
- color: ...
- spacing: ...
- typography: ...
- radius / shadow / motion: ...

## Story plan
- Default
- Variants matrix: <axes>
- States: <list>
- Interactions: <list with what each play() asserts>
- Edge content: <list>

## Open questions
1. [blocker] ...
2. [clarify] ...

## Status
**[Ready / Iterate / Blocked]**

Audit report

# Component Audit: <name or directory>
> Files examined: <clickable paths>

## Findings

### <Dimension>
**[Severity] — <title>**
- Location: file:line
- Observation: <what is there>
- Impact: <what a consumer or end user notices>
- Suggestion: <concrete change>

[repeat per finding, grouped by dimension]

## Summary
| Severity | Count |
|----------|-------|
| Critical | N |
| High     | N |
| Medium   | N |
| Low      | N |

## Status
**[Ready / Iterate / Blocked]**
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 464kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 464kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 464kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 192kUpdated Claude CodeCodexVerifiedInstall