@reinvented/design 0.4.0 → 1.1.0

package/skills/apps/project-management.md

@@ -0,0 +1,95 @@
+# App Type: Project Management
+
+Task boards, timelines, issue trackers, sprint views, and team collaboration setups.
+
+## Layout
+Use `layouts/sidebar.md`. Each project appears in the sidebar as a collapsible group. Main content often stretches the full width bounds depending on the view type (e.g. Kanban boards require horizontal scrolling).
+
+## Key Screens
+1. **Kanban Board** — Horizontal scrolling columns containing draggable cards.
+2. **List/Backlog View** — Dense data table showing hierarchy and issue properties.
+3. **Issue Detail Modal/Page** — Split view with main description on the left, metadata (assignees, labels, dates) on the right.
+
+## Component Composition Example
+
+```tsx
+<!-- Project Header & Board Layout -->
+<div className="h-full flex flex-col h-screen overflow-hidden">
+  <!-- Project Topbar -->
+  <div className="flex flex-col sm:flex-row sm:items-center justify-between p-6 border-b shrink-0">
+    <div className="flex items-center gap-4">
+      <div className="w-10 h-10 rounded-md bg-primary/10 flex items-center justify-center">
+        <FolderKanban className="w-5 h-5 text-primary" />
+      </div>
+      <div>
+        <h1 className="text-xl font-semibold">Frontend Redesign</h1>
+        <p className="text-sm text-muted-foreground">Q3 Engineering Sprint</p>
+      </div>
+    </div>
+    
+    <div className="flex items-center gap-3">
+      <!-- Team Avatars Array -->
+      <div className="flex -space-x-2 mr-4">
+        <Avatar className="border-2 border-background w-8 h-8" />
+        <Avatar className="border-2 border-background w-8 h-8" />
+        <Avatar className="border-2 border-background w-8 h-8" />
+      </div>
+      <div className="flex items-center rounded-md bg-muted p-1">
+        <Button variant="secondary" size="sm" className="h-7 text-xs shadow-sm">Board</Button>
+        <Button variant="ghost" size="sm" className="h-7 text-xs">List</Button>
+      </div>
+      <Button size="sm"><Plus className="w-4 h-4 mr-1" /> Add Task</Button>
+    </div>
+  </div>
+
+  <!-- Horizontal Scrolling Board Area -->
+  <div className="flex-1 overflow-x-auto p-6 bg-muted/20">
+    <div className="flex gap-4 h-full pb-4">
+      
+      <!-- Kanban Column -->
+      <div v-for="column in columns" :key="column.id" className="w-80 shrink-0 flex flex-col max-h-full">
+        <div className="flex items-center justify-between mb-3 px-1">
+          <h3 className="text-sm font-medium flex items-center gap-2">
+            {{ column.title }}
+            <Badge variant="secondary" className="font-normal">{{ column.tasks.length }}</Badge>
+          </h3>
+          <Button variant="ghost" size="icon" className="h-6 w-6"><MoreHorizontal className="w-4 h-4" /></Button>
+        </div>
+        
+        <!-- Draggable Area Wrapper -->
+        <ScrollArea className="flex-1">
+          <div className="space-y-3 pr-3">
+            <Card v-for="task in column.tasks" :key="task.id" className="cursor-pointer hover:border-primary/50 transition-colors shadow-sm">
+              <CardContent className="p-4 space-y-3">
+                <div className="flex gap-2">
+                  <Badge variant="outline" className="text-[10px] uppercase font-medium">{{ task.projectKey }}</Badge>
+                  <Badge v-if="task.priority === 'High'" variant="destructive" className="text-[10px] uppercase font-medium">Urgent</Badge>
+                </div>
+                <p className="text-sm font-medium leading-tight">{{ task.title }}</p>
+                <div className="flex items-center justify-between pt-2">
+                  <div className="flex items-center gap-2 text-muted-foreground">
+                    <MessageSquare className="w-3 h-3" /> <span className="text-xs">{{ task.comments }}</span>
+                  </div>
+                  <Avatar className="w-6 h-6" />
+                </div>
+              </CardContent>
+            </Card>
+          </div>
+        </ScrollArea>
+      </div>
+      
+    </div>
+  </div>
+</div>
+```
+
+## Anti-Patterns (DO NOT DO)
+
+- ❌ **Do not use heavy, padded cards for tasks**: Task cards need to be compact (`p-3` or `p-4`). Do not use full `CardHeader` and `CardFooter` elements inside Kanban cards.
+- ❌ **Do not limit the horizontal scroll of the board**: Kanban boards must use `overflow-x-auto` on the parent container, and columns should be fixed width (`w-80` or `w-72`) with `shrink-0`.
+- ❌ **Do not ignore the metadata**: Issue trackers require priority colored badges (`variant="destructive"` for high, `variant="outline"` for low), status icons, and assignee avatars on every row or card.
+
+## Design Notes
+
+- **Task IDs**: Usually displayed in small muted text (e.g. `PROJ-123`) to identify tasks.
+- **Filters**: Highly important. Always place a filter bar above the content (Assignee, Label, Status, Search).

