Relevant source files

The following files were used as context for generating this wiki page: - [src/app/(frontend)/design-system/page.tsx](https://github.com/net-work-studio/PIT-www_Pittogramma/blob/main/src/app/%28frontend)/design-system/page.tsx) - [src/app/(frontend)/design-system/_components/ui-section.tsx](https://github.com/net-work-studio/PIT-www_Pittogramma/blob/main/src/app/%28frontend)/design-system/_components/ui-section.tsx) - [src/sanity/types.ts](https://github.com/net-work-studio/PIT-www_Pittogramma/blob/main/src/sanity/types.ts) - [src/components/modules/project/project-info.tsx](https://github.com/net-work-studio/PIT-www_Pittogramma/blob/main/src/components/modules/project/project-info.tsx) - [src/sanity/components/fetch-website-data-button.tsx](https://github.com/net-work-studio/PIT-www_Pittogramma/blob/main/src/sanity/components/fetch-website-data-button.tsx) - [src/components/modules/designer/designer-info.tsx](https://github.com/net-work-studio/PIT-www_Pittogramma/blob/main/src/components/modules/designer/designer-info.tsx) - [package.json](https://github.com/net-work-studio/PIT-www_Pittogramma/blob/main/package.json)

# Design System & UI Components The Pittogramma design system is a structured framework of reusable UI primitives and complex modules built with Next.js 16, TypeScript, Tailwind CSS 4, and shadcn/ui. It serves as the visual and functional foundation for the Pittogramma platform, ensuring consistency across project showcases, interviews, and resource glossaries. The system is organized into four primary domains: Colors, Typography, UI Components, and Modules. While UI components represent atomic elements like buttons and inputs, Modules represent high-level assemblies that integrate directly with Sanity CMS data, such as project metadata headers and designer profiles. Sources: [src/app/(frontend)/design-system/page.tsx:18-23](), [src/app/(frontend)/design-system/_components/ui-section.tsx:142-145]() ## Architecture Overview The design system implementation follows a tiered architecture where generic UI primitives (Radix UI / shadcn) are wrapped into specialized React components. The frontend consumes these components through a dedicated design system showcase available during development mode. ```mermaid graph TD subgraph UI_Primitives ["UI Primitives (shadcn/ui)"] Button[Button Component] Badge[Badge Component] Accordion[Accordion Component] Tabs[Tabs Component] end subgraph Business_Modules ["Business Modules"] ProjectInfo[Project Info Module] DesignerInfo[Designer Info Module] MediaBlocks[Media Blocks] end subgraph Data_Layer ["Data Layer (Sanity CMS)"] SanityTypes[TypeScript Definitions] StudioComponents[Custom Studio Inputs] end SanityTypes --> Business_Modules UI_Primitives --> Business_Modules Business_Modules --> Frontend[Frontend Features] ``` The architecture separates generic UI state from data-fetching modules, allowing components like `ProjectInfo` to remain focused on layout and presentation while utilizing the design system's primitive definitions. Sources: [src/app/(frontend)/design-system/page.tsx:25-45](), [src/sanity/types.ts:241-260]() ## UI Components The system provides a comprehensive set of interactive elements. These are managed via a development-only design system page that allows for visual testing of variants and states. ### Core Primitives The atomic components are categorized by their function and visual variants: | Component | Variants | Usage Example | | :--- | :--- | :--- | | **Button** | `default`, `destructive`, `outline`, `secondary`, `ghost`, `link` | Primary actions and navigation | | **Badge** | `project`, `article`, `interview`, `feat`, `event` | Content type labeling | | **Input** | `default`, `disabled` | Search and form fields | | **Accordion** | `collapsible`, `single` | FAQs and Glossary definitions | Sources: [src/app/(frontend)/design-system/_components/ui-section.tsx:64-105](), [src/app/(frontend)/(resources)/glossary/page.tsx:75-80]() ### Complex Interactive Elements The design system utilizes Radix UI primitives for accessible complex interactions: * **Tabs:** Used for switching views (e.g., List vs. Grid) in resource pages. * **Dialog & Sheet:** Provide contextual overlays and slide-in panels for mobile navigation or detailed settings. * **Dropdown Menu:** Used for filtering and checkbox-based selections. Sources: [src/app/(frontend)/design-system/_components/ui-section.tsx:151-240](), [src/components/resources/websites-content.tsx:112-120]() ## Media Blocks and Gallery System A critical aspect of the design system is the Media Block architecture, which defines how visual content is structured in Project and Journal galleries. These blocks are strictly typed and support responsive orientations. ```mermaid classDiagram class MediaItem { +String type +Image image +Video video +String caption +String alt } class SingleMediaBlock { +String orientation +MediaItem media } class SideBySideMediaBlock { +String orientation +MediaItem left +MediaItem right } class GridFourMediaBlock { +String orientation +MediaItem topLeft +MediaItem topRight +MediaItem bottomLeft +MediaItem bottomRight } SingleMediaBlock --* MediaItem SideBySideMediaBlock --* MediaItem GridFourMediaBlock --* MediaItem ``` The gallery system supports both `landscape` and `portrait` orientations across all block types, ensuring a flexible grid for design portfolios. Sources: [src/sanity/types.ts:241-274](), [scripts/archive/import-projects.ts:160-185]() ## Specialized Business Modules Business modules are high-level components designed to render specific Sanity document types. ### Project and Designer Information Modules like `ProjectInfo` and `DesignerInfo` standardize the layout for technical metadata. They utilize a definition list (`dl`) structure with mono-spaced, uppercase headers for technical accuracy. ```typescript // Example structure of a Business Module header {designerNames ? (

{designerNames}

) : null} {title ? (

{title}

) : null} ``` Sources: [src/components/modules/project/project-info.tsx:43-56](), [src/components/modules/designer/designer-info.tsx:32-40]() ## Sanity Studio Extensions The design system extends into the Sanity Studio through custom UI components designed for content creators. A primary example is the `FetchWebsiteDataButton`, which uses `@sanity/ui` primitives to provide an automated data enrichment tool. **Logic Flow for Website Data Fetching:** 1. User enters a URL in the Studio. 2. `FetchWebsiteDataButton` triggers a proxy request to an internal API (`/api/websites/fetch-og`). 3. The API extracts OpenGraph (OG) tags (title, description, image). 4. The component auto-fills Studio fields and uploads the cover image as a Sanity asset. ```mermaid sequenceDiagram participant Editor as Studio Editor participant Button as FetchWebsiteDataButton participant Proxy as API Proxy participant External as Target Website Editor->>Button: Click "Fetch Data" Button->>Proxy: GET /api/websites/fetch-og?url=... Proxy->>External: Scrape OG Tags External-->>Proxy: HTML with meta tags Proxy-->>Button: JSON (title, desc, imageUrl) Button->>Button: Upload image to Sanity Assets Button->>Editor: Patch Document Fields ``` Sources: [src/sanity/components/fetch-website-data-button.tsx:187-216](), [src/sanity/components/fetch-website-data-button.tsx:120-155]() ## Integration and Tooling The design system is managed via standard Node.js/Bun scripts and integrated through a robust type-generation pipeline. * **Type Generation:** The `typegen` script extracts the Sanity schema into `src/sanity/extract.json` and generates TypeScript types in `src/sanity/types.ts`. * **Styling:** Tailwind CSS 4 is used for utility-first styling, with custom theme extensions defined in `src/app/globals.css` (referenced by usage in components). * **Accessibility:** Radix UI primitives provide the underlying accessibility layer for all complex interactive components. Sources: [package.json:10-12](), [package.json:28-40]() ## Conclusion The Pittogramma Design System & UI Components module provides a unified architecture for both the public-facing platform and the administrative Sanity Studio. By combining generic shadcn/ui primitives with specialized business modules and automated CMS tools, the system maintains high technical standards and content consistency while streamlining the editorial process for designers and studios. Sources: [src/app/(frontend)/design-system/page.tsx](), [src/sanity/types.ts]()