⚛️ Developing a Scalable React App with Atomic Design and LLMs

“Clean code is a love language. So is yelling at your LLM when it hallucinates a non-existent API.”

Aug 04, 2025

In this post, we’re combining Atomic Design (your UI’s best structural friend) with Large Language Models (the AI sidekick who mostly knows what it’s doing) to build a React app that’s modular, maintainable, and doesn’t cry when scaled.

We’ll go from zero to well-structured hero—bootstrapping the architecture, training the LLM with your design system, and building components from atoms to pages like a software biologist with TypeScript.

The result? A codebase that’s clean, testable, and smart enough to play nice with AI tools. Think scalable structure meets AI-assisted speed—without sacrificing sanity or style.

This isn’t just code—it’s architecture with sarcasm, structure, and a side of /dev/null. Let’s build something that won’t fall apart by sprint four.

🧬 What the Heck is Atomic Design (in React)?

You ever look at your React codebase and feel like it’s a Jenga tower built entirely out of divs and regret?

Yeah. That’s where Atomic Design comes in—a methodology by Brad Frost that helps you build UIs like an engineer, not a caffeine-fueled raccoon smashing components together.

Applied to React, it’s all about breaking your UI into logical layers—from the tiniest pixel-pushers to full-blown pages—so your app doesn’t melt the moment you add a new feature.

🔗 The Hierarchy: UI, But Make It Modular

Atomic Design splits components into five levels—think chemistry class, but with better variable names.

🧪 Atoms

The smallest possible React pieces. Simple. Reusable. Dumb as bricks (in a good way).
Examples:

<Button />
<Input />
<Label />
<Icon />

🧬 Molecules

When atoms team up to do something useful.
Think: a button with an icon or a labeled input field.
Examples:

<SearchInput /> = <Label /> + <Input />
<IconButton /> = <Button /> + <Icon />

🧫 Organisms

Now we’re cookin’. These are full-blown UI chunks made from molecules and atoms.
Examples:

<Navbar /> with logo, search, and user dropdown
<Card /> with image, title, and action button

📐 Templates

Layout blueprints. They show structure, not content—like a wireframe in JSX.
Examples:

Blog post layout
Dashboard scaffold

📄 Pages

Templates brought to life with real data. These are your route-level React components.
Examples:

/profile
/dashboard
/404 (when your router gives up)

✅ Why This Isn’t Just Fancy Folder Naming

Consistency – No more "button-v2-final-FINAL.jsx"
Reusability – Build it once, use it everywhere.
Testability – Small parts = easy unit tests + fewer headaches.
Scalability – Want to grow the app? Do it without rage refactors.

🤖 How Large Language Models Actually Work (No Magic, Just Math and Mayhem)

You’ve probably heard that LLMs like GPT, Claude, or LLaMA are changing the game. True. But they’re not sorcerers—they're just glorified matrix calculators with an uncanny knack for language. Let’s unpack how they work without summoning a PhD thesis.

🧾 How to Prompt Like a Pro (LLM Edition)

If you’re slinging code with the help of an LLM, you're not just writing prompts—you’re programming the programmer. And in this case, your programmer is a blazingly fast intern with the IQ of a potato and the confidence of a senior architect.

LLMs are lightning-fast, but dumb as bricks without context. They’ll happily invent APIs, over-engineer a <Button>, and give you TypeScript errors wrapped in poetic nonsense—unless you teach them like you're onboarding a caffeine-fueled junior on their first day.

This section lays out a three-tiered prompting strategy tailored for React projects using Atomic Design. Each prompt type has a purpose. Used together, they guide your overenthusiastic AI sidekick to follow your structure, respect your theme, and—ideally—not hallucinate its way into architectural chaos.

Treat it like a powerful-but-distracted intern. Give it clarity, guardrails, and no room for interpretation.

And maybe hide the deploy button.

🎓 Teaching Prompts: Train the Bot, Don’t Just Ask It to Build

These are your foundational prompts—the onboarding docs for your LLM. Their job? Load context into the model's brain without triggering any code output. Think of it as setting up your team before they touch the repo.

🧠 Golden Rule:
No code. No implementation. Just confirm understanding like a good intern.

🧱 Explain the Project (Atomic Design FTW)

Prompt:

You are a Senior React + Vite + Tailwind Developer who speaks fluent Atomic Design.
The project structure is layered into Atoms, Molecules, Organisms, Layouts, and Pages.
Your job is to fully understand this structure so you can implement accordingly.
Do not write code. Just confirm understanding.

✔️ Why it works:
It sets expectations, defines structure, and builds shared mental models—without jumping the gun.

🎓 Result : Noting Said Confirmed and explani what confirmd.

