[IDEA] Adopt Atomic Design for Shared UI

[kyra0126]

📅 Date

2025-08-20

💡 Idea

Refactor the shared/ui folder using Atomic Design principles to improve reusability, scalability, and clarity.
This approach separates generic design system components from feature/domain-specific components, ensuring the codebase remains maintainable as the portfolio project grows.

---

Why Atomic Design?

• Atoms: The smallest, indivisible components (Button, Tag, Icon, Toggle, etc.)
• Molecules: Combinations of atoms forming small functional units (Card, LanguageMenu, etc.)
• Organisms: Larger independent blocks with meaning (Navbar, Footer, Hero, etc.)
• Layout: Wrappers responsible for consistent spacing and structure (Container, Section, Grid, etc.)

Benefits

• Reusability: Atoms like Button are consistent and reusable across the app.
• Scalability: Molecules and Organisms scale without collapsing into a flat UI folder.
• Separation of Concerns: Domain-specific components stay in features/, while the design system lives in shared/ui/.
• Layout Consistency: Dedicated shared/layout ensures uniform spacing, grid, and section wrappers.

---

📂 Suggested Folder Structure

shared/
  hooks/            # Generic React hooks (useMediaQuery, useMounted, etc.)
  lib/              # Pure utility functions (clsx, fetcher, etc.)
  types/            # Global types (Theme, Locale, etc.)
  styles/           # CSS tokens + Tailwind entrypoint
  layout/           # Layout-only components (Container, Section, Grid)
  ui/
    atoms/          # Button, Tag, Icon, ModeSwitch
    molecules/      # Card, LanguageMenu, SectionHeader
    organisms/      # Navbar, Footer, Hero

[kyra0126]

Atoms (Build First)

Component	Role	Required Props	Variants/States	O/X
Button	Basic action trigger	Label/slot	Size (sm/md/lg/hero), Style (solid/outline/ghost), Icon (left/right), Full width, Loading/Disabled	✅
Tag/Chip	Label for skills/categories	Text	Tone (primary/neutral/success), Size, With/without icon	✅
Icon	Icon wrapper	Name/node	Size, Alt text
Typography	Consistent headings/body	Level (H1/H2/H3/Body)	Align, Weight, Tone	✅
Link	Styled link (internal/external)	Text/slot, href	External flag, Underline (always/hover)
Divider	Section divider	None	Spacing (dense/normal)
Avatar	Profile/project logo	Image/initials	Size, Shape (circle/rounded)
Badge	Status indicator	Text	Color (Info/Success/Warning), Icon
ModeSwitch	Theme toggle	None	State (light/dark/system)	✅
Input	Text input	Value/placeholder	State (default/focus/error), Helper text
Textarea	Multiline input	Value	Rows, State
Select	Option selector	Options array	State, Icon, With label

---

Molecules

Component	Role	Required Props	Variants/States	Priority
SectionHeader	Section heading	Title	Subtitle, Action button (right side)
Card	Content container	Title/Body (optional)	Divider yes/no, Shadow level, Media slot
LanguageMenu	Language dropdown	Current language	Menu alignment, Icon display
KeyValue	Label : Value pair	Items array	Density (dense/normal), Divider
ListItem	List row	Title	Subtext, Right-side action, Icon
MetricItem	Highlighted metric	Label/Value	Icon, Align
SkillTagList	Group of tags	Tag array	Wrap/scroll, Max count
ContactRow	Icon + link row	Type (mail/github/etc.)	External flag, Subtext
CardHeader	Thumbnail + title	Image/Title	Badge, Subtext

---

Organisms

Component	Role	Required Props	Variants/States	Priority
Navbar	Top navigation	Menu list	Sticky, Active item highlight, Includes Mode/Language
Footer	Bottom info	Social links / copyright	Compact/expanded layout
Hero	Intro section	Title/Description	Align (left/center), Avatar, CTA button
ProjectsGrid	Grid of project cards	Project array	Columns (responsive), Pagination/Load more
ProjectCard	Project summary card	Title/Image/Summary	Tags, Links (Detail/Repo), Badge
Timeline	Education/Experience/Awards timeline	Items array	Orientation, Density
AboutSection	Profile/about block	Description text	Tech/Soft skills included
ContactSection	Contact area	Intro text	Link buttons / form

---

Layout (Wrapper Components)

Component	Role	Required Props	Variants/States	Priority
Container	Max-width + padding wrapper	None	Size (sm/md/lg/xl), Centered	✅ High
Section	Vertical spacing + title/body wrapper	Title (optional)	Spacing scale, Background (plain/subtle)	✅
Grid	Grid utility	Columns/gap	Breakpoint configs