package/skills/apps/saas-dashboard.md

@@ -0,0 +1,104 @@
+# App Type: SaaS Dashboard
+
+Admin panels, web-app hubs, and B2B SaaS applications.
+
+## Layout
+Use `layouts/sidebar.md` with a full sidebar navigation. The layout must handle deeply nested settings and multi-tenant organization switchers.
+
+## Key Screens
+1. **Dashboard/Overview** — Stats row (4 KPI cards) + chart area + activity feed + recent table.
+2. **List Views** — Data tables with search, filters, pagination, and row actions.
+3. **Detail Views** — Entity detail with tabs (Overview, Activity, Settings).
+4. **Settings** — Grouped configurations with left-hand section nav (`layouts/settings-page.md`).
+
+## Nav Structure & Tenant Switcher
+B2B apps frequently switch contexts. The sidebar should include an organization selector at the very top:
+
+```tsx
+<!-- SaaS Sidebar Top Header -->
+<div className="flex items-center justify-between p-4 border-b">
+  <div className="flex flex-col">
+    <span className="text-sm font-semibold truncate">Acme Corp</span>
+    <span className="text-xs text-muted-foreground truncate">Free Plan</span>
+  </div>
+  <Button variant="ghost" size="icon" className="h-8 w-8">
+    <ChevronsUpDown className="w-4 h-4 text-muted-foreground" />
+  </Button>
+</div>
+```
+
+## Component Composition Example
+
+```tsx
+<!-- SaaS Workspace Dashboard -->
+<div className="space-y-8">
+  <!-- Context Header -->
+  <div className="flex items-center justify-between">
+    <div>
+      <h1 className="text-2xl font-bold">Workspace Overview</h1>
+      <p className="text-muted-foreground">Monitor your team's usage and activity.</p>
+    </div>
+    <div className="flex items-center gap-3">
+      <Button variant="outline">Invite Team</Button>
+      <Button>Create Project</Button>
+    </div>
+  </div>
+
+  <!-- Quick Stats -->
+  <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-4">
+    <!-- Typical KPI Card -->
+    <Card>
+      <CardHeader className="flex flex-row items-center justify-between pb-2">
+        <CardTitle className="text-sm font-medium">Active Seats</CardTitle>
+        <Users className="h-4 w-4 text-muted-foreground" />
+      </CardHeader>
+      <CardContent>
+        <div className="text-2xl font-bold">12 / 15</div>
+        <p className="text-xs text-muted-foreground mt-1 text-warning">80% of limit reached</p>
+      </CardContent>
+    </Card>
+    <!-- Repeat for other KPIs: API Requests, Storage Used, etc -->
+  </div>
+
+  <!-- Split View: Insights & Activity -->
+  <div className="grid grid-cols-1 lg:grid-cols-7 gap-6">
+    <Card className="lg:col-span-4">
+      <CardHeader>
+        <CardTitle>Usage Over Time</CardTitle>
+      </CardHeader>
+      <CardContent>
+        <ComponentPlaceholder name="LineChart" description="Line chart comparing API calls vs Storage limits over 30 days" height="300px" /> <!-- (Mockup Mode Only) -->
+      </CardContent>
+    </Card>
+
+    <Card className="lg:col-span-3">
+      <CardHeader>
+        <CardTitle>Recent Activity</CardTitle>
+      </CardHeader>
+      <CardContent className="space-y-6">
+        <div v-for="i in 4" :key="i" className="flex gap-4">
+          <Avatar className="w-8 h-8 rounded-full" />
+          <div className="space-y-1">
+            <p className="text-sm">
+              <span className="font-medium">Sarah Jenkins</span> deployed to production
+            </p>
+            <p className="text-xs text-muted-foreground">2 hours ago</p>
+          </div>
+        </div>
+      </CardContent>
+    </Card>
+  </div>
+</div>
+```
+
+## Anti-Patterns (DO NOT DO)
+
+- ❌ **Do not bury the 'Create' action**: Every primary SaaS list view needs a clear "Create [Entity]" or "New [Entity]" button in the top right.
+- ❌ **Do not design flat detail pages**: Detail pages should use `<Tabs>` to segment Overview, History/Logs, and Settings, otherwise they become noisy.
+- ❌ **Do not stretch forms across the screen**: SaaS configuration forms look terrible at 1200px wide. Constrain form layouts to `max-w-2xl` inside cards.
+
+## Design Notes
+
+- **Settings**: Use `layouts/settings-page.md` for organization, billing, and team settings.
+- **Empty States**: B2B apps often launch empty. Every list view MUST design the empty state showing the value proposition and a "Create" button.
+- **Plan Limits**: Usage progress bars (`<Progress>`) are very common in SaaS headers/sidebars to upsell users.

