Blueprint
Product thesis and MVP scope
Provide frontend developers with a customizable component library and tooling to rapidly build UI without locking into a hosted service.
Target user
Frontend developers and teams building React applications who want a flexible, extendable design system.
MVP scope
- Set of 15-20 core accessible components (Button, Input, Dialog, Tabs, Select, etc.)
- CLI tool for initializing a project and adding components via `npx my-lib add`
- Documentation site with interactive examples and code snippets
- Open-source component registry (static JSON) served over HTTPS
- Tailwind CSS integration and theming support via CSS variables
- TypeScript definitions for all components
System
Entities, flows, and modules
Entities
Component
name, files (list of file paths relative to registry root), dependencies (npm packages required), registry (string identifier), version (semver) — The fundamental unit of distribution; each component is a set of source files and metadata that the CLI copies into a consumer's project.
Registry
name, url (base endpoint for fetching files), components (list of Component references), maintainer — A collection of components that the CLI can install from. The default registry is a public GitHub repo; private registries can be added later.
ProjectConfig
tailwind (config object with paths and plugins), aliases (object mapping component categories to import paths), style (enum: 'default', 'new-york'), components (list of installed component names) — Stored in `components.json` in the consumer's project root; defines how components are integrated, themed, and where they are placed.
Flows
CLI init
`my-lib init` — Scaffolds `components.json` and project configuration with default Tailwind settings and aliases.
CLI add component
`my-lib add <component>` — Copies component source files and dependencies into the user's project, merging the configuration.
Docs component page
/docs/components/<component-name> — Shows interactive example, code preview, and installation instructions for the component.
Docs theming page
/docs/theming — Explains how to customize colors, spacing, and typography via CSS variables.
Registry index endpoint
https://registry.my-lib.com/index.json — Returns a JSON list of all available components with metadata, consumed by the CLI.
Backend modules
Registry Content Pipeline
Generates the registry index and component file bundles from the monorepo, ready for deployment to static hosting (CDN). — Enables the CLI to fetch components reliably; start with static JSON to avoid server complexity.
CLI Module
Reads the registry index, resolves component dependencies (including other components and npm packages), and writes files to the user's project. — Core distribution mechanism; must be tightly integrated with the registry and project configuration from day one.
Documentation App
Serves the reference for all components, including live previews, code snippets, and theming guides. — Adoption depends on developers being able to see and try components quickly; the docs site acts as a primary discovery and evaluation surface.
Phases
Implementation phases
Foundation
Set up the monorepo, create the first 10-15 components, and a basic CLI with init and add commands.
Deliverables
- Monorepo structure with Turborepo, pnpm workspaces, shared TypeScript and ESLint configs
- Component library package with 15 core components using Radix and Tailwind
- CLI tool able to successfully run `init` and `add` against a local registry
- Minimal documentation site with component listing (no interactivity yet)
Exit criteria
- All components render without errors in a Next.js consumer app
- `my-lib add button` copies Button source files and updates `components.json`
- Docs site is live and shows basic usage snippets
Expansion
Grow the component library to 30+ components, add rich theming, and interactive documentation.
Deliverables
- 30+ components covering forms, layouts, overlays, and data display
- Dark mode and CSS variable-based theming system
- Interactive component previews on the docs site (using iframe or live editor)
- Storybook integration for component development and testing
Exit criteria
- A developer can build a typical SaaS dashboard using only the library
- Theming guide successfully explains how to customize colors, spacing, and fonts
Registry and Distribution
Build a versioned, scalable registry system that supports third-party registries and component updates.
Deliverables
- Automated registry index generation from monorepo
- Versioning scheme for components (semver for component packages)
- Support for multiple registries in CLI (e.g., official, community, enterprise)
- Update mechanism that merges changes without overwriting user customizations
Exit criteria
- User can add a component from a third-party registry by URL
- Running `my-lib update button` updates only the component files, not user modifications
Community and Growth
Establish contribution workflows, telemetry, and usage analytics to guide development.
Deliverables
- Contributor guide with coding standards and pull request process
- Opt-in telemetry in CLI for component popularity and error tracking
- Public roadmap and issue templates
- Automated changelog generation
Exit criteria
- External contributors successfully submit new components through a standardized review process
- Telemetry data shows top used components and common CLI errors
Monetization Foundations
Introduce paid features: private registries, team collaboration, and premium templates.
Deliverables
- User authentication and team management service
- Private registry hosting with access controls
- Payment integration (Stripe) for team seat subscriptions
- Curated premium component packs and starter templates
Exit criteria
- A team can purchase a plan, create a private registry, and add it via the CLI
- Revenue from early adopters covers infrastructure costs
Build first
Build first, skip first, and watchouts
First things to build
- Monorepo setup with Turborepo, pnpm workspaces, and base ESLint/TypeScript configs
- First 10 components: Button, Input, Select, Dialog, DropdownMenu, Tabs, Card, Avatar, Badge, Tooltip, using Radix primitives and Tailwind
- CLI core: `init` command that scaffolds `components.json` with default Tailwind configuration and aliases
- CLI `add` command that reads a static registry JSON, resolves dependencies, and writes files to the consumer's project
- Basic documentation site with a listing of components and their usage (markdown or MDX)
- A simple registry file (index.json) with metadata for the first 10 components
Not to build yet
- Private registry hosting and authentication
- Premium templates and starter kits
- Telemetry/analytics
- Component drag-and-drop builder
- Figma or design tool integration
- Enterprise support ticketing system
- Multi-framework support (Vue, Svelte, etc.)
Risks / blockers
- Maintainer burnout: the project may depend on a single leader; bus factor risk could stall development.
- Community fragmentation: third-party registries causing inconsistencies and support burden could dilute trust.
- Adoption hurdles: potential users may already use shadcn/ui itself, making competition tough without a clear differentiator.
- No testing culture: without comprehensive tests, component bugs may undermine production confidence.
Builder prompts
Derived builder prompts
Master
Master context prompt
Expand prompt
You are building a fresh implementation inspired by the shadcn-ui/ui repository. Treat the repository as a reverse-engineering reference, not as the default destination codebase. Infer the product, architecture, entities, and flows from the reference repository, then rebuild the core system intentionally from scratch. Do not blindly clone the original repo. Do not default to patching or refactoring it in place. Build in small phases and keep the first version focused and maintainable. Product thesis: Provide frontend developers with a customizable component library and tooling to rapidly build UI without locking into a hosted service. Commercial/product framing: By decoupling components from the library, developers own the code and avoid vendor lock-in, while still benefiting from a curated, high-quality starting point and a CLI for seamless integration. Target user: Frontend developers and teams building React applications who want a flexible, extendable design system. MVP scope: - Set of 15-20 core accessible components (Button, Input, Dialog, Tabs, Select, etc.) - CLI tool for initializing a project and adding components via `npx my-lib add` - Documentation site with interactive examples and code snippets - Open-source component registry (static JSON) served over HTTPS - Tailwind CSS integration and theming support via CSS variables - TypeScript definitions for all components Stack assumptions: - Monorepo managed with Turborepo and pnpm workspaces - Components built with React, TypeScript, Tailwind CSS, and Radix UI primitives - CLI built with Node.js and published as npm package - Documentation site using Next.js (App Router) with live previews - Registry stored as JSON files on GitHub, consumed by CLI via HTTPS - Testing with Vitest and Storybook for component development - CI via GitHub Actions for build, test, and publish - Consumer project configuration via `components.json` file Key entities: - Component: name, files (list of file paths relative to registry root), dependencies (npm packages required), registry (string identifier), version (semver) - Registry: name, url (base endpoint for fetching files), components (list of Component references), maintainer - ProjectConfig: tailwind (config object with paths and plugins), aliases (object mapping component categories to import paths), style (enum: 'default', 'new-york'), components (list of installed component names) Core pages / routes / flows: - CLI init (`my-lib init`): Scaffolds `components.json` and project configuration with default Tailwind settings and aliases. - CLI add component (`my-lib add <component>`): Copies component source files and dependencies into the user's project, merging the configuration. - Docs component page (/docs/components/<component-name>): Shows interactive example, code preview, and installation instructions for the component. - Docs theming page (/docs/theming): Explains how to customize colors, spacing, and typography via CSS variables. - Registry index endpoint (https://registry.my-lib.com/index.json): Returns a JSON list of all available components with metadata, consumed by the CLI. Backend services / modules: - Registry Content Pipeline: Generates the registry index and component file bundles from the monorepo, ready for deployment to static hosting (CDN). - CLI Module: Reads the registry index, resolves component dependencies (including other components and npm packages), and writes files to the user's project. - Documentation App: Serves the reference for all components, including live previews, code snippets, and theming guides. Do not build yet: - Private registry hosting and authentication - Premium templates and starter kits - Telemetry/analytics - Component drag-and-drop builder - Figma or design tool integration - Enterprise support ticketing system - Multi-framework support (Vue, Svelte, etc.) Major risks / blockers: - Maintainer burnout: the project may depend on a single leader; bus factor risk could stall development. - Community fragmentation: third-party registries causing inconsistencies and support burden could dilute trust. - Adoption hurdles: potential users may already use shadcn/ui itself, making competition tough without a clear differentiator. - No testing culture: without comprehensive tests, component bugs may undermine production confidence. Work in phases. After each phase, summarize what was built, what remains, and which assumptions from the reference repo you intentionally did or did not keep.
Phase 1
Phase 1 foundation prompt
Expand prompt
Phase 1 foundation Objective: Set up the monorepo, create the first 10-15 components, and a basic CLI with init and add commands. Deliverables: - Monorepo structure with Turborepo, pnpm workspaces, shared TypeScript and ESLint configs - Component library package with 15 core components using Radix and Tailwind - CLI tool able to successfully run `init` and `add` against a local registry - Minimal documentation site with component listing (no interactivity yet) - Exit: All components render without errors in a Next.js consumer app - Exit: `my-lib add button` copies Button source files and updates `components.json` - Exit: Docs site is live and shows basic usage snippets Rules: - Start by reverse engineering the product shape from the reference repo, then create a clean fresh project structure. - Set up the minimum schema, services, routes, and project structure required for the MVP. - Avoid polish work, avoid optional abstractions, and avoid copying implementation details you do not understand. Start by reverse engineering the reference repository, then implement the fresh build in the smallest clean sequence.
Phase 2
Phase 2 core flow prompt
Expand prompt
Phase 2 core flow Objective: Grow the component library to 30+ components, add rich theming, and interactive documentation. Deliverables: - 30+ components covering forms, layouts, overlays, and data display - Dark mode and CSS variable-based theming system - Interactive component previews on the docs site (using iframe or live editor) - Storybook integration for component development and testing - Exit: A developer can build a typical SaaS dashboard using only the library - Exit: Theming guide successfully explains how to customize colors, spacing, and fonts Rules: - Implement the core pages, routes, and backend modules needed for the happy path in the fresh build. - Use the reference repo for behavior and architecture cues, not as the code target. - Preserve maintainability and add only the minimum comments needed. Start by reverse engineering the reference repository, then implement the fresh build in the smallest clean sequence.
Phase 3
Phase 3 polish/refactor prompt
Expand prompt
Phase 3 polish and refactor Objective: Build a versioned, scalable registry system that supports third-party registries and component updates. Deliverables: - Automated registry index generation from monorepo - Versioning scheme for components (semver for component packages) - Support for multiple registries in CLI (e.g., official, community, enterprise) - Update mechanism that merges changes without overwriting user customizations - Exit: User can add a component from a third-party registry by URL - Exit: Running `my-lib update button` updates only the component files, not user modifications Rules: - Refine the fresh implementation without introducing a large refactor. - Improve validation, edge cases, and developer ergonomics where the core flow already exists. - Prefer targeted cleanup over architecture churn or feature creep. Start by reverse engineering the reference repository, then implement the fresh build in the smallest clean sequence.
Deploy
Deploy/finalization prompt
Expand prompt
Deploy and finalization Objective: Prepare the implementation for release, verification, and handoff. Deliverables: - Verify the main flows work. - Check configuration, environment assumptions, and release blockers. - Summarize remaining risks and suggested follow-up work. Rules: - Do not add speculative infrastructure. - Focus on practical release readiness, tests, and explicit known gaps versus the reference repo. Start by reverse engineering the reference repository, then implement the fresh build in the smallest clean sequence.
Bugfix
Bugfix/refinement prompt
Expand prompt
Bugfix and refinement Objective: Fix the specific bug or implementation gap in the fresh build while preserving the established architecture. Deliverables: - Reproduce the issue in the rebuilt implementation. - Patch the smallest reliable fix. - Explain what caused it, how to verify the fix, and whether the reference repo suggests an architecture guardrail you missed. Rules: - Inspect the fresh implementation before editing. - Do not rewrite working systems just to fix a localized issue. Start by reverse engineering the reference repository, then implement the fresh build in the smallest clean sequence.