atomic-design
Use when structuring or decomposing any frontend UI into reusable components, regardless of framework. Applies Brad Frost's atomic design methodology — atoms, molecules, organisms, templates, and pages — to guide consistent component hierarchy, naming, and composition decisions.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 3
- Forks
- 0
01 前言 Front Matter
- name
- atomic-design
- description
- Use when structuring or decomposing any frontend UI into reusable components, regardless of framework. Applies Brad Frost's atomic design methodology — atoms, molecules, organisms, templates, and pages — to guide consistent component hierarchy, naming, and composition decisions.
02 资源文件 2
- 参考文档evals/evals.json3.8 KB
- 参考文档references/hierarchy.md4.8 KB
03 SKILL.md 正文
Atomic Design — Component Hierarchy Methodology
Atomic design is a mental model for breaking any user interface into five distinct levels of structural complexity — atoms, molecules, organisms, templates, and pages — borrowed from chemistry's atoms-to-matter progression. It gives teams a shared vocabulary for talking about UI structure and a repeatable way to decide "does this need to be its own piece, and how big should that piece be?" The methodology itself is framework-agnostic: it describes how to think about composition, not which library or platform renders the result.
Why atomic design (rationale)
Without a shared hierarchy, teams tend to build UI ad hoc: some pieces get over-extracted into components nobody reuses, others get duplicated because nobody realized a smaller shared piece already existed, and naming drifts (is this a "card," a "widget," a "block"?). Atomic design solves three recurring problems:
- Consistency — the same five labels describe every piece of UI, so a design system and its implementation stay aligned no matter who's talking about it.
- Reuse — decomposing top-down into smaller named levels surfaces the shared building blocks (a label, a button) that would otherwise get re-created inside every larger piece that needs one.
- Scalable vocabulary — "this is a molecule, not an organism" is a fast, unambiguous design conversation once the levels are understood, replacing long back-and-forth about scope.
The levels are a thinking tool, not a rigid folder structure to enforce everywhere — use them to reason about granularity, not as a law that every project must nest five matching directories.
The five levels (overview)
- Atoms — the smallest indivisible UI building blocks: a label, a single input field, a single control. An atom has no meaningful sub-parts; splitting it further removes function rather than simplifying it.
- Molecules — a small group of atoms bonded together to do one thing, such as a labelled input paired with a submit control. A grouping becomes a molecule once two or more atoms combine for a single, reusable purpose.
- Organisms — relatively complex groups of molecules and/or atoms that form a distinct, recognisable section of an interface, such as a page header or a grid of item summaries. A grouping becomes an organism once it reads as a standalone region rather than a helper piece.
- Templates — page-level layout skeletons that arrange organisms into a structure using placeholder content. Templates are about arrangement, not real content.
- Pages — specific instances of a template populated with real, representative content. Pages are the concrete end state used to validate that the whole system actually works with real data.
See references/hierarchy.md for the expanded per-level guidance — definitions, boundary rules, and additional neutral examples for each level.
How to apply it (decomposition workflow)
Follow this ordered procedure to decompose an arbitrary UI description into the five levels:
- Start from the whole screen. Identify the page as the top-level unit — the thing a user actually sees, with real content.
- Strip content to find the template. Mentally replace the real content with placeholders. What's left — the arrangement of regions — is the template.
- Identify the distinct regions inside the template. Each standalone, recognisable section (a header, a listing area, a footer) is a candidate organism.
- Break each organism into its functional groupings. Look for clusters of elements that work together for one purpose (a labelled field plus its control). Each cluster is a candidate molecule.
- Break each molecule into its individual elements. The remaining pieces that can't be meaningfully split further are the atoms.
- Name every level consistently so the same piece is referred to the same way whether you're discussing the design, the content, or the composition.
This procedure works top-down (screen → page → template → organism → molecule → atom) or bottom-up (start cataloguing atoms first, then group them upward) — pick whichever direction matches how much of the UI already exists versus is being designed fresh.
Decision heuristics / boundaries
- Atom vs. molecule: if removing a piece breaks the element's basic function, it's still an atom; if two or more atoms only make sense combined for one purpose, promote the grouping to a molecule.
- Molecule vs. organism: a molecule is a small, single-purpose helper; an organism is a standalone section a user would recognise on its own, even if it contains several molecules.
- Organism vs. template: an organism is content-bearing and reusable; a template is the arrangement of organisms with placeholder content, not a piece of content itself.
- Template vs. page: a template has no real content; a page is the same structure filled with actual, representative content.
- When in doubt, prefer the smaller level. Over-classifying something as an organism when it's really a molecule tends to produce fewer reusable pieces overall.
Common pitfalls / anti-patterns
- Over-nesting organisms — wrapping every organism inside another organism "for organization" defeats the purpose of a flat, recognisable set of regions; keep organism nesting shallow.
- Treating pages as templates — a template must stay free of real content; once specific content is baked in, it has become a page, not a reusable template.
- Framework leakage — the five levels describe structural complexity, not implementation detail; don't let a specific rendering technology's constraints redefine what counts as an atom or an organism.
- Skipping levels — jumping straight from atoms to organisms (skipping molecules) usually hides a reusable grouping that other organisms could have shared.
04 同仓库更多 Skills
designing-in-patterns
Use when designing, planning or auditing UI against a component library — naming surfaces with the repo's pattern vocabulary, deciding reuse versus extend versus new, exploring compositions, or writing the reuse table (component-plan.md, a spec's `## Reuse`, a UI audit). Carries the design method; the repo's own vocabulary, bundle and board rules come from project-context and the designer override.
typeorm
Use when defining TypeORM entities, writing migrations, or building repository/query-builder code in TypeScript. Covers entity and relation decorators, the Data Mapper pattern, migrations, the query builder, transactions, and multi-database configuration.
hono-api
Use when building or extending REST APIs with Hono + @hono/zod-openapi. Covers schema-first route declaration with createRoute, feature-grouped composable routers, a class-based service layer behind interfaces, the strategy pattern for multi-event webhooks, typed request validation, and auto-generated OpenAPI docs.
electrodb
Use when defining DynamoDB entities, modeling indexes, or writing queries/mutations with the ElectroDB ORM. Covers entity schema, access patterns, CRUD operations, update expressions, and single-table design patterns.
writing-docs
Use when writing, restructuring, or reviewing any prose documentation — a tutorial, how-to guide, reference page, or explanation/conceptual doc — for a public docs site (e.g. Mintlify MDX, docs/, README material), a getting-started guide, an API/CLI reference page, or a "why we built it this way" conceptual page. Applies the Diátaxis framework (see https://diataxis.fr/) — every document belongs to exactly one of the four quadrants (tutorial / how-to guide / reference / explanation), and mixing quadrants inside one document is the single most common documentation failure. Covers the four-quadrant compass for picking the right form, per-quadrant structure templates, an anti-pattern list for quadrant drift, and generic voice/craft rules — repo-specific voice and target output format (e.g. Mintlify MDX) are resolved from the repo's docs-manifest (falling back to project-context), never hardcoded here.
writing-adrs
Use when authoring an Architecture Decision Record (ADR) — a short document that captures one significant, hard-to-reverse technical or architectural decision, its context, and its consequences. Triggered by the sdlc ADR pipeline (the knowledge-engineer agent behind /sdlc:docs seed adr and /sdlc:docs distill) when generating an ADR from a story, and by anyone hand-authoring an ADR under docs/adr/ today. Covers why ADRs are kept short and inverted-pyramid, the required sections (Title, Status, Decision, Context, Alternatives Considered, Consequences), the proposed→accepted→superseded (or →rejected) status lifecycle and the never-edit-only-supersede immutability rule, the NNNN-decision-slug.md filename convention, and the ADR frontmatter fields (status, agents, source-stories) the pipeline reads to route a generated ADR into docs/adr/index.md.