Think Like Shadcn

Think like shadcn

The organizing belief is about who owns the abstraction. A package is a closed abstraction maintained by someone else; a registry is an open one maintained by you. Everything else follows: code arrives as files you can read and change, the uninstall path is deleting them, and responsibility for what you shipped transfers with the paste.

The second habit is deciding as little as possible for the consumer while still giving them something good on the first run. Defaults exist to be overwritten, and the escape hatch is designed with the same care as the default path.

The moves

Ship open code, not a closed dependency

The test for any abstraction: can the person using it open it and change it. Packages remain right for real dependencies, and this is not dependency-zero absolutism, the stated form is to own most of your dependencies. What changes is the default for code that is meant to be read, adapted, and made yours.

Three obligations come with that model:

• Uninstalling is deleting the file. If removal requires understanding a system, the abstraction closed itself again.
• Ownership transfers with the copy. The code someone pasted is their code, and their responsibility.
• Easier distribution means fewer execution privileges. The installer never executes code and has no post-install hooks, deliberately. Verify code you did not write, whether it came from a package, a search result, or a model. When you lower the friction of getting code onto a machine, remove powers in the same change.

Open code is also what makes migration possible at all: a codemod can rewrite what lives in the repo, and cannot rewrite what lives behind a version number.

Great defaults, with an escape hatch to zero

Design the default for the majority case, then make overriding it first class rather than grudging. The stated target for a token system is that it works and is not overwhelming to customize for most cases while staying open to bridging your own.

The base is deliberately underspecified so it can be painted over: think of it as a coloring template and a starting point rather than a finished theme. The escape hatch goes all the way, including an option to skip the default setup entirely and start from nothing.

Contested aesthetic decisions become a flag, not a decree. When a styling detail split the community, the sequence was to poll for how common each practice was, then ship a switch rather than pick a winner. The framing: the point is not to decide for you.

Push variance into the install step

The most transferable move here. When a capability is needed by a minority of consumers, make the distribution layer pay for it rather than the source everyone reads.

The clean case is right-to-left support. The industry default bakes directional classes into every component, so everyone deals with the concept whether or not they need it. The alternative is to transform classes at install time, so you do not have to learn it until you need it. The same shape appears in rewriting a utility-class prefix so components drop into an existing system without conflict, and in resolving imports so a registry stops dictating the consumer's file structure.

Ask, for any new requirement: does this belong in the code everyone reads, or in the step that puts the code there?

Decouple the cadence of content from the cadence of the tool

The original architectural decision was to download components rather than bundle them, so adding one does not require releasing the tool. Later versions of the same idea: namespaced endpoints as a versioning mechanism so the commands stay stable, and static distribution staying static while dynamic features are opt-in.

If shipping content forces a release of the machinery, the two are coupled and one of them will slow the other down.

Delete preconditions to widen who can use it

Three years of releases follow one direction: works only in a fresh project, then existing ones, then any framework, then remote sources, then monorepos, then any repository with a manifest, then no config file at all. Every release removes a setup requirement.

The constraint that makes this safe is a near-absolute compatibility rule. Major capability arrives as opt-in flags, new namespaces, or new item types, and existing setups keep working.

Treat agents as a first-class reader

Machine consumers get design attention equal to human ones:

• Error messages are an API surface. State what went wrong, why it happened, how to fix it, and where to find help. Useful for a person and load-bearing for an agent that has nothing else to go on.
• Schema fields exist to be read by models, not only parsed by code.
• Deprecation copy is guidance, phrased so an agent picks up what to do next, and tested by checking which phrasing actually worked.
• Config files are context. Agents read them the way they read a manifest, so what you put there shapes what they do.
• Ship a way to fetch ground truth, such as a docs command that returns documentation, source, and examples, so the model is not guessing from memory.

The underlying claim: distribution is a multiplier for generated code, which makes the registry infrastructure rather than a convenience.

Never move a reader against their intent

The densest interface work in the corpus is a specification for streaming chat, and its rules generalize to any surface where content arrives while someone is reading:

• Auto-scrolling is never the default. Follow the live edge only while the reader is already at it.
• Every interaction is intent. Scrolling is not the only signal: selecting text, using the keyboard, opening a link, or searching all mean stop moving things.
• Content arriving offscreen gets announced out of band rather than by moving the viewport.
• Restore to the last meaningful position, usually the last thing the reader sent, rather than the absolute bottom.
• Layout changes, including images loading, content expanding, and history prepending, must not cost the reader their place.
• Interruptions such as stopping, retrying, or regenerating must not steal position either.

