docs/v3.md
# Componentry v3 - Atomic Accelerator ⚛️🚀
_Componentry is upgrading 🎉🎉🎉_
Very exciting improvements are underway that will be part of the next major
release, code named _Atomic Accelerator_. The goal of the updates are to provide
better scoping of component styles, as well as better separation between atomic
and component stuyles.
#### Update goals
- Improve library scalability by providing clear mappings of classes to scoped
styles.
- Simplify library setup and customization by consolidating the Bootstrap base
styles and Componentry library styles.
- Improve the process of creating a design system by providing a cohesive tool
for defining design system primitives and composed components.
## 🤔 Why
Componentry v3 is about incorporating the lessons learned by the web community
from CSS in JS libraries: Using styles scoped to a single component and single
purpose atomic classes removes the uncertainty of how CSS is used and what
impacts of changing styles might be.
We think the combination of atomic classes with scoped component classes
provides the best foundation for writing reusable and scalable CSS.
## 🗺 Direction
Componentry began as a React component library for working with Bootstrap
styles, and this layering has worked well most of the time, but there is
non-neglible overhead to distinguishing the boundaries between Componentry and
Bootstrap, and that additional overhead extends into library setup and
development.
Componentry v3 is an evolution of the existing Bootstrap usage rather than a
direct departure, with the intent of mirroring the classes used by Bootstrap
whenever possible. Updates will be focused on ensuring that any class name is
scoped to a single component usage.
## 🚧 Upcoming changes
- [ ] Update bundled Bootstrap styles to v4.1.1 (latest)
- [ ] Update package to declare webpack `sideEffects` to allow applications to
start importing single components.
- [ ] Create a `styles/atomic` directory for separation of atomic styles.
- [ ] Identify and migrate atomic theme mixins/functions to allow applications
to begin consuming single components.
- [ ] Create a `theme.scss` styles entrypoint that includes all variables and
helper mixins/functions required by component styles.
- [ ] Validate that any component class name can be imported and used without
impact or dependency on global styles.
- [ ] Validate that component styles do no assume styling provided by general
Bootstrap content styles.
## Type Components
v3 offers type components for consumers looking to standardize their styles by
using props. This also provides a way to set app level defaults using the theme
default props. The `Link` component `as` prop can be set to the routing
component from your routing library of choice.
## 📖 Notes
Importance of a design system: by understanding the why of our lego blocks, we
can better understand how the complete system should evolve.
> ...understanding not only the what, but the why, behind the design of a system
> is critical to creating an exceptional user experience.
>
> - Marco Suarez (https://www.invisionapp.com/blog/guide-to-design-systems/)