Atomic Design
3cosystem uses atomic design to organize interface primitives, reusable components, templates, and product experiences across a shared multi-surface ecosystem. Build once, adapt by surface, role, and state.
A shared vocabulary across every surface
Without a named system, components drift. Each surface reinvents the same patterns with slightly different names, sizes, and behaviors — leading to inconsistency, duplicated effort, and a growing gap between the brand guide and what ships in code.
Tokens → atoms → molecules → organisms → templates → pages. Every contributor speaks the same language.
Named, documented components close the gap between brand guide and implementation. Prior audits found significant drift — this is one step toward fixing it.
An atom built for M3ET works in N3TWORK, SP3AK EASY, and future surfaces without rework — only the surface token context changes.
Composing from existing organisms reduces time-to-feature on each surface from weeks to days.
From tokens to pages
Each layer inherits from the one below it. Change a token and it cascades up through atoms, molecules, organisms, templates, and pages — across all 10 surfaces at once.
Design decisions encoded as named variables — colors, type scales, spacing, radius, motion, and per-surface theming. The foundation everything else inherits from.
The smallest functional UI elements that cannot be broken down further without losing their utility.
Functional groupings of two or more atoms that work together as a single coherent unit.
Complex, standalone UI sections composed of molecules and atoms. Self-contained and reusable across templates.
Page-level layout patterns that place organisms into a structural wireframe. Content-agnostic. Shared across surfaces.
Concrete, content-filled routes. Templates plus real data, per-surface theming, and feature-flagged organisms.
Real examples across the ecosystem
Every component in production maps to exactly one layer. If you're unsure where something belongs, use the definition column.
| Layer | Definition | Examples |
|---|---|---|
◈Tokens | Color, type, spacing, radius, motion, surface theming | --l-primary--l-surface--fs-base--space-4surface vars |
⬡Atoms | Smallest reusable UI elements | ButtonInputBadgeAvatarIconButtonTagToggle |
◎Molecules | Functional groupings of atoms | Search barKPI cardProfile summary rowCTA rowStat card |
✦Organisms | Larger reusable sections | App SwitcherAuth shellSidebar navEvent moduleNarrative panel |
▣Templates | Layout patterns — content-agnostic | DashboardAuthProfileEventCRMNarrativeLandingAdmin |
◆Pages | Concrete routes per surface | M3ET /dashboardSP3AK /narrativeM3SH /hostingN3TWORK /pipeline |
Global · Shared-surface · Surface-native
Every component belongs to one of three scope tiers. Scope determines where it lives in the monorepo, who owns it, and how freely it can be changed.
Core ecosystem infrastructure. Changes require design system version bump and impact every surface simultaneously.
Useful to multiple surfaces but not required for all. Owned by the surfaces that use them; proposable for global promotion.
Interaction or layout unique to that surface's domain. May be promoted to shared if another surface needs the same pattern.
When to reuse, extend, or introduce new
The default answer is always reuse. New components cost documentation, test coverage, and long-term maintenance. Treat "new component" as a last resort, not a first instinct.
Prefer variants + props over duplication. If an existing component covers 80% of the use case, extend it.
Use a named variant prop when behavior or appearance genuinely differs but the core interaction is the same.
Only when the interaction pattern or layout cannot be expressed as a variant or composition of existing components.
Page-level components that only appear once and are never added to the component library.
Slightly different duplicates of existing components with no variant name, living in separate files.
Using hex values instead of var(--l-primary) or var(--l-surface). Prevents surface theming from working.
8 reusable layout patterns
Templates define the structural wireframe of a page without prescribing content. Each template lists the organisms it expects and which surfaces it ships on.
Login, signup, password reset
KPIs, activity feed, quick actions
User/public profile view
Event detail, RSVP, logistics
Pipeline, contacts, filter
Story discovery & interview
Surface landing pages
Platform management
Required states for every component
Every atom, molecule, and organism must document which states it supports. Undocumented states become production bugs. Use this matrix as your PR checklist.
| State | Description | Atoms | Molecules | Organisms |
|---|---|---|---|---|
Default | Base resting state | ✓ | ✓ | ✓ |
Hover / Focus / Active | Interactive pointer & keyboard states | ✓ | ✓ | ✓ |
Loading | Async operation in flight — skeleton or spinner | ✓ | ✓ | ✓ |
Empty | Zero-data state — illustrated or instructive | ✓ | ✓ | |
Error | Validation or system failure | ✓ | ✓ | ✓ |
Success | Completion confirmation | ✓ | ✓ | ✓ |
Disabled | Not interactable — reduced opacity + no pointer | ✓ | ✓ | |
Locked / Permissioned | Visible but gated by role or subscription | ✓ | ✓ | |
Feature-flagged | Staged rollout — hidden from some cohorts | ✓ |
Who owns what — and how changes ship
The design system is a living product. Every change is a PR. Every organism or template addition requires documentation. Breaking token changes require a version bump.
- ▸Design + engineering pairing — every new component requires both
- ▸Global components owned by the design system team
- ▸Shared-surface components co-owned by adopting surfaces
- ▸Surface-native components owned by the surface team
- ▸New organism or template → must add to component library docs
- ▸New global atom → requires design review before merge
- ▸Token change → must note which surfaces are affected
- ▸State coverage documented in the PR description
- ▸Accessibility: axe + keyboard nav verified
- ▸Current version: v1.2
- ▸Changes to global tokens → design system version bump required
- ▸Additive changes (new atoms) → minor version
- ▸Breaking changes (token renames, removed components) → major version
- ▸Surface-native changes → no version bump needed