B2B Frontend Blueprint

AI-ready rules and a runnable starter for building practical B2B / enterprise console frontends.

B2B products are usually dense, permission-sensitive, workflow-driven, and heavily customized. Generic landing-page UI patterns do not translate well to tables, filters, dialogs, imports, detail pages, batch actions, and operational dashboards.

This repository turns those interaction decisions into reusable rules, docs, packages, demos, and a small framework-agnostic starter.

What You Get

• AI-ready interaction rules for common B2B components and page patterns.
• Human-readable docs in English and Chinese.
• Compact AI rule bundles that can be loaded into coding agents.
• A runnable vanilla demo for list CRUD, import workflow, detail pages, dialogs, state views, theme, and i18n.
• A local scaffold script for generating a clean starter project.
• Reusable packages for request handling, runtime config, i18n, theme, resource modules, form schema, auth skeleton, and import workflow.
• Resource module conventions for building new CRUD pages with less repeated glue code.

Current Status

This is an MVP blueprint, not a finished admin framework.

It is ready for:

• studying and reusing B2B interaction rules;
• asking AI to generate more consistent console UI;
• running the vanilla demo locally;
• generating a simple starter project;
• extending resource modules and API contracts.

It does not yet include:

• a released npm CLI version (the package is publish-ready but not released yet);
• framework-specific React / Vue component libraries;
• a complete RBAC platform;
• a complete login/register/account system;
• a full E2E test suite.

Quick Start

Install dependencies and run the demo:

pnpm install
pnpm dev

Open:

http://127.0.0.1:4173/apps/demo-vanilla/

Do not open apps/demo-vanilla/index.html directly with file://. The demo uses ES modules and cross-package imports, so it needs the local dev server.

How To Use This Repo

Choose the path that matches your goal:

• Try the demo: run the vanilla app and inspect B2B interaction patterns.
• Create a project: generate a clean console shell with --without-demo.
• Add a resource: copy the Orders Resource Example and adapt it to your business object.
• Connect backend APIs: configure apiBaseUrl, create a request client, and adapt list/error responses.

Start here:

• Adoption Guide
• 使用接入指南
• Orders Resource Example

Generate A Starter

Create a new framework-agnostic console project:

node scripts/create-blueprint.mjs my-console --template vanilla --with-demo

After the CLI is released, the same flow is available without cloning the repository:

npx create-b2b-blueprint my-console

Add a generated resource module to a project that includes the resource runtime:

npx create-b2b-blueprint add-resource orders --target . --endpoint /orders

Create a cleaner starter without demo modules:

node scripts/create-blueprint.mjs my-console --template vanilla --without-demo

Generate a starter with runtime config:

node scripts/create-blueprint.mjs ops-console \
  --template vanilla \
  --modules users,imports,projects,activities \
  --app-name "Operations Console" \
  --locale zh \
  --theme system \
  --density compact \
  --api-base-url "https://api.example.com"

Then run the generated project:

cd my-console
pnpm build
pnpm dev

The generated app opens at:

http://127.0.0.1:4173/apps/web/

Scaffold Options

--target <path>       Target directory. Overrides positional project name.
--template vanilla    Template name. Currently only vanilla is supported.
--with-demo           Include demo modules. Default.
--without-demo        Generate the app shell without demo modules.
--modules <list>      Comma-separated modules. Supported: users, imports, projects, activities.
--app-name <name>     App display name written to blueprint.config.js.
--locale <zh|en>      Default locale.
--theme <system|light|dark>
--density <comfortable|compact>
--api-base-url <url>  Backend API base URL.
--force               Overwrite target files.
--dry-run             Preview planned output without writing files.

Validate scaffold output:

pnpm test:scaffold

Demo Coverage

The vanilla demo currently covers:

• User Management: filter bar, table, pagination, selection, batch actions, row detail, create/edit dialog, ConfirmDialog, disabled permission states, loading, empty, error, and request race handling.
• Import Records: upload workflow, stepper, field mapping, validation errors, failed-row download, result summary, recent import tasks, and partial failure state.
• Project Detail: detail page layout, edit mode, settings form, related members table, security switches, section-level forbidden/error states, danger zone, and activity log.
• Generic Resource CRUD: module registry, resource API contract, schema-driven forms, list/detail/edit/delete actions, refresh after save, and error handling.
• Shared Runtime: light/dark theme, Chinese/English i18n, density config, pending prevention, dangerous action confirmation, and section-level state handling.

