mirror of
https://github.com/NicholaiVogel/dashore-incubator.git
synced 2026-03-31 06:40:32 +00:00
Nicholai
2e051e4bef
- add WorkOS AuthKit authentication with middleware protection - add dashboard with sidebar layout (shadcn/ui components) - add contributor documentation (CONTRIBUTING, CODE_OF_CONDUCT, SECURITY, START-HERE, Documentation/) - add CI workflow for lint and build on PRs - switch from pnpm to bun - add CLAUDE.md and AGENTS.md for AI assistant context
94 lines
3.7 KiB
Markdown
94 lines
3.7 KiB
Markdown
UI Guidelines
|
|
===
|
|
|
|
This document outlines the mandatory styling and UI development standards for the Dashore Incubator project.
|
|
|
|
General Principles
|
|
---
|
|
|
|
- **Consistency**: All UI elements must follow the project's established design patterns.
|
|
- **Accessibility**: Compliance with WCAG 2.1 Level AA is mandatory.
|
|
- **Themability**: Use CSS variables for all colors and spacing to ensure the application remains easily re-themable.
|
|
- **Modern Standards**: Leverage Tailwind CSS 4.0 features and modern CSS functions (like `oklch`).
|
|
|
|
Component Architecture
|
|
---
|
|
|
|
### Shadcn/UI First
|
|
|
|
We use **Shadcn/UI** as our primary component library.
|
|
|
|
- Always check if a required component exists in the `src/components/ui` directory before building a custom one.
|
|
- If a new Shadcn/UI component is needed, add it using the CLI: `bunx shadcn@latest add [component-name]`.
|
|
- Custom components should be built by composing Shadcn/UI primitives and following their established patterns (e.g., using `cn()` utility for class merging).
|
|
|
|
### Hardcoded Styling
|
|
|
|
Hardcoded values for colors, spacing, and shadows are **HEAVILY discouraged**.
|
|
|
|
- **Colors**: Use semantic theme variables from `globals.css` (e.g., `text-muted-foreground` instead of `text-zinc-500`).
|
|
- **Spacing**: Use Tailwind spacing scale (`p-4`, `m-2`) or theme variables if available.
|
|
- **Shadows**: Use theme-defined shadows (`shadow-sm`, `shadow-md`).
|
|
|
|
Theming & Globals
|
|
---
|
|
|
|
Our theme is defined in `src/app/globals.css` using Tailwind 4.0's `@theme` directive and `oklch` color functions.
|
|
|
|
### Color Variables
|
|
|
|
All colors must be derived from the CSS variables defined in `:root` and `.dark` blocks:
|
|
|
|
- `--background` / `--foreground`: Base page colors.
|
|
- `--primary` / `--primary-foreground`: Primary action colors.
|
|
- `--secondary` / `--secondary-foreground`: Secondary action colors.
|
|
- `--muted` / `--muted-foreground`: For less prominent elements.
|
|
- `--accent` / `--accent-foreground`: For highlighting and hover states.
|
|
- `--destructive` / `--destructive-foreground`: For dangerous actions.
|
|
- `--border`, `--input`, `--ring`: For UI structure and focus states.
|
|
|
|
### Updating the Theme
|
|
|
|
To update the theme or add new variables:
|
|
1. Modify the variable values in `src/app/globals.css`.
|
|
2. Ensure both light mode (`:root`) and dark mode (`.dark`) are updated to maintain contrast and readability.
|
|
|
|
Accessibility (WCAG)
|
|
---
|
|
|
|
- **Contrast**: Ensure text-to-background contrast ratios meet WCAG AA standards (4.5:1 for normal text, 3:1 for large text).
|
|
- **Semantics**: Use appropriate HTML elements (`<button>`, `<nav>`, `<main>`).
|
|
- **Aria Attributes**: Use Radix-based components (via Shadcn/UI) which provide robust ARIA support out of the box. Ensure `aria-label` and other attributes are correctly applied to custom elements.
|
|
- **Keyboard Navigation**: All interactive elements must be focusable and operable via keyboard.
|
|
|
|
Testing
|
|
---
|
|
|
|
Thorough testing of UI components and user flows is mandatory.
|
|
|
|
- **Unit Tests**: Test complex component logic.
|
|
- **Integration Tests**: Verify that components work together as expected.
|
|
- **Accessibility Testing**: Use automated tools (like Axe) and manual keyboard/screen reader testing to ensure compliance.
|
|
|
|
Examples
|
|
---
|
|
|
|
### Correct (Using Theme Variables)
|
|
|
|
```tsx
|
|
<div className="bg-card text-card-foreground p-4 rounded-lg border border-border shadow-sm">
|
|
<h2 className="text-primary font-bold">Themed Header</h2>
|
|
<p className="text-muted-foreground">This uses semantic variables.</p>
|
|
</div>
|
|
```
|
|
|
|
### Incorrect (Hardcoded Values)
|
|
|
|
```tsx
|
|
// AVOID THIS
|
|
<div className="bg-white text-[#333] p-[15px] border border-zinc-200 shadow-[0_1px_2px_rgba(0,0,0,0.1)]">
|
|
<h2 className="text-blue-600 font-bold">Hardcoded Header</h2>
|
|
<p className="text-zinc-500">This is hard to retheme.</p>
|
|
</div>
|
|
```
|