Component grammar: when shadcn defaults stop being neutral
Shadcn's defaults are a position, not a blank slate. When agents apply them unchanged, the result reads as AI-built before the user consciously registers why.
Every component library ships with defaults. Padding values, border radii, font sizes, spacing scales, color tokens. These defaults are not neutral — they're a position. They represent the library author's judgment about what looks competent at a general-purpose level. Shadcn's defaults are well-calibrated for that goal: they produce interfaces that look professional without looking distinctive.
The problem isn't that they're bad. The problem is that when an agent applies them unchanged across a product, the result reads as AI-built before any individual user could explain why. Something about it is familiar in the wrong way. It looks like the last three tools you used.
That's component grammar breaking down.
What component grammar means
Component grammar is the visual logic that makes a product's components feel like they belong to each other and to the product. Not just "consistent" in the sense that buttons look alike — but coherent in the sense that the spacing, the weight distribution, the radius choices, and the density all communicate the same underlying sensibility.
A product with strong component grammar feels like it was designed by one hand, or at least by a team with a shared point of view. The components feel specific to the context: a dense internal operations tool feels different from a consumer-facing onboarding flow even when they share the same underlying component kit. Component grammar is what produces that difference.
When grammar is weak, the product feels assembled rather than designed. Each component looks fine individually. Together, they don't read as a system.
How shadcn defaults flatten it
Shadcn's defaults cluster around a particular aesthetic: 0.5rem border radius, slate palette, 14px body text, generous but not generous whitespace, medium border weight. These are defensible choices. They also appear in roughly half the agent-built products shipped in 2025.
The issue isn't the choices themselves — it's that they're applied uniformly, without reference to what the product is, who uses it, or what it needs to communicate. A warehouse operations tool and a consumer budgeting app have different grammar requirements. They need different density levels, different emphasis weight, different radius sensibilities. Shadcn defaults produce the same output for both.
Pattern: defaults are a position. If the agent applies them unchanged, the product looks like the agent built it — because every other agent is making the same choices. Component grammar is how you encode the product's actual sensibility into the build.
The signal that grammar is failing
Users don't usually say "your component grammar is weak." They say things like "it looks kind of generic," "it doesn't feel like our product," or "it's fine but I'm not excited about it." Designers say "the shadcn defaults are showing" and mean it as a diagnosis.
The more precise signal is in the details. Button padding that doesn't feel native to the content density. Input borders that read as default web rather than considered choice. A card radius that works at 12px in every other context but reads as wrong here. Typography hierarchy that's functional but not expressive. These are all component grammar failures. Each one is small. Together they produce a product that reads as assembled.
The hardest part is that the failures are invisible until you look for them. A product with weak grammar passes a quick scan. It's only when you sit with it — or when you put it next to a product with strong grammar — that the difference becomes obvious.
How TheDesignAgent scores it
The /visual lens includes component_grammar as one of seven sub-scores. It asks: do the components feel like they belong to this product, or do they read as defaults applied without modification?
Low scores on component_grammar produce patches that are unusually specific: radius adjustments calibrated to the product's density, color token replacements that shift from slate to a more specific palette, spacing scale changes that match the product's actual content weight. These are changes the agent could make on its own — but won't, without being told what the product's sensibility actually is.
That specificity is what makes component_grammar one of the hardest scores to hit on a first build. The agent knows how to apply components. It doesn't know what the product is supposed to feel like. Project memory helps — once a product's visual decisions are captured, future builds get compared against them. But the first build is always working from the corpus, and the corpus can only tell the agent what's generally wrong. It can't tell it what's specifically right for you.
We'll write more about how to encode visual taste into project memory so that agents build to a higher baseline from the start.