Guide to combining Atomic methodology and Colocation principles in Next.js

Overview

This guide serves the purpose of explaining how to effectively combine atomic design with colocation. This approach leverages the benefits of both methdologies to organize your components and pages in a scalable and maintainable way.

Atomic Design Overview

Atomic design is a methodology for creating design systems by breaking down UI components into a hierarchy:

1. Atoms

Simplest components and cannot be broken down further. Basic HTML elements or simple dummy components that provide functionality or visual elements.

• Basic, reusable element.
• Focus on single functionality or appearance.
• Does not have any outter margin/padding.

Basic Examples

Button

export default function Button({ onClick, children }) {
  return <button onClick={onClick}>{children}</button>;
}

Input

export default function Input({ placeholder, value, onChange }) {
  return <input placeholder={placeholder} value={value} onChange={onChange} />;
}

2. Molecules

Groups of atoms that work together as a unit. Combine multimple atoms to form a functional group that performs a specific function or represent a piece of the UI.

• Must be composed of atoms.
• More complex and functional then atoms.
• Can have inner spacings and layout controllers that affect Molecule and nothing outside of it.

Basic Examples

Form

export default function Form({
  headingVariant,
  heading,
  onChange,
  placeholder,
  value,
  onClick,
  buttonLabel,
}) {
  return (
    <div className="flex flex-col gap-y-4">
      <Heading variant={headingVariant}>{heading}</Heading>
      <Input onChange={onChange} placeholder={placeholder} value={value} />
      <Button onClick={onClick}>{buttonLabel}}</Button>
    </div>
  );
}

3. Organisms

Complex components that consist of groups of molecules and atoms. They represent sections or parts of a UI that work together to form a functional area.

• Composed of molecules, atoms and other organisms.
• Has to represent sections of a page or UI.
• Can affect outter layout outside of organism.

Basic Examples

Header

import Logo from "../Atoms/Logo.tsx
Import Form from "../Molecules/Form.tsx"
 
export default function Header({
  headingVariant,
  heading,
  onChange,
  placeholder,
  value,
  onClick,
  buttonLabel,
}) {
  const handleOnClick = () => console.log("Click me hard")
  const handleOnChange = () => console.log("On change, change me")
 
  return (
    <header className="flex flex justify-between">
        <Logo>
            <Image src="https://example-url" width={200} height={200} />
        </Logo>
        <Form
            headingVariant="primary",
            heading="Super cool organism"
            onChange={handleOnChange}
            placeholder="Some wierd placeholder"
            value={value}
            onClick={handleOnClick}
            buttonLabel="Click me!!"
         />
    </header>
  );
}

2. Colocation

Involves placing related files together in the same directory.

3. Combining Atomic Design and Colocation

This section explains how to effectively cmbine these two principles in a project.

• Centralized Shared Components
• Organized by atomic design principles
  • Atoms -> basic elements
  • Molecules -> combination of atoms
  • Organisms -> for complex UI or page sections

/components
--/Atoms
--/Molecules
--/Organisms

• Colocated Page-Specific Components
• Organized by colocation principles
  • Use Route Groups to indicate this folder is for organizational purposes and its not included in routes URL path

(home)
--/page.tsx
--/UICardSpecificForHomepage
----/UICardSpecificForHomepage.tsx
----/index.ts

4. Naming conventions

• Shared Components
  • Name components clearly to indicate their role and scope
• Pace-Specific components
  • Prefix page-specific components with the page name to distinguish their scope -- Eg. HomeBanner.tsx

5. Benefits of this approach

• Improved organization: Clear separation between shared and page-specific components, project is easier to navigate
• Reusability: Centralized components are designed for reuse, reducing duplication.
• Scalability: This structure supports scaling as the project grows by keeping components and pages organized
• Maintainability: Colocation page-specific files helps in managing related change more effectively

6. Q/A

What if non-shared component becomes shared?

• You move it to coresponding folder in components folder

...Add more