🎨 Explain Theme + Colors (Design Systems Matter)

Prompt:

You’ll be using a custom theme that includes a design palette, spacing rules, shadow depth, and border radii.
The theme is passed via a ThemeProvider.
Reference Material Blue for style logic, but adapt to the custom setup.
Do not implement anything. Just confirm you get it.

✔️ Why it works:
It teaches the model how the UI should look and feel before it starts suggesting rainbow gradients in Comic Sans.

🎓 Result : Noting Said Confirmed and explani what confirmd.

🔤 Explain Typography (Fonts Are Not a Vibe—They’re a System)

Prompt:

Understand the typography spec for this project. That includes:
Font families (Inter, Roboto)
Font sizes (xs to 5xl)
Font weights
Theming-based text colors
Line height + letter spacing as needed
These are part of the theme and used globally.
Do not generate code. Just acknowledge.

✔️ Why it works:
It primes the LLM to respect visual hierarchy and consistency, not free-styling font styles like it’s a MySpace page.

🎓 Result : Noting Said Confirmed and explani what confirmd.

🧪 Initial Prompts: Sanity-Checking Before We Code Ourselves Into a Corner

Not every prompt should yell “CODE!” at your LLM. Sometimes, what you need is a vibe check—a quiet brainstorm, a dry run, or a gentle “Are we sure this architecture won’t collapse in two sprints?”

These initial prompts are for exploration. They help your AI buddy think before it types. No code. No commit. Just ideas, structures, and architectural gut checks.

🔍 What These Prompts Are Good For

💡 Asking “How would you build X?” without ending up with 200 lines of hallucinated JSX
🧱 Getting logical breakdowns of Atomic Design layers
🏗️ Evaluating different architecture paths
🕵️ Spotting missing pieces in your folder structure or design system

Basically: architecture therapy sessions with your LLM.

🧱 Prompt: Create Project Directory Structure

Generate the full base folder structure for a React project using Atomic Design principles.
Include folders like:
src/components/atoms/
src/components/molecules/
src/components/organisms/
src/components/layouts/
src/pages/
src/theme/
src/hooks/
src/utils/
For each folder, create one sample subfolder with an index.ts(x) file.
Use placeholders or empty files (README.md, index.ts) to scaffold.
Return it as a tree-style directory listing and Guide me To Implement With npx
🚫 DO NOT implement components or logic. Just the file skeletons—this is scaffolding, not shipping.

✔️ Why it matters:
It helps align project structure with your design principles before your team starts building FinalComponent_v3_copy.jsx.

🧪 Result : Guide You To Create Your React Project and Create Atomic Struct

Note : If You Can Not Create React Project , Close This Blog.

🎨 Prompt: Create Project Theme Provider

Build a standalone theme system using styled-components or @emotion.
Requirements:
Set up a ThemeProvider with light/dark mode support
Include a theme object with:
Material Blue-inspired color palette
Typography (Inter/Roboto, font sizes, weights)
Spacing, radii, and shadow tokens
Provide a global context or custom hook for access
Type it properly with ThemeType or interface
📁 Directory: src/theme/
📄 Files:
theme.ts (core definitions)
ThemeProvider.tsx (React wrapper)
types.ts (for your precious TypeScript)

🚫 DO NOT integrate this with pages or components yet. This is theme logic in isolation—like mood lighting before furniture.

✔️ Why it matters:
You’ll get structured, reusable theme infrastructure before your UI starts fighting about font sizes and shadow depths.

🧪 Result : Guide To implement ThemeProvider, theme.ts, types.ts

// src/theme/ThemeProvider.tsx

import React, { createContext, useContext, useMemo, useState } from 'react';
import { ThemeProvider as StyledThemeProvider } from 'styled-components';
import { lightTheme, darkTheme } from './theme';
import { ThemeType } from './types';

type ThemeMode = 'light' | 'dark';

interface ThemeContextProps {
  mode: ThemeMode;
  toggleTheme: () => void;
  theme: ThemeType;
}

const ThemeContext = createContext<ThemeContextProps | undefined>(undefined);

export const useTheme = (): ThemeContextProps => {
  const context = useContext(ThemeContext);
  if (!context) {
    throw new Error('useTheme must be used within ThemeProvider');
  }
  return context;
};

export const AppThemeProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
  const [mode, setMode] = useState<ThemeMode>('light');

  const toggleTheme = () => setMode((prev) => (prev === 'light' ? 'dark' : 'light'));

  const theme = useMemo(() => (mode === 'light' ? lightTheme : darkTheme), [mode]);

  const contextValue: ThemeContextProps = {
    mode,
    toggleTheme,
    theme,
  };

  return (
    <ThemeContext.Provider value={contextValue}>
      <StyledThemeProvider theme={theme}>{children}</StyledThemeProvider>
    </ThemeContext.Provider>
  );
};

