@nimblegiant/stilts 0.2.0-alpha.3 → 0.2.0-alpha.5

package/README.md

@@ -1,16 +1,21 @@
-# 🦒 Stilts Design System
+# Stilts Design System
 
-Nimble Giant's whimsical yet disciplined design system - a collection of reusable React components and design tokens built for flexibility and delight.
+[![npm version](https://img.shields.io/npm/v/@nimblegiant/stilts)](https://www.npmjs.com/package/@nimblegiant/stilts)
+[![license](https://img.shields.io/npm/l/@nimblegiant/stilts)](./LICENSE)
+
+Nimble Giant's whimsical yet disciplined design system — a collection of reusable React components and design tokens built for flexibility and delight.
 
 ## Overview
 
-Stilts is a framework-agnostic design system extracted from Nimble Giant's website. It provides:
+Stilts is a framework-agnostic design system built with React, TypeScript, and Tailwind CSS. It provides:
 
-- 10 production-ready React components
-- Comprehensive design tokens (colors, spacing, typography, animations)
-- Full TypeScript support
+- 32 production-ready React components across 4 categories
+- Comprehensive design tokens (colors, spacing, animations)
+- Full TypeScript support with exported types
 - Tree-shakable ESM and CJS builds
-- Tailwind CSS integration
+- Tailwind CSS 4 integration
+
+**See it in action:** [nimble-giant.com](https://nimble-giant.com)
 
 ## Installation
 
@@ -22,6 +27,8 @@ bun add @nimblegiant/stilts
 yarn add @nimblegiant/stilts
 ```
 
+**Peer dependencies:** React 18+ and React DOM 18+. Tailwind CSS 4.1+ is optional.
+
 ## Quick Start
 
 ### 1. Import Styles
@@ -44,7 +51,7 @@ function App() {
         subtitle="A whimsical yet disciplined design system"
         align="center"
       />
-      <TeamGrid team={teamMembers} />
+      <TeamGrid members={teamMembers} />
     </>
   );
 }
@@ -53,19 +60,20 @@ function App() {
 ### 3. Access Design Tokens
 
 ```typescript
-import { colors, spacing, animations } from '@nimblegiant/stilts/tokens';
+import { colors, spacing, durations, easings } from '@nimblegiant/stilts/tokens';
 
-const primaryColor = colors.primary.DEFAULT; // '#02aec2'
-const space4 = spacing[4]; // '1rem'
-const springEasing = animations.easings.spring; // 'cubic-bezier(0.175, 0.885, 0.32, 1.275)'
+colors.primary.DEFAULT   // '#02aec2'
+spacing[4]               // '1rem'
+easings.spring           // 'cubic-bezier(0.175, 0.885, 0.32, 1.275)'
 ```
 
 ## Components
 
-### Layout Components
+### Layout (2)
 
 #### MainNav
-Responsive navigation with theme toggle and mobile menu.
+
+Responsive navigation with theme toggle, mobile menu, and active link indicator.
 
 ```tsx
 import { MainNav } from '@nimblegiant/stilts';
@@ -73,30 +81,56 @@ import { MainNav } from '@nimblegiant/stilts';
 <MainNav currentPath="/about" isPortfolioPage={false} />
 ```
 
-### UI Components
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `currentPath` | `string` | required | Current page path for active link highlighting |
+| `isPortfolioPage` | `boolean` | `false` | Light text mode for dark backgrounds |
+
+#### TopBanner
+
+Dismissible announcement banner with gradient background. Persists dismissal state in session storage.
+
+```tsx
+import { TopBanner } from '@nimblegiant/stilts';
+
+<TopBanner />
+```
+
+No props — self-contained component.
+
+### UI (1)
 
 #### Toast
-Global toast notification system.
+
+Global toast notification system with four types and auto-dismissal.
 
 ```tsx
 import { Toast } from '@nimblegiant/stilts';
 
-// Component usage
+// Mount the container
 <Toast />
 
-// Programmatic usage (global)
+// Trigger from anywhere
 window.showToast({
   type: 'success',
-  title: 'Success!',
+  title: 'Saved',
   message: 'Your changes have been saved.',
   duration: 3000
 });
 ```
 
-### Pattern Components
+| Prop (via `showToast`) | Type | Default | Description |
+|------|------|---------|-------------|
+| `type` | `"success" \| "error" \| "info" \| "warning"` | `"info"` | Toast variant |
+| `title` | `string` | — | Bold heading |
+| `message` | `string` | — | Body text |
+| `duration` | `number` | `5000` | Auto-dismiss ms (0 = never) |
+
+### Patterns (14)
 
 #### PageHero
-Simple hero section with optional background image.
+
+Hero section with animated entrance, optional background image, and eyebrow text.
 
 ```tsx
 import { PageHero } from '@nimblegiant/stilts';
@@ -111,28 +145,54 @@ import { PageHero } from '@nimblegiant/stilts';
 />
 ```
 
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `title` | `string` | required | Main heading |
+| `subtitle` | `string` | — | Secondary heading |
+| `description` | `string` | — | Body text |
+| `eyebrow` | `string` | — | Label above title with gradient |
+| `backgroundImage` | `string` | — | Background image URL (25% opacity) |
+| `align` | `"left" \| "center" \| "right"` | `"left"` | Layout alignment |
+
 #### VideoHero
-Full-screen hero with video background and service cards.
+
+Full-screen hero with video background and optional service cards grid.
 
 ```tsx
 import { VideoHero } from '@nimblegiant/stilts';
 
 <VideoHero
   title="Transform Your Business"
-  tagline="Digital Solutions"
+  eyebrow="Digital Solutions"
   description="We build products that scale"
-  cards={serviceCards}
+  videoSrc="/hero.mp4"
+  serviceCards={[
+    { href: "/services", icon: svgString, title: "Development", description: "..." }
+  ]}
 />
 ```
 
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `videoSrc` | `string` | — | MP4 video source |
+| `fallbackImage` | `string` | — | Fallback if video fails |
+| `title` | `string` | — | Main heading |
+| `eyebrow` | `string` | — | Label above title |
+| `subtitle` | `string` | — | Secondary heading |
+| `description` | `string` | — | Body text |
+| `serviceCards` | `ServiceCard[]` | `[]` | Cards with href, icon, title, description |
+| `showScrollIndicator` | `boolean` | `true` | Animated scroll arrow |
+| `scrollTarget` | `string` | `"#work"` | Scroll target anchor |
+
 #### TeamGrid
-Display team members in a responsive grid.
+
+Responsive team member grid with social links and hover effects.
 
 ```tsx
 import { TeamGrid } from '@nimblegiant/stilts';
 
 <TeamGrid
-  team={[
+  members={[
     {
       name: "Jane Doe",
       role: "Engineering",
@@ -142,11 +202,19 @@ import { TeamGrid } from '@nimblegiant/stilts';
       linkedin: "https://linkedin.com/in/jane"
     }
   ]}
+  cols={3}
 />
 ```
 
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `members` | `TeamMember[]` | required | Array of team members |
+| `cols` | `2 \| 3 \| 4` | `3` | Grid columns |
+| `title` | `string` | — | Section title |
+
 #### ServiceSection
-Service features section with grid layout.
+
+Feature grid section with title and description.
 
 ```tsx
 import { ServiceSection } from '@nimblegiant/stilts';
@@ -155,65 +223,594 @@ import { ServiceSection } from '@nimblegiant/stilts';
   id="services"
   title="Our Services"
   description="What we offer"
-  features={featuresList}
+  features={[
+    { title: "Development", description: "Full-stack web development" }
+  ]}
 />
 ```
 
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `id` | `string` | required | Section ID |
+| `title` | `string` | required | Section heading |
+| `description` | `string` | required | Section description |
+| `features` | `Feature[]` | required | Array with title and description |
+
 #### ProcessSteps
-Horizontal or vertical process timeline.
+
+Process timeline in horizontal or vertical layout.
 
 ```tsx
 import { ProcessSteps } from '@nimblegiant/stilts';
 
 <ProcessSteps
   steps={[
-    { title: "Step 1", description: "First step" },
-    { title: "Step 2", description: "Second step" }
+    { title: "Discovery", description: "Understanding the problem" },
+    { title: "Design", description: "Creating the solution" }
   ]}
-  orientation="horizontal"
+  variant="horizontal"
 />
 ```
 
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `steps` | `Step[]` | required | Steps with title, description, optional number |
+| `title` | `string` | — | Section title |
+| `variant` | `"horizontal" \| "vertical"` | `"horizontal"` | Layout direction |
+| `background` | `"default" \| "muted"` | `"muted"` | Background style |
+
 #### StatBar
-Statistics display bar.
+
+Statistics display with large numbers, optional prefix/suffix.
 
 ```tsx
 import { StatBar } from '@nimblegiant/stilts';
 
 <StatBar
   stats={[
-    { value: "100+", label: "Projects" },
-    { value: "50+", label: "Clients" }
+    { value: "100", suffix: "+", label: "Projects" },
+    { value: "50", suffix: "+", label: "Clients" }
   ]}
 />
 ```
 
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `stats` | `StatData[]` | required | Stats with value, label, optional prefix/suffix |
+| `title` | `string` | — | Section title |
+| `description` | `string \| string[]` | — | Description text(s) |
+| `centered` | `boolean` | `true` | Center alignment |
+| `background` | `"default" \| "muted"` | `"muted"` | Background style |
+
 #### IndustryGrid
-Industry showcase grid.
+
+Industry card grid layout.
 
 ```tsx
 import { IndustryGrid } from '@nimblegiant/stilts';
 
 <IndustryGrid
   industries={[
-    { name: "Healthcare", icon: "🏥" },
-    { name: "Finance", icon: "💰" }
+    { title: "Healthcare", description: "Digital health solutions" },
+    { title: "Finance", description: "Fintech products" }
   ]}
+  cols={3}
 />
 ```
 
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `industries` | `Industry[]` | required | Array with title and description |
+| `title` | `string` | — | Section title |
+| `cols` | `2 \| 3` | `3` | Grid columns |
+
 #### ContentPage
-MDX content page wrapper.
+
+Page wrapper for MDX/prose content with metadata.
 
 ```tsx
 import { ContentPage } from '@nimblegiant/stilts';
 
-<ContentPage>
-  <h1>Page Title</h1>
+<ContentPage title="Privacy Policy" subtitle="Legal" lastUpdated="Jan 15, 2024">
   <p>Content goes here...</p>
 </ContentPage>
 ```
 
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `title` | `string` | required | Page heading |
+| `subtitle` | `string` | — | Secondary heading |
+| `lastUpdated` | `string` | — | Update timestamp |
+| `children` | `ReactNode` | required | Page content |
+
+#### TerminalWindow
+
+Animated terminal with typewriter effect, triggered on viewport entry.
+
+```tsx
+import { TerminalWindow } from '@nimblegiant/stilts';
+
+<TerminalWindow
+  filename="getting-started"
+  lines={[
+    { text: "npm install @nimblegiant/stilts", type: "command" },
+    { text: "added 1 package", type: "success" },
+    { text: "Ready to build!", type: "highlight" }
+  ]}
+/>
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `lines` | `TerminalLine[]` | required | Lines with text, type, optional delay |
+| `filename` | `string` | `"terminal"` | Title bar text |
+| `typingSpeed` | `number` | `20` | Typing speed (ms per char) |
+| `initialDelay` | `number` | `800` | Delay before animation starts (ms) |
+| `title` | `string` | — | Heading above terminal |
+
+Line types: `"command"`, `"output"`, `"highlight"`, `"success"`, `"muted"`
+
+#### TerminalChrome
+
+Terminal window frame without animation — for wrapping custom content.
+
+```tsx
+import { TerminalChrome } from '@nimblegiant/stilts';
+
+<TerminalChrome filename="example.tsx">
+  <pre><code>const hello = "world";</code></pre>
+</TerminalChrome>
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `filename` | `string` | — | Title bar text |
+| `children` | `ReactNode` | required | Content inside the frame |
+| `footer` | `ReactNode` | — | Optional footer element |
+
+#### TerminalHero
+
+Two-column hero with profile image in terminal frame, typewriter animation, and CTA buttons.
+
+```tsx
+import { TerminalHero } from '@nimblegiant/stilts';
+
+<TerminalHero
+  greeting="Hello, World."
+  name="Jane Doe"
+  tagline="Engineer + Designer"
+  terminalText="Building great products..."
+  button1={{ text: "View Work", href: "/projects" }}
+  button2={{ text: "Contact", href: "/contact" }}
+  image={{ src: "/profile.jpg", alt: "Jane Doe" }}
+/>
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `greeting` | `string` | `"Hello, World."` | Status badge text |
+| `name` | `string` | — | Large gradient heading |
+| `tagline` | `string` | — | Subheading |
+| `terminalText` | `string` | `""` | Typewriter animation text |
+| `button1` | `{ text, href }` | — | Primary CTA |
+| `button2` | `{ text, href }` | — | Secondary CTA |
+| `image` | `{ src, alt, height?, width? }` | — | Profile image |
+
+#### CTAButton
+
+Call-to-action button with three variants and framework-agnostic link support.
+
+```tsx
+import { CTAButton } from '@nimblegiant/stilts';
+
+<CTAButton href="/contact" variant="primary">
+  Get in Touch
+</CTAButton>
+
+// With a framework link component (e.g., Next.js)
+<CTAButton href="/about" LinkComponent={Link}>
+  Learn More
+</CTAButton>
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `href` | `string` | required | Link destination |
+| `children` | `ReactNode` | required | Button label |
+| `variant` | `"primary" \| "secondary" \| "outline"` | `"primary"` | Visual style |
+| `external` | `boolean` | `false` | Opens in new tab |
+| `icon` | `"arrow" \| "external" \| "none"` | `"arrow"` | Trailing icon |
+| `LinkComponent` | `ElementType` | `"a"` | Custom link element |
+
+#### ProductCard
+
+Product listing card with thumbnail, tags, and hover effects.
+
+```tsx
+import { ProductCard } from '@nimblegiant/stilts';
+
+<ProductCard
+  name="My Product"
+  tagline="A great product"
+  description="Description of the product..."
+  thumbnail="/products/thumb.jpg"
+  href="/products/my-product"
+  tags={["React", "TypeScript"]}
+/>
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `name` | `string` | required | Product name |
+| `tagline` | `string` | required | Short tagline |
+| `description` | `string` | required | Product description |
+| `thumbnail` | `string` | required | Image URL |
+| `href` | `string` | required | Link destination |
+| `tags` | `string[]` | required | Category tags |
+| `LinkComponent` | `ElementType` | `"a"` | Custom link element |
+
+#### CodeBlock
+
+Code display with syntax styling, optional line numbers, and copy-to-clipboard.
+
+```tsx
+import { CodeBlock } from '@nimblegiant/stilts';
+
+<CodeBlock
+  code={`import { MainNav } from '@nimblegiant/stilts';`}
+  language="typescript"
+  filename="App.tsx"
+  showLineNumbers
+/>
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `code` | `string` | required | Code content |
+| `language` | `string` | `"bash"` | Language label |
+| `filename` | `string` | — | Filename in header |
+| `showLineNumbers` | `boolean` | `false` | Show line numbers |
+
+#### FeatureShowcase
+
+Feature grid or list with icons, title, and description.
+
+```tsx
+import { FeatureShowcase } from '@nimblegiant/stilts';
+
+<FeatureShowcase
+  title="Why Stilts?"
+  subtitle="Built for real projects"
+  features={[
+    { icon: <IconComponent />, title: "TypeScript", description: "Full type safety" },
+    { icon: <IconComponent />, title: "Tailwind", description: "Utility-first styling" }
+  ]}
+  layout="grid"
+/>
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `features` | `Feature[]` | required | Features with icon (ReactNode), title, description |
+| `title` | `string` | — | Section title |
+| `subtitle` | `string` | — | Section subtitle |
+| `layout` | `"grid" \| "list"` | `"grid"` | Display layout |
+| `background` | `"default" \| "muted"` | `"default"` | Background style |
+
+### Sections (15)
+
+Section components are designed for building case study pages and rich content layouts. They accept structured data props and handle their own layout and styling.
+
+#### BeforeAfter
+
+Interactive image comparison slider with drag/touch support.
+
+```tsx
+import { BeforeAfter } from '@nimblegiant/stilts';
+
+<BeforeAfter
+  data={{
+    before_image: "/before.jpg",
+    after_image: "/after.jpg",
+    title: "Redesign",
+    content: "A complete visual overhaul...",
+    before_label: "Before",
+    after_label: "After"
+  }}
+/>
+```
+
+#### CaseStudyBreakdown
+
+Three-column breakdown with metrics, services used, and optional results.
+
+```tsx
+import { CaseStudyBreakdown } from '@nimblegiant/stilts';
+
+<CaseStudyBreakdown
+  data={{
+    title: "Project Results",
+    what_we_did: "<p>Built a new platform...</p>",
+    how_we_did_it: "<p>Using React and Node...</p>",
+    services_used: ["Development", "Design", "Strategy"],
+    metrics: [
+      { value: "40", suffix: "%", label: "Faster", trend: "up" }
+    ]
+  }}
+/>
+```
+
+#### ContactForm
+
+Full contact form with service selection, budget dropdown, and HubSpot integration.
+
+```tsx
+import { ContactForm } from '@nimblegiant/stilts';
+
+// With HubSpot
+<ContactForm portalId="12345" formId="abc-123" />
+
+// With custom handler
+<ContactForm
+  onSubmit={async (data) => { /* handle submission */ }}
+  onSuccess={(res) => { /* success callback */ }}
+  submitButtonText="Send Message"
+/>
+```
+
+Fields: name, email, company, services (multi-select), budget (dropdown), project description.
+
+#### CompactContactForm
+
+Minimal inline form with name and email fields.
+
+```tsx
+import { CompactContactForm } from '@nimblegiant/stilts';
+
+<CompactContactForm
+  onSubmit={async (data) => { /* { firstname, email } */ }}
+  submitButtonText="Subscribe"
+  namePlaceholder="Your Name"
+  emailPlaceholder="Your Email"
+/>
+```
+
+#### FullWidthImage
+
+Full-width image with optional overlay and caption.
+
+```tsx
+import { FullWidthImage } from '@nimblegiant/stilts';
+
+<FullWidthImage
+  data={{
+    image: "/hero-shot.jpg",
+    alt: "Product screenshot",
+    caption: "The new dashboard in action"
+  }}
+/>
+```
+
+#### ImageGrid
+
+Responsive image grid with three layout options.
+
+```tsx
+import { ImageGrid } from '@nimblegiant/stilts';
+
+<ImageGrid
+  data={{
+    title: "Screenshots",
+    grid_type: "2x2",
+    images: [
+      { src: "/img1.jpg", alt: "Screenshot 1", caption: "Home page" },
+      { src: "/img2.jpg", alt: "Screenshot 2", caption: "Dashboard" }
+    ]
+  }}
+/>
+```
+
+Grid types: `"50-50"`, `"2x2"`, `"3x3"`
+
+#### ImageGridModal
+
+Clickable image grid with lightbox modal, navigation arrows, and image counter.
+
+```tsx
+import { ImageGridModal } from '@nimblegiant/stilts';
+
+<ImageGridModal
+  data={{
+    title: "Gallery",
+    grid_type: "mixed",
+    images: [
+      { src: "/img1.jpg", alt: "Photo 1", layout: "landscape" },
+      { src: "/img2.jpg", alt: "Photo 2", layout: "portrait" }
+    ]
+  }}
+/>
+```
+
+Layouts: `"landscape"`, `"portrait"`, `"square"`, `"wide"`
+
+#### ProblemStatement
+
+Structured challenge/background/goals breakdown with optional stakeholders.
+
+```tsx
+import { ProblemStatement } from '@nimblegiant/stilts';
+
+<ProblemStatement
+  data={{
+    title: "The Challenge",
+    problem: "<p>Users were struggling with...</p>",
+    context: "<p>The existing system was built in...</p>",
+    goals: ["Improve load time by 50%", "Reduce support tickets", "Modernize the stack"],
+    stakeholders: [
+      { role: "Product Manager", description: "Owns the roadmap" }
+    ]
+  }}
+/>
+```
+
+#### ProcessTimeline
+
+Detailed process timeline with phases, deliverables, and duration.
+
+```tsx
+import { ProcessTimeline } from '@nimblegiant/stilts';
+
+<ProcessTimeline
+  data={{
+    title: "Our Process",
+    layout: "vertical",
+    style: "cards",
+    steps: [
+      {
+        phase: "Phase 1",
+        title: "Discovery",
+        description: "Research and planning...",
+        deliverables: ["User research report", "Technical audit"],
+        duration: "2 weeks"
+      }
+    ]
+  }}
+/>
+```
+
+Layouts: `"vertical"`, `"horizontal"`. Styles: `"default"`, `"minimal"`, `"cards"`.
+
+#### RelatedProjects
+
+Project cards with grid, list, or carousel layout.
+
+```tsx
+import { RelatedProjects } from '@nimblegiant/stilts';
+
+<RelatedProjects
+  data={{
+    title: "Related Work",
+    layout: "grid",
+    projects: ["project-slug-1", "project-slug-2"]
+  }}
+  allProjects={projectsMap}
+/>
+```
+
+Layouts: `"grid"`, `"list"`, `"carousel"`
+
+#### SolutionSummary
+
+Solution overview with approach steps, key features, tech tags, and optional quote.
+
+```tsx
+import { SolutionSummary } from '@nimblegiant/stilts';
+
+<SolutionSummary
+  data={{
+    title: "Our Solution",
+    overview: "<p>We built a modern platform...</p>",
+    technologies: ["React", "Node.js", "PostgreSQL"],
+    key_features: [
+      { title: "Real-time", description: "Live updates via WebSockets" }
+    ]
+  }}
+/>
+```
+
+#### TeamCredits
+
+Team credits section with photos, roles, and social links.
+
+```tsx
+import { TeamCredits } from '@nimblegiant/stilts';
+
+<TeamCredits
+  data={{
+    title: "The Team",
+    layout: "grid",
+    members: [
+      { name: "Jane", role: "Lead Engineer", photo: "/jane.jpg" }
+    ]
+  }}
+/>
+```
+
+Layouts: `"grid"`, `"list"`, `"carousel"`. Social links: LinkedIn, Twitter, GitHub, Dribbble, Behance.
+
+#### Testimonial
+
+Single featured quote or multi-testimonial grid with ratings.
+
+```tsx
+import { Testimonial } from '@nimblegiant/stilts';
+
+// Single quote
+<Testimonial
+  data={{
+    type: "testimonial",
+    title: "What They Say",
+    single_quote: {
+      text: "Stilts transformed our workflow.",
+      author: "Jane Doe",
+      title: "CTO",
+      company: "Acme Inc."
+    }
+  }}
+/>
+
+// Multi-testimonial grid
+<Testimonial
+  data={{
+    type: "testimonial",
+    title: "Reviews",
+    testimonials: [
+      { quote: "Amazing!", name: "John", rating: 5 }
+    ]
+  }}
+/>
+```
+
+#### TextBlock
+
+Rich text section with layout options, lists, quotes, and CTA.
+
+```tsx
+import { TextBlock } from '@nimblegiant/stilts';
+
+<TextBlock
+  data={{
+    type: "text_block",
+    layout: "centered",
+    title: "Our Mission",
+    content: "<p>Building tools that empower teams...</p>",
+    lists: [
+      { title: "Values", style: "checkmarks", items: ["Quality", "Speed", "Craft"] }
+    ],
+    cta: { text: "Learn More", url: "/about", style: "primary" }
+  }}
+/>
+```
+
+Layouts: `"standard"`, `"centered"`, `"wide"`. List styles: `"bullets"`, `"checkmarks"`, `"numbered"`.
+
+#### VideoSection
+
+Video player with optional device frame overlay and caption.
+
+```tsx
+import { VideoSection } from '@nimblegiant/stilts';
+
+<VideoSection
+  data={{
+    type: "video_hero",
+    video: "/demo.mp4",
+    title: "Product Demo",
+    content: "<p>See the platform in action.</p>"
+  }}
+/>
+```
+
 ## Design Tokens
 
 ### Colors
@@ -221,21 +818,42 @@ import { ContentPage } from '@nimblegiant/stilts';
 ```typescript
 import { colors } from '@nimblegiant/stilts/tokens';
 
-colors.primary.DEFAULT // '#02aec2'
-colors.primary[500]    // Shade variants
-colors.accent.violet   // Brand accents
-colors.semantic.success // Semantic colors
-colors.gray[500]       // Neutral scale
+// Primary
+colors.primary.DEFAULT    // '#02aec2' (teal)
+colors.primary[50]        // Lightest shade
+colors.primary[900]       // Darkest shade
+
+// Accents
+colors.accent.warm        // Warm accent palette
+colors.accent.violet      // Violet accent palette
+colors.accent.emerald     // Emerald accent palette
+colors.accent.rose        // Rose accent palette
+
+// Semantic
+colors.semantic.success   // Green
+colors.semantic.warning   // Amber
+colors.semantic.error     // Red
+colors.semantic.info      // Blue
+
+// Neutrals
+colors.gray[50]           // Near white
+colors.gray[950]          // Near black
 ```
 
 ### Spacing
 
+4px base unit system with 40+ predefined sizes.
+
 ```typescript
 import { spacing } from '@nimblegiant/stilts/tokens';
 
-spacing[4]  // '1rem' (16px)
-spacing[8]  // '2rem' (32px)
-spacing[16] // '4rem' (64px)
+spacing.px    // '1px'
+spacing[0]    // '0'
+spacing[1]    // '0.25rem' (4px)
+spacing[4]    // '1rem' (16px)
+spacing[8]    // '2rem' (32px)
+spacing[16]   // '4rem' (64px)
+spacing[64]   // '16rem' (256px)
 ```
 
 ### Animations
@@ -243,15 +861,31 @@ spacing[16] // '4rem' (64px)
 ```typescript
 import { durations, easings } from '@nimblegiant/stilts/tokens';
 
-durations.fast     // '100ms'
-durations.normal   // '200ms'
-easings.spring     // Bouncy easing
-easings.smooth     // Smooth easing
+// Durations
+durations.instant   // '0ms'
+durations.fast      // '100ms'
+durations.normal    // '200ms'
+durations.moderate  // '300ms'
+durations.slow      // '400ms'
+durations.slower    // '600ms'
+durations.slowest   // '800ms'
+durations.glacial   // '1000ms'
+
+// Easings
+easings.linear      // 'linear'
+easings.spring      // 'cubic-bezier(0.175, 0.885, 0.32, 1.275)'
+easings.bounce      // 'cubic-bezier(0.68, -0.55, 0.265, 1.55)'
+easings.smooth      // 'cubic-bezier(0.4, 0, 0.2, 1)'
+easings.snappy      // 'cubic-bezier(0.2, 0, 0, 1)'
 ```
 
-## Tailwind CSS Integration
+### TypeScript Types
 
-Stilts works seamlessly with Tailwind CSS. The design system uses CSS variables that can be integrated into your Tailwind configuration.
+```typescript
+import type { ColorToken, SpacingToken, DurationToken, EasingToken } from '@nimblegiant/stilts/tokens';
+```
+
+## Tailwind CSS Integration
 
 ### Option 1: Use Pre-compiled CSS
 
@@ -272,90 +906,83 @@ export default {
     extend: {
       colors: {
         primary: 'var(--color-primary)',
-        // ... map other CSS variables
       },
     },
   },
 };
 ```
 
-## TypeScript Support
-
-Stilts is built with TypeScript and includes full type definitions.
-
-```typescript
-import type { ColorToken, SpacingToken } from '@nimblegiant/stilts/tokens';
-
-const myColor: ColorToken = colors.primary;
-const mySpacing: SpacingToken = spacing;
-```
-
 ## Framework Compatibility
 
-Stilts components are pure React components with no framework-specific dependencies. They work with:
+Stilts components are React components with no framework-specific dependencies. They work with:
 
-- **React** ✅
-- **Next.js** ✅
-- **Astro** ✅ (with @astrojs/react)
-- **Gatsby** ✅
-- **Remix** ✅
+- **React** — Direct usage
+- **Next.js** — Works out of the box
+- **Astro** — Via `@astrojs/react`
+- **Remix** — Direct usage
+- **Gatsby** — Direct usage
 - Any other React-based framework
 
-## Browser Support
+Components that accept a `LinkComponent` prop (CTAButton, ProductCard) can integrate with framework-specific routers.
 
-Stilts supports all modern browsers:
+## Browser Support
 
-- Chrome (last 2 versions)
-- Firefox (last 2 versions)
-- Safari (last 2 versions)
-- Edge (last 2 versions)
+All modern browsers (last 2 versions): Chrome, Firefox, Safari, Edge.
 
 ## Development
 
-### Build
-
 ```bash
-bun install
-bun run build
-```
-
-### Type Check
-
-```bash
-bun run typecheck
-```
-
-### Watch Mode
-
-```bash
-bun run dev
+bun install          # Install dependencies
+bun run build        # Build ESM + CJS bundles
+bun run dev          # Watch mode
+bun run typecheck    # Type checking
+bun run lint         # Lint source
 ```
 
 ## Package Structure
 
 ```
 stilts/
-├── dist/               # Built files
-│   ├── index.js        # ESM bundle
-│   ├── index.cjs       # CommonJS bundle
-│   └── index.d.ts      # TypeScript definitions
+├── dist/
+│   ├── index.js          # ESM bundle
+│   ├── index.cjs         # CJS bundle
+│   ├── index.d.ts        # Type definitions
+│   ├── styles/           # CSS files
+│   ├── tokens/           # Token bundles
+│   └── components/       # Individual component bundles
 ├── src/
-│   ├── components/     # React components
-│   ├── styles/         # CSS design tokens
-│   ├── tokens/         # TypeScript tokens
-│   └── types/          # Shared types
+│   ├── components/
+│   │   ├── layout/       # MainNav, TopBanner
+│   │   ├── ui/           # Toast
+│   │   ├── patterns/     # 14 pattern components
+│   │   └── sections/     # 15 section components
+│   ├── styles/           # CSS design tokens
+│   ├── tokens/           # TypeScript token definitions
+│   └── types/            # Shared type definitions
 └── package.json
 ```
 
-## License
+## Changelog
 
-MIT © Nimble Giant
+See [CHANGELOG.md](./CHANGELOG.md) for release history.
 
 ## Contributing
 
-This package is currently maintained internally by Nimble Giant. For questions or issues, please contact the team.
+Stilts is open source under the MIT license. Contributions are welcome.
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feat/my-feature`)
+3. Make your changes and ensure `bun run typecheck` and `bun run build` pass
+4. Submit a pull request
+
+For questions or issues, please [open an issue](https://github.com/nimble-giant/giantkit/issues).
+
+## License
+
+MIT - see [LICENSE](./LICENSE)
 
 ## Links
 
-- [Nimble Giant Website](https://nimble-giant.com)
+- [Live Demo](https://nimble-giant.com) — Stilts components in production
 - [GitHub Repository](https://github.com/nimble-giant/giantkit)
+- [npm Package](https://www.npmjs.com/package/@nimblegiant/stilts)