Storybook Tutorial

How to use the visual UI catalog for ShipRules AI — with real examples from the app.

What Is Storybook?

Storybook is a visual catalog of every screen and component in your app. Each item in the catalog is called a story. Stories render with mock data — no database, no API, no Shopify login needed.

The Interface

When you open Storybook, you see three areas:

Sidebar — lists all stories, grouped by Pages and Components. Click to preview.
Canvas — renders the selected story with Polaris Web Components.
Toolbar — viewport switcher, zoom, accessibility checker.

Here's what it actually looks like:

The Storybook home screen. Components group is expanded; Pages group is collapsed.

Page Stories — Full Screens

Page stories show complete app screens. These are what the merchant sees inside the Shopify admin.

Dashboard

The main screen: KPI cards (Zones, Methods, Rules, Groups, Blended Rates, Plan), the NLP prompt box, recent rules table, and plan usage metrics.

Dashboard with mock data — 3 zones, 5 methods, 12 rules, plan usage meters.

Settings

Shop configuration: test mode toggle, weight unit, currency, import/export, API keys, and shop info.

Settings page — Polaris form controls (select, checkbox, text field, button).

Rate Simulation

The test rates page: destination fields, cart items, and rate results with rule traces.

Rate simulation — 2-column destination form, cart items, and two rate result cards.

Component Stories — Building Blocks

Component stories show individual UI elements in isolation. This is where you catch visual inconsistencies before they reach a full page.

NLP Confirmation Card

What the merchant sees after typing a natural language prompt. Shows the AI's interpretation, proposed operations, and Confirm/Edit/Cancel actions.

NLP confirmation — 95% confidence, one proposed rule, with Confirm/Edit/Cancel/Queue buttons.

Banners

All four Polaris banner tones: success, warning, critical, and info. These appear as toast notifications and inline alerts throughout the app.

Banner component in all four tones — used for feedback after every action.

Empty States

What pages look like before the merchant has created any data. Each empty state has a specific message and a suggested first action.

Product Groups empty state — explains what groups are and suggests a prompt to create one.

Usage Meter

Plan usage progress bars at three levels: healthy (green), warning (amber), and critical (red).

Usage meters — Methods at 50% (green), Groups at 67% (amber), Prompts at 96% (red).

How Stories Work

A story is a JavaScript function that returns HTML. That's it.

// A simple component story
export const KPICard = {
  render: () => `
    <s-section>
      <s-stack direction="block" gap="100">
        <s-text tone="subdued">Shipping Methods</s-text>
        <s-text type="strong">5</s-text>
      </s-stack>
    </s-section>
  `,
};

The <s-section> and <s-text> tags are Polaris Web Components — Shopify's UI library. Storybook loads Polaris from the CDN automatically, so they render as styled Shopify UI.

File Structure

Workflow

Quick Reference