Litho

A modern React component library for building Mantle extensions and web applications. Litho provides a comprehensive set of accessible, themeable, and composable UI components, designed for rapid development and seamless integration with Tailwind CSS and Shopify Polaris icons.

Installation

npm install @heymantle/litho

Note: tailwindcss, react, and react-dom (v18+) are required as peer dependencies.

Usage

1. Import the CSS (required for correct styling):

// index.css paths here may differ depending on your project structure
@source "./node_modules/@heymantle/litho";
@import "./node_modules/@heymantle/litho/index.css";

2. Wrap your app with AppProvider (required for Frame and/or Form usage):

import { AppProvider, Page, Button } from "litho";

function App() {
  return (
    <AppProvider darkModeAvailable darkModeStorageKey="my-app-dark-mode">
      <Page title="Welcome to Litho">
        <Button primary onClick={() => alert("Hello!")}>
          Click me
        </Button>
      </Page>
    </AppProvider>
  );
}

3. Use any component:

import { Banner, Card, ResourceList } from 'litho';

<Banner status="success" title="Success!">
  Your operation was successful.
</Banner>

<Card>
  <ResourceList
    items={[{ id: 1, name: 'Item 1' }]}
    renderItem={item => <div key={item.id}>{item.name}</div>}
  />
</Card>

Components

Litho exports a wide range of components, including:

• Layout: Page, Frame, Layout, Card, Grid, Stack
• Forms: TextField, Select, Checkbox, RadioButton, RangeSlider, ChoiceList, DatePicker, ColorField
• Navigation: Navigation, Tabs, Pagination, TopBar, Pane
• Feedback: Banner, Tip, InlineError, EmptyState, Loading, SkeletonText, FooterHelp
• Actions: Button, ButtonGroup, ActionList, Popover, Modal, ContextualSaveBar
• Data Display: Table, ResourceList, List, Badge, Tag, Thumbnail, Image, Tooltip
• Utilities: useIndexResourceState, useTableScrollState, and more

See the source code for full API documentation and JSDoc usage examples for each component.

Theming & Customization

• Litho is designed to work with Tailwind CSS. You can customize themes and extend styles using your Tailwind config.

// index.css paths here may differ depending on your project structure
@source "./node_modules/@heymantle/litho";
@import "./node_modules/@heymantle/litho/index.css";

Peer Dependencies

• react >= 18
• react-dom >= 18
• tailwindcss >= 4

AI Assistant Integration

Litho includes comprehensive guides for AI coding assistants (Claude, ChatGPT, Cursor, Copilot, etc.) to help generate accurate, consistent UI code:

• AI_COMPONENTS_GUIDE.md - Complete component API reference
• AI_PATTERNS_GUIDE.md - Ready-to-use UI patterns and examples
• AI_INTEGRATION_GUIDE.md - Guidelines for AI code generation
• COMPONENT_QUICK_REFERENCE.md - Fast component lookup
• AI_USAGE_IN_PROJECTS.md - How to use these guides in your projects

Using in Your Projects

After installing Litho, the guides are available in node_modules/@heymantle/litho/. Reference them in your AI prompts:

@node_modules/@heymantle/litho/AI_PATTERNS_GUIDE.md

Build a customer list page with search and filtering using Litho components.

See AI_USAGE_IN_PROJECTS.md for detailed instructions on accessing guides and Storybook examples from projects using Litho as a dependency.

Visual Regression Testing

Litho includes automated visual regression tests using Playwright to catch unintended UI changes.

Running Tests

# Run visual regression tests (uses Docker for CI parity)
npm run test:visual:docker

# Update baseline screenshots (uses Docker for CI parity)
npm run test:visual:docker:update

Note: The Docker commands ensure baselines match CI exactly. Native commands (npm run test:visual) are also available but may produce different results due to font rendering differences between macOS and Linux.

When Baselines Need Updating

Update baselines when you've made intentional visual changes:

• Modified component styles or layout
• Changed default props or variants
• Updated theme colors or typography
• Added new visual states to existing components

Adding New Stories

When you add a new component or story:

1. The visual tests automatically discover all stories from Storybook
2. Run npm run test:visual:update to generate baseline screenshots for new stories
3. Commit the new baseline images in tests/visual/stories.spec.js-snapshots/

Skipped Stories

Some stories are skipped because they contain non-deterministic content:

• Image stories - Use random external images from picsum.photos
• Add problematic stories to SKIP_STORIES in tests/visual/stories.spec.js

CI Integration

Visual tests run automatically on PRs to main. If tests fail:

1. Download the visual-regression-diffs artifact from the workflow
2. Review the diff images to determine if changes are intentional
3. If intentional, use the Update Visual Baselines workflow to regenerate baselines

Generating Baselines from CI

Since macOS and Linux render fonts differently, generate baselines from CI for best results:

1. Go to Actions → Update Visual Baselines → Run workflow
2. The workflow will create a PR with updated baselines
3. Review and merge the PR

License

MIT