devstack 0.1.0

package/vendor/skills/skills/building-components/references/design-tokens.mdx

@@ -0,0 +1,57 @@
+---
+title: Design Tokens
+description: How semantic naming conventions and design tokens create a flexible, maintainable theming system.
+type: conceptual
+summary: Semantic CSS variable architecture for theming with layers of abstraction that separate what something is from how it looks.
+prerequisites:
+  - /styling
+related:
+  - /data-attributes
+---
+
+One of the core foundations of modern component libraries lies in their thoughtful approach to styling. Rather than hardcoding colors or creating rigid class systems, we can employ a semantic naming convention that separates the concerns of theme, context, and usage.
+
+This semantic naming convention is known as design tokens. This architectural decision creates a maintainable, flexible system that scales beautifully across applications.
+
+## The Philosophy of Semantic CSS Variables
+
+Traditional CSS approaches often couple color values directly to their usage contexts, creating brittle systems that are difficult to maintain. Design tokens take a different approach by creating layers of abstraction that separate what something is from how it looks.
+
+## Understanding the Variable Architecture
+
+Let's examine how we can structure our CSS variables to create this flexible system:
+
+```css title="globals.css"
+@import "tailwindcss";
+@import "tw-animate-css";
+
+@custom-variant dark (&:is(.dark *));
+
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+}
+
+:root {
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.145 0 0);
+  --primary: oklch(0.205 0 0);
+  --primary-foreground: oklch(0.985 0 0);
+}
+
+.dark {
+  --background: oklch(0.145 0 0);
+  --foreground: oklch(0.985 0 0);
+  --primary: oklch(0.922 0 0);
+  --primary-foreground: oklch(0.205 0 0);
+}
+```
+
+In the above example, we have four design tokens:
+
+- `--background`, which is used for background colors (primarily the background of the page)
+- `--foreground`, which is used for foreground colors (the general text color)
+- `--primary`, which is used for primary colors (the main color of the brand)
+- `--primary-foreground`, which is used for primary foreground colors (the text color, as seen against the primary color)

package/vendor/skills/skills/building-components/references/docs.mdx