package/skills/apps/social-platform.md

@@ -0,0 +1,50 @@
+# App Type: Social Platform
+
+Feeds, profiles, interactions, and discovery interfaces.
+
+## Layout
+Use `layouts/topbar.md` for consumer social, or `layouts/sidebar.md` for community platforms.
+
+## Key Screens
+1. **Feed** — Vertical list of post cards with author, content, interactions
+2. **Profile** — User header + stats + tabbed content (see `patterns/user-profiles.md`)
+3. **Discover** — Card grid of suggested content/people
+
+## Post Card
+```tsx
+<Card>
+  <CardContent className="p-4 space-y-3">
+    <!-- Author -->
+    <div className="flex items-center gap-3">
+      <div className="w-10 h-10 rounded-full shrink-0 bg-muted" />
+      <div className="flex-1 min-w-0">
+        <p className="text-sm font-medium">{{ post.author }}</p>
+        <p className="text-xs text-muted-foreground">{{ post.time }}</p>
+      </div>
+      <Button variant="ghost" size="icon" className="h-8 w-8"><MoreHorizontal className="w-4 h-4" /></Button>
+    </div>
+    <!-- Content -->
+    <p className="text-sm">{{ post.content }}</p>
+    <!-- Image (optional) -->
+    <div v-if="post.hasImage" className="aspect-video rounded-lg bg-gradient-to-br from-secondary to-secondary/50" />
+    <!-- Interactions -->
+    <div className="flex items-center gap-4 pt-1">
+      <Button variant="ghost" size="sm" className="gap-1.5 text-muted-foreground">
+        <Heart className="w-4 h-4" /> {{ post.likes }}
+      </Button>
+      <Button variant="ghost" size="sm" className="gap-1.5 text-muted-foreground">
+        <MessageCircle className="w-4 h-4" /> {{ post.comments }}
+      </Button>
+      <Button variant="ghost" size="sm" className="gap-1.5 text-muted-foreground">
+        <Share2 className="w-4 h-4" /> Share
+      </Button>
+    </div>
+  </CardContent>
+</Card>
+```
+
+## Design Notes
+- **Feed layout**: `max-w-2xl mx-auto` for optimal reading width
+- **Post images**: `aspect-video` with gradient placeholders
+- **Interaction buttons**: `variant="ghost"` with `text-muted-foreground`
+- **5–8 feed items** for a realistic mockup

