Components & Patterns

Overview

Portfolio OS ships with two layers of components:

• UI primitives in packages/ui that power both the site and dashboard
• Surface components co-located with their respective apps (for example apps/site/components/projects)

This page documents the expectations for building, documenting, and consuming components so Storybook, MDX embeds, and production experiences all stay in sync.

Authoring Principles

1. Single responsibility – build narrowly scoped primitives (Button, Card, Tabs) and compose them for higher-order sections.
2. Accessibility-first – prefer Radix UI primitives, include ARIA labels, and replicate keyboard support (see the Gallery component for an example of focus trapping + arrow navigation).
3. Dark-mode parity – every component must include dark: styles that map to the design tokens defined in apps/docs/styles/globals.css.
4. Deterministic variants – use class-variance-authority or explicit props instead of ad-hoc className concatenation to guarantee theme consistency.

File Placement

Always colocate stories next to the component (Component.stories.tsx) and import them in Storybook via absolute paths (@/components/...).

Documentation Requirements

• Storybook stories covering default, edge, and error states. Reuse controls to show prop-driven variations.
• MDX usage snippets when a component is referenced from docs (see /docs/component-library/storybook for canonical examples).
• Props tables – expose Props types from the component file so Storybook autodocs can derive metadata.

Testing Expectations

Useful References

• Storybook Component Library
• Development Practices
• Testing Guide

Following these guardrails keeps authored UI consistent across the three apps, ensures every component is testable, and makes the documentation trustworthy.