@@ -0,0 +1,153 @@
+---
+title: Docs
+description: How to document your components.
+type: guide
+summary: Essential documentation sections for components including demos, installation, API reference, accessibility notes, and changelog.
+prerequisites:
+  - /composition
+related:
+  - /registry
+  - /npm
+  - /marketplaces
+---
+
+Good documentation is essential for making your components accessible and easy to use. This guide outlines the key elements every component documentation page should include.
+
+## Documentation Framework
+
+To scale your documentation, you can use a documentation framework. There are many options available depending on your projects' language and project needs. Popular options include:
+
+- [Fumadocs](https://fumadocs.dev/) - Fast, feature-rich documentation framework for Next.js
+- [Nextra](https://nextra.site/) - Markdown-based documentation with built-in search and theming
+- [Content Collections](https://content-collections.dev/) - Type-safe content management for documentation
+- [Docusaurus](https://docusaurus.io/) - Feature-rich documentation sites with versioning support
+- [VitePress](https://vitepress.dev/) - Vue-powered static site generator optimized for documentation
+
+Preferably, your framework choice should support syntax highlighting, custom components and be generally well designed.
+
+## Essential Documentation Sections
+
+### Overview
+
+Start with a brief introduction explaining what the component does and when to use it.
+
+### Demo, Source Code, and Preview
+
+For a great first impression for developers, you should include a demo that shows the component in action, as well as the code used to create the demo.
+
+If you're using an open source [Registry](/registry), you can also include a preview of the source code that is used to create the component.
+
+Use code blocks with syntax highlighting and copy-to-clipboard functionality. Consider using tabbed interfaces to switch between these views without cluttering the page.
+
+### Installation
+
+Include a clear instruction on how to install the component. Preferably this should be a single command you can copy and paste into your terminal.
+
+If you're building on shadcn/ui, you can use the [shadcn CLI](https://ui.shadcn.com/docs/cli) to install the component e.g.
+
+```package-install
+npx shadcn@latest add <your-component-url>
+```
+
+If you're publishing to a [Marketplace](/marketplaces), you can use the marketplace's CLI to install the component e.g.
+
+```package-install
+npx shadcn@latest add https://21st.dev/r/<your-author>/<your-component>
+```
+
+If you're not using shadcn/ui but you are building a [Registry](/registry), you could build your own CLI to install the component, e.g.
+
+```package-install
+npx your-registry-cli@latest add <your-component-url>
+```
+
+Lastly, if you're publishing to npm, you can use the npm CLI to install the component e.g.
+
+```package-install
+npm install <your-component-name>
+```
+
+<Callout>
+  To show multiple installation options like we've done above, you can use something like Fumadocs'
+  [`package-install` syntax](https://fumadocs.dev/docs/headless/mdx/install).
+</Callout>
+
+### Features
+
+List the key features of your component to help users quickly understand its capabilities and advantages. For example:
+
+- **Customizable** – Easily adjust styles, sizes, and behavior to fit your needs.
+- **Accessible by default** – Follows best practices for keyboard navigation, ARIA roles, and screen reader support.
+- **Composable** – Designed to work seamlessly with other components and patterns.
+- **Type-safe** – Ships with comprehensive TypeScript types for maximum safety and autocomplete.
+- **Theming support** – Integrates with your design tokens or theme system.
+- **Lightweight** – Minimal dependencies and optimized for performance.
+- **SSR/SSG ready** – Works with server-side and static rendering frameworks.
+- **Well-documented** – Includes clear usage examples and API reference.
+
+Tailor this list to your specific component. Highlight what makes it unique or especially useful for developers.
+
+### Examples
+
+Demonstrate the component's flexibility with practical examples:
+
+- **Variants** - Different visual styles or sizes available
+- **States** - Loading, disabled, error, or success states
+- **Advanced Usage** - Complex scenarios and edge cases
+- **Composition** - How the component works with other components
+- **Responsive Behavior** - How it adapts to different screen sizes
+
+Each example should include both the rendered output and the corresponding code.
+
+### Props and API Reference
+
+Document all available props, methods, and configuration options. Consider grouping related props together and highlighting commonly used ones. For each prop, include:
+
+- **Name** - The prop identifier
+- **Type** - TypeScript type definition
+- **Default** - Default value if not specified
+- **Required** - Whether the prop is mandatory
+- **Description** - What the prop does and when to use it
+
+<Callout>
+  If you're using Fumadocs, you might consider using [Auto Type
+  Table](https://fumadocs.dev/docs/ui/components/auto-type-table) to ensure accuracy and reduce
+  maintenance burden.
+</Callout>
+
+### Accessibility
+
+Document how your component supports accessibility features:
+
+- Keyboard navigation patterns
+- ARIA attributes and roles
+- Screen reader support
+- Focus management
+- Color contrast considerations
+
+### Changelog and Versioning
+
+It can be useful to maintain a changelog on each component documentation page covering:
+
+- Version numbers following semantic versioning
+- New features and enhancements
+- Bug fixes
+- Breaking changes
+- Migration guides for major version updates
+
+Help users understand what changed between versions and how to upgrade safely. Include code examples showing before/after patterns for breaking changes.
+
+<Callout>
+  If your syntax highlighting framework supports it (like Shiki), you might want to use a [diff
+  transformer notation](https://shiki.style/packages/transformers#transformernotationdiff) to show
+  the changes between versions.
+</Callout>
+
+## Best Practices
+
+- Keep documentation up-to-date with code changes
+- Use real-world examples that solve actual problems
+- Include common pitfalls and troubleshooting tips
+- Provide performance considerations when relevant
+- Link to related components and patterns
+- Make all code examples runnable and tested

package/vendor/skills/skills/building-components/references/marketplaces.mdx

@@ -0,0 +1,144 @@
+---
+title: Marketplaces
+description: Using component marketplaces to share your components.
+type: conceptual
+summary: Centralized platforms like 21st.dev for publishing, discovering, and installing UI components with built-in previews and community feedback.
+prerequisites:
+  - /registry
+related:
+  - /npm
+  - /docs
+---
+
+Component marketplaces represent another new paradigm in how developers share and discover UI components. Platforms like [21st.dev](https://21st.dev) have emerged as centralized hubs where creators can publish components and consumers can discover, preview, and install them seamlessly.
+
+These marketplaces combine the accessibility of registries with the discoverability of traditional package repositories, creating vibrant ecosystems for component sharing.
+
+## How Marketplaces Work
+
+When you publish to a marketplace, the platform typically:
+
+1. **Hosts your component code** - No need to manage your own infrastructure
+2. **Provides a unified CLI** - Users install components through the marketplace's tooling
+3. **Generates previews** - Live demos and interactive examples are created automatically
+4. **Handles discovery** - Search, categories, and recommendations surface relevant components
+
+For example, installing from 21st.dev uses the familiar shadcn CLI pattern:
+
+```bash title="Terminal"
+npx shadcn@latest add https://21st.dev/r/haydenbleasel/dialog-stack
+```
+
+The marketplace handles serving the component metadata and source code, making the installation process seamless.
+
+## Benefits of Component Marketplaces
+
+Marketplaces offer unique advantages that neither registries nor npm packages can match on their own.
+
+### For Component Authors
+
+#### Distribution Without Infrastructure
+
+Publishing to a marketplace eliminates infrastructure concerns. You don't need to setup hosting for your components, or manage CDN distribution.
+
+The marketplace handles all of this, letting you focus on creating great components.
+
+#### Built-in Audience
+
+Marketplaces aggregate demand. When developers visit 21st.dev or similar platforms, they're actively looking for components. Your work gets discovered organically through search, categories, and recommendations.
+
+This built-in traffic means you don't need to market your components independently.
+
+#### Monetization Opportunities
+
+Some marketplaces enable creators to monetize their work through premium component tiers, sponsorship programs, usage-based pricing, and one-time purchase models.
+
+This creates sustainable incentives for maintaining high-quality components.
+
+#### Community Feedback
+
+Marketplaces typically include rating systems, comment sections, usage analytics, and issue tracking.
+
+This feedback loop helps you understand how developers use your components and what improvements they need.
+
+### For Component Consumers
+
+#### Curated Discovery
+
+Unlike searching through GitHub or npm, marketplaces offer curated experiences:
+
+```
+Browse by category:
+├── Marketing
+│   ├── Heroes
+│   ├── Pricing
+│   └── Testimonials
+├── Application
+│   ├── Dashboards
+│   ├── Forms
+│   └── Data Display
+└── E-commerce
+    ├── Product Cards
+    ├── Cart
+    └── Checkout
+```
+
+This organization makes finding the right component significantly faster.
+
+#### Quality Assurance
+
+Many marketplaces implement review processes. Components might go through code quality checks, accessibility audits, performance testing, and documentation review.
+
+This curation ensures a baseline quality that self-published components might lack.
+
+#### Unified Tooling
+
+Using a single CLI for all marketplace components simplifies workflow. You can install any component from the marketplace using the same command:
+
+```bash title="Terminal"
+npx shadcn@latest add https://21st.dev/r/<author>/<component>
+```
+
+## Challenges of Marketplaces
+
+While marketplaces offer compelling benefits, they also introduce unique challenges.
+
+### For Authors
+
+#### Competition and Visibility
+
+In a crowded marketplace, standing out becomes difficult. You're competing with hundreds of similar components, established creators with followings, featured or sponsored content, and algorithm-driven recommendations.
+
+Success requires more than just good code - you need compelling previews, excellent documentation, and often, active promotion.
+
+#### Platform Dependency
+
+Publishing on a marketplace means accepting their terms of service, revenue sharing models, technical requirements, and review processes.
+
+If the platform changes policies or shuts down, your distribution channel disappears.
+
+#### Quality Pressure
+
+Marketplace users expect polished, production-ready components. This means comprehensive documentation, multiple demo variations, responsive design, cross-browser testing, and accessibility compliance.
+
+Meeting these expectations requires significant time investment beyond just writing component code.
+
+### For Consumers
+
+#### Variable Quality
+
+Despite review processes, marketplace quality varies wildly. You might encounter abandoned components with outdated dependencies, poorly documented code, components that work in demos but break in production, and inconsistent coding styles across different authors.
+
+Due diligence is still required when selecting components.
+
+#### Lock-in Concerns
+
+While marketplaces use standard tools like the shadcn CLI, they might introduce proprietary metadata formats, custom configuration requirements, and platform-specific dependencies.
+
+This can make migrating away from the marketplace difficult.
+
+#### Discovery Paradox
+
+Too much choice can be paralyzing. When searching for a button component, finding 200 options doesn't necessarily help. You need to evaluate multiple similar components, compare subtle differences, assess long-term maintainability, and consider author reputation.
+
+This evaluation process can take longer than building the component yourself.

package/vendor/skills/skills/building-components/references/npm.mdx

@@ -0,0 +1,166 @@
+---
+title: NPM
+description: How to publish your components to NPM.
+type: guide
+summary: Publishing component libraries to npm with versioned distribution, Tailwind configuration, TypeScript support, and package.json setup.
+prerequisites:
+  - /registry
+related:
+  - /marketplaces
+  - /docs
+---
+
+NPM packages represent the traditional approach to distributing component libraries. While [registries](/registry) have gained popularity for their flexibility, npm publishing remains a powerful option with distinct advantages for certain use cases.
+
+The fundamental difference between npm packages and registries lies in how they distribute code and manage ownership.
+
+## Package Model
+
+When you publish components as an npm package, you're distributing pre-built, versioned code that users install as a dependency:
+
+```bash title="Terminal"
+npm install @acme/ui-components
+```
+
+```tsx title="MyApp.tsx"
+import { Button } from "@acme/ui-components";
+
+// Component is imported from node_modules
+// Source code is not directly editable
+```
+
+This offers several compelling advantages that make them the right choice for many component libraries.
+
+### Version Management
+
+As the package author, you control versioning and updates. Users can lock to specific versions, ensuring stability:
+
+```json
+{
+  "dependencies": {
+    "@acme/ui-components": "^2.1.0"
+  }
+}
+```
+
+This centralized version control means you can push updates, security patches, and new features that users receive through standard dependency updates.
+
+### Simplified Installation
+
+NPM packages provide a frictionless installation experience. A single command adds your entire component library:
+
+```bash
+npm install @acme/ui-components
+```
+
+No need to manually copy files, manage dependencies, or configure build tools. Everything works out of the box.
+
+### Dependency Resolution
+
+NPM automatically handles transitive dependencies. If your components require specific versions of React, Framer Motion, or other libraries, npm resolves these dependencies automatically, preventing version conflicts.
+
+### TypeScript Support
+
+Published packages can include pre-built type definitions, providing immediate TypeScript support without additional configuration:
+
+```json
+{
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  }
+}
+```
+
+## Limitations of NPM Packages
+
+While npm packages excel in distribution, they come with trade-offs that registries specifically address.
+
+### Source Code Ownership
+
+The most significant limitation is the lack of source code access. Users cannot:
+
+- Modify component behavior directly
+- Fix bugs without waiting for updates
+- Customize implementation details
+- Remove unused code
+
+This creates a dependency relationship where users must rely on the package maintainer for all changes.
+
+### Customization Constraints
+
+Tweaking components requires working within the exposed API. While you can provide props for customization:
+
+```tsx
+<Button variant="primary" size="large" className="custom-styles" />
+```
+
+Users cannot fundamentally alter how the component works without forking the entire package.
+
+### Bundle Size
+
+NPM packages include all components, even if users only need a subset. While tree-shaking helps, it's not always perfect, potentially adding unnecessary weight to applications.
+
+## CSS and Tailwind Configuration
+
+One critical consideration when publishing Tailwind-based components via npm is ensuring styles work correctly in the consuming application.
+
+By default, Tailwind only generates styles for classes it finds in your project files. It doesn't look inside `node_modules`, which means your component styles won't be included.
+
+To fix this, users need to add a `@source` directive to their Tailwind configuration, telling it to scan your package for class names:
+
+```css title="globals.css"
+@import "tailwindcss";
+
+/* Tell Tailwind to look for classes in your package */
+@source "../node_modules/@acme/ui-components";
+```
+
+Always document this requirement prominently in your package README.
+
+## Publishing Your Component Library
+
+To publish your components to npm, you need a properly configured `package.json` which might look like this:
+
+```json title="package.json"
+{
+  "name": "@acme/ui-components",
+  "version": "1.0.0",
+  "description": "A collection of accessible React components",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./styles.css": "./dist/styles.css"
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsup",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0"
+  },
+  "dependencies": {
+    "clsx": "^2.0.0",
+    "tailwind-merge": "^2.0.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  }
+}
+```
+
+NPM packages remain a vital part of the component ecosystem. While registries offer compelling benefits for source code ownership and customization, npm packages provide stability, version management, and ease of use that many teams require.
+
+The key is understanding your users' needs and choosing the distribution method that best serves them. Sometimes, that means offering both options and letting developers choose what works best for their project.