Page Development

This workflow is for developers who know C# and .NET but are new to React and TypeScript. Page work supplies business contracts; it does not redesign color, layout, and states.

Concept map

C# / .NET concept	Frontend equivalent	Rule
Typed API Client	`@bitz/platform-sdk`	Do not handwrite DTOs or call `fetch` from a page
Application Query	Query hook or loader	Orchestrate a read model and page state
Command	Mutation hook	Use shared success, error, and invalidation behavior
Authorization Policy	PermissionGate / FeatureGate	UX only; the backend remains authoritative
Razor Component parameter	React prop	Keep it explicit and read-only
Result / ProblemDetails	SDK error model	Do not parse private error strings
Integration test	Playwright user flow	Cover real state transitions

Six steps

Inherit a Profile: the product chooses Theme, Mode, Density, Shell, and Workspace.
Choose a Recipe: List, Detail, Edit, Wizard, Dashboard, or Identity.
Choose contracts: locate generated SDK Query/Command and server permission codes.
Supply content: declare columns, fields, validation, copy, and business operations.
Complete states: implement applicable Loading, Empty, Error, Unauthorized, and Disabled states.
Pass gates: lint, typecheck, tests, build, representative visual matrix, and Design Guardian.

Recipes

Recipe	Fixed composition
List	PageHeader + QueryToolbar + AppliedSummary + DataToolbar + ServerDataTable + Pagination
Detail	PageHeader + Summary + LocalTabs + ActivityTimeline
Edit	FormSection + FieldGroup + ValidationSummary + ActionBar
Wizard	Stepper + StepPanel + SaveDraft + Review
Dashboard	QueryToolbar + MetricStrip + WorkQueue + DenseTable
Identity	IdentityShell + FormState + Recovery/Verification Action + Security Context

Product developers own SDK calls, permissions, fields, columns, copy, and operations. The Design System owns color, elevation, row height, breakpoints, focus, errors, and loading skeletons.

Dependency rules

Pages belong in the matching apps/app feature or route.
Import primitives from @bitz/components.
Import composed patterns and recipes from @bitz/widgets or their future dedicated package.
Call the backend only through the single @bitz/platform-sdk request pipeline.
Consume generated material output; never import token Source from a page.
Import from package barrels, not private deep paths.

Page redlines

No raw brand color, arbitrary gradient, colored shadow, or page-owned theme.
No handwritten backend DTO, scattered fetch, or local HTTP adapter.
No TenantId, Role, Permission, or refresh token in localStorage.
No frontend visibility treated as server authorization.
No page-specific Shell, tabs, filter system, or data table.
No happy path without the relevant failure and empty states.

Classify the destination before choosing a component:

cross-domain destinations are primary module navigation owned by the Shell;
destinations inside one domain are current-module navigation, shown in the Side context panel or Top secondary bar;
simultaneously open URLs or resources are Managed Workspace Tabs;
sections inside the current page use WorkspaceLocalTabs.

Do not copy module destinations into WorkspaceHeader. Local Tabs stay on one line and map to a URL or recoverable state. The widget owns sticky positioning, overflow, selected state, and keyboard semantics; a page supplies only labels and content.

Before a contribution

# Run the gates that exist today from the frontend root.
cd frontend
yarn install --immutable
yarn lint
yarn typecheck
yarn build

Run Vitest for affected packages. For layout, theme, density, narrow-screen, or accessibility changes, run yarn workspace @bitz/app test:visual (install Chromium first with test:visual:install). A standalone Design Lab and unified ui:check remain future capabilities and must not be reported as available.

Record the result in a stable, reviewable form:

Design Guardian: pass | changes-required
Contract: Theme / Mode / Density / Shell / Workspace / Recipe
States verified: default, hover, active, focus-visible, disabled, loading, data states
Accessibility: contrast, keyboard, text zoom, narrow viewport, reduced motion
Exceptions: none | ADR/ledger reference
Visual baseline: unchanged | intentional update reference

Read Design System 1.2 and implementation gates before beginning UI work.