Who is this for? Anyone joining this project or evaluating this approach. Read time: 2 minutes.
Learning reference, not a framework. This prototype demonstrates Angular 21 atomic design patterns for educational purposes. It is not a library to depend on, not actively maintained as open-source, and not a production starter kit. Fork it or follow the replication guide to apply these patterns in your own project.
Start here. This repo contains process documentation for building Angular 21 + PrimeNG 21 applications using Atomic Design principles, targeting small teams (2-4 people).
What it gives you. On a team of 2-4 developers sharing a codebase, the same problems keep showing up: a button looks one way on the dashboard and another way on the detail page, two people build slightly different search bars in the same sprint, a designer hands off specs that don't map to anything in code, and edge-case states (empty, error, loading) get handled inconsistently -- or not at all. Atomic structure fixes this by giving every component a single home with a clear API. New team members can explore the design system directory and know immediately what's available instead of grepping through pages. The result is less rework, faster PR reviews, and fewer "why does this look different over here?" bugs.
When NOT to use it. Be honest with yourself about scope. If you're building a one-page internal tool, a throwaway prototype you won't maintain past next month, or you're a solo developer who already knows every corner of the codebase -- the overhead of atoms/molecules/organisms isn't worth it. Same if the team has zero Angular experience; learn Angular first, then layer on structure. Below roughly 5-10 components, flat organisation is fine.
Why not just use PrimeNG directly? You can, and it's faster on day one. The tradeoff hits later. When every page imports PrimeNG components directly, you've coupled your entire app to one library's API. Swapping or upgrading PrimeNG means touching every consumer. Worse, each page ends up reimplementing its own loading states, error handling, and empty states around PrimeNG primitives. Wrapping PrimeNG in thin atoms and composing those into organisms centralises that logic. The wrapper cost is small; the consistency payoff compounds every sprint.
- 01-atomic-hierarchy -- Component taxonomy and cascade rule
- 02-maturity-stages -- POC, Prototype, Production quality levels
- 03-project-structure -- Where files go, how they're named
Then pick your role-based path below.
Developer (new to the project):
00 -> 01 -> 02 -> 03 -> 11-implementation-tips -> explore src/
Developer (prototype work): All of the above, plus 05-token-pipeline -> 07-qa-per-atomic-level -> 10-derisking -> production-plan-sketch (for Wave 1 implementation status)
BA / Product Owner: 00 -> 01 -> 02 -> 08-pbi-and-ba-guide -> acceptance-criteria
Designer: 00 -> 13-designers-guide -> 01 -> 05-token-pipeline -> 04-parallel-development -> design-spec
Tech Lead: 00 -> 01 -> 02 -> 06-tooling-landscape -> simulation-report
Evaluator (deciding whether to adopt): 00 -> simulation-report -> 02 -> 10-derisking -> 12-decision-guides
See docs/README.md for the full documentation index.