barefootjs

Component Development Skill

Build UI components using @barefootjs/cli for component discovery, scaffolding, testing, and signal inspection.

Setup

Ensure the CLI is available. If the project doesn't already have it installed:

npx @barefootjs/cli --help

Or install it as a dev dependency:

npm install -D @barefootjs/cli
# or
bun add -d @barefootjs/cli

Once installed, use npx bf (or bunx bf) to run commands.

Workflow

1. npx bf search <query> — Find components and docs by name/category/tags
2. npx bf docs <component> — Get props, examples, accessibility info
3. npx bf guide <topic> — Read framework docs (signals, compiler constraints, etc.)
4. npx bf gen component <name> <comp...> — Generate skeleton + basic IR test
5. Implement the component
6. Run tests — Verify compilation
7. npx bf gen test <name> — Regenerate richer IR test
8. Run tests — Final verification
9. Create previews and run npx bf preview <name> — Visual preview in browser
10. Ask the user to check the browser for visual/interaction verification

Signal Inspection & Debugging

Use these commands to understand and debug a component's reactive structure without running any code. All analysis is static (from IR).

npx bf debug graph <component>

Show the signal dependency graph for a component. Use this before modifying a stateful component to understand its reactive structure: which signals exist, what memos depend on them, and which DOM nodes are bound.

• Add --json for machine-readable output.
• Example: npx bf debug graph combobox

npx bf debug trace <component> <signal|memo>

Reverse-lookup: trace the full propagation path from a signal/memo to every DOM binding it affects. Use this to answer "why does this DOM node update?" or to verify that a signal change reaches the expected targets.

• If the signal name is wrong, the CLI lists available signals/memos.
• Add --json for machine-readable output.
• Example: npx bf debug trace combobox open

npx bf debug signals <component>

Show a signal initialization trace: every signal, its initial value, and its effect bindings. Useful for verifying that signals are wired correctly in a newly written or modified component.

• Add --json for machine-readable output.
• Example: npx bf debug signals select

npx bf debug fallbacks <component>

Surface fallback-wrapped expressions emitted by Solid-style wrap-by-default. Use this to find candidates for createMemo refactor — places where the compiler couldn't statically prove reactivity and fell back to wrapping.

• Add --json for machine-readable output.
• Example: npx bf debug fallbacks combobox

When to use inspection

• Before editing a stateful component — run debug graph to map the reactive graph.
• Unexpected re-renders or missing updates — run debug trace to trace propagation.
• After implementing a new component — run debug signals to verify signal wiring.
• Reviewing a PR — run debug graph --json to diff the dependency graph before/after.

Previews

Previews provide visual preview with full hydration support.

File location

ui/components/ui/__previews__/<name>.previews.tsx

Format

Each export function becomes a separate preview. PascalCase names are auto-converted to display titles (e.g., WithLabel → "With Label").

"use client"

import { ComponentName } from '../component-name'

/** Default usage */
export function Default() {
  return <ComponentName />
}

/** Show a specific variant or state */
export function WithProps() {
  return <ComponentName variant="outline" disabled />
}

Guidelines

• Always include a Default preview showing basic usage.
• Add previews for key variants, states, and compositions (e.g., WithLabel, Disabled, PreFilled).
• Previews that use signals need "use client" at the top.
• Import components via relative path from ../ (e.g., import { Button } from '../button').
• After creating previews, run npx bf preview <name> and ask the user to verify in the browser.

Rules

• Use bf search and bf docs for component discovery. Do not read source files to learn component APIs.
• Use bf guide error-codes to check compiler constraints (BF001, BF021, etc.) before writing components.
• New components go in ui/components/ui/<name>.tsx.
• IR tests go in ui/components/ui/__tests__/<name>.test.ts.
• Stateful components (using signals) must have "use client" as the first line.
• Stateful components must use props.xxx (not destructuring) to maintain reactivity.
• Use createSignal, createMemo, createEffect from @barefootjs/client (SolidJS-style, not React hooks).
• Use for attribute on <Label> (not htmlFor).
• Event handlers have typed e.target — write onInput={e => setValue(e.target.value)} directly. Do not cast with as HTMLInputElement.
• Use className in JSX (not class). class is a JS reserved keyword.
• Signal getters must be called in JSX: value={name()} (not value={name}).