zero-fucks-given/docs/architecture/react-frontend/layers/shared.md

Shared Layer

Global reusable building blocks used across the entire application — framework-level, never feature-specific.

shared/
| --- ui/                # primitive UI components (Button, Modal, Card)
| --- widgets/           # reusable composed UI blocks (DataGrid, screens)
| --- forms/             # reusable form composition (composed inputs)
| --- editors/           # reusable editor wrappers (tinymce, image_input)
| --- hooks/             # generic reusable hooks (useDebounce, useToggle, useLocalStorage)
| --- utils/             # pure helper functions (formatDate, generateId, sleep)
| --- lib/               # pure helpers and utility services (time/, phone_number/, resolveFileURL)
| --- assets/            # images, icons, fonts
| --- styles/            # global CSS, variables, Tailwind overrides
| --- constants/         # global constants

UI Components

Simple, composable, customizable building blocks — Lego pieces that combine into larger UI:

• Simple — Button, Input, Card, Modal, Dropdown.

• Composable — complex UI is built by composition, not by modifying base components:

  <Card>
    <CardHeader />
    <CardContent />
    <CardFooter />
  </Card>
  

• Customizable — through className, variants, props, and composition:

  <Button variant="outline" size="lg">
    Save
  </Button>
  

• No business logic — presentation only (local state allowed): no API calls, React Query, form submission, or domain logic.

Styling

Utility-first, design tokens, variants instead of style duplication, minimal centralized custom CSS.

Stack: TailwindCSS (primary styling), class-variance-authority (variants), CSS variables (design tokens), Radix primitives (accessible building blocks).

Other Folders

• hooks/ — generic hooks with no entity or business-logic dependencies.
• utils/ — stateless pure helper functions.
• lib/ — pure helpers and utility services (date, name, path, phone formatting).
• assets/ — static resources (icons, fonts).
• styles/ — CSS variables, Tailwind extensions, global resets.