Just Progress Bar Skill

just-progress-bar-skill Agent-native progress bars: pick a pattern, generate source, audit accessibility, and wire it into CLI or MCP workflows.

Live Gallery · 中文说明 · CLI · Skill · MCP · Roadmap

What It Is

just-progress-bar-skill is a source-first progress UI toolkit for agents and frontend projects. It includes a catalog, React wrappers, standalone HTML/CSS snippets, a CLI, recipe generation, an Agent Skill package, accessibility checks, and MCP-ready runtime adapters.

| Surface | What you get | | --- | --- | | Gallery | Browse 24 progress patterns, filter by category/tag, preview values, and copy source. | | React | JustProgressBar, CircularProgress, StepProgress, plus one wrapper per catalog pattern. | | HTML/CSS | Standalone snippets for projects that do not use React. | | CLI | List, generate, audit, export the Skill, inspect roadmap, and run MCP JSON-lines stdio. | | Skill | packages/skill/SKILL.md teaches agents how to choose, generate, and audit progress bars. | | MCP | Tools for listing, reading, generating, validating recipes, auditing, and returning design tokens. |

Progress Levels

The README now shows the progress bars at different value levels and complexity levels, not only a single gallery screenshot.

| Level | Best for | Example patterns | | --- | --- | --- | | 0-25% | queued, starting, first byte, early generation | gradient-loading, dot-line-minimal, download-button | | 50-75% | active build, upload, review, media playback | line-number-progress, music-player, player-progress | | 100% | completion, success, status confirmation | status-feedback, order-steps, step-progress | | Circular | dashboards, runtime health, compact proof | circular-basic, circular-dashboard, neon-ring, apple-watch-rings | | Creative | branded or playful states for demos and products | lightsaber, cute-game-loading, happy-heart, helix-bar, thai-pattern-progress |

Quick Start

This repository is meant to be published and validated through GitHub Actions. For local exploration, install dependencies and run the gallery:

pnpm install
pnpm dev

Use the CLI directly from source:

node packages/cli/src/index.mjs list --limit 8
node packages/cli/src/index.mjs generate --id neon-ring --target react
node packages/cli/src/index.mjs generate --prompt "upload progress" --target react --out ./UploadProgress.tsx
node packages/cli/src/index.mjs audit ./src/MyProgressBar.tsx
node packages/cli/src/index.mjs skill export --out ./dist/just-progress-bar-skill

30-Second React Example

import { JustProgressBar, CircularProgress, StepProgress, NeonRingProgress } from '@just-progress-bar/react';
import '@just-progress-bar/core/styles.css';

export function UploadProgress() {
  return ;
}

export function BuildRing() {
  return ;
}

export function CheckoutSteps() {
  return ;
}

export function AgentSelectedPattern() {
  return ;
}

Catalog

The v0.5.0 catalog includes 24 original patterns:

gradient-loading, icon-progress, dot-line-minimal, line-number-progress,
download-button, status-feedback, vertical-progress, circular-basic,
circular-dashboard, neon-ring, emoji-schedule, apple-watch-rings,
happy-heart, cute-game-loading, music-player, bubble-slider,
three-d-capsule, step-progress, lightsaber, order-steps,
color-ball, player-progress, helix-bar, thai-pattern-progress

Agent And MCP Workflows

| Workflow | Command or entry point | | --- | --- | | Prompt to source | just-progress-bar generate --prompt "neon loader for AI generation" --target react | | Repeatable recipe | just-progress-bar recipe ./recipes/upload-progress.json --out ./tmp/upload | | Accessibility audit | just-progress-bar audit ./src/MyProgressBar.tsx | | Skill export | just-progress-bar skill export --out ./dist/just-progress-bar-skill | | JSON-lines MCP manifest | node packages/cli/src/index.mjs mcp --describe | | Official SDK runtime | pnpm --filter @just-progress-bar/mcp-server sdk:stdio |

MCP tools include:

list_progress_bars
get_progress_bar
get_progress_bar_source
generate_progress_bar
validate_progress_bar_recipe
generate_progress_bar_from_recipe
audit_progress_bar_accessibility
create_gallery_demo
get_design_tokens
suggest_progress_bar_by_prompt

Resources include progressbar://catalog, progressbar://component/{id}, progressbar://tokens/default, progressbar://a11y/checklist, progressbar://recipes/{id}, and progressbar://roadmap.

Accessibility Baseline

Generated progress bars follow these rules:

• use native ` or role="progressbar"`;
• provide a visible or ARIA-linked label;
• expose aria-valuenow for determinate progress;
• omit aria-valuenow for indeterminate progress;
• avoid color-only status feedback;
• include prefers-reduced-motion handling or import the core stylesheet.

See [docs/accessibility.md](./docs/accessibility.md).

Repository Map

apps/gallery/          Vite gallery published by GitHub Pages
packages/core/         catalog, registry, types, tokens, source generation, a11y audit
packages/react/        React components and pattern wrappers
packages/cli/          just-progress-bar command
packages/skill/        Agent Skill package and resources
packages/mcp-server/   dependency-light helpers and official MCP SDK runtime
examples/              React and HTML/CSS examples
recipes/               repeatable generation specs
docs/                  architecture, release, runtime, visual, CLI, Skill, MCP docs
docs/readme-assets/    README showcase screenshots and thumbnail assets

GitHub Actions Release Path

Local full builds are not required for release preparation. Push the repository to Just-Agent/just-progress-bar-skill; GitHub Actions owns the heavy checks:

| Workflow | Purpose | | --- | --- | | CI | installs dependencies, runs smoke tests, browser checks, typecheck, and build | | Pages | builds apps/gallery and deploys the public Gallery | | Release | verifies, packages a source ZIP, and can optionally publish npm packages |

Useful zero-install checks when editing source files:

node scripts/smoke-test.mjs
node scripts/validate-roadmap.mjs
node scripts/validate-catalog.mjs
node scripts/html-css-snippet-smoke.mjs
node scripts/release-readiness.mjs

Showcase Assets

README and social preview assets are generated from a static source at [docs/readme-assets/showcase.html](./docs/readme-assets/showcase.html).

| Asset | Path | | --- | --- | | Desktop README proof | [docs/readme-assets/desktop-showcase.png](./docs/readme-assets/desktop-showcase.png) | | Mobile README proof | [docs/readme-assets/mobile-showcase.png](./docs/readme-assets/mobile-showcase.png) | | Progress level matrix | [docs/readme-assets/progress-levels.png](./docs/readme-assets/progress-levels.png) | | README logo | [docs/readme-assets/logo.svg](./docs/readme-assets/logo.svg) | | Open Graph card | [docs/readme-assets/thumbnail/og.png](./docs/readme-assets/thumbnail/og.png) | | Responsive thumbnail | [docs/readme-assets/thumbnail/responsive.png](./docs/readme-assets/thumbnail/responsive.png) | | Matrix / square / app / story thumbs | [docs/readme-assets/thumbnail/](./docs/readme-assets/thumbnail/) |

Originality And License

The included examples are original implementations inspired by common progress UI patterns. Do not copy third-party Dribbble shots, PSDs, PNGs, animation files, source code, or trademarked assets into this repository.

MIT licensed. See [LICENSE](./LICENSE), [CONTRIBUTING.md](./CONTRIBUTING.md), [SECURITY.md](./SECURITY.md), and [CHANGELOG.md](./CHANGELOG.md).

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Just-Agent
• Source: Just-Agent/just-progress-bar-skill
• License: MIT
• Homepage: https://just-agent.github.io/just-progress-bar-skill/

Install and usage instructions live in the source repository linked above.