Understanding AgnosticUI #

AgnosticUI is a set of UI primitives that start their lives in clean HTML and CSS. These standards compliant components are then copied to our framework implementations in: React, Vue, Svelte, and Angular (experimental).

Approach #

Decoupled CSS #

AgnosticUI is not tied to a particular JavaScript framework, because our build process complies and even enforces the 1 stylesheet…many frameworks approach which works as follows:

Our first step to building a component (like a Button) starts in the agnostic-css package. Generally, this results in a component.html file, and a component.css file. For example, button.html and button-core.css.

When we're ready to create a corresponding component (e.g. a React button), we utilize a simple NodeJS script that literally copies the component.css (e.g. button-core.css) into the framework's component directory and import it directly.

For Svelte and Vue's SFC we instead replace the contents within the <style></style> tags.

The above approach forces our framework-specific implementations to use the same single stylesheet. Ultimately, this means you can make theme customizations once, then use these CSS custom property overrides across your React, Vue, Svelte, and Angular (experimental) based applications…and they will have a consistent look and feel!

If you're curious, there's an article on css-tricks — How to Make a Component That Supports Multiple Frameworks in a Monorepo~~ — that describes how much of this gets set up in painstaking details. Note AgnosticUI no longer uses yarn workspaces or hoisted dependencies, but otherwise, the article explains the same setup.

Frameworks #

AgnosticUI has 5 packages.

The agnostic-css package is where all component HTML and CSS starts. All styles derive from this package as described earlier.

If you'd like to use AgnosticUI as a purely CSS based framework, see the CSS Components section on the left navigation.

The framework-specific implementations available are: agnostic-react, agnostic-vue, agnostic-angular, and agnostic-svelte.

If you'd like to use AgnosticUI framework based components, see the Framework Components section on the left navigation.

Primitives #

Think of the components AgnosticUI provides as primitive or presentational components that you can build atop. We purposely avoid overly complex components like the Data Grid in efforts to keep AgnosticUI's core as minimal and maintainable as possible.

We may consider a community-driven addons repository in the future for more complex components that don't belong in core if there's support from the community.

Clean CSS #

Broadly-speaking, AgnosticUI's CSS follows Jonathan Snook's SMACSS and Nicole Sullivan's OOCSS. Mark Otto describes a similar approach in his article on using chained classes.

We don't generally follow the state rules in SMACSS like is-STATE e.g. we'll generally favor using native [disabled] over creating an extra class .is-disabled since it's likely that we've needed to interact with the native [disabled] from JavaScript anyway. There's an exception: if we've disabled an anchor tag by adding the [disabled] attribute, but we want to further add a class on its parent wrapper, that class on the parent may in fact use is-disabled. To add to the confusion, our JavaScript framework props do in fact use isState props to allow consumers to specify the state of a component. 😎

No Preprocessing #

While preprocessors certainly supply an enjoyable developer experience, AgnosticUI favors the use of standards-based raw CSS. This means structures like loops, maps, and lists, are not available. Essentially, these sorts of structures need to be unrolled, and thus the code is a bit more verbose. But, the benefit of coding directly on the platform and moving towards upcoming web standards seems worth it. Of course, we do use autoprefixer to help out with any vendor prefix shenanigans.

Components + Tokens + Utilities #

AgnosticUI mostly consists of UI components and the CSS custom properties mentioned in the Theming section. However, for convenience we've included some minimal CSS Utilities in common. These are mostly for rapid layout development using Flexbox, margin/padding via logical properties. At time of writing, AgnosticUI adds these with some trepidation as we don't want to increase the build size. If you're looking for a full-blown utility-first library you should probably look at TailWind or similar.

The utilities page shows the available CSS utilities as does the source code on GitHub.

Benefits #

As AgnosticUI works across many frameworks—one stylesheet…many frameworks—your design system team will be able to generate a single source of truth. This theme will manifest as a single CSS custom properties theme that can be imported across your various projects.

For example, let's imagine your company's flagship product is coded in React, an administraction site is coded in Vue 3, and a back-office application is coded in Angular. All of these would share the same CSS custom properties theme, and would therefore have a consistent look and feel.

Then, your front-end developer rock star decides she wants to use Svelte on that hackathon project. Well, she can simply drop in the custom properties theme and get right to hacking up her Svelte idea.

We don't recommend the use of 2+ frameworks in an application with a single HTTP payload due to the increased bundle size that will be sent down to your users. However, completely separate applications are fair game for using different front-end frameworks; especially for polyglot teams that long to use new technologies, or letting an outsourced team use the technology they're most proficient in.

Roadmap #

As AgnosticUI is still very much in its infancy, we advise you to hold off using it for mission critical production applications. That said, things are moving along quite nicely with a current focus on increasing the overall component coverage provided. We invite you to view the upcoming components planned for development on our GitHub issue tracker. Also, feel free to participate in our discussions or help us out by contributing to AgnosticUI.

Angular #

The Angular package should especially be considered experimental as we're not using the library for any production applications. We've elected to challenge ourselves to create comparable component implementations, but you should probably assume there will be bugs that you may need to contribute your own pull request patches for if you elect to use it for your projects. You've been warned ¯\_(ツ)_/¯