⚙️ Implementation Prompts (a.k.a. Build Time, Baby)

Welcome to the part where stuff gets real. By now, your LLM knows the project's vibe—Atomic structure, theme rules, and typography quirks. It’s fully briefed and caffeinated.

These Implementation Prompts are the heavy lifters. They generate actual, production-ready code—layer by layer, from atoms to pages. Each prompt follows strict rules: type-safe, theme-aware, and folder-disciplined.

Because if your components don’t follow the structure, they don’t get deployed. That’s the law.

⚛️ Prompt: Create Button Atom

📁 src/components/atoms/Button/
Build a reusable Button component that speaks fluent theme.
✅ Requirements:
Props: children, variant (primary, secondary), size (sm, md, lg), onClick, disabled
Use theme values for:
Background & text color
Padding & border-radius
Hover, focus, and disabled states
Styled with Emotion or styled-components
TypeScript FTW
Must support dark/light modes via ThemeProvider
Structure:
Button.tsx

🛠️ Result: A full Button atom

import React from 'react';
import styled, { css } from 'styled-components';

type Variant = 'primary' | 'secondary';
type Size = 'sm' | 'md' | 'lg';

interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  children: React.ReactNode;
  variant?: Variant;
  size?: Size;
}

const variantStyles = {
  primary: css`
    background-color: ${({ theme }) => theme.colors.primary};
    color: ${({ theme }) => theme.colors.text};
  `,
  secondary: css`
    background-color: ${({ theme }) => theme.colors.secondary};
    color: ${({ theme }) => theme.colors.text};
  `,
};

const sizeStyles = {
  sm: css`
    padding: ${({ theme }) => `${theme.spacing.xs} ${theme.spacing.sm}`};
    font-size: ${({ theme }) => theme.typography.fontSize.sm};
  `,
  md: css`
    padding: ${({ theme }) => `${theme.spacing.sm} ${theme.spacing.md}`};
    font-size: ${({ theme }) => theme.typography.fontSize.base};
  `,
  lg: css`
    padding: ${({ theme }) => `${theme.spacing.md} ${theme.spacing.lg}`};
    font-size: ${({ theme }) => theme.typography.fontSize.lg};
  `,
};

const StyledButton = styled.button<Required<Pick<ButtonProps, 'variant' | 'size'>>>`
  border: none;
  border-radius: ${({ theme }) => theme.radii.md};
  font-family: ${({ theme }) => theme.typography.fontFamily};
  font-weight: ${({ theme }) => theme.typography.fontWeight.medium};
  cursor: pointer;
  transition: background-color 0.2s, box-shadow 0.2s;

  ${({ variant }) => variantStyles[variant]};
  ${({ size }) => sizeStyles[size]};

  &:hover:not(:disabled) {
    box-shadow: ${({ theme }) => theme.shadows.md};
  }

  &:focus {
    outline: 2px solid ${({ theme }) => theme.colors.primary};
    outline-offset: 2px;
  }

  &:disabled {
    opacity: 0.6;
    cursor: not-allowed;
    box-shadow: none;
  }
`;

export const Button: React.FC<ButtonProps> = ({
  children,
  variant = 'primary',
  size = 'md',
  ...rest
}) => {
  return (
    <StyledButton variant={variant} size={size} {...rest}>
      {children}
    </StyledButton>
  );
};

🔤 Prompt: Create TextField Atom

📁 src/components/atoms/TextField/
Because every app needs inputs—and no, <input type="text" /> doesn’t cut it.
✅ Requirements:
Props: label, value, onChange, placeholder, error
Renders a styled <label> + <input>
Theme-based styling (spacing, font, colors)
If error is true, show red border + helper text
Structure:
TextField.tsx

Bonus: Impress your future self by making it accessible.

🛠️ Result: Run it yourself—I’m not your terminal monkey

🔐 Prompt: Create InputPassword Atom

📁 src/components/atoms/InputPassword/
A password field that doesn’t suck.
✅ Requirements:
Props: value, onChange, placeholder, label, error
Show/hide password with a toggle (eye icon)
Theme-based styling, red for errors
Internal toggle state + a11y labels

🛠️ Result: Run it yourself—I’m not your terminal monkey

🔘 Prompt: Create IconButton Atom

📁 src/components/atoms/IconButton/
A button that only shows an icon—but it better be pixel-perfect.
✅ Requirements:
Props: icon, onClick, ariaLabel, variant (default, ghost)
Theme styling for color, padding, radius, hover/focus
Optional props for rounded or square variant
44px min touch target (because fingers exist)
Styled with Emotion or styled-components

