What is the atomic-design-fundamentals skill?
The atomic-design-fundamentals skill is a SKILL.md inside the Han plugin marketplace that teaches an AI coding agent Atomic Design with an extra level for tokens. Components are sorted into quarks, atoms, molecules, organisms, templates and pages, with import rules that only let each level use the ones below it.
The atomic-design-fundamentals skill sits at plugins/patterns/atomic-design in the Han repository, a marketplace whose README counts 340 plugins. This one belongs to the Pattern category, which the README describes as methodologies and workflow practices.
It teaches Brad Frost's Atomic Design for building scalable component-based interfaces, extended with a level zero called quarks. The frontmatter marks it user-invocable false and allows Bash, Read, Write, Edit, Glob and Grep.
The six levels
| Level | What it holds | Examples |
|---|---|---|
| 0 Quarks | Design tokens, pure values with no UI | Colors, spacing scale, type tokens, radii, shadows, easing, breakpoints |
| 1 Atoms | Smallest functional UI units | Buttons, inputs, labels, icons, avatars |
| 2 Molecules | Atoms working as one unit | Search form, form field, media object |
| 3 Organisms | Standalone interface sections | Header, footer, sidebar, product card |
| 4 Templates | Page layouts with placeholder content | Blog post, dashboard, landing page structure |
| 5 Pages | Templates filled with real content | Homepage with actual hero content |
Rules the skill enforces
- Imports flow downward only. Quarks feed every level, atoms feed molecules and above, and pages are not imported by any other component.
- Quarks cannot import from any other level, and atoms carry no business logic.
- Molecules are composed of atoms only and have a single purpose.
- Props flow downward, and business logic lives in organisms or higher.
Who the atomic-design-fundamentals skill is for
Best for
- Setting up a new design system, or organizing an existing component library into levels.
- Refactoring a monolithic component into pieces with clear responsibilities.
- Onboarding teammates to one shared vocabulary for components.
- Auditing a codebase for atoms that import molecules and other circular dependencies.
Not for
- Defining actual token values. The skill names the quarks level, and its related skills list points to a separate atomic-design-quarks skill for tokens. See also design-token.
- Visual critique. It organizes code, and it does not judge how an interface looks.
- Anyone tempted to split everything into atoms. The skill itself warns that over-atomization creates needless layers such as a ButtonText atom.
Use it with UiChemy
The skill structures source code, so its output is component folders, not WordPress pages. If your design lives in Figma, name layers by level for a tidy file, then convert with UiChemy Figma to WordPress. Click Get Started on uichemy.com. For design system context, see design-system-patterns.
How to install Atomic Design Fundamentals Skill: Quarks to Pages
git clone https://github.com/TheBushidoCollective/han.githan plugin install <name>, for installing whole plugins. The manual copy above takes only this one skill.Clone the repository
Run
git clone https://github.com/TheBushidoCollective/han.git. The skill sits in plugins/patterns/atomic-design/skills/atomic-design-fundamentals.Copy the skill folder
Copy that atomic-design-fundamentals folder to wherever your AI coding agent loads skills from. For Claude Code, use its skills location.
Point it at your components
Open the project that holds your UI components so the agent can read and reorganize the files.
Ask for the structure
Request a design system setup, an audit of your component folders or a refactor of one large component into atoms and molecules.
Check that it loaded
Ask the agent how to classify a search form and a site header. It should call the form a molecule made of atoms and the header an organism, and place token values in a quarks folder.
Key features
- Quarks as a zeroth levelDesign tokens such as color tokens, spacing scales, type sizes, border radii, shadows, animation durations, easing functions and breakpoints sit below atoms as a single source of truth.
- Atoms without business logicAtoms are self-contained, highly reusable and accept styling props. A BAD example in the skill shows an atom fetching a product price with a hook.
- Molecules from atoms onlyA molecule has one job and uses atoms only, such as a search form made of an input and a button, or a form field with label, input and error message.
- Organisms, templates and pagesOrganisms are standalone sections like a header or comment section. Templates give structure with placeholder content. Pages fill templates with representative content for testing.
- Strict composition tableA usage chart states which levels may consume which, and shows invalid imports such as an atom importing a molecule or an organism importing a template.
- Three directory layoutsThe skill offers a standard structure with quarks, atoms, molecules, organisms, templates and pages folders, an alternative flat structure and a feature-based hybrid.
- Naming and barrel exportsPascalCase component files, index files for clean imports, paired test and story files, and barrel exports per level and for the whole components folder.
- Token integrationExamples cover token files for colors, spacing and typography, and show atoms reading those tokens instead of hardcoding values.
- Named pitfallsOver-atomization, under-atomization, circular dependencies and inconsistent naming each get a BAD and GOOD code comparison.
Frequently asked questions
What is the atomic-design-fundamentals skill?
It is a skill in the Han plugin marketplace that teaches Atomic Design, extended with a quarks level for design tokens. It explains six levels, composition rules, directory layouts, naming, token integration and common pitfalls so an AI coding agent can organize UI components consistently.
How do I install the atomic-design-fundamentals skill?
Clone thebushidocollective/han and copy plugins/patterns/atomic-design/skills/atomic-design-fundamentals into your agent's skills folder. The README also documents a Han CLI that installs plugins with commands such as han plugin install, which fetch whole plugins.
What are quarks in this skill?
Quarks are the sub-atomic level: design tokens and primitive values that atoms consume. They include colors, spacing scales, typography tokens, border radii, shadows, animation durations, easing functions and breakpoints. They are not UI components, and they cannot import from any other level.
Which AI coding agents can use the atomic-design-fundamentals skill?
The Han repository describes itself as a marketplace of Claude Code plugins, and its README refers to Claude Code and to AI coding agents in general. It does not list other agents by name. Test the folder in your own agent after copying it.
Does the skill require React?
No. The code examples are TypeScript and React-style components, but the skill says atoms should be framework-agnostic when possible. The hierarchy, import rules and folder layouts apply to any component-based front end.
When should I use atomic design on a project?
The skill lists setting up a new design system, organizing an existing library, onboarding teammates, auditing component structure, planning architecture, writing design system docs and refactoring monolithic components. It also warns against splitting too finely, so keep atoms meaningful.
How does it relate to design tokens?
It treats tokens as the quarks level and shows token files and atoms that consume them. For deeper work on token naming and structure, browse design-token and component-spec in this hub.
What license does the atomic-design-fundamentals skill use?
GitHub does not detect a license for the repository, while the README says MIT and links a LICENSE file. Read that file in the repository before you redistribute the skill folder inside a product.