First principles of UI composition for your coding agents

A developer guide lays out four levels of UI components — headless, design system (such as shadcn/ui), layout, and consumer — and five rules for keeping AI coding agents from producing sloppy interfaces. The rules direct developers to scaffold projects with shadcn/ui, route styling changes through the design system rather than consumer components, and keep each component level in separate directories such as components/ui and components/layout. The guide advises having agents mimic shadcn/ui's composition patterns, using props like variant and size before className.

First Principles of UI Composition This is the valuable insight I've gained regarding avoiding UI sloppiness... If you are vibe-coding user interfaces and you are a layperson when it comes to UI/UX, to keep your app from looking like slop, just feed this article to your agents. There are four levels of components. 1. Level I: the headless components. They handle all the low-level, tedious, and laborious tasks—the core behavior of a component, its DOM positioning, accessibility, and mobile adaptation not stylistic adjustments, but things like “Can the context menu be brought up by long-pressing on mobile?” . They don’t concern themselves with how the component looks visually; if you use them directly, you’ll only get a complex API and an unstyled appearance. 2. Level II: the design system components, like shadcn/ui. These components form the cornerstone of the entire UI design system, e.g. buttons and cards. They are primarily wrappers around Level I headless components, adding styles that ensure consistency across all components and providing multiple variants. 3. Level III: the layout components. These components aren’t necessarily related to the first two levels, but they abstract the layouts commonly used in your app. Extracting layout components rather than having them scattered throughout the code improves code maintainability and readability. However, this is not a must. 4. Level IV: the consumer components. These are the components that actually use design system components and layout components to directly build your user interface. To make your UI code readable and maintainable, here are five minimal rules. 1. Use shadcn/ui to create ↗ https://ui.shadcn.com/create a project. Unless you have a solid grasp of the ins and outs, don’t mess with it since it’s the best and most streamlined architecture you’ll ever come across. 2. When you need to modify a component’s styling, think about your design system. If you’re completely new to this, just go to https://ui.shadcn.com/create ↗ https://ui.shadcn.com/create I linked above. It offers simple options that even a novice can use, yet they’re powerful enough to create a wide variety of interface styles. Click Get Code – Existing Project to send your customized presets to your agents. Please keep in mind that this is a rare opportunity to experiment with styling while avoiding a sloppy look. Opportunities like this really don’t come along very often. Thank shadcn<sup 1 user-content-fn-1 </sup . 3. If you’re determined to do so, or if your agents have convinced you to, you can allow them to modify the component styles in shadcn/ui. For experienced developers, shadcn/ui actually encourages this; that’s precisely why it’s distributed as copyable and modifiable code. 4. Keep components at each level separate. Keep design system components in components/ui , layout components in components/layout , and consumer components organized within your feature or page modules. As your project grows rapidly, there’s no need to rush to strictly extract layout components, but doing so from time to time is very helpful in making you realize just how much your app resembles slop, so you can then correct it. If you create a button with a new style in a consumer component, be careful. You r agent should be writing a design system component according to the standards for design system components and reuse it. 5. When using components, strictly adhere to the “composition” advocated by the design system components. For example, place individual fields inside a FieldGroup rather than using a single div and writing a bunch of Flexbox styles. Consider props like variant , size , etc. before writing className= . If you create design system components other than those from shadcn/ui, please ensure that they also provide out-of-the-box compositions, just like the shadcn/ui components. Your agents are good at mimicking; have them mimic shadcn/ui. The above assumes you are using Tailwind CSS. If you aren’t, you likely won’t be able to use shadcn/ui either, but the underlying principles remain the same, and your agents will have no trouble understanding them. The above assumes you are developing an application in React. If you aren’t, the underlying principles remain the same, and your agents will have no trouble understanding them. The above assumes you know absolutely nothing about UI design but still have some aspirations in that area. If that’s not the case, thank you for listening and for your laughter. Footnotes footnote-label 1. In addition to shadcn/ui, there are other excellent similar projects out there. If you or your agents are familiar enough with them, it’s entirely possible to replace it ↩ user-content-fnref-1