package/skills/blocks/auth.md

@@ -0,0 +1,106 @@
+# Identity & Auth Blocks
+
+This document covers composite UI blocks designed for Authentication flows such as Login, Signup, SSO, Password Reset, and Two-Factor Authentication (2FA).
+
+## When to use Blocks vs Primitives
+
+Use these blocks whenever the app requires authentication interfaces. DO NOT build login cards manually using raw `<Card>` or raw pin inputs. These blocks provide standardized spacing, SSO aesthetic boundaries, and interaction layouts out-of-the-box.
+
+## 1. AuthCard
+
+The `AuthCard` block is the fundamental wrapper container for authentication screens. 
+
+### Anatomy
+```tsx
+// React Component
+import { Input } from '@reinvented/design'
+import { Label } from '@reinvented/design'
+import { Button } from '@reinvented/design'
+import { AuthCard } from '@reinvented/design'
+
+
+export default function Component() {
+  return (
+    <>
+  <AuthCard 
+    title="Create an account"
+    description="Enter your email below to create your account"
+    footerText="Already have an account?"
+    footerLinkText="Sign in"
+    footerLinkHref="/login"
+  >
+    <div className="grid gap-4">
+      <div className="grid gap-2">
+        <Label for="email">Email</Label>
+        <Input id="email" type="email" placeholder="m@example.com" />
+      </div>
+      <div className="grid gap-2">
+        <Label for="password">Password</Label>
+        <Input id="password" type="password" />
+      </div>
+      <Button className="w-full">Create account</Button>
+    </div>
+  </AuthCard>
+    </>
+  )
+}
+```
+
+### Usage Rules
+- `<AuthCard>` binds Shadcn's `<Card>` into a perfectly sized semantic login wrapper out of the box (centers content, strict `max-w-md` constraints).
+- Use `footerText` and `footerLinkText` to automatically add standard bottom links (e.g. "Don't have an account? Sign up").
+
+## 2. SocialLoginGroup
+
+The `SocialLoginGroup` provides a standard block of SSO buttons along with the "Or continue with" HTML divider.
+
+### Anatomy
+```tsx
+// React Component
+import { SocialLoginGroup } from '@reinvented/design'
+
+
+export default function Component() {
+  return (
+    <>
+  <div className="grid gap-6">
+    <SocialLoginGroup :providers="['github', 'google']" layout="row" />
+    
+    <!-- Email/Password form goes here -->
+  </div>
+    </>
+  )
+}
+```
+
+### Usage Rules
+- `providers` defaults to `['github', 'google']`.
+- `layout` can be `'row'` (which places icons side-by-side using Grid) or `'column'` (which stacks them vertically).
+- Always place it above or below the primary email/password authentication block. The trailing divider is built-in.
+
+## 3. TwoFactorForm
+
+The `TwoFactorForm` block provides a unified 6-digit pin UI using the design system's `PinInput` API.
+
+### Anatomy
+```tsx
+// React Component
+import { TwoFactorForm } from '@reinvented/design'
+
+
+export default function Component() {
+  return (
+    <>
+  <TwoFactorForm 
+    email="user@reinvented.inc" 
+    @complete="(code) => handleVerification(code)" 
+  />
+    </>
+  )
+}
+```
+
+### Usage Rules
+- Emits a `@complete` payload string uniquely when exactly 6 digits have been entered by the user.
+- Disables the "Verify" button automatically until length constraints are met.
+- Accepts an optional `email` prop to display where the code was dispatched.

