@reinvented/design 1.0.0 → 1.2.0

package/skills/blocks/navigation.md

@@ -0,0 +1,136 @@
+# Navigation & Shells Blocks
+
+This document covers composite UI blocks designed for Application Shells, Sidebars, Top Navbars, and Context Switchers.
+
+## When to use Blocks vs Primitives
+
+Use these blocks anytime you are constructing the foundational shell of a dashboard, portal, or desktop web app. DO NOT build sidebars manually using arbitrary Flex/Grid math. These blocks automatically handle fixed widths (`w-64`), scrolling (`<ScrollArea>`), and bottom-aligned footers.
+
+## 1. AppSidebar & NavItem
+
+The `AppSidebar` standardizes the left-hand navigation column common in standard SaaS products.
+
+### Anatomy
+```tsx
+// React Component
+import { AppSidebar, NavItem } from '@reinvented/design'
+import { ContextSwitcher } from '@reinvented/design'
+import { LayoutDashboard, Users, Settings } from 'lucide-react'
+import { Badge } from '@reinvented/design'
+
+
+export default function Component() {
+  return (
+    <>
+  <AppSidebar>
+    <template #header>
+      <ContextSwitcher 
+        :contexts="[{ id: '1', name: 'Acme Corp' }]" 
+        activeId="1" 
+      />
+        </>
+  )
+}
+    
+    <NavItem title="Dashboard" :icon="LayoutDashboard" isActive />
+    <NavItem title="Team Members" :icon="Users">
+      <template #badge>
+        <Badge variant="secondary" className="ml-auto">12</Badge>
+          </>
+  )
+}
+    </NavItem>
+    
+    <template #footer>
+      <NavItem title="Settings" :icon="Settings" />
+        </>
+  )
+}
+  </AppSidebar>
+    </>
+  )
+}
+```
+
+### Usage Rules
+- `AppSidebar` establishes a strict `h-screen w-64` boundary.
+- Places the default `<slot>` content into a perfectly calculated `<ScrollArea>` so an overflowing number of links won't push the layout down.
+- Provides named `#header` and `#footer` slots.
+- `NavItem` renders a flexible anchor tag (`<a>` if `href` is present, `<button>` otherwise). It conditionally applies `primary` tints if `isActive` is true.
+
+## 2. TopNavbar
+
+The `TopNavbar` establishes a horizontal header spanning the top of the interface.
+
+### Anatomy
+```tsx
+// React Component
+import { TopNavbar } from '@reinvented/design'
+import { Input } from '@reinvented/design'
+import { Avatar, AvatarFallback } from '@reinvented/design'
+
+
+export default function Component() {
+  return (
+    <>
+  <TopNavbar @menu-click="sidebarOpen = true">
+    <template #brand>
+      <div className="font-black text-xl tracking-tight">AcmeApp</div>
+        </>
+  )
+}
+    
+    <template #center>
+      <Input placeholder="Global search..." className="w-full" />
+        </>
+  )
+}
+    
+    <template #actions>
+      <Avatar className="h-8 w-8">
+        <AvatarFallback>JD</AvatarFallback>
+      </Avatar>
+        </>
+  )
+}
+  </TopNavbar>
+    </>
+  )
+}
+```
+
+### Usage Rules
+- Standardizes a sticky, frosted-glass header (`bg-background/95 backdrop-blur`).
+- Auto-collapses the `#center` slot entirely on mobile to prioritize `brand` and `actions`.
+- Features an embedded mobile hamburger `<Menu>` icon button that is `md:hidden`, emitting `@menu-click` so the developer can wire up a mobile Sidebar Sheet easily.
+
+## 3. ContextSwitcher
+
+The `ContextSwitcher` is a highly specialized dropdown used for jumping between Projects, Teams, or Organizations.
+
+### Anatomy
+```tsx
+// React Component
+import { ContextSwitcher } from '@reinvented/design'
+
+
+export default function Component() {
+  return (
+    <>
+  <ContextSwitcher 
+    :contexts="[
+      { id: 'acme', name: 'Acme Design Corp' },
+      { id: 'personal', name: 'Personal Workspace' }
+    ]" 
+    activeId="personal" 
+    @select="(id) => switchWorkspace(id)" 
+  />
+    </>
+  )
+}
+```
+
+### Usage Rules
+- Automates the complex layout of pairing small `<Avatar>` thumbnails with a truncated organization name and a trailing `<ChevronsUpDown>` caret.
+- Natively controls Shadcn's `<DropdownMenu>` sequence, rendering out standard menu items for each available context.
+- Drops a permanent "Create Workspace..." action at the bottom of the list.

