UI Library Hardening

Hardening goals

• stable public exports
• predictable variant behavior where variants are needed
• accessibility and styling consistency
• complete Storybook coverage for reusable components

Rules

1. Export intentionally from libs/ui/src/index.ts.
2. Add variants only when a component has real usage pressure for multiple visual states.
3. Use cva + defaultVariants for variantable primitives.
4. Keep data-slot markers and focus/ARIA behavior intact.
5. Keep business/domain logic out of shared UI components.
6. Validate in both admin and client apps before merge.

Storybook policy

• Every reusable UI or app-shell component in libs/ui/src/components should have a colocated *.stories.tsx file.
• Stories should cover at least default state and one meaningful alternate/edge state.
• Prefer composition stories for higher-level app components (app-shell, billing, feedback) to catch integration-level drift early.

Performance checks

• Build and snapshot Storybook metrics with:

bun run storybook:perf
bun run storybook:perf:enforce

• The report is written to docs/performance/storybook-latest.md.
• Budget thresholds are defined in docs/performance/budgets.json.
• Metrics are file-output based, so this works with Storybook 10.

Current variant baseline

• Button: default|outline|secondary|ghost|destructive|link
• Badge: default|secondary|destructive|outline|ghost|link
• Alert: default|destructive
• ButtonGroup: horizontal|vertical
• EmptyMedia: default|icon