devstack 0.1.0

package/vendor/skills/skills/building-components/references/data-attributes.mdx

@@ -0,0 +1,409 @@
+---
+title: Data Attributes
+description: Using data attributes for declarative styling and component identification.
+type: reference
+summary: Using data-state for declarative visual state styling and data-slot for stable component identification in Tailwind-based systems.
+prerequisites:
+  - /composition
+  - /styling
+related:
+  - /design-tokens
+  - /accessibility
+---
+
+Data attributes provide a powerful way to expose component state and structure to consumers, enabling flexible styling without prop explosion. Modern component libraries use two primary patterns: `data-state` for visual states and `data-slot` for component identification.
+
+## Styling state with data-state
+
+One of the most common anti-patterns in component styling is exposing separate className props for different states.
+
+In less modern components, you'll often see APIs like this:
+
+```tsx
+<Dialog
+  openClassName="bg-black"
+  closedClassName="bg-white"
+  classes={{
+    open: "opacity-100",
+    closed: "opacity-0",
+  }}
+/>
+```
+
+This approach has several problems:
+
+- It couples the component's internal state to its styling API
+- It creates an explosion of props as components grow more complex
+- It makes the component harder to use and maintain
+- It prevents styling based on state combinations
+
+### The solution: data-state attributes
+
+Instead, use `data-*` attributes to expose component state declaratively. This allows consumers to style components based on state using standard CSS selectors:
+
+```tsx title="component.tsx"
+const Dialog = ({ className, ...props }: DialogProps) => {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <div
+      data-state={isOpen ? "open" : "closed"}
+      className={cn("transition-all", className)}
+      {...props}
+    />
+  );
+};
+```
+
+Now consumers can style the component based on state from the outside:
+
+```tsx title="app.tsx"
+<Dialog className="data-[state=open]:opacity-100 data-[state=closed]:opacity-0" />
+```
+
+### Benefits of this approach
+
+1. **Single className prop** - No need for multiple state-specific className props
+2. **Composable** - Combine multiple data attributes for complex states
+3. **Standard CSS** - Works with any CSS-in-JS solution or plain CSS
+4. **Type-safe** - TypeScript can infer data attribute values
+5. **Inspectable** - States are visible in DevTools as HTML attributes
+
+### Common state patterns
+
+Use data attributes for all kinds of component state:
+
+```tsx
+// Open/closed state
+<Accordion data-state={isOpen ? 'open' : 'closed'} />
+
+// Selected state
+<Tab data-state={isSelected ? 'active' : 'inactive'} />
+
+// Disabled state (in addition to disabled attribute)
+<Button data-disabled={isDisabled} disabled={isDisabled} />
+
+// Loading state
+<Button data-loading={isLoading} />
+
+// Orientation
+<Slider data-orientation="horizontal" />
+
+// Side/position
+<Tooltip data-side="top" />
+```
+
+### Styling with Tailwind
+
+Tailwind supports arbitrary variants, making data attribute styling elegant:
+
+```tsx
+<Dialog
+  className={cn(
+    // Base styles
+    "rounded-lg border p-4",
+    // State-based styles
+    "data-[state=open]:animate-in data-[state=open]:fade-in",
+    "data-[state=closed]:animate-out data-[state=closed]:fade-out",
+    // Multiple attributes
+    "data-[state=open][data-side=top]:slide-in-from-top-2"
+  )}
+/>
+```
+
+For commonly-used states, you can extend Tailwind's configuration:
+
+```js title="tailwind.config.js"
+module.exports = {
+  theme: {
+    extend: {
+      data: {
+        open: 'state="open"',
+        closed: 'state="closed"',
+        active: 'state="active"',
+      },
+    },
+  },
+};
+```
+
+Now you can use shorthand:
+
+```tsx
+<Dialog className="data-open:opacity-100 data-closed:opacity-0" />
+```
+
+### Integration with Radix UI
+
+This pattern is used extensively by [Radix UI](https://www.radix-ui.com/), which automatically applies data attributes to its primitives:
+
+```tsx
+import * as Dialog from "@radix-ui/react-dialog";
+
+<Dialog.Root>
+  <Dialog.Trigger />
+  <Dialog.Portal>
+    {/* Radix automatically adds data-state="open" | "closed" */}
+    <Dialog.Overlay className="data-[state=open]:animate-in data-[state=closed]:animate-out" />
+    <Dialog.Content className="data-[state=open]:fade-in data-[state=closed]:fade-out" />
+  </Dialog.Portal>
+</Dialog.Root>;
+```
+
+Other data attributes Radix provides include:
+
+- `data-state` - open/closed, active/inactive, on/off
+- `data-side` - top/right/bottom/left (for positioned elements)
+- `data-align` - start/center/end (for positioned elements)
+- `data-orientation` - horizontal/vertical
+- `data-disabled` - present when disabled
+- `data-placeholder` - present when showing placeholder
+
+## Component identification with data-slot
+
+While `data-state` tracks visual states, `data-slot` identifies component types within a composition. This pattern, popularized by [shadcn/ui](https://ui.shadcn.com/), allows parent components to target and style specific child components without relying on fragile class names or element selectors.
+
+### The problem with child targeting
+
+Traditional approaches to styling child components have significant limitations:
+
+```tsx
+// Relies on element types - breaks if implementation changes
+<form className="[&_input]:rounded-lg [&_button]:mt-4" />
+
+// Relies on class names - breaks if classes change
+<form className="[&_.text-input]:rounded-lg" />
+
+// Requires passing classes through props - verbose
+<form>
+  <input className={inputClasses} />
+  <button className={buttonClasses} />
+</form>
+```
+
+### The solution: data-slot attributes
+
+Use `data-slot` to give components stable identifiers that can be targeted by parents:
+
+```tsx title="field-set.tsx"
+function FieldSet({ className, ...props }: React.ComponentProps<"fieldset">) {
+  return (
+    <fieldset
+      data-slot="field-set"
+      className={cn(
+        "flex flex-col gap-6",
+        // Target specific child slots
+        "has-[>[data-slot=checkbox-group]]:gap-3",
+        "has-[>[data-slot=radio-group]]:gap-3",
+        className
+      )}
+      {...props}
+    />
+  );
+}
+```
+
+```tsx title="checkbox-group.tsx"
+function CheckboxGroup({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div data-slot="checkbox-group" className={cn("flex flex-col gap-2", className)} {...props} />
+  );
+}
+```
+
+### Benefits of data-slot
+
+1. **Stable identifiers** - Won't break when implementation details change
+2. **Semantic targeting** - Target based on component purpose, not structure
+3. **Encapsulation** - Internal classes remain private
+4. **Composable** - Works with arbitrary nesting and composition
+5. **Type-safe** - Can be validated and documented
+
+### Using `has-[]` for parent-aware styling
+
+Tailwind's `has-[]` selector combined with `data-slot` creates powerful parent-aware styling:
+
+```tsx title="form.tsx"
+function Form({ className, ...props }: React.ComponentProps<"form">) {
+  return (
+    <form
+      data-slot="form"
+      className={cn(
+        "space-y-4",
+        // Adjust spacing when specific slots are present
+        "has-[>[data-slot=form-section]]:space-y-6",
+        "has-[>[data-slot=inline-fields]]:space-y-2",
+        // Style based on slot states
+        "has-[[data-slot=submit-button][data-loading=true]]:opacity-50",
+        className
+      )}
+      {...props}
+    />
+  );
+}
+```
+
+### Using `[&_]` for descendant targeting
+
+For deeper nesting, use the `[&_selector]` pattern to target any descendant:
+
+```tsx title="card.tsx"
+function Card({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card"
+      className={cn(
+        "rounded-lg border p-4",
+        // Target any descendant with data-slot
+        "[&_[data-slot=card-header]]:mb-4",
+        "[&_[data-slot=card-title]]:text-lg [&_[data-slot=card-title]]:font-semibold",
+        "[&_[data-slot=card-description]]:text-sm [&_[data-slot=card-description]]:text-muted-foreground",
+        "[&_[data-slot=card-footer]]:mt-4 [&_[data-slot=card-footer]]:border-t [&_[data-slot=card-footer]]:pt-4",
+        className
+      )}
+      {...props}
+    />
+  );
+}
+```
+
+### Global CSS with data-slot
+
+Data slots work beautifully with global CSS for theme-wide consistency:
+
+```css title="globals.css"
+/* Style all buttons within forms */
+[data-slot="form"] [data-slot="button"] {
+  @apply w-full sm:w-auto;
+}
+
+/* Style submit buttons specifically */
+[data-slot="form"] [data-slot="submit-button"] {
+  @apply bg-primary text-primary-foreground;
+}
+
+/* Adjust inputs within inline layouts */
+[data-slot="inline-fields"] [data-slot="input"] {
+  @apply flex-1;
+}
+
+/* Style based on state combinations */
+[data-slot="dialog"][data-state="open"] [data-slot="dialog-content"] {
+  @apply animate-in fade-in;
+}
+```
+
+### Naming conventions
+
+Follow these conventions for consistent `data-slot` naming:
+
+1. **Use kebab-case** - `data-slot="form-field"` not `data-slot="formField"`
+2. **Be specific** - `data-slot="submit-button"` not `data-slot="button"`
+3. **Match component purpose** - Name reflects what it does, not how it looks
+4. **Avoid implementation details** - `data-slot="user-avatar"` not `data-slot="rounded-image"`
+
+```tsx
+// Good examples
+data-slot="search-input"
+data-slot="navigation-menu"
+data-slot="error-message"
+data-slot="submit-button"
+data-slot="card-header"
+
+// Avoid
+data-slot="input"           // Too generic
+data-slot="blueButton"      // Includes styling
+data-slot="div-wrapper"     // Implementation detail
+data-slot="mainContent"     // Use camelCase
+```
+
+## When to use data attributes vs props
+
+Understanding when to use each pattern is key to a clean API:
+
+### `data-state` use cases
+
+- **Visual states** - open/closed, active/inactive, loading, etc.
+- **Layout states** - orientation, side, alignment
+- **Interaction states** - hover, focus, disabled (when you need to style children)
+
+### `data-slot` use cases
+
+- **Component identification** - Stable identifiers for targeting
+- **Composition patterns** - Parent-child relationships
+- **Global styling** - Theme-wide component styling
+- **Variant-independent targeting** - Target any variant of a component
+
+### `props` use cases
+
+- **Variants** - Different visual designs (primary, secondary, destructive)
+- **Sizes** - sm, md, lg
+- **Behavioral configuration** - controlled/uncontrolled, default values
+- **Event handlers** - onClick, onChange, etc.
+
+### Combined approach
+
+A well-designed component uses all three patterns appropriately:
+
+```tsx title="button.tsx"
+type ButtonProps = {
+  variant?: "primary" | "secondary" | "destructive";
+  size?: "sm" | "md" | "lg";
+  loading?: boolean;
+  disabled?: boolean;
+  onClick?: () => void;
+  className?: string;
+};
+
+const Button = ({
+  variant = "primary",
+  size = "md",
+  loading,
+  disabled,
+  className,
+  ...props
+}: ButtonProps) => {
+  return (
+    <button
+      // Slot for targeting
+      data-slot="button"
+      // State for conditional styling
+      data-loading={loading}
+      data-disabled={disabled}
+      className={cn(
+        // Variant styles via props
+        buttonVariants({ variant, size }),
+        // Additional state styling allowed via className
+        className
+      )}
+      disabled={disabled}
+      {...props}
+    />
+  );
+};
+```
+
+Now the button can be used and styled in multiple ways:
+
+```tsx
+// Basic usage with variants
+<Button variant="primary" size="lg">Submit</Button>
+
+// Parent targeting via data-slot
+<form className="[&_[data-slot=button]]:w-full">
+  <Button>Submit</Button>
+</form>
+
+// State-based styling via data-state
+<Button
+  loading={isLoading}
+  className="data-[loading=true]:opacity-50"
+>
+  Submit
+</Button>
+
+// Global CSS can target any button
+// [data-slot="button"][data-loading="true"] { ... }
+```
+
+Data attributes provide a robust foundation for styling modern component libraries. By using `data-state` for visual states and `data-slot` for component identification, you create a flexible, maintainable API that scales from simple components to complex design systems.

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

@@ -0,0 +1,256 @@
+---
+title: Definitions
+description: This page establishes precise terminology used throughout the specification. Terms are intentionally framework agnostic, but we will use React for examples.
+type: reference
+summary: Precise terminology for the specification covering primitives, components, patterns, blocks, pages, templates, and utilities.
+related:
+  - /principles
+  - /composition
+---
+
+## 1. Artifact Taxonomy
+
+### 1.1 Primitive
+
+A primitive (or, unstyled component) is the **lowest‑level building block** that provides behavior and accessibility without any styling.
+
+Primitives are completely headless (i.e. unstyled) and encapsulate semantics, focus management, keyboard interaction, layering/portals, ARIA wiring, measurement, and similar concerns. They provide the behavioral foundation but require styling to become finished UI.
+
+Examples:
+
+- [Radix UI Primitives](https://www.radix-ui.com/primitives) (Dialog, Popover, Tooltip, etc.)
+- [React Aria Components](https://react-spectrum.adobe.com/react-aria)
+- [Base UI](https://base-ui.com)
+- [Headless UI](https://headlessui.com/)
+
+Expectations:
+
+- Completely unstyled (headless).
+- Single responsibility; composable into styled components.
+- Ships with exhaustive a11y behavior for its role.
+- Versioning favors stability; breaking changes are rare and documented.
+
+<Callout>
+  The terms primitive and component are typically used interchangeably across the web, but they are
+  not the same.
+</Callout>
+
+### 1.2 Component
+
+A component is a styled, reusable UI unit that adds visual design to primitives or composes multiple elements to create complete, functional interface elements.
+
+Components are still relatively low-level but include styling, making them immediately usable in applications. They typically wrap unstyled primitives with default visual design while remaining customizable.
+
+Examples:
+
+- [shadcn/ui components](https://ui.shadcn.com/) (styled wrappers of Radix primitives)
+- [Material UI components](https://mui.com/components/)
+- [Ant Design components](https://ant.design/components/overview/)
+
+Expectations:
+
+- Clear props API; supports controlled and uncontrolled usage where applicable.
+- Includes default styling but remains override-friendly (classes, tokens, slots).
+- Fully keyboard accessible and screen-reader friendly (inherits from primitives).
+- Composable (children/slots, render props, or compound subcomponents).
+- May be built from primitives or implement behavior directly with styling.
+
+### 1.3 Pattern
+
+Patterns are a specific composition of primitives or components that are used to solve a specific UI/UX problem.
+
+Examples:
+
+- Form validation with inline errors
+- Confirming destructive actions
+- Typeahead search
+- Optimistic UI
+
+Expectations.
+
+- Describes behavior, a11y, keyboard map, and failure modes.
+- May include reference implementations in multiple frameworks.
+
+### 1.4 Block
+
+An opinionated, production-ready composition of components that solves a concrete interface use case (often product-specific) with content scaffolding. Blocks trade generality for speed of adoption.
+
+Examples:
+
+- Pricing table
+- Auth screens
+- Onboarding stepper
+- AI chat panel
+- Billing settings form
+
+Expectations.
+
+- Strong defaults, copy-paste friendly, easily branded/themed.
+- Minimal logic beyond layout and orchestration; domain logic is stubbed via handlers.
+- Accepts data via props; never hides data behind fetches without a documented adapter.
+
+<AuthorNote
+  name="Rob Austin"
+  role="Founder of shadcnblocks.com"
+  githubUsername="JugglerX"
+  link="https://www.shadcnblocks.com/"
+>
+  Blocks are typically not reusable like a component. You don't import them, but they typically
+  import components and primitives. This makes them good candidates for a [Registry](/registry)
+  distribution method.
+</AuthorNote>
+
+### 1.5 Page
+
+A complete, single-route view composed of multiple blocks arranged to serve a specific user-facing purpose. Pages combine blocks into a cohesive layout that represents one destination in an application.
+
+Examples:
+
+- Landing page (hero block + features block + pricing block + footer block)
+- Product detail page (image gallery block + product info block + reviews block)
+- Dashboard page (stats block + chart block + activity feed block)
+
+Expectations:
+
+- Combines multiple blocks into a unified layout for a single route.
+- Focuses on layout and block orchestration rather than component-level details.
+- May include page-specific logic for data coordination between blocks.
+- Self-contained for a single URL/route; not intended to be reused across routes.
+
+### 1.6 Template
+
+A multi-page collection or full-site scaffold that bundles pages, routing configuration, shared layouts, global providers, and project structure. Templates are complete starting points for entire applications or major application sections.
+
+Examples:
+
+- [TailwindCSS Templates](https://tailwindui.com/templates)
+- [shadcnblocks Templates](https://www.shadcnblocks.com/templates) (full application shells)
+- "SaaS starter" (auth pages + dashboard pages + settings pages + marketing pages)
+- "E-commerce template" (storefront + product pages + checkout flow + admin pages)
+
+Expectations:
+
+- Includes multiple pages with routing/navigation structure.
+- Provides global configuration (theme providers, auth context, layout shells).
+- Opinionated project structure with clear conventions.
+- Designed as a comprehensive starting point; fork and customize rather than import as dependency.
+- May include build configuration, deployment setup, and development tooling.
+
+### 1.7 Utility (Non-visual)
+
+A helper exported for developer ergonomics or composition; not rendered UI.
+
+Examples:
+
+- React hooks (useControllableState, useId)
+- Class utilities
+- Keybinding helpers
+- Focus scopes
+
+Expectations.
+
+- Side-effect free (except where explicitly documented).
+- Testable in isolation; supports tree-shaking.
+
+## 2. API and Composition Vocabulary
+
+### 2.1 Props API
+
+The public configuration surface of a component. Props are stable, typed, and documented with defaults and a11y ramifications.
+
+### 2.2 Children / Slots
+
+Placeholders for caller-provided structure or content.
+
+- Children (implicit slot). JSX between opening/closing tags.
+- Named slots. Props like icon, footer, or `<Component.Slot>` subcomponents.
+- Slot forwarding. Passing DOM attributes/className/refs through to the underlying element.
+
+### 2.3 Render Prop (Function-as-Child)
+
+A function child used to delegate rendering while the parent supplies state/data.
+
+```tsx
+<ParentComponent data={data}>{item => <ChildComponent key={item.id} {...item} />}</ParentComponent>
+```
+
+Use when the parent must own data/behavior but the consumer must fully control markup.
+
+### 2.4 Controlled vs. Uncontrolled
+
+**Controlled** and **uncontrolled** are terms used to describe the state of a component.
+
+**Controlled** components have their value driven by props, and typically emit an `onChange` event (source of truth is the parent). **Uncontrolled** components hold internal state; and may expose a `defaultValue` and imperative reset.
+
+Many inputs should support both. Learn more about [controlled and uncontrolled state](/state).
+
+### 2.5 Provider / Context
+
+A top-level component that supplies shared state/configuration to a subtree (e.g., theme, locale, active tab id). Providers are explicitly documented with required placement.
+
+### 2.6 Portal
+
+Rendering UI outside the DOM hierarchy to manage layering/stacking context (e.g., modals, popovers, toasts), while preserving a11y (focus trap, aria-modal, inert background).
+
+## 3. Styling and Theming Vocabulary
+
+### 3.1 Headless
+
+Implements behavior and accessibility without prescribing appearance. Requires the consumer to supply styling.
+
+### 3.2 Styled
+
+Ships with default visual design (CSS classes, inline styles, or tokens) but remains override-friendly (className merge, CSS vars, theming).
+
+### 3.3 Variants
+
+Discrete, documented style or behavior permutations exposed via props (e.g., `size="sm|md|lg"`, `tone="neutral|destructive"`). Variants are not separate components.
+
+### 3.4 Design Tokens
+
+Named, platform-agnostic values (e.g., `--color-bg`, `--radius-md`, `--space-2`) that parameterize visual design and support theming.
+
+## 4. Accessibility Vocabulary
+
+### 4.1 Role / State / Property
+
+WAI-ARIA attributes that communicate semantics (`role="menu"`), state (`aria-checked`), and relationships (`aria-controls`, `aria-labelledby`).
+
+### 4.2 Keyboard Map
+
+The documented set of keyboard interactions for a widget (e.g., `Tab`, `Arrow keys`, `Home/End`, `Escape`). Every interactive component declares and implements a keyboard map.
+
+### 4.3 Focus Management
+
+Rules for initial focus, roving focus, focus trapping, and focus return on teardown.
+
+## 5. Distribution Vocabulary
+
+### 5.1 Package (Registry Distribution)
+
+The component/library is published to a package registry (e.g., `npm`) and imported via a bundler. Favors versioned updates and dependency management.
+
+### 5.2 Copy-and-Paste (Source Distribution)
+
+Source code is integrated directly into the consumer's repository (often via a CLI). Favors ownership, customization, and zero extraneous runtime.
+
+### 5.3 Registry (Catalog)
+
+A curated index of artifacts (primitives, components, blocks, templates) with metadata, previews, and install/copy instructions. A registry is not necessarily a package manager.
+
+## 6. Classification Heuristics
+
+Use this decision flow to name and place an artifact:
+
+1. Does it encapsulate a single behavior or a11y concern, with no styling? → **Primitive**
+2. Is it a styled, reusable UI element that adds visual design to primitives or composes multiple elements? → **Component**
+3. Does it solve a concrete product use case with opinionated composition and copy? → **Block**
+4. Does it scaffold a page/flow with routing/providers and replaceable regions? → **Template**
+5. Is it documentation of a recurring solution, independent of implementation? → **Pattern**
+6. Is it non-visual logic for ergonomics/composition? → **Utility**
+
+## 7. Non-Goals and Clarifications
+
+- Web Components vs. "Components." In this spec, "component" refers to a reusable UI unit (examples in React). It does not imply the HTML Custom Elements standard unless explicitly stated. Equivalent principles apply across frameworks.
+- Widgets. The term “widget” is avoided due to ambiguity; use component (general) or pattern (documentation-only solution).
+- Themes vs. Styles. A theme is a parameterization of styles (via tokens). Styles are the concrete presentation. Components should support themes; blocks/templates may ship opinionated styles plus theming hooks.