ADR-014: Build, Buy, or Wrap
| Field | Value |
|---|---|
| Type | Skill Resource |
| Source | ~/.copilot/skills/adr/references/adr-014-build-buy-or-wrap.md |
| Description | Not specified |
Source Content
ADR-014: Build, Buy, or Wrap
Decision
Adopt a mature community library before building any new capability or behavior-heavy component, and ship it as a thin design-system wrapper rather than a raw dependency. A net-new build is allowed only after the alternatives have been audited and proven insufficient.
Key rules
- Decision order: read ADRs, audit existing components, reuse, extend (add a prop), wrap a library, then build new — in that order.
- Check for a community library before writing any new abstraction, utility package, or behavior-heavy component (date pickers, comboboxes, data tables, drag-and-drop surfaces, and the like). Prefer a thin wrapper over a full build.
- If a suitable library is already in the bundle, prefer it over a custom implementation.
- Wrap the third-party primitive behind a design-system API. Consumers must not depend on the underlying library directly, and the public API must not expose raw library props or component references.
- The wrapper adds only what the library does not provide: platform defaults, design-token application, and accessibility augmentation. It does not reimplement behavior.
- Do not add features to the wrapper that belong upstream — contribute or fork instead.
- Re-export reusable capability under the
@dmwd-io/<capability>namespace (@dmwd-io/design-system,@dmwd-io/auth-client,@dmwd-io/form-engine, etc.). - Extending an existing component (adding a prop) is always preferred over creating a near-duplicate.
- No new component without at least one existing component audited as a candidate. A new-component proposal must state which existing components were evaluated and why each was insufficient.
- Document the decision in the PR or story so the reasoning does not live only in someone’s head.
Why
A wrapper-over-library default keeps behavior battle-tested upstream while the design system owns only tokens and accessibility, and a real audit gate keeps the component set from accreting near-duplicates. Wrapping behind @dmwd-io/<capability> lets the upstream choice change without breaking consumers. This record consolidates ADR-014 (don’t reinvent the wheel), the original ADR-014 component-decision policy, and ADR-014 (open source first); the three were complementary and contained no contradictions, so the merge is faithful with no rules dropped. The one alignment to current practice: the namespace and @dmwd-io/design-system re-export pattern named here match the global stack defaults exactly.
Applies when
You are about to build a new component, abstraction layer, utility package, or any behavior-heavy UI pattern — or you are reviewing a proposal that adds one.
Related
- ADR-009 — icon role, placement, and layout (applies to any wrapped component’s icon API).
- ADR-008 — border, surface, and overlay discipline for wrapped surfaces.