Technical Reference

Component Library

Reusable components for building installation pages and features.

Component architecture

Installation components are organized by type: Astro components for static content and React islands for interactivity.

Type	Location	Usage
Astro Components	`src/components/*.astro`	Static layouts, content blocks
React Islands	`src/components/*.tsx`	Interactive features requiring client-side JS
UI Components	`src/components/ui/*.tsx`	shadcn/ui design system components
Doc Components	`src/components/docs/*.astro`	Documentation-specific components

Astro components

Server-rendered components that generate static HTML at build time.

`BaseLayout.astro`

Main layout wrapper providing consistent structure, SEO metadata, and View Transitions.

Props

Prop	Type	Required	Description
`title`	string	Yes	Page title (appears in browser tab)
`description`	string	No	Meta description for SEO

Usage

 ---
import BaseLayout from '../layouts/BaseLayout.astro';
---

<BaseLayout title="Page Title" description="Page description">
  <h1>Page Content</h1>
</BaseLayout> 

`HandDrawn.astro`

Emphasis component with hand-drawn visual effects (underline, circle, box, arrow).

Props

Prop	Type	Default	Description
`variant`	string	"underline"	`underline` \| `circle` \| `box` \| `arrow`
`color`	string	"craft-accent"	Tailwind color class

Usage

 ---
import HandDrawn from '../components/HandDrawn.astro';
---

<p>
  This is <HandDrawn variant="underline">emphasized text</HandDrawn>.
</p> 

`BottomNav.astro`

Fixed bottom navigation for quadrant switching (Experience, Process, Craft, Philosophy).

Props

No props. Navigation items are hardcoded.

Usage

 ---
import BottomNav from '../components/BottomNav.astro';
---

<BaseLayout title="Page">
  <!-- Page content -->
  <BottomNav />
</BaseLayout> 

React island components

Client-rendered components for interactive functionality. Require client: directive.

`ChatInterface.tsx`

Interactive chat interface with message history and streaming responses.

Props

Prop	Type	Required	Description
`client`	string	Yes	Client directive: `load` \| `visible` \| `idle`

Usage

 ---
import ChatInterface from '../components/ChatInterface';
---

<ChatInterface client:load /> 

`ForkingExplainer.tsx`

Interactive visualization of git forking workflow using Alice and Bob bakery story.

Props

Prop	Type	Required	Description
`client`	string	Yes	Client directive (typically `only="react"`)

Usage

 ---
import ForkingExplainer from '../components/ForkingExplainer';
---

<ForkingExplainer client:only="react" /> 

shadcn/ui components

Design system components from shadcn/ui, located in src/components/ui/.

Component	File	Purpose
Button	`ui/button.tsx`	Primary, secondary, ghost button variants
Card	`ui/card.tsx`	Container with header, content, footer
Input	`ui/input.tsx`	Text input field
Textarea	`ui/textarea.tsx`	Multi-line text input
Badge	`ui/badge.tsx`	Status indicator or label
ScrollArea	`ui/scroll-area.tsx`	Custom scrollbar styling

Adding new shadcn/ui components

 # List available components
npx shadcn@latest add

# Add specific component
npx shadcn@latest add dialog

# Component appears in src/components/ui/dialog.tsx 

Documentation components

Specialized components for documentation pages, located in src/components/docs/.

Component	Purpose
`DocLayout.astro`	Three-column layout with sidebar and TOC
`DocSidebar.astro`	Hierarchical section navigation
`TableOfContents.astro`	Auto-generated page TOC with scroll tracking
`Breadcrumbs.astro`	Navigation path (Home → Quadrant → Page)
`CodeBlock.astro`	Syntax-highlighted code with Shiki
`StepIndicator.astro`	Tutorial progress tracker
`NavigationCard.astro`	Reusable link card with quadrant styling
`CrossRef.astro`	Cross-quadrant reference links

Component creation guidelines

Follow these patterns when creating new components.

Choose component type

• Astro component - Static content, no client JavaScript needed
• React island - Interactive features, event handlers, state management
• shadcn/ui - Standard UI patterns (buttons, forms, dialogs)

File naming conventions

• Astro components: ComponentName.astro
• React components: ComponentName.tsx
• Use PascalCase for component names
• Group related components in subdirectories

Props and types

• Define TypeScript interfaces for all props
• Use JSDoc comments for prop descriptions
• Provide sensible defaults for optional props
• Export types for reuse in other components

Styling

• Use Tailwind utility classes
• Reference CSS variables from globals.css
• Use cn() utility for conditional classes
• Avoid inline styles unless absolutely necessary

Import aliases

Use @/ prefix for clean imports from the src directory.

 // Instead of relative paths:
import Button from '../../../components/ui/button';

// Use alias:
import Button from '@/components/ui/button';

// Configured in tsconfig.json:
{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
} 