package/skills/blocks/communication.md

@@ -0,0 +1,98 @@
+# Communication & Chat Blocks
+
+This document covers composite UI blocks designed for messaging, activity feeds, and comment threads.
+
+## When to use Blocks vs Primitives
+
+Use these blocks whenever the app requires displaying messages or activity logs. DO NOT build these flows from scratch using raw `<Card>`, `<Avatar>`, or `<div>` elements. These blocks provide strict layout, spacing, and state alignments out-of-the-box.
+
+## 1. ChatBubble
+
+The `ChatBubble` block is a composite for rendering a single message in a chat UI. It supports sent/received states to control alignment and colors.
+
+### Anatomy
+```tsx
+// React Component
+import { 
+  ChatBubble, 
+  ChatBubbleAvatar, 
+  ChatBubbleMessage, 
+  ChatBubbleTimestamp 
+} from '@reinvented/design'
+
+
+export default function Component() {
+  return (
+    <>
+  <div className="flex flex-col gap-4 p-4">
+    <!-- Received Message (Aligned Left) -->
+    <ChatBubble variant="received">
+      <ChatBubbleAvatar src="/avatars/user1.png" fallback="JD" />
+      <ChatBubbleMessage variant="received">
+        Hey, did you review the final PR?
+        <ChatBubbleTimestamp timestamp="10:42 AM" />
+      </ChatBubbleMessage>
+    </ChatBubble>
+
+    <!-- Sent Message (Aligned Right) -->
+    <ChatBubble variant="sent">
+      <ChatBubbleAvatar fallback="ME" />
+      <ChatBubbleMessage variant="sent">
+        Looking at it right now!
+        <ChatBubbleTimestamp timestamp="10:44 AM" />
+      </ChatBubbleMessage>
+    </ChatBubble>
+  </div>
+    </>
+  )
+}
+```
+
+### Props
+- `variant` (`"sent" | "received"` default: `"received"`): Controls layout direction. `"sent"` aligns items right and swaps the bubble color to the primary token. Both `<ChatBubble>` and `<ChatBubbleMessage>` accept this prop and it MUST match.
+
+## 2. ActivityItem
+
+The `ActivityItem` block builds timeline-based activity feeds with relative connecting lines between items.
+
+### Anatomy
+```tsx
+// React Component
+import { 
+  ActivityItem, 
+  ActivityItemAvatar, 
+  ActivityItemContent 
+} from '@reinvented/design'
+
+
+export default function Component() {
+  return (
+    <>
+  <div className="flex flex-col">
+    <ActivityItem>
+      <ActivityItemAvatar fallback="JD" />
+      <ActivityItemContent>
+        <p className="text-sm font-medium">Jane Doe commented on Task #104</p>
+        <p className="text-sm text-muted-foreground mt-1">
+          "Can we get this merged before EOD?"
+        </p>
+        <span className="text-xs text-muted-foreground mt-2">2 hours ago</span>
+      </ActivityItemContent>
+    </ActivityItem>
+
+    <ActivityItem>
+      <ActivityItemAvatar fallback="SS" />
+      <ActivityItemContent>
+        <p className="text-sm font-medium">System merged PR #42</p>
+        <span className="text-xs text-muted-foreground mt-1">Yesterday</span>
+      </ActivityItemContent>
+    </ActivityItem>
+  </div>
+    </>
+  )
+}
+```
+
+### Usage Rules
+- Wrap a list of `ActivityItem`s in a flex column container.
+- The `ActivityItem` automatically handles the rendering of the chronological connecting line between avatars. The last item naturally hides the line.

package/skills/blocks/content.md

@@ -0,0 +1,107 @@
+# Knowledge & Content Blocks
+
+This document covers composite UI blocks designed for Articles, Blog Headers, Wikis, and Rich Text Viewers.
+
+## When to use Blocks vs Primitives
+
+Use these blocks whenever the app renders long-form editorial content. DO NOT build Article headers by stacking avatars and headings manually. These blocks strictly adhere to optimal reading widths (`max-w-3xl`) and semantic typography scales.
+
+## 1. ArticleHeader
+
+The `ArticleHeader` block establishes the core typography hierarchy for the start of any editorial view.
+
+### Anatomy
+```tsx
+// React Component
+import { ArticleHeader } from '@reinvented/design'
+
+
+export default function Component() {
+  return (
+    <>
+  <ArticleHeader 
+    title="The Future of Serverless Computing"
+    description="Exploring the next wave of edge functions and how they eliminate cold starts entirely."
+    authorName="Sarah Drasner"
+    authorAvatar="/avatars/sarah.jpg"
+    date="Nov 24, 2024"
+    readTime="5 min read"
+    :tags="['Engineering', 'Architecture', 'Edge']"
+  />
+    </>
+  )
+}
+```
+
+### Usage Rules
+- `title` is rendering as a massive semibold `h1`.
+- `description` acts as the optional sub-leadin paragraph.
+- The block automatically scales the Avatar and groups the author meta-data horizontally.
+
+## 2. RichTextContent
+
+The `RichTextContent` block is a layout wrapper designed specifically to ingest unsanitized HTML, markdown, or rich-text editor output. It applies the `@tailwindcss/typography` "prose" layer and binds it firmly to Shadcn CSS variables automatically.
+
+### Anatomy
+```tsx
+// React Component
+import { RichTextContent } from '@reinvented/design'
+
+
+export default function Component() {
+  return (
+    <>
+  <RichTextContent>
+    <h2>Introduction</h2>
+    <p>This is standard HTML that will be beautifully formatted because it's caught inside the RichTextContent block.</p>
+    <blockquote>The future is already here — it's just not very evenly distributed.</blockquote>
+    <p>Code chunks look great too: <code>npm run build</code></p>
+  </RichTextContent>
+    </>
+  )
+}
+```
+
+### Usage Rules
+- The component does not take props other than `class`.
+- Wrap it entirely around either a `v-html` dump or semantic HTML.
+- It automatically forces `max-w-3xl` to keep reading line lengths optimal.
+
+## 3. AuthorCard
+
+The `AuthorCard` block is an end-of-article credit box.
+
+### Anatomy
+```tsx
+// React Component
+import { AuthorCard } from '@reinvented/design'
+import { Button } from '@reinvented/design'
+import { Twitter } from 'lucide-react'
+
+
+export default function Component() {
+  return (
+    <>
+  <AuthorCard 
+    name="Sarah Drasner"
+    role="VP of Developer Experience at Netlify"
+    bio="Sarah is an award-winning Speaker, Engineering Manager, and author of SVG Animations. She's a Vue Core team member and an organizer of the Vue.js meetup."
+    avatar="/avatars/sarah.jpg"
+  >
+    <template #action>
+      <Button variant="outline">
+        <Twitter className="mr-2 h-4 w-4" />
+        Follow
+      </Button>
+        </>
+  )
+}
+  </AuthorCard>
+    </>
+  )
+}
+```
+
+### Usage Rules
+- Usually appended immediately beneath the `RichTextContent`.
+- Leverages the `<slot name="action">` to allow custom buttons (e.g. "Follow on Twitter", "View Profile", or standard Outline button).

package/skills/blocks/data-management.md

@@ -0,0 +1,109 @@
+# Data Management Blocks
+
+This document covers composite UI blocks designed for complex structural data interfaces like Kanban boards and nested Tree Views.
+
+## When to use Blocks vs Primitives
+
+Use these blocks whenever building advanced data-manipulation views often found in project management, CMS admin layouts, or IDE-like software. DO NOT build Kanban lanes or collapsible trees manually using raw DOM iterations, as maintaining state and strict overflow interactions is highly repetitive.
+
+## 1. Kanban Board
+
+The `KanbanBoard` block set provides a horizontal scrolling pipeline divided into columns and stackable cards.
+
+### Anatomy
+```tsx
+// React Component
+import { 
+  KanbanBoard, 
+  KanbanColumn, 
+  KanbanCard 
+} from '@reinvented/design'
+
+
+export default function Component() {
+  return (
+    <>
+  <KanbanBoard className="h-[calc(100vh-140px)]">
+    <!-- To Do -->
+    <KanbanColumn title="To Do" :count="3">
+      <KanbanCard 
+        title="Design system color tokens" 
+        id="TSK-412" 
+        priority="high"
+        :labels="['Design', 'System']"
+        :comments="4"
+        :attachments="2"
+        :assignee="{ name: 'Alice Adams', avatar: '/avatars/alice.png' }"
+      />
+      <KanbanCard 
+        title="Audit dependency tree" 
+        id="TSK-413" 
+        priority="low"
+        :labels="['Engineering']"
+      />
+    </KanbanColumn>
+
+    <!-- In Progress -->
+    <KanbanColumn title="In Progress" :count="1">
+      <KanbanCard 
+        title="Implement Kanban UI block" 
+        id="TSK-408" 
+        priority="high"
+        :comments="12"
+        :assignee="{ name: 'Janakan', avatar: '/avatars/janakan.png' }"
+      />
+    </KanbanColumn>
+  </KanbanBoard>
+    </>
+  )
+}
+```
+
+### Usage Rules
+- `<KanbanBoard>` sets up the core horizontal timeline. Usually needs a firm `height` constraint (like `h-[calc(100vh-200px)]`) so the columns can scroll vertically independent of the page.
+- `<KanbanColumn>` builds a solid column constraint of `300px` width. The `title` and `count` drive the top header.
+- `<KanbanCard>` handles hover, grab, and metadata visualizations. Use `priority`, `labels`, and numerical summaries (`comments`, `attachments`) to inject rich data pills automatically.
+
+## 2. TreeView
+
+The `TreeView` block constructs collapsible file or folder hierarchies natively using Shadcn `Collapsible`.
+
+### Anatomy
+```tsx
+// React Component
+import { 
+  TreeView, 
+  TreeItem 
+} from '@reinvented/design'
+
+
+export default function Component() {
+  return (
+    <>
+  <TreeView className="max-w-xs">
+    <TreeItem title="src" isFolder defaultExpanded :level="0">
+      <TreeItem title="assets" isFolder :level="1" />
+      <TreeItem title="components" isFolder defaultExpanded :level="1">
+        <TreeItem title="ui" isFolder :level="2" />
+        <TreeItem title="blocks" isFolder defaultExpanded :level="2">
+          <TreeItem title="data-management" isFolder defaultExpanded :level="3">
+            <TreeItem title="TreeView.tsx" :level="4" />
+            <TreeItem title="TreeItem.tsx" :level="4" />
+          </TreeItem>
+        </TreeItem>
+      </TreeItem>
+      <TreeItem title="App.tsx" :level="1" />
+      <TreeItem title="main.ts" :level="1" />
+    </TreeItem>
+    <TreeItem title="package.json" :level="0" />
+    <TreeItem title="README.md" :level="0" />
+  </TreeView>
+    </>
+  )
+}
+```
+
+### Usage Rules
+- Nest `<TreeItem>` inside a parent `<TreeItem isFolder>`.
+- Pass `:level="X"` explicitly to each item, increasing the depth iteratively. This physically sets the `padding-left` natively so deeply nested lines do not misalign. `0` is the root indentation.
+- Uses `defaultExpanded` boolean modifier on folders to start opened.