dashore-incubator/Documentation/ui-guidelines.md

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)

<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)

// 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>