@movable/ui

todo: update

This repo contains the shared components for our frontend applications. Using this react component library guide

Local Development

Installation

1. Ensure you have volta installed on your computer
2. Clone the repo
3. npm install (note: npm, not yarn)

Usage

Ensure the project consuming this library has all the required peer dependencies.

WARNING: Providing Theme Colors to Custom Components

While within using app you'll be able to use (theme) => theme.palette... style of sx props. But within our custom component this does NOT traverse to the using app. You'll want to use the theme palette directly to ensure proper color strings. See #224

import palette from 'path_to_src/theme/palette';

export default InkCustomComponent() {
  return (
    <Box sx={{ backgroundColor: palette.neutral50 }}>
      ...
    </Box>
  )
}

Alpha Pre-release Workflow

This project supports alpha releases for testing changes before full releases.

Manual Alpha Release

For testing specific features or changes:

1. Navigate to Actions tab in GitHub repository
2. Select "Release to NPM" workflow
3. Click "Run workflow" button
4. Configure options:
   • release_type: Select prerelease
   • dist_tag: Leave as alpha or customize (e.g., beta, feature-test)
   • increment: Leave empty for auto-increment or specify (patch, minor, major)
5. Click "Run workflow" to trigger the release

Result: Creates version like 3.4.1-alpha.0 and publishes to npm with @alpha tag

Using Alpha Versions in Other Projects

Install alpha versions in your consuming projects:

# Install latest alpha
npm install @movable/ui@alpha
yarn add @movable/ui@alpha

# Install specific alpha version
npm install @movable/[email protected]
yarn add @movable/[email protected]

View all available versions at: https://www.npmjs.com/package/@movable/ui?activeTab=versions

Claude Code Skills

This repo includes local Claude Code skills for common workflows. See CLAUDE.md for the full list of available /slash commands.

MCP Server

This repo includes an MCP (Model Context Protocol) server that exposes component information to AI assistants like Claude Code. See mcp-server/README.md for setup instructions.

Visual Regression Testing

Visual regression testing is handled via Percy with Storybook (Storybook-only approach):

• Storybook Stories: All visual states must be captured in Storybook stories
• Percy Integration: npm run percy:storybook runs Percy snapshots on built Storybook
• Cypress Tests: Focus on functional/integration testing only (no Percy snapshots)

This consolidated approach reduces duplicate snapshots and CI runtime while maintaining comprehensive visual coverage.

Conventional Commits

This repo uses conventional commits to drive automated versioning. Commits are linted both pre-commit and in PR checks.

Breaking changes must use feat!: or include a BREAKING CHANGE: footer — see CONTRIBUTING.md for details.

fix(percy): added percy snapshots for all component states

- active
- disabled
- focused

GitHub Issue to Shortcut Sync

This repository automatically syncs GitHub issues to Shortcut stories on the Designer Team board. GitHub Issues are the source of truth - all work should start and be managed here.

For Engineers

📖 See .github/SHORTCUT_SYNC.md for the complete workflow guide, including:

• How the automation works (automatic + manual triggers)
• Recommended workflow for working through issues
• Issue types and state transitions
• Troubleshooting common scenarios

Quick summary: When you open an issue, it automatically creates a Shortcut story. When you open a PR that fixes the issue, it moves the story to "In Development". When you close the issue, it completes the story.

Updating the Shortcut API Token

If the Shortcut API token needs to be rotated or updated:

1. Create a new token in Shortcut:

   • Go to Shortcut Settings → API Tokens
   • Create new token with description "GitHub Issue Sync"
   • Copy the token value

2. Update the GitHub secret:

   Via GitHub CLI:

   gh secret set SHORTCUT_API_TOKEN
   # Paste the new token when prompted

   Or via GitHub web UI:

   • Go to Settings → Secrets and variables → Actions
   • Click on SHORTCUT_API_TOKEN and update the value

3. Test the automation by creating a test issue to verify the sync is working