This was an opinion for two years before it became a primitive, which is the recurring pipeline: say the thing publicly, keep saying it, then ship the implementation.

Read a competing product by enumerating mechanisms

When analyzing an interface someone else built, list properties and their consequences rather than reacting. Not "the navigation is nice" but: it shows the whole conversation rather than one message, it gives one focus target you can bind a shortcut to, it is a list so search and arrow keys become possible, it stays open while you jump around.

For landing pages the same discipline reduces to showing more and telling less, validated by watching someone unfamiliar try to understand the product.

Design in the harsher rendering environment

Work in light mode, because shadows, borders, and depth are more forgiving in dark mode and light mode exposes what is wrong. Dark mode is for screenshots.

Judge a component API by output variance

The acceptance test is not feature coverage, it is whether the API produces different-looking results. A composition that took several iterations was iterated specifically so that consumers would not all end up with the same thing.

After human testing, hand the components to a generation tool and try to break them. Generators double as fuzzers for component APIs.

The compressed statement

Convention over configuration. Platform over abstraction. Predictable over magical. Platform here means the language, framework, native APIs, and runtime: bet on the substrate rather than on a wrapper over it.

Mechanics

Launches follow a fixed shape: a teaser that withholds the noun, a header post naming the thing in one sentence, then numbered replies with one capability each and a video or screenshot on every one, then the compatibility reassurance, then the escape hatch, then a short sign-off with the changelog and named credit to contributors.

Arguments start from the mechanism of the status quo, not from a value claim. Describe how it is normally done and what that costs, introduce the different approach, then state the consequence in second person. Disputes get reframed as questions about which abstraction is open, or settled with a command line and a short recording.

Replies answer first in one word, then give one sentence of mechanism, then the exact command. Bug triage runs acknowledge, ask for a reproduction, take a look, then post the fix with a changelog link.

Register is fragment stacking: noun phrases separated by periods, no connectives. Second person throughout. No jargon, no credentials, and notably no metrics used as argument. Numbers appear in celebration posts and never as evidence in a design argument, which is the sharpest contrast with measurement-first engineering voices.

Using this lens well

Copy-in defers maintenance, it does not delete it. The model works here because the deferred bill gets paid by whoever writes the codemods: migration scripts for framework upgrades, styling migrations, directional-class rewrites. Without the capacity to write codemods, many drifted copies are worse than one version bump. Fan-out is affordable in proportion to your codemod capability.

Verification burden transfers to the consumer. "Verify code you did not write" is honest and it is a transfer. In a regulated setting, one audited dependency with a lockfile and a bill of materials can beat forty inlined files nobody re-reviews. Keep the no-execution discipline; be skeptical of the ownership framing at that scale.

Install-time transformation presupposes a shared substrate. Rewriting classes only works because everything downstream shares a component model, a utility-class system, and a token contract. Remove any of those and the registry degrades into a fancy file copy. The demonstrated transforms are specific to one styling system, whatever the framework-agnostic framing suggests.

Compatibility is cheap for files and expensive for runtimes. Promising no breaking changes costs little when the boundary is files on disk. Anything with behavioral guarantees, a wire protocol, or persisted state cannot buy compatibility that cheaply, and holding the line there preserves bad design.

The defaults are calibrated to one product shape. Dashboards, auth, marketing sections, chat. Data-dense enterprise tables, editors, canvas and timeline tools, and offline-first apps are not what this was tuned on. Right-to-left support arriving two and a half years in is evidence that the default path lags products outside the assumed shape.

Non-opinionation is itself a cost transfer. Refusing to decide is right for a public library and often wrong inside a company, where the value of a design system is precisely that it decides. A neutral foundation given to a team without taste produces many inconsistent products rather than many tasteful ones.

Solo velocity is not team velocity. One owner with total context over one codebase can work on one branch in one thread. That is a personal workflow, not an engineering standard.

Agent-readability can cost human ergonomics. Verbose errors, flat schemas, and retrieval-shaped docs all take something from the human reader. Name the tradeoff rather than defaulting to the machine.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: zaidmukaddam
• Source: zaidmukaddam/skills
• License: MIT
• Homepage: https://zaidmukaddam.com/skill

Install and usage instructions live in the source repository linked above.