Atomic Design in Nucleify – Build Consistent and Scalable UIs

Nucleify implements the Atomic Design methodology to create UI systems that are consistent, maintainable, and scalable.

What is Atomic Design?

Atomic Design, created by Brad Frost, breaks user interfaces into fundamental building blocks. Inspired by chemistry, it organizes components in a hierarchy from the smallest elements to complete pages.

Key Benefits:

• Consistency – reusable components ensure a unified look
• Maintainability – changes propagate automatically across the system
• Scalability – easily extend functionality without breaking existing components
• Collaboration – clear structure improves teamwork

Core Principle: No Business Logic

Atomic Design components should not contain business logic. Components only handle functionality related to their UI behavior:

✅ Allowed	❌ Not Allowed
Input validation (format, length)	Hardcoded API calls
Animations and transitions	Direct data fetching
Local component state	Store mutations
Event emission	Hardcoded URLs or endpoints
Render based on props	Auth checks or domain-specific logic
Accessibility functions	Domain-specific calculations
Configurable callbacks via props	Rigid business rules
Generic event handlers	Hardcoded configuration

Business logic belongs to:

• Stores (Pinia)
• Composables
• Services

Nucleify Extensions

Nucleify extends standard Atomic Design with modules where business logic is allowed:

Module	Purpose
nuc_templates	Reusable component templates (cards, forms, modals)
nuc_sections	Page sections with layout logic, data handling, and section-specific behavior
nuc_pages	Full page components with API calls, store access, and business rules

These modules are separated from nuxt/atomic/ to keep UI components clean and reusable.

Hierarchy Overview

Nucleify introduces an additional Bosons layer for types and utilities.

Bosons     → Interfaces, utility functions, constants (invisible layer)
Atoms      → Basic UI elements (Button, Input, Icon)
Molecules  → Simple atom combinations (FloatLabel, Tile)
Organisms  → Complex UI sections (DataTable, Dialog, Menu)
Templates  → Reusable component layouts (nuc_templates)
Sections   → Page sections with logic (nuc_sections)
Pages      → Full pages with API calls and store access (nuc_pages)

Bosons – The Invisible Foundation

Bosons are the smallest, indivisible units of reusable logic. They don’t render anything but form the foundation for all components:

// types/interfaces.ts
export interface ButtonInterface {
  label?: string
  variant?: 'primary' | 'secondary' | 'danger'
  disabled?: boolean
}

// utils/format_date.ts
export function formatDate(date: Date): string {
  return new Intl.DateTimeFormat('en-US').format(date)
}

// constants/breakpoints.ts
export const BREAKPOINTS = {
  mobile: 768,
  tablet: 1024,
  desktop: 1440,
} as const

Atoms – Basic Visual Elements

Atoms are the smallest UI components that can’t be broken down further without losing meaning. Examples: Button, Input, Icon, Label, Badge, Checkbox, Avatar.

Allowed logic:

• Handle click/focus/hover events
• Manage internal state (e.g., input value)
• Conditional styling based on props
• Emit events to parent

<template>
  <button :class="[$style['ad-button'], variant && $style[variant]]" :disabled="disabled" @click="$emit('click', $event)">
    <slot />
  </button>
</template>

<script setup lang="ts">
import type { ButtonInterface } from './types'
defineProps<ButtonInterface>()
defineEmits<{ click: [event: MouseEvent] }>()
</script>

Molecules – Simple Combinations

Molecules combine atoms into functional units while maintaining simplicity. Examples: FloatLabel, Anchor, Tile.

Allowed logic:

• Coordinate child atom states
• Simple computed values
• Local validation (format only, no business rules)

Organisms – Complex Sections

Organisms are composed of molecules, atoms, or other organisms. They are still purely presentational. Examples: DataTable, Dialog, Menu, Card.

Allowed logic:

• Render data passed via props
• Local filtering/sorting of provided data
• Manage open/close states
• Emit user interaction events

Not allowed: API calls or store access.

Templates, Sections, and Pages

• Templates (nuc_templates) – reusable layouts for cards, forms, modals; business logic allowed
• Sections (nuc_sections) – page blocks combining templates and organisms with layout and data logic
• Pages (nuc_pages) – full pages connecting UI components with stores and API calls

Best Practices

1. Keep components clean – predictable outputs, no side effects
2. Props down, events up – parent handles business logic
3. Single responsibility – each component does one thing well
4. Use TypeScript interfaces – type-safe props and data