atomic-design-fundamentals_skill

Overview

This skill codifies Atomic Design fundamentals (extended with quarks) to help teams structure UI components into quarks, atoms, molecules, organisms, templates, and pages. It explains the hierarchy, composition rules, directory patterns, naming conventions, and common pitfalls for scalable design systems. Use it to align component architecture, token usage, and development workflows.

How this skill works

The skill inspects and describes each atomic level: quarks (design tokens), atoms (primitive UI elements), molecules (composed units), organisms (complex sections), templates (layout skeletons), and pages (real content instances). It provides concrete composition rules, import/barrel patterns, and directory layouts so components only depend on allowed levels. It highlights best practices, anti-patterns, and token integration examples for TypeScript projects.

When to use it

• Bootstrapping a new design system or component library
• Refactoring a monolithic UI into manageable components
• Defining or enforcing component import and dependency rules
• Documenting component purpose, levels, and tokens for team onboarding
• Auditing component structure to eliminate circular dependencies
• Planning folder structure and naming conventions for consistency

Best practices

• Start from quarks and atoms before composing molecules and organisms
• Keep atoms free of business logic; push state and domain code to organisms or pages
• Use design tokens (quarks) as a single source of truth for colors, spacing, typography
• Follow strict import direction: quarks→atoms→molecules→organisms→templates→pages
• Use consistent PascalCase file and component names and maintain barrel exports for clean imports
• Document level, composition, and examples for each component to aid discovery and testing

Example use cases

• Create a token-first theming system (quarks) shared across apps
• Build a reusable SearchForm molecule composed from Input and Button atoms
• Refactor a large Header into atoms, molecules, and an organism with clear props flow
• Design a Dashboard template from organisms and validate layouts with real pages
• Audit a codebase to remove atoms that import higher-level modules (fix circular dependencies)