🚫 No invisible click zones. We respect thumbs here

🛠️ Result: Run it yourself—I’m not your terminal monkey

🧪 Prompt: Create LoginForm Molecule

📁 src/components/molecules/LoginForm/
Your login form deserves better than two <input>s and vibes.
✅ Requirements:
Use:
TextField for username
InputPassword for password
Button or IconButton for submission
Props: onSubmit (returns { username, password })
Local state: useState for input values
Disable submit if fields are empty
Stack vertically using theme spacing
Accessibility-first (label hooks, aria as needed)
Structure:
LoginForm.tsx

🛠️ Result: A beautifully styled form, straight outta your atom toolkit

import React, { useState } from 'react';
import styled from 'styled-components';
import { Button } from '../../atoms/Button';
// Assuming these two exist and are built like Button
import { TextField } from '../../atoms/TextField';
import { InputPassword } from '../../atoms/InputPassword';

interface LoginFormProps {
  onSubmit: (data: { username: string; password: string }) => void;
}

const Form = styled.form`
  display: flex;
  flex-direction: column;
  gap: ${({ theme }) => theme.spacing.md};
  width: 100%;
  max-width: 400px;
`;

export const LoginForm: React.FC<LoginFormProps> = ({ onSubmit }) => {
  const [username, setUsername] = useState('');
  const [password, setPassword] = useState('');

  const isDisabled = !username || !password;

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    if (!isDisabled) {
      onSubmit({ username, password });
    }
  };

  return (
    <Form onSubmit={handleSubmit} aria-label="Login form">
      <TextField
        id="username"
        label="Username"
        value={username}
        onChange={(e) => setUsername(e.target.value)}
        required
        aria-required="true"
      />

      <InputPassword
        id="password"
        label="Password"
        value={password}
        onChange={(e) => setPassword(e.target.value)}
        required
        aria-required="true"
      />

      <Button type="submit" disabled={isDisabled}>
        Log In
      </Button>
    </Form>
  );
};

🧬 Prompt: Create AuthCard Organism

📁 src/components/organisms/AuthCard/
Because a naked login form floating in space looks... weird.
✅ Requirements:
Contains LoginForm molecule
Wrap with a styled card:
Header title (“Welcome Back”)
Optional subtitle/helper text
Props: onSubmit, title (optional override)
Style: theme-based background, spacing, shadows, radius
Vertically centered layout
Structure:
AuthCard.tsx

🛠️ Result: Don’t just read—build it. Your brain and fingers were literally designed for this

🧱 Prompt: Create AuthLayout Layout

📁 src/components/layouts/AuthLayout/
It’s a layout, not a design afterthought.
✅ Requirements:
Full-page container for auth flows
Center AuthCard both vertically and horizontally
Themed background (solid or gradient, your call)
Optional: add branding or visuals
Responsive by default
Props:
children (slot for AuthCard or other components)
Structure:
AuthLayout.tsx

🛠️ Result: Yep, it’s a 404—but at least it’s a good-looking one

📄 Prompt: Create LoginPage Page

📁 src/pages/LoginPage/
It’s all been leading to this.
✅ Requirements:
Use AuthLayout to wrap
Render AuthCard with onSubmit handler
For now: mock the handler (console.log works)
Route: /login
Structure:
LoginPage.tsx

🛠️ Result: A login page so clean, it practically logs you in out of respect

import React from 'react';
import { AuthLayout } from '../../components/layouts/AuthLayout';
import { AuthCard } from '../../components/organisms/AuthCard';

export const LoginPage: React.FC = () => {
  const handleLogin = (credentials: { username: string; password: string }) => {
    console.log('Login submitted:', credentials);
    // TODO: Replace with real login logic
  };

  return (
    <AuthLayout>
      <AuthCard onSubmit={handleLogin} />
    </AuthLayout>
  );
};

🧠 Final Word:

These prompts are where thinking turns into shipping. They give your LLM precise orders, structured logic, and clear constraints—so what you get isn’t junk, guesswork, or some cursed markup from the prompt graveyard.

Smart architecture + clean prompts = fewer refactors, better DX, and code that doesn’t make you cry at 2 AM.

And here’s the fun part:
Once you master this flow, you can repurpose it to build intelligent dev agents or even Modular Code Producers (MCPs)—LLM-powered workflows that scaffold, reason, and generate like that one hyperactive intern… but on steroids and without the energy drinks.

Train once, reuse forever.
Prompts become systems. Systems become agents. Agents become your secret weapon.

Let the humans sleep—your AI team is clocked in.

Amirmohammad Shakeri

Discussion about this post