# Component Driven UI Design

> Atomic Design - maximizing reusability, consistency, and visual hierarchy.

- Skill: `lucas-martino/component-driven-ui-design` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add lucas-martino/component-driven-ui-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lucas-martino/component-driven-ui-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: lucas-martino (https://skillmd.com/u/lucas-martino)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/lucas-martino/component-driven-ui-design

---


# Component-driven UI design (Atomic Design)

**Context:** Enterprise Use: Architecture for frontend, excellent for ensuring visual consistency.
**Focus:** "Compositional UI". Breaking down interfaces into fundamental building blocks to create a robust, scalable Design System.
**Strengths:** Enforces visual consistency, simplifies testing, facilitates "White-Labeling", and creates a shared vocabulary between Design and Dev.
**Weaknesses:** Can feel tedious for simple pages, "naming things" becomes hard (is it a molecule or organism?), and risk of "Prop Drilling" if not managed well.

---

## 1 The Component Hierarchy
The agent must enforce the strict separation of components based on their complexity and responsibility:

1.  **Base UI (Atoms):**
    * Indivisible UI elements (e.g., `Button`, `Input`, `Label`, `Icon`).
    * **Constraint:** strictly visual, **zero** business logic, **zero** external dependencies.
2.  **Simple Groups (Molecules):**
    * Collections of atoms functioning as a unit (e.g., `SearchField` = Input + Button, `FormLabel` = Label + Icon).
    * **Constraint:** Layout-agnostic (should look good anywhere).
3.  **Complex Sections (Organisms):**
    * Distinct sections of an interface (e.g., `Header`, `ProductGrid`, `Footer`).
    * **Constraint:** Can contain business context but should remain "dumb" regarding *fetching* data (receive data via props).
4.  **Layouts (Templates):**
    * Page-level layout structures without real content (e.g., `DashboardLayout`, `BlogLayout`).
    * **Constraint:** Focus on grid/positioning (Grid, Flexbox), defining *where* components sit.
5.  **Instances (Pages):**
    * Specific instances where templates meet real data.
    * **Constraint:** This is the "Smart Component" layer. Connects to Stores/Hooks/APIs and passes data down.

---

## 2 Mandatory Heuristics
-   **Context Agnostic (No Margins):** Atoms and Molecules must **NOT** have external margins (e.g., `margin-right`). Spacing is the responsibility of the parent (Organism/Template) or a layout wrapper.
-   **Dumb Components:** Atoms and Molecules must be "Pure Functions" of their props. They render solely based on input and emit events (`onClick`, `onChange`) for actions.
-   **Composition over Complexity:** Instead of adding 10 boolean flags to a component (e.g., `isBlue`, `isLarge`, `hasIcon`), compose smaller components or use "Variants".
-   **Strict Upward Dependency:** An Atom can never import a Molecule. A Molecule can never import an Organism. Dependencies strictly flow **upwards**.

---

## 3 Rejection Criteria (Hard Fails)
-   **Business Logic in Atoms:** Importing a Store, Service, or API Client inside an Atom (e.g., `Button` calling `UserAPI`).
-   **Layout-Specific Styles in Reuse:** Hardcoding widths (e.g., `width: 300px`) in an Atom/Molecule, making it unusable in a responsive grid.
-   **Circular Dependencies:** A component importing a parent or sibling from a higher layer (e.g., a `Card` importing the `Page` context).
-   **HTML Element Leakage:** Exposing raw HTML props globally without encapsulation (unless intended).

---

## 4 Review Checklist
* [ ] Can I drop this Molecule into a completely different page and it still looks/works correctly?
* [ ] Are all external margins handled by the parent container, not the component itself?
* [ ] Is the component name derived from what it *is*, not what it *does* (e.g., `PrimaryButton` vs `SubmitOrderButton`)?
* [ ] Are Atoms strictly using tokens from the Design System (colors, spacing, typography)?
* [ ] Is data fetching strictly isolated to the Page/Container layer?