# puranderdua8/ui-design-system architecture

> Architecture diagram of the GitHub repository puranderdua8/ui-design-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/puranderdua8/ui-design-system
- Repository: https://github.com/puranderdua8/ui-design-system

## Overview

This monorepo packages a token-driven React design system and presents it through a portfolio site and interactive playground. The user workflow is to browse the site’s component categories, inspect live examples and their source, then consume the UI package in an application. The README also describes theme variants and token tiers, but their source files are absent from the supplied tree, so those internals are not mapped. Relationships reflect shown imports or documented capabilities; unsampled implementation links are omitted.

Main entry points: [`packages/ui/src/index.ts`](https://github.com/puranderdua8/ui-design-system/blob/main/packages/ui/src/index.ts) (Package exports), [`packages/ui/src/components`](https://github.com/puranderdua8/ui-design-system/tree/main/packages/ui/src/components) (Form controls), [`apps/site/src/app/components/[category]/page.tsx`](https://github.com/puranderdua8/ui-design-system/blob/main/apps/site/src/app/components/%5Bcategory%5D/page.tsx) (Category pages), [`apps/site/src/app/components/page.tsx`](https://github.com/puranderdua8/ui-design-system/blob/main/apps/site/src/app/components/page.tsx) (Category index)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_showcase["Site showcase"]
  node_home["Portfolio home<br/>[page.tsx]"]
  node_category_index["Category index<br/>[page.tsx]"]
  node_category_page["Category pages<br/>[page.tsx]"]
  node_category_data["Category definitions<br/>[categories.ts]"]
  node_category_content["Category examples<br/>[category-pages.tsx]"]
  node_example_frame["Example frame<br/>[example.tsx]"]
end

subgraph group_ui["UI package"]
  node_typography["Typography"]
  node_actions["Actions"]
  node_layout["Layout"]
  node_forms["Form controls"]
  node_display["Display components"]
  node_field["Field wiring<br/>[field.tsx]"]
  node_fieldset["Fieldset wiring<br/>[fieldset.tsx]"]
  node_select["Select control<br/>[select.tsx]"]
  node_ui_exports["Package exports<br/>[index.ts]"]
end

subgraph group_play["Playground"]
  node_playground["CSS playground<br/>[main.tsx]"]
end

subgraph group_themes["Themes"]
  node_theme_variants["Theme variants"]
  node_theme_tokens["Token tiers"]
end

node_visitor(("Site visitor"))

node_visitor -->|"opens"| node_home
node_visitor -->|"browses"| node_category_index
node_category_index -->|"reads categories"| node_category_data
node_category_page -->|"looks up category"| node_category_data
node_category_page -->|"selects content"| node_category_content
node_category_content -->|"renders examples"| node_example_frame
node_example_frame -->|"uses UI components"| node_ui_exports
node_home -->|"uses UI components"| node_ui_exports
node_category_index -->|"uses UI components"| node_ui_exports
node_category_page -->|"uses UI components"| node_ui_exports
node_ui_exports -->|"exports"| node_typography
node_ui_exports -->|"exports"| node_actions
node_ui_exports -->|"exports"| node_layout
node_ui_exports -->|"exports"| node_forms
node_ui_exports -->|"exports"| node_display
node_forms -->|"includes"| node_field
node_forms -->|"includes"| node_fieldset
node_forms -->|"includes"| node_select
node_select -->|"reads context"| node_field
node_visitor -->|"previews styles"| node_playground
node_theme_tokens -->|"defines roles"| node_theme_variants
node_theme_variants -.->|"styles components"| node_ui_exports

click node_home "https://github.com/puranderdua8/ui-design-system/blob/main/apps/site/src/app/page.tsx"
click node_category_index "https://github.com/puranderdua8/ui-design-system/blob/main/apps/site/src/app/components/page.tsx"
click node_category_page "https://github.com/puranderdua8/ui-design-system/blob/main/apps/site/src/app/components/%5Bcategory%5D/page.tsx"
click node_category_data "https://github.com/puranderdua8/ui-design-system/blob/main/apps/site/src/lib/categories.ts"
click node_category_content "https://github.com/puranderdua8/ui-design-system/blob/main/apps/site/src/components/category-pages.tsx"
click node_example_frame "https://github.com/puranderdua8/ui-design-system/blob/main/apps/site/src/components/example.tsx"
click node_typography "https://github.com/puranderdua8/ui-design-system/tree/main/packages/ui/src/components"
click node_actions "https://github.com/puranderdua8/ui-design-system/tree/main/packages/ui/src/components"
click node_layout "https://github.com/puranderdua8/ui-design-system/tree/main/packages/ui/src/components"
click node_forms "https://github.com/puranderdua8/ui-design-system/tree/main/packages/ui/src/components"
click node_display "https://github.com/puranderdua8/ui-design-system/tree/main/packages/ui/src/components"
click node_field "https://github.com/puranderdua8/ui-design-system/blob/main/packages/ui/src/components/field.tsx"
click node_fieldset "https://github.com/puranderdua8/ui-design-system/blob/main/packages/ui/src/components/fieldset.tsx"
click node_select "https://github.com/puranderdua8/ui-design-system/blob/main/packages/ui/src/components/select.tsx"
click node_ui_exports "https://github.com/puranderdua8/ui-design-system/blob/main/packages/ui/src/index.ts"
click node_playground "https://github.com/puranderdua8/ui-design-system/blob/main/packages/ui/playground/src/main.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_home,node_category_index,node_category_page,node_category_data,node_category_content,node_example_frame toneBlue
class node_typography,node_actions,node_layout,node_forms,node_display,node_field,node_fieldset,node_select,node_ui_exports toneAmber
class node_playground toneMint
class node_theme_variants,node_theme_tokens toneRose
class node_visitor toneIndigo
```

## Components

### Site showcase

- [Portfolio home](https://github.com/puranderdua8/ui-design-system/blob/main/apps/site/src/app/page.tsx): `apps/site/src/app/page.tsx`
- [Category index](https://github.com/puranderdua8/ui-design-system/blob/main/apps/site/src/app/components/page.tsx): `apps/site/src/app/components/page.tsx`
- [Category pages](https://github.com/puranderdua8/ui-design-system/blob/main/apps/site/src/app/components/%5Bcategory%5D/page.tsx): `apps/site/src/app/components/[category]/page.tsx`
- [Category definitions](https://github.com/puranderdua8/ui-design-system/blob/main/apps/site/src/lib/categories.ts): `apps/site/src/lib/categories.ts`
- [Category examples](https://github.com/puranderdua8/ui-design-system/blob/main/apps/site/src/components/category-pages.tsx): `apps/site/src/components/category-pages.tsx`
- [Example frame](https://github.com/puranderdua8/ui-design-system/blob/main/apps/site/src/components/example.tsx): `apps/site/src/components/example.tsx`

### UI package

- [Typography](https://github.com/puranderdua8/ui-design-system/tree/main/packages/ui/src/components): `packages/ui/src/components`
- [Actions](https://github.com/puranderdua8/ui-design-system/tree/main/packages/ui/src/components): `packages/ui/src/components`
- [Layout](https://github.com/puranderdua8/ui-design-system/tree/main/packages/ui/src/components): `packages/ui/src/components`
- [Form controls](https://github.com/puranderdua8/ui-design-system/tree/main/packages/ui/src/components): `packages/ui/src/components`
- [Display components](https://github.com/puranderdua8/ui-design-system/tree/main/packages/ui/src/components): `packages/ui/src/components`
- [Field wiring](https://github.com/puranderdua8/ui-design-system/blob/main/packages/ui/src/components/field.tsx): `packages/ui/src/components/field.tsx`
- [Fieldset wiring](https://github.com/puranderdua8/ui-design-system/blob/main/packages/ui/src/components/fieldset.tsx): `packages/ui/src/components/fieldset.tsx`
- [Select control](https://github.com/puranderdua8/ui-design-system/blob/main/packages/ui/src/components/select.tsx): `packages/ui/src/components/select.tsx`
- [Package exports](https://github.com/puranderdua8/ui-design-system/blob/main/packages/ui/src/index.ts): `packages/ui/src/index.ts`

### Playground

- [CSS playground](https://github.com/puranderdua8/ui-design-system/blob/main/packages/ui/playground/src/main.tsx): `packages/ui/playground/src/main.tsx`

### Themes

- **Theme variants**
- **Token tiers**

### Other components

- **Site visitor**

## Connections

- Site visitor → Portfolio home: opens (evidence: `apps/site/src/app/page.tsx`)
- Site visitor → Category index: browses (evidence: `apps/site/src/app/components/page.tsx`)
- Category index → Category definitions: reads categories (evidence: `apps/site/src/app/components/page.tsx`)
- Category pages → Category definitions: looks up category (evidence: `apps/site/src/app/components/[category]/page.tsx`)
- Category pages → Category examples: selects content (evidence: `apps/site/src/app/components/[category]/page.tsx`)
- Category examples → Example frame: renders examples (evidence: `apps/site/src/components/category-pages.tsx`)
- Example frame → Package exports: uses UI components (evidence: `apps/site/src/components/example.tsx`)
- Portfolio home → Package exports: uses UI components (evidence: `apps/site/src/app/page.tsx`)
- Category index → Package exports: uses UI components (evidence: `apps/site/src/app/components/page.tsx`)
- Category pages → Package exports: uses UI components (evidence: `apps/site/src/app/components/[category]/page.tsx`)
- Package exports → Typography: exports (evidence: `packages/ui/src/index.ts`)
- Package exports → Actions: exports (evidence: `packages/ui/src/index.ts`)
- Package exports → Layout: exports (evidence: `packages/ui/src/index.ts`)
- Package exports → Form controls: exports (evidence: `packages/ui/src/index.ts`)
- Package exports → Display components: exports (evidence: `packages/ui/src/index.ts`)
- Form controls → Field wiring: includes (evidence: `packages/ui/src/index.ts`)
- Form controls → Fieldset wiring: includes (evidence: `packages/ui/src/index.ts`)
- Form controls → Select control: includes (evidence: `packages/ui/src/index.ts`)
- Select control → Field wiring: reads context (evidence: `packages/ui/src/components/select.tsx`)
- Site visitor → CSS playground: previews styles (evidence: `packages/ui/playground/src/main.tsx`)
- Token tiers → Theme variants: defines roles
- Theme variants → Package exports: styles components