Use With AI

For AI-assisted page generation, start with:

• Machine-readable Rules Manifest
• Agent Instructions
• LLM Discovery Entry
• All AI Rules Entry
• Core Foundation Bundle
• List CRUD Bundle
• Form Overlay Bundle
• Data Feedback Bundle
• Import Workflow Bundle

Example prompt:

Use the B2B Frontend Blueprint AI rules.
Build a resource management page with FilterBar, Table, pagination, row actions,
batch actions, create/edit dialog, ConfirmDialog for delete, loading/empty/error states,
and refresh after save. Follow the List CRUD and Form Overlay bundles.

Documentation

Recommended entry points:

Topic	English	Chinese
Adoption Guide	adoption-guide.md	adoption-guide.zh.md
Getting Started	getting-started.md	getting-started.zh.md
MVP Scope	mvp-scope.md	mvp-scope.zh.md
Add Resource Module	add-resource-module.md	add-resource-module.zh.md
API Integration	api-integration.md	api-integration.zh.md
Browser Support	browser-support.md	browser-support.zh.md
Rule Authoring	rule-authoring-guide.md	rule-authoring-guide.zh.md
Template Architecture	template-architecture.md	template-architecture.zh.md
MVP Implementation Plan	mvp-implementation-plan.md	mvp-implementation-plan.zh.md

Rule entry points:

• Component Rules README
• AI Rule Bundles
• Rules Inventory
• Component Architecture Rules

Page and prompt examples:

• Prompt Examples
• Page Demo Blueprints
• Resource Examples

Rule File Convention

Each component rule module uses four files:

{module}-rules.md
{module}-rules.zh.md
{module}-ai-rules.md
{module}-ai-rules.zh.md

File meanings:

• *-rules.md: English human-readable detailed rules.
• *-rules.zh.md: Chinese human-readable detailed rules.
• *-ai-rules.md: English AI-executable compact rules.
• *-ai-rules.zh.md: Chinese AI-executable compact rules.

Packages

The current MVP keeps the implementation small and framework-agnostic:

packages/
├── auth/              Permission and auth skeleton.
├── compatibility/     Browser feature detection and storage fallback.
├── data/              Demo data helpers.
├── dom/               Small DOM utilities.
├── form-schema/       Schema-driven form metadata.
├── headless/          Headless interaction logic.
├── i18n/              Runtime language controller.
├── import-workflow/   Import workflow contract.
├── observability/     Replaceable structured logger and redaction.
├── recipes/           Reusable page composition helpers.
├── request/           API adapter and error normalization.
├── resource/          Resource module and CRUD conventions.
├── runtime-config/    Runtime project configuration.
├── security/          Redirect, escaping, and upload safety helpers.
└── theme/             Theme and density controller.

The goal is to keep the starter portable. Teams can later wrap the same concepts in React, Vue, Svelte, or another stack.

The repository also includes an official React reference adapter under adapters/react/. It consumes the same framework-independent contracts and is intentionally not copied into Vanilla projects.

Repository Layout

.
├── apps/demo-vanilla/          Runnable framework-agnostic demo.
├── adapters/react/             Official React reference adapter.
├── component-rules/            Human and AI component interaction rules.
├── docs/                       Product, architecture, and integration docs.
├── examples/                   Prompt examples and page blueprints.
├── packages/                   Reusable framework-agnostic packages.
├── scripts/                    Local scaffold and validation scripts.
├── system-rules/               Architecture-level rules.
├── templates/vanilla/          Starter template used by the scaffold script.
├── ROADMAP.md
├── LICENSE
└── README.md

Development

Run the full build check:

pnpm build

The build validates JavaScript syntax, Markdown links, shared template synchronization, headless/data behavior, and generated scaffold output.

After changing packages/ or apps/demo-vanilla/, synchronize the distributable template:

pnpm sync:template

Run scaffold validation:

pnpm test:scaffold

Run Chromium E2E and accessibility checks after installing the browser runtime:

pnpm exec playwright install chromium
pnpm exec playwright test --project=chromium

Run the local demo:

pnpm dev

Roadmap

Near-term direction:

• publish and tag the first npm CLI release;
• continue extracting large demo features behind ModuleDefinition boundaries;
• validate the React adapter through a standalone React template;
• add real backend auth provider examples;
• expand AI evaluations with generated-code review fixtures.

See ROADMAP.md for the broader plan.

License

MIT