@openpawlabs/diy-guides-ui

Open-source React UI library for building iFixit-style DIY guides — step-by-step instructions with tools, warnings, and media.

Status

Active development. The core guide component set is implemented, tested, and documented in Storybook (deployed to GitHub Pages on every push to main):

| Component | Purpose | |-----------|---------| | GuideLayout | Responsive page shell: header, intro + tools row, full-width steps | | GuideStepList | Auto-numbered step sequence with a derived progress bar | | GuideStep | A single step — number badge, completion checkbox, media, and bulleted instructions | | MediaFigure | Image/video with percentage-positioned annotation markers | | ToolList | Titled card of required tools and parts | | LinkButton | Download / link button with an optional dropdown of file variants | | Callout | Safety / informational callout (note → danger types) | | DifficultyBadge | Color-coded difficulty pill (easy / moderate / difficult) |

Guide colors (COLORS / GuideColor) link step bullet dots to image annotation markers. Callout types (CalloutType) drive safety and informational tone in Callout boxes.

Tech stack

• React 19 + TypeScript
• HeroUI v3 for accessible UI primitives
• Tailwind CSS v4
• Storybook for component development
• Vite library mode for publishing
• Vitest + React Testing Library

Getting started (development)

Requires pnpm 9+.

pnpm install
pnpm dev        # Storybook at http://localhost:6006
pnpm test       # Run tests
pnpm build      # Build library to dist/

Project structure

src/
  components/     # One folder per component (tsx, stories, tests, index)
  hooks/          # Shared hooks (e.g. useControlledState)
  types/          # Shared design tokens (colors, callout types) and types
  styles/         # Tailwind + HeroUI CSS entry
  index.ts        # Public API exports
.storybook/       # Storybook configuration

See AGENTS.md for contributor and AI agent conventions.

Using in another app

pnpm add @openpawlabs/diy-guides-ui @heroui/react @heroui/styles tailwindcss

Import styles in your app CSS:

@import "tailwindcss";
@import "@heroui/styles";
@import "@openpawlabs/diy-guides-ui/styles";

import "@openpawlabs/diy-guides-ui/styles";
import {
  GuideLayout,
  GuideStepList,
  GuideStep,
  MediaFigure,
  ToolList,
  Callout,
} from "@openpawlabs/diy-guides-ui";

export function BatteryGuide() {
  return (
    <GuideLayout>
      <GuideLayout.Header
        title="Replace a Smartphone Battery"
        difficulty="moderate"
        timeEstimate="20 – 30 minutes"
      />

      <GuideLayout.Intro>
        A worn battery drains fast and can swell. This guide covers a safe swap.
      </GuideLayout.Intro>

      <GuideLayout.Sidebar>
        <ToolList title="Tools">
          <ToolList.Item name="Pro Tech Toolkit" href="#" price="$67.96" />
        </ToolList>
      </GuideLayout.Sidebar>

      <GuideLayout.Content>
        <Callout type="danger" title="Battery safety">
          A punctured lithium battery can catch fire. Work slowly.
        </Callout>
        <GuideStepList>
          <GuideStep title="Open the case">
            <GuideStep.Media>
              <MediaFigure
                src="/step-1.jpg"
                annotations={[{ x: 50, y: 45, color: "ORANGE", label: 1 }]}
              />
            </GuideStep.Media>
            <GuideStep.Bullets>
              <GuideStep.Bullet color="ORANGE">
                Soften the adhesive with even heat before prying.
              </GuideStep.Bullet>
            </GuideStep.Bullets>
          </GuideStep>
        </GuideStepList>
      </GuideLayout.Content>
    </GuideLayout>
  );
}

License

MIT — see LICENSE.