@flamingo-stack/openframe-frontend-core

Shared design system and component library for Flamingo platforms (OpenMSP, OpenFrame, Admin Hub, Flamingo Website, TMCG).

Installation

npm install https://pkg.pr.new/flamingo-stack/openframe-oss-lib/@flamingo-stack/openframe-frontend-core@<x.y.z>

Usage

Components

import { Button, Card, Input, Modal, Tag } from '@flamingo-stack/openframe-frontend-core/components/ui'
import { YouTubeEmbed, FigmaPrototypeViewer } from '@flamingo-stack/openframe-frontend-core/components/features'
import { GithubIcon, OpenframeLogoIcon } from '@flamingo-stack/openframe-frontend-core/components/icons-v2'

Hooks

import { useDebounce, useMediaQuery, useToast } from '@flamingo-stack/openframe-frontend-core/hooks'

Utilities

import { cn, formatDate, formatPrice, getPlatformUrl } from '@flamingo-stack/openframe-frontend-core/utils'

Styles

// Import in your layout or _app.tsx
import '@flamingo-stack/openframe-frontend-core/styles'

Tailwind Config

Extend the shared Tailwind config in your project:

import designSystemConfig from '@flamingo-stack/openframe-frontend-core/tailwind.config.ts'
import { appStyleSources } from '@flamingo-stack/openframe-frontend-core/style-sources'

export default {
  presets: [designSystemConfig],
  // The files your App Router routes import, yours and this library's: never this library's whole
  // `dist` or `src`, which puts every component's classes in the stylesheet every page blocks on.
  content: appStyleSources({ root: __dirname, appDir: 'src/app' }),
}

appStyleSources (scripts/style-sources.cjs) walks the import graph from the route files, tree-shaken as your bundler does. A host can leave the lazily loaded chat out of the page's stylesheet with firstPaint: true, and give EmbeddableChat a loadStyles that loads a full stylesheet built without it (see the file's header).

Then send the stylesheet inside each page's HTML, so a page never waits on a second request to paint, and hold its size to a budget in your checks (scripts/next-styles.cjs says why and what it costs):

// next.config.mjs
import { withInlineStyles } from '@flamingo-stack/openframe-frontend-core/next-styles'
export default withInlineStyles(nextConfig)

node node_modules/@flamingo-stack/openframe-frontend-core/dist/build/next-styles.cjs budget \
  --input src/app/globals.css --config tailwind.config.ts --budget 31500

Package Exports

Design System (ODS)

The package includes the OpenFrame Design System (ODS) with:

• CSS Variables — Design tokens as custom properties
• Responsive Typography — text-h1 through text-h6 utilities via Tailwind plugin
• Platform Theming — Automatic color adaptation based on NEXT_PUBLIC_APP_TYPE
• Breakpoints — md: 800px, lg: 1280px, xl: 1440px (mobile-first)

Tailwind Merge Configuration

The cn() utility extends tailwind-merge to recognize ODS typography classes (text-h1–text-h6) as a separate group, so they don't conflict with text-color classes:

import { cn } from '@flamingo-stack/openframe-frontend-core/utils'

// text-h5 and text-red-500 coexist correctly
cn('text-h5', 'text-red-500') // => "text-h5 text-red-500"

Platform Support

Platform detection is automatic via NEXT_PUBLIC_APP_TYPE environment variable.

Development

# Build the package
npm run build

# Build without type declarations (faster)
npm run build:fast

# Watch mode
npm run dev

# Type checking
npm run type-check

# Run tests
npm run test

# Storybook
npm run storybook

# Publish via yalc (local development)
npm run yalc:push
npm run yalc:watch

Architecture

src/
  components/
    ui/           # Base components (Button, Card, Input, Modal, Tag, etc.)
    features/     # Complex components (YouTubeEmbed, FigmaPrototypeViewer)
    icons/        # Centralized icon components
    icons-v2-generated/  # Auto-generated icon set
    navigation/   # Header, StickySectionNav
    toast/        # Toast notification system
  hooks/
    ui/           # UI hooks (useDebounce, useMediaQuery)
    api/          # Data fetching hooks
    platform/     # Platform configuration hooks
  styles/
    index.css     # Main stylesheet
    ods-*.css     # Design token modules
  utils/
    cn.ts         # clsx + tailwind-merge
    platform-config.tsx  # Unified platform configuration
  types/          # TypeScript type definitions
  nats/           # NATS WebSocket integration

Tutorials

End-to-end guides under docs/:

• MIGRATING_COMPONENTS.md — how to move a component from the hub into this lib (3-layer model, barrel rules, runtime-context injection).
• EMBEDDING.md — runtime providers (EndpointsRuntimeContext, ChatRuntimeContext) for non-hub React apps.
• EMBEDDING_DOCS_HUB.md — embed <DocsHubPage> (sidebar tree + content + RAG search bar) in a third-party app. The hub uses this same component at /knowledge-base and /data-room.
• CHAT_EMBEDDING_TUTORIAL.md — embed the full <EmbeddableChat> panel (Guide + Mingo modes).
• EMBEDDING_HUBSPOT_MEETINGS.md — embed <HubSpotMeetingScheduler> (natively-branded HubSpot booking flow) behind a host proxy; includes the link naming convention and the proxy endpoint contract.

Key Dependencies

• React 18+/19 — Peer dependency
• Radix UI — Accessible component primitives
• Tailwind CSS 3 — Styling with custom design tokens
• Class Variance Authority — Component variant management
• Framer Motion — Animations
• Lucide React — Icons

License

Private package for Flamingo CX projects.