package/skills/blocks/onboarding.md

@@ -0,0 +1,75 @@
+# Onboarding & Walkthrough Blocks
+
+This document covers composite UI blocks designed for Welcome Modals, Multi-step setup Wizards, and Feature Tooltips.
+
+## When to use Blocks vs Primitives
+
+Use these blocks anytime a user is encountering an app or a complex feature workflow for the first time. DO NOT build step trackers manually using raw `<p>` and `<hr>` elements; calculating Flex overlaps and dynamic progress lines requires these structured blocks.
+
+## 1. OnboardingWelcome
+
+The `OnboardingWelcome` is a heavily themed `<Card>` designed uniquely to appear as a pop-up or a standalone hero page just after user registration.
+
+### Anatomy
+```tsx
+// React Component
+import { OnboardingWelcome } from '@reinvented/design'
+
+
+export default function Component() {
+  return (
+    <>
+  <OnboardingWelcome 
+    title="Welcome to Reinvented"
+    description="You've successfully joined the platform. Let's get your account set up perfectly so you can hit the ground running."
+    image="/illustrations/welcome-hero.jpg"
+    :features="['Connect your design system', 'Invite your core team', 'Launch your first mockup']"
+    primaryAction="Get Started"
+    secondaryAction="Skip for now"
+    @primary="startSetup"
+    @secondary="skipSetup"
+  />
+    </>
+  )
+}
+```
+
+### Usage Rules
+- `image` expects an absolute or relative path to a cover photo/illustration. If omitted, the block gracefully falls back to an abstract branded gradient header.
+- The `features` prop renders an automatically aligned list using `<CheckCircle2>` Lucide icons.
+- Exposes two explicit events: `@primary` and `@secondary`. Use them to trigger routing or API calls.
+
+## 2. StepWizard
+
+The `StepWizard` block creates a horizontal sequence tracker.
+
+### Anatomy
+```tsx
+// React Component
+import { StepWizard } from '@reinvented/design'
+import { ref } from 'react'
+
+const currentStep = ref(2)
+const mySteps = [
+  { title: 'Create Profile', description: 'Your basic details' },
+  { title: 'Workspace', description: 'Setup your team' },
+  { title: 'Billing', description: 'Choose a plan' },
+]
+
+
+export default function Component() {
+  return (
+    <>
+  <div className="max-w-3xl w-full mx-auto">
+    <StepWizard :steps="mySteps" :currentStep="currentStep" />
+  </div>
+    </>
+  )
+}
+```
+
+### Usage Rules
+- `steps` takes an array of objects containing `title` and an optional `description`.
+- `currentStep` is 1-indexed (e.g., passing `1` means the *first* step is active).
+- **Automated Aesthetics:** The block automatically fills a solid `primary` progress bar connecting the completed steps. Completed circles swap to `<Check>` icons; the active step gets a thick Focus ring; future steps remain grayed out.
+- It hides standard text on mobile, ensuring the timeline bubbles do not squish or overflow out of bounds on small screens.

package/skills/blocks/profiles.md

@@ -0,0 +1,131 @@
+# User Profile Blocks
+
+This document covers composite UI blocks designed for User Profiles, Stat Summaries, and Connection Lists (followers/following).
+
+## When to use Blocks vs Primitives
+
+Use these blocks whenever the app requires user profile viewing or management interfaces. DO NOT build Profile Header banners manually by absolutely positioning avatars over background images. This `ProfileHeader` handles z-indexing, negative margin overlays, and mobile-responsive flex-wrapping automatically.
+
+## 1. ProfileHeader
+
+The `ProfileHeader` block is the massive hero section at the top of a user's page.
+
+### Anatomy
+```tsx
+// React Component
+import { ProfileHeader } from '@reinvented/design'
+import { Button } from '@reinvented/design'
+import { UserPlus, MessageCircle } from 'lucide-react'
+
+
+export default function Component() {
+  return (
+    <>
+  <ProfileHeader 
+    name="Sarah Drasner"
+    handle="@sarah_edo"
+    bio="Engineering Manager, Speaker, Author of SVG Animations. Vue Core team member."
+    avatar="/avatars/sarah.jpg"
+    banner="/banners/tech-pattern.jpg"
+    verified
+  >
+    <template #actions>
+      <Button variant="outline" size="sm">
+        <MessageCircle className="mr-2 h-4 w-4" />
+        Message
+      </Button>
+      <Button size="sm">
+        <UserPlus className="mr-2 h-4 w-4" />
+        Follow
+      </Button>
+        </>
+  )
+}
+  </ProfileHeader>
+    </>
+  )
+}
+```
+
+### Usage Rules
+- `banner` prop automatically handles the `object-cover` height. If omitted, it gracefully falls back to a branded gradient placeholder.
+- The Avatar is forced to `h-32 w-32` and automatically pulls itself up over the banner via negative margin `-mt-20`.
+- Use the `#actions` slot to inject standard buttons aligned beautifully to the far right on desktop, or stacked beneath on mobile.
+
+## 2. ProfileStats
+
+The `ProfileStats` block is a horizontal readout of macro-numbers often placed right beneath the ProfileHeader bio.
+
+### Anatomy
+```tsx
+// React Component
+import { ProfileStats } from '@reinvented/design'
+
+const myStats = [
+  { label: 'Followers', value: '12.4K' },
+  { label: 'Following', value: 891 },
+  { label: 'Repositories', value: 42 }
+]
+
+
+export default function Component() {
+  return (
+    <>
+  <ProfileStats :stats="myStats" />
+    </>
+  )
+}
+```
+
+### Usage Rules
+- Takes a simple array of `stats` mapping `{ label, value }`.
+- Automatically handles typography scaling (massive numbers, muted labels).
+- Wraps reliably on small breakpoints without breaking grid constraints.
+
+## 3. ConnectionList
+
+The `ConnectionList` set builds the "Followers", "Following", or "Team Members" tabular views.
+
+### Anatomy
+```tsx
+// React Component
+import { ConnectionList, ConnectionItem } from '@reinvented/design'
+import { Button } from '@reinvented/design'
+
+
+export default function Component() {
+  return (
+    <>
+  <ConnectionList className="max-w-2xl mt-8">
+    <ConnectionItem 
+      name="Evan You"
+      description="Creator of Vue and Vite"
+      avatar="/avatars/evan.jpg"
+    >
+      <template #action>
+        <Button variant="secondary" size="sm">Following</Button>
+          </>
+  )
+}
+    </ConnectionItem>
+    
+    <ConnectionItem 
+      name="Janakan"
+      description="Design Systems Engineer"
+    >
+      <template #action>
+        <Button variant="outline" size="sm">Follow</Button>
+          </>
+  )
+}
+    </ConnectionItem>
+  </ConnectionList>
+    </>
+  )
+}
+```
+
+### Usage Rules
+- `<ConnectionItem>` acts as a wide `<Card>` exposing a `#action` slot on the far right.
+- The `avatar` maps to a standard Shadcn `<Avatar>` handling missing src fallbacks with initials identically to other blocks.
+- The `ConnectionList` is merely a flex-column wrapper enforcing standard `gap-4` uniform spacing.

package/skills/blocks/scheduling.md

@@ -0,0 +1,117 @@
+# Scheduling & Calendaring Blocks
+
+This document covers composite UI blocks designed for Event representations, Booking workflows, and Time-series tracking.
+
+## When to use Blocks vs Primitives
+
+Use these blocks anytime the app requires plotting events against time. DO NOT build timeline nodes manually using absolute `div` positioning. The `TimelineRow` handles the exact Z-indexing and intersecting SVG drawing lines natively.
+
+## 1. EventCard
+
+The `EventCard` standardizes the display of agenda items, meetings, or scheduled tasks.
+
+### Anatomy
+```tsx
+// React Component
+import { EventCard } from '@reinvented/design'
+
+
+export default function Component() {
+  return (
+    <>
+  <EventCard 
+    title="Design System Sync"
+    date="October 24, 2026"
+    time="10:00 AM - 11:30 AM"
+    isVirtual
+    :attendees="12"
+    tag="Engineering"
+    tagVariant="outline"
+  />
+    </>
+  )
+}
+```
+
+### Usage Rules
+- Composes a left-border-accented Card (`border-l-4`).
+- Uses standard Lucide calendar/clock taxonomy to plot the time data.
+- Automatically handles the logic for rendering the `MapPin` (if `location` is provided) OR the `<Video>` icon (if `isVirtual` is set to true).
+- If `attendees` > 0, drops down a footer containing an overlapped avatar skeleton cluster mimicking traditional SaaS invite stacks.
+
+## 2. TimelineRow
+
+The `TimelineRow` creates a vertically flowing history or agenda block.
+
+### Anatomy
+```tsx
+// React Component
+import { TimelineRow } from '@reinvented/design'
+
+
+export default function Component() {
+  return (
+    <>
+  <div className="max-w-md">
+    <TimelineRow 
+      time="09:00 AM" 
+      title="Kickoff Presentation" 
+      status="past" 
+    />
+    <TimelineRow 
+      time="10:30 AM" 
+      title="Interactive Workshop" 
+      description="Breakout into 4 groups to tackle the component library mapping."
+      status="current"
+      tag="Live" 
+    />
+    <TimelineRow 
+      time="01:00 PM" 
+      title="Catered Networking Lunch" 
+      status="future" 
+      isLast 
+    />
+  </div>
+    </>
+  )
+}
+```
+
+### Usage Rules
+- Designed to be stacked. The component is just a row.
+- **`status` engine:**
+  - `'past'`: Bubble fills solid `primary`; text is solid `foreground`.
+  - `'current'`: Bubble gets an `animate-pulse` halo ring; text is solid `foreground`.
+  - `'future'`: Bubble turns into a `muted` inner ring; text drops back to `muted-foreground`.
+- **CRITICAL:** You must pass `isLast` to the final `<TimelineRow>` in your array so it stops rendering the downward connective line.
+
+## 3. BookingSlot
+
+The `BookingSlot` provides a standardized, accessible button specific to Calendly-style time pickers.
+
+### Anatomy
+```tsx
+// React Component
+import { BookingSlot } from '@reinvented/design'
+import { ref } from 'react'
+
+const slot = ref<string | null>(null)
+
+
+export default function Component() {
+  return (
+    <>
+  <div className="grid grid-cols-2 gap-3 max-w-sm">
+    <BookingSlot time="9:00 AM" available @select="slot = '9:00 AM'" :selected="slot === '9:00 AM'" />
+    <BookingSlot time="9:30 AM" :available="false" />
+    <BookingSlot time="10:00 AM" available @select="slot = '10:00 AM'" :selected="slot === '10:00 AM'" />
+  </div>
+    </>
+  )
+}
+```
+
+### Usage Rules
+- The component is functionally a massive `<button>` with deeply tied transition aesthetics.
+- Defaults to transparent boundaries on normal state. Once `selected` is True, it pops into filled `<primary>` color and drops down a small `<Check>` icon via CSS animation in the right corner.
+- Passing `available="false"` natively applies CSS `opacity-60`, drops the background to `muted`, and applies `cursor-not-allowed`.

package/skills/blocks/settings.md

@@ -0,0 +1,102 @@
+# Settings & Config Blocks
+
+This document covers composite UI blocks designed for Account Settings, Organization Preferences, Integrations, and Billing dashboards.
+
+## When to use Blocks vs Primitives
+
+Use these blocks anytime the user is managing backend configurations or account state. DO NOT build settings layouts manually using arbitrary grid splits. The `SettingsSection` enforces the standard "Label Left, Controls Right" pattern.
+
+## 1. SettingsSection
+
+The `SettingsSection` is the core structural wrapper for any form or preference block on a settings page.
+
+### Anatomy
+```tsx
+// React Component
+import { Input } from '@reinvented/design'
+import { Label } from '@reinvented/design'
+import { Button } from '@reinvented/design'
+import { SettingsSection } from '@reinvented/design'
+
+
+export default function Component() {
+  return (
+    <>
+  <SettingsSection 
+    title="Display Name" 
+    description="This will be displayed on your public profile and in team channels."
+  >
+    <div className="flex flex-col gap-4 max-w-sm">
+      <Input placeholder="Enter your display name" />
+      <Button className="w-fit">Save Changes</Button>
+    </div>
+  </SettingsSection>
+    </>
+  )
+}
+```
+
+### Usage Rules
+- Automatically parses into a 3-column Grid (`md:grid-cols-3`). The title and description lock to the left column (`col-span-1`), while the `<slot>` claims the remaining right-hand space (`col-span-2`).
+- Stacks cleanly into a single column automatically on mobile breakpoints.
+- Interleaves cleanly with other `<SettingsSection>` blocks, automatically injecting a dividing border between them (`border-b`).
+
+## 2. IntegrationCard
+
+The `IntegrationCard` standardizes 3rd-party connection toggles (e.g., Slack, Stripe).
+
+### Anatomy
+```tsx
+// React Component
+import { IntegrationCard } from '@reinvented/design'
+
+
+export default function Component() {
+  return (
+    <>
+  <IntegrationCard 
+    name="Slack"
+    description="Send notifications and incident alerts perfectly formatted to your team's channel."
+    icon="/icons/slack.svg"
+    status="connected"
+    isConfigurable
+  />
+    </>
+  )
+}
+```
+
+### Usage Rules
+- Exposes a `status` prop (`'connected' | 'disconnected' | 'error'`). Passing `'connected'` natively toggles the top-right `<Switch>` component to true. Passing `'error'` mounts a red destructive badge.
+- The `icon` injects an image src into the top-left square bounded box.
+- Setting `isConfigurable` drops a grey footer containing a "Configure integration" button, mimicking robust standard SaaS settings.
+
+## 3. BillingUsage
+
+The `BillingUsage` block renders a progress bar and usage stats against plan limits.
+
+### Anatomy
+```tsx
+// React Component
+import { BillingUsage } from '@reinvented/design'
+
+
+export default function Component() {
+  return (
+    <>
+  <BillingUsage 
+    title="API Requests"
+    description="Total API calls made this billing cycle."
+    :used="8500"
+    :limit="10000"
+    unit="requests"
+  />
+    </>
+  )
+}
+```
+
+### Usage Rules
+- Takes `used` and `limit` as raw numbers to automatically compute math logic (percentages, remaining budget).
+- Automatically mounts the Shadcn `<Progress>` bar.
+- *Defensive UI:* The progress bar natively shifts its color mapping to `rose-500` (red) the moment usage exceeds 85%, indicating impending limit breaks to the user visually.