Blueprint Storybook — Fluent 2

A self-growing Storybook repository that houses pipeline-graduated, verified Fluent 2 React components. Components that pass UI verification are proposed via human-reviewed PRs. Once merged and deployed, they become available to any agent that queries this Storybook via MCP.

Quick Start

npm install
npm run dev        # Storybook dev server at http://localhost:6006
npm run build      # Static build to storybook-static/
npm test           # Run vitest
npm run lint       # TypeScript type-check

Repository Structure

src/
├── components/         # Graduated components, organized by category
│   ├── data-display/   # KPI cards, stat tiles, metric indicators
│   ├── layout/         # Page shells, split panes, grids
│   ├── navigation/     # Breadcrumbs, side navs, tab bars
│   ├── cards/          # Resource cards, link cards, info cards
│   ├── forms/          # Form groups, field layouts, filter panels
│   ├── feedback/       # Message bars, empty states, loading skeletons
│   ├── overlays/       # Dialogs, panels, drawers
│   ├── composition/    # Page headers, toolbar groups, action bars
│   └── content/        # Rich text blocks, hero sections
├── icons/              # All icon sets (fluent, azure-portal, custom)
└── index.ts            # Barrel export
meta/
├── component-index.json    # Machine-readable index (auto-generated)
└── graduation-log.json     # History of all graduation events

Component Requirements

Every graduated component must be fully standalone — copy-pasteable into any Fluent 2 React project.

Allowed Dependencies

• @fluentui/react-components
• @fluentui/react-icons
• @fluentui/tokens
• react (peer)

Forbidden

• Project-specific imports
• Runtime fetch/API calls
• CSS modules, Tailwind, styled-components
• Hardcoded hex colors, px font sizes, raw spacing values

Graduation Flow

1. Pipeline build produces a component that passes UI verification (score ≥ 0.85)
2. Agent performs deduplication check against component-index.json
3. Agent suggests graduation: Add New / Create Variant / Extend Existing
4. Human reviews and approves the PR
5. Merge triggers deploy to Azure SWA and index rebuild

Token Strategy

Direct Fluent tokens only — tokens.colorBrandForeground1, etc. No alias layer.

Publishing to npm

The package is published manually by a developer — there is no automated publish on merge.

Prerequisites

• You are logged in to npm (npm whoami to check, npm login to authenticate)
• All changes are merged to main and CI is green
• You have reviewed the diff since the last publish (git log v$(node -p "require('./package.json').version")..HEAD --oneline)

Steps

# 1. Pull latest main
git checkout main && git pull

# 2. Bump the version (choose one)
npm version patch   # 0.0.1 → 0.0.2  — bug fixes, docs, snapshot updates
npm version minor   # 0.0.2 → 0.1.0  — new graduated components
npm version major   # 0.1.0 → 1.0.0  — breaking API changes (rare)

# 3. Publish (runs lint + test + build:pkg automatically via prepublishOnly)
npm publish

# 4. Push the version commit and tag
git push && git push --tags

What gets published

Only the files listed in package.json → "files" are included in the tarball:

| Path | Contents | |------|----------| | dist/ | Compiled JS + type declarations (tsc --project tsconfig.build.json) | | meta/component-index.json | Machine-readable component index for fast lookups |

Storybook config, stories, tests, snapshots, and scripts are excluded.

Consuming the package

npm install blueprint-storybook-fluent

import { IconCard } from 'blueprint-storybook-fluent';
import { DatabaseIcon } from 'blueprint-storybook-fluent/dist/icons/fluent';

Version strategy

| Change | Bump | Example | |--------|------|---------| | New graduated component | minor | IconCard added | | Prop added to existing component | minor | size prop on IconCard | | Bug fix / style tweak / docs | patch | Fix spacing token | | Prop removed or renamed | major | trend → direction |

Dry run

Preview what will be published without actually pushing to the registry:

npm pack --dry-run   # list files in the tarball
npm publish --dry-run # simulate the full publish

Hosting

Azure Static Web Apps — always reflects main HEAD. No version pinning.