b99799c2fe
- Updated various components to use consistent color tokens, improving visual coherence. - Refactored layout components to utilize the new PublicShell for better structure. - Enhanced error and status messaging styles for improved user feedback. - Standardized button usage across forms and modals for a unified interaction experience. - Introduced new UI design tokens and guidelines in documentation to support future development.
37 lines
1.7 KiB
Markdown
37 lines
1.7 KiB
Markdown
## Portal UI Design System (Frontend)
|
||
|
||
This project uses **Tailwind CSS v4** with a **token-based theme** so pages look cohesive and remain easy to maintain.
|
||
|
||
### Principles
|
||
|
||
- **Use semantic tokens** instead of raw colors (`bg-card`, `text-foreground`, `border-border`, `text-muted-foreground`, `ring-ring`).
|
||
- **Use shared shells and templates**:
|
||
- Public pages: `PublicShell` via `apps/portal/src/app/(public)/layout.tsx`
|
||
- Authenticated pages: `AppShell` via `apps/portal/src/app/(authenticated)/layout.tsx`
|
||
- Authenticated page content: `PageLayout` for titles/breadcrumbs/loading/error
|
||
- **Prefer shared primitives** (`Button`, `AlertBanner`, `ErrorState`, `Loading*`, `SubCard`) over ad-hoc markup.
|
||
- **Keep motion subtle** (shadow/color transitions; avoid big gradients/translate/scale).
|
||
|
||
### Quick reference: what to use
|
||
|
||
- **Page wrapper**: `PageLayout`
|
||
- Use `loading`, `error`, `onRetry`, and `breadcrumbs` for consistent states.
|
||
- **Surfaces**
|
||
- Use `bg-card border-border shadow-[var(--cp-shadow-1)]` for panels.
|
||
- Use `.cp-card` for simple card surfaces when you don’t need a component.
|
||
- **Typography**
|
||
- Titles: `text-foreground`
|
||
- Secondary text: `text-muted-foreground`
|
||
- **Inputs**
|
||
- Use `Input` / `FormField` to get correct borders/focus/invalid states.
|
||
- **Buttons**
|
||
- Use `Button` variants (`default`, `outline`, `secondary`, `ghost`, `link`).
|
||
- **Status/feedback**
|
||
- Use `AlertBanner` (`success|info|warning|error`) and `StatusPill`.
|
||
|
||
### Token sources
|
||
|
||
- Global semantic colors: `apps/portal/src/app/globals.css`
|
||
- Portal-specific tokens/spacing/shadows: `apps/portal/src/styles/tokens.css`
|
||
- Semantic utility classes: `apps/portal/src/styles/utilities.css`
|