{"id":51466114,"url":"https://github.com/roryford/atomic-prototype","last_synced_at":"2026-07-06T11:30:25.035Z","repository":{"id":347667333,"uuid":"1188526690","full_name":"roryford/atomic-prototype","owner":"roryford","description":"Angular 21 + PrimeNG 21 atomic design system prototype — a reference implementation for small teams","archived":false,"fork":false,"pushed_at":"2026-06-20T09:26:42.000Z","size":11906,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-20T10:03:34.322Z","etag":null,"topics":["angular","atomic-design","design-system","primeng","storybook"],"latest_commit_sha":null,"homepage":"https://roryford.github.io/atomic-prototype/","language":"TypeScript","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/roryford.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-22T07:47:08.000Z","updated_at":"2026-06-20T09:26:46.000Z","dependencies_parsed_at":null,"dependency_job_id":"a16f66d3-76b0-4698-881a-d75a0ca9407b","html_url":"https://github.com/roryford/atomic-prototype","commit_stats":null,"previous_names":["roryford/atomic-prototype"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/roryford/atomic-prototype","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roryford%2Fatomic-prototype","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roryford%2Fatomic-prototype/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roryford%2Fatomic-prototype/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roryford%2Fatomic-prototype/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/roryford","download_url":"https://codeload.github.com/roryford/atomic-prototype/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roryford%2Fatomic-prototype/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35189713,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-06T02:00:07.184Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["angular","atomic-design","design-system","primeng","storybook"],"created_at":"2026-07-06T11:30:22.835Z","updated_at":"2026-07-06T11:30:25.029Z","avatar_url":"https://github.com/roryford.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Atomic Design Prototype\n\nAn Angular 21 + PrimeNG 21 prototype demonstrating atomic design methodology for small teams.\n\n**[Browse the component library](https://roryford.github.io/atomic-prototype/)**\n\n## What Is This?\n\nThis is a working prototype that demonstrates how to build a component library\nusing Brad Frost's Atomic Design principles in Angular 21 with PrimeNG 21. It\npairs real, runnable components with the process documentation a small team\nneeds to adopt atomic design without guesswork.\n\nThe repository includes process documentation (15 guides covering hierarchy,\ntokens, QA, tooling, decision-making, and maturity stages) alongside working\ncode (7 atoms, 3 molecules, 5 organisms, and 3 pages). Every component is exercised in\nStorybook and covered by Vitest unit tests.\n\nTarget audience: small teams (2-4 developers) building design systems. This\nprototype is useful for learning atomic design concepts, Angular 21 patterns\n(signals, httpResource, standalone components), and the surrounding process\n(PBIs, acceptance criteria, testing strategy).\n\n\u003e **Note:** This repository is shared as a reference implementation. It is not\n\u003e actively accepting contributions.\n\n\u003e **Educational reference only.** This is a prototype built to demonstrate atomic design\n\u003e principles with Angular 21 and PrimeNG. It is not a production-ready library, not\n\u003e actively maintained as open-source, and not accepting contributions. Use it as a\n\u003e learning reference or fork it as a starting point — see [docs/14-replication-guide.md](docs/14-replication-guide.md).\n\n## Screenshots\n\n| Dashboard (light) | Dashboard (dark) |\n|---|---|\n| ![Dashboard light mode](./docs/screenshots/dashboard-light.png) | ![Dashboard dark mode](./docs/screenshots/dashboard-dark.png) |\n\n| List page | Detail page | Error state |\n|---|---|---|\n| ![List page](./docs/screenshots/list-table.png) | ![Detail page](./docs/screenshots/detail-page.png) | ![Error state](./docs/screenshots/detail-error.png) |\n\n| Mobile (375px) | Wide (1440px) |\n|---|---|\n| ![Dashboard mobile](./docs/screenshots/dashboard-mobile.png) | ![Dashboard wide](./docs/screenshots/dashboard-wide.png) |\n\n## Atomic Design Hierarchy\n\n```\nAtoms                    Molecules                 Organisms\n------------------       -------------------       -------------------------\nDsButton                 DsSearchBar               DsStatGrid\nDsInput                  DsStatCard                DsProjectCardGrid\nDsTag                    DsFormField               DsProjectTable\nDsEmptyState                                       DsProjectDetailCard\nDsSkeleton                                         DsProjectDetailCardSkeleton\nDsMessage                                          Pages\nDsDivider                                          -------------------------\n                                                   -------------------------\n                                                   Dashboard\n                                                   List\n                                                   Detail\n```\n\n## Quick Start\n\n\u003e **Note:** The project targets Node 24 (the active LTS). Node 26 LTS will be a\n\u003e straightforward bump when it lands (expected late 2026).\n\n```\nPrerequisites: Node 24+, npm 11+ (both enforced via package.json \"engines\")\n\ngit clone https://github.com/roryford/atomic-prototype.git\ncd atomic-prototype\nnpm install\nnpm start              # Dev server at http://localhost:4200\nnpm run storybook      # Component library at http://localhost:6006\nnpm test               # Unit tests via Vitest\nnpm run lint           # ESLint (TypeScript + templates)\nnpm run lint:fix       # ESLint auto-fix\nnpm run e2e            # Playwright E2E — Gherkin/BDD behavioral suite (headless; LOCAL ONLY, not run in CI)\nnpm run e2e:ui         # Playwright E2E with UI\nnpm run screenshots    # Regenerate doc screenshots (separate from the e2e run)\nnpm run build:tokens   # Regenerate preset.ts from tools/token-pipeline/tokens/primitives.json\n```\n\n## Project Structure\n\n```\nsrc/app/\n  design-system/\n    atoms/        — Button, Input, Tag, EmptyState, Skeleton, Message, Divider\n    molecules/    — SearchBar, StatCard, FormField\n    organisms/    — StatGrid, ProjectCardGrid, ProjectTable, ProjectDetailCard, ProjectDetailCardSkeleton\n    templates/    — DashboardLayout, FullWidthLayout (ng-content layout shells)\n    tokens/       — PrimeNG theme preset, design tokens\n  pages/          — Dashboard, List, Detail\n  services/       — ProjectService (httpResource-based)\n  mocks/          — MSW handlers + fixture data\ne2e/              — Playwright tests (Gherkin/BDD features + plain specs)\ndocs/             — Process guides (00-14) + prototype findings\n```\n\n## What's Implemented\n\n- **7 atoms:** DsButton, DsTag, DsInput, DsEmptyState, DsSkeleton, DsMessage, DsDivider\n- **3 molecules:** DsStatCard, DsSearchBar, DsFormField\n- **5 organisms:** DsStatGrid, DsProjectCardGrid, DsProjectTable, DsProjectDetailCard, DsProjectDetailCardSkeleton\n- **2 templates:** DsDashboardLayout, DsFullWidthLayout (data-free `ng-content` shells)\n- **3 pages:** Dashboard, List, Detail (each composed into a template shell)\n- **Tooling:** CI (GitHub Actions), ESLint, Stylelint, Playwright E2E with Gherkin/BDD ([`playwright-bdd`](./e2e/README.md)) — **run locally, not in CI** (see below), Storybook, Vitest, MSW mocks\n\n### Continuous Integration\n\nThe GitHub Actions CI pipeline ([`.github/workflows/ci.yml`](./.github/workflows/ci.yml)) runs: dependency audit, Prettier format check, Stylelint, ESLint, Vitest unit tests, and a production build, plus a Storybook build-and-deploy to GitHub Pages on `main`.\n\n**Playwright E2E is intentionally NOT part of CI.** The hosted runner's cold-Chromium download stalls indefinitely, so the BDD/e2e suite runs **locally only** via `npm run e2e`. Run it before pushing changes that affect user-facing behavior.\n\nNot yet implemented: real API integration, authentication, visual regression testing, axe-core in CI, performance budgets in CI, and E2E in CI (runs locally only — see above).\n\n## Known Limitations\n\nThis is a prototype scoped to demonstrate atomic design methodology, not a production design system. These limitations are intentional — they mark where the prototype ends and production work begins.\n\n**Theming.** One theme with light and dark modes. No multi-brand support, density modes, or high-contrast accessibility themes. The token architecture supports these — the preset structure allows multiple themes via `definePreset()` — but only one is implemented.\n\n**Layout primitives.** The templates level provides two page-level layout shells (DsDashboardLayout, DsFullWidthLayout), but there are no finer-grained reusable layout primitives (grid, spacer, container) — pages still use CSS grid and flex directly for intra-page layout. A production system would add these before scaling past a handful of pages.\n\n**Accessibility automation.** Manual a11y checklists exist (see [QA per atomic level](./docs/07-qa-per-atomic-level.md) and [manual test checklist](./docs/manual-test-checklist.md)), Storybook has the a11y addon installed, and keyboard navigation rules are documented per level. What's missing is automated enforcement — axe-core is not in CI. Manual review catches issues; automation prevents regressions.\n\n**Forms.** DsFormField demonstrates the molecule pattern, but there is no form validation framework, error strategy, or form layout system. PrimeNG forms are used minimally. Production forms need dedicated patterns.\n\n**Backend.** MSW provides realistic API mocking gated behind `isDevMode()`. There is no API client abstraction, auth flow, or real data layer. This is intentional — it keeps the prototype focused on UI architecture.\n\n**Internationalization.** No i18n pipeline, RTL support, or locale-aware formatting. These are production concerns that interact heavily with the token and component layers but are outside the scope of demonstrating atomic structure.\n\n**Icons.** PrimeIcons are used via PrimeNG. There is no custom icon library, icon tokens, or icon component. A production system with custom iconography would need these.\n\n**Motion.** PrimeNG controls its own animation lifecycle. There are no custom duration tokens, easing tokens, or motion guidelines. Custom animation patterns would need to be layered on top.\n\n**Figma library.** This is a code-first prototype. There is no shared Figma file or component spec library in the repository. A local Figma plugin is included at [`tools/figma-plugin`](./tools/figma-plugin/) for manual primitive-token import/export, but it is a prototype workflow helper rather than a full design-library sync setup. The [Designer's Guide](./docs/13-designers-guide.md) describes the broader handoff workflow.\n\n**Distribution.** This is a reference repository, not a publishable npm package. There is no versioning strategy, monorepo structure, or release pipeline. See [production plan sketch](./docs/production-plan-sketch.md) for notes on what a production release pipeline would require.\n\n## Documentation\n\nSee [docs/README.md](./docs/README.md) for the full documentation index and role-based reading paths. Start with the [Quickstart Guide](./docs/00-quickstart.md).\n\n## Tech Stack\n\n- Angular 21.2, PrimeNG 21.1, Storybook 10.3, Vitest 4.1, MSW 2.12, TypeScript 5.9\n- ESLint (via angular-eslint), Playwright (E2E), GitHub Actions (CI/CD)\n\n## License\n\nMIT — see [LICENSE](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froryford%2Fatomic-prototype","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Froryford%2Fatomic-prototype","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froryford%2Fatomic-prototype/lists"}