opensite-ai/opensite-skills / page-speed-library
page-speed-library
Verifiedpage-speed-* library development patterns. Use when creating or modifying @page-speed/* packages (blocks, router, forms, img, video, skins, maps, icon, lightbox, pdf-viewer, venn-diagram, hooks, social-share, humanizer) or the opensite-hooks and pressable libraries. Covers tsup bundling, peer dependency management, and the sub-library architecture.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 9.0 KB |
| agents/openai.yaml | config | 497 B |
| references/activation.md | markdown | 1013 B |
| templates/package-change-brief.md | markdown | 355 B |
SKILL.md
View on GitHub---
name: page-speed-library
description: >
page-speed-* library development patterns. Use when creating or modifying
@page-speed/* packages (blocks, router, forms, img, video, skins, maps, icon,
lightbox, pdf-viewer, venn-diagram, hooks, social-share, humanizer) or the
opensite-hooks and pressable libraries. Covers tsup bundling, peer dependency
management, and the sub-library architecture.
compatibility: >
Requires a React or TypeScript monorepo with tsup and the page-speed package
graph.
metadata:
opensite-category: frontend
opensite-scope: ui
opensite-visibility: public
---
# Page-Speed Library Development Skill
## Skill Resources
- Activation and cross-agent notes: [references/activation.md](references/activation.md)
- Template: [templates/package-change-brief.md](templates/package-change-brief.md)
You are working in the OpenSite `@page-speed/*` sub-library ecosystem — a set of focused, tree-shakable React component packages that compose into `@opensite/ui` and work together to deliver OpenSite's groundbreaking Semantic UI Design System.
## Library Inventory
| Package | Purpose | Key Dependency |
|---------|---------|----------------|
| `@page-speed/blocks` | Pre-compiled Tailwind CSS rendering runtime | `@opensite/ui` |
| `@page-speed/router` | SPA routing for site builder pages | React |
| `@page-speed/forms` | Form components with validation | React Hook Form |
| `@page-speed/img` | Optimized image component | React |
| `@page-speed/video` | Video player/embed component | React |
| `@page-speed/skins` | Theme/skin CSS variable system | CSS |
| `@page-speed/maps` | MapLibre GL map component | maplibre-gl |
| `@page-speed/icon` | SVG icon system | React |
| `@page-speed/lightbox` | Image/media lightbox | React |
| `@page-speed/pdf-viewer` | PDF rendering in browser | React |
| `@page-speed/venn-diagram` | Venn diagram visualization | React |
| `@page-speed/hooks` | Shared React hooks | React |
| `@page-speed/social-share` | Social sharing buttons | React |
| `@page-speed/humanizer` | AI content humanization (in progress) | React |
| `@opensite/hooks` | Core OpenSite hooks library | React |
| `pressable` | Accessible press/click abstraction | React |
## Standard tsup Configuration
Every `@page-speed/*` library uses this base tsup config:
```typescript
// tsup.config.ts
import { defineConfig } from "tsup"
export default defineConfig({
entry: ["src/index.ts"],
format: ["cjs", "esm"],
dts: true,
splitting: true,
sourcemap: true,
clean: true,
treeshake: true,
external: [
"react",
"react-dom",
// Add any other peerDeps here
],
esbuildOptions(options) {
options.banner = {
js: '"use client"', // Required for Next.js RSC compatibility
}
},
})
```
## Package.json Template
```json
{
"name": "@page-speed/your-package",
"version": "0.1.0",
"description": "Short description of what this package does",
"main": "./dist/index.js",
"module": "./dist/index.mjs",
"types": "./dist/index.d.ts",
"exports": {
".": {
"import": "./dist/index.mjs",
"require": "./dist/index.js",
"types": "./dist/index.d.ts"
}
},
"files": ["dist"],
"sideEffects": false,
"peerDependencies": {
"react": ">=17.0.0",
"react-dom": ">=17.0.0"
},
"devDependencies": {
"@types/react": "^18.3.3",
"@types/react-dom": "^18.3.0",
"react": "^18.3.1",
"react-dom": "^18.3.1",
"tsup": "^8.0.1",
"typescript": "^5.6.2",
"vitest": "^3.0.0"
},
"scripts": {
"build": "tsup",
"dev": "tsup --watch",
"test": "vitest",
"type-check": "tsc --noEmit"
}
}
```
## src/index.ts Export Pattern
Every package exports from a central `src/index.ts`. Keep it flat and explicit:
```typescript
// src/index.ts — named exports only, no barrel re-exports of internal utils
export { YourComponent, type YourComponentProps } from "./components/YourComponent"
export { AnotherComponent, type AnotherComponentProps } from "./components/AnotherComponent"
export { useYourHook } from "./hooks/useYourHook"
export type { SharedType } from "./types"
// Never export internal utilities that consumers shouldn't use
// Never use: export * from "./components" (breaks tree-shaking)
```
## Component Pattern for Library Components
Library components should be:
1. Framework-agnostic styled (no Tailwind in lib components — let consumer apply classes)
2. Fully typed with exported prop types
3. Accessible (ARIA attributes, keyboard navigation)
4. Forwardable refs when wrapping DOM elements
```typescript
// src/components/YourComponent.tsx
"use client" // Required for Next.js App Router compatibility
import React from "react"
export interface YourComponentProps
extends React.HTMLAttributes<HTMLDivElement> {
/** Primary content */
children: React.ReactNode
/** Optional secondary content */
label?: string
/** Controlled open state */
isOpen?: boolean
/** Callback when state changes */
onOpenChange?: (open: boolean) => void
}
export const YourComponent = React.forwardRef<HTMLDivElement, YourComponentProps>(
({ children, label, isOpen, onOpenChange, className, ...props }, ref) => {
return (
<div
ref={ref}
className={className}
role="region"
aria-label={label}
{...props}
>
{children}
</div>
)
}
)
YourComponent.displayName = "YourComponent"
```
## @page-speed/img Deep Dive
`@page-speed/img` is used everywhere. Key usage patterns:
```typescript
import { Img, type ImgProps } from "@page-speed/img"
// Basic image with lazy loading
<Img
src="https://example.com/image.jpg"
alt="Description"
width={800}
height={450}
className="w-full h-auto"
/>
// Fill container (parent must be relative + overflow-hidden)
<div className="relative h-64 overflow-hidden">
<Img
src={imageUrl}
alt={alt}
fill
className="object-cover object-center"
/>
</div>
// With blur placeholder
<Img
src={src}
alt={alt}
width={400}
height={300}
placeholder="blur"
blurDataURL={blurDataUrl}
/>
```
## @page-speed/hooks Usage
```typescript
import {
useIntersectionObserver,
useMediaQuery,
useLocalStorage,
useDebounce,
useClickOutside,
} from "@page-speed/hooks"
// Intersection observer for lazy loading/animations
const { ref, isIntersecting } = useIntersectionObserver({
threshold: 0.1,
rootMargin: "50px",
})
// Responsive breakpoint detection
const isMobile = useMediaQuery("(max-width: 768px)")
const isTablet = useMediaQuery("(min-width: 768px) and (max-width: 1024px)")
// Click outside detection
const containerRef = useRef<HTMLDivElement>(null)
useClickOutside(containerRef, () => setIsOpen(false))
```
## @opensite/hooks Usage
```typescript
import {
useSiteContext,
useComponentRegistry,
useTheme,
useSkin,
} from "@opensite/hooks"
// Access the current site context (for site builder components)
const { siteId, accountId, locale } = useSiteContext()
// Access the component registry (for dynamic rendering)
const { getComponent, registerComponent } = useComponentRegistry()
// Access the current theme
const { theme, setTheme } = useTheme()
// Access and apply skins
const { currentSkin, applySkin } = useSkin()
```
## Testing Pattern for Libraries
```typescript
// src/__tests__/YourComponent.test.tsx
import { render, screen } from "@testing-library/react"
import userEvent from "@testing-library/user-event"
import { describe, it, expect, vi } from "vitest"
import { YourComponent } from "../components/YourComponent"
describe("YourComponent", () => {
it("renders children", () => {
render(<YourComponent>Content</YourComponent>)
expect(screen.getByText("Content")).toBeInTheDocument()
})
it("calls onOpenChange when triggered", async () => {
const onOpenChange = vi.fn()
render(<YourComponent onOpenChange={onOpenChange}>Click me</YourComponent>)
await userEvent.click(screen.getByText("Click me"))
expect(onOpenChange).toHaveBeenCalledWith(true)
})
it("forwards ref to DOM element", () => {
const ref = React.createRef<HTMLDivElement>()
render(<YourComponent ref={ref}>Content</YourComponent>)
expect(ref.current).toBeInstanceOf(HTMLDivElement)
})
})
```
## Version Publishing Checklist
Before publishing a new version:
- [ ] Run `pnpm build` — ensure no type errors
- [ ] Run `pnpm test` — all tests pass
- [ ] Check bundle size with `size-limit` (if configured)
- [ ] Verify exports are tree-shakable (import one component, bundle size should be minimal)
- [ ] Update `CHANGELOG.md` with breaking changes
- [ ] Bump version in `package.json`
- [ ] Test in the `ui-library` showcase before publishing
- [ ] Ensure peer deps are not bundled (check dist/index.js for React imports)
## pressable Library
`pressable` is an accessibility-first press/tap interaction library:
```typescript
import { Pressable, usePressable } from "@page-speed/pressable"
// Declarative usage
<Pressable
onPress={() => handlePress()}
onLongPress={() => handleLongPress()}
disabled={isLoading}
>
{({ isPressed }) => (
<div className={cn("cursor-pointer", isPressed && "scale-95 transition-transform")}>
Press me
</div>
)}
</Pressable>
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| canvas-designanthropics/skillsCreate beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| docxanthropics/skillsUse this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', '.dotx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| pdfanthropics/skillsUse this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| pptxanthropics/skillsUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx or .potx filename, regardless of what they plan to do with the content afterward. If a .pptx or .potx file needs to be opened, created, or touched, use this skill. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |