Customizing and Extending UI Blocks
Relevant source files
The following files were used as context for generating this wiki page:
Poneglyph utilizes a modular UI architecture designed for rapid development and high consistency across its monorepo structure. The system leverages a shared UI package to distribute atomic components and design tokens to consumer applications, primarily the web frontend.
The UI strategy is built on shadcn/ui primitives, utility-first styling via TailwindCSS, and a centralized design token system. This allows developers to extend the library by adding new shared primitives or creating app-specific blocks while maintaining a unified visual language.
Sources: README.md:5-9, README.md:73-81
Shared UI Architecture
The project is structured as a Turborepo where UI components are decoupled from application logic. Shared primitives reside in packages/ui, while application-specific features are built within apps/web.
The UI Package Structure
The @Poneglyph/ui package acts as the single source of truth for the design system. It exports styles, components, and hooks that are consumed by other workspaces.
The diagram above shows the relationship between the shared UI package and the application layer.
Sources: package.json:3-9, packages/ui/package.json:5-11
Component Distribution
Shared components are imported into applications using the @Poneglyph/ui workspace alias. This ensures that any update to a base primitive is instantly reflected across all applications.
| Export Type | Directory Path | Purpose |
|---|---|---|
| Styles | src/styles/globals.css | Tailwind base, theme variables (OKLCH), and global resets. |
| Components | src/components/*.tsx | Reusable shadcn/ui primitives like Buttons, Badges, and Inputs. |
| Libraries | src/lib/*.ts | Utility functions like cn (tailwind-merge). |
| Sources: packages/ui/package.json:5-11, apps/web/src/app/layout.tsx:5-6 |
Design Tokens and Styling
Poneglyph uses CSS variables defined in a centralized global stylesheet to manage its theme. The system supports both light and dark modes using the oklch color space for better perceptual uniformity.
Theme Configuration
Design tokens are categorized into functional groups such as backgrounds, foregrounds, and primary accents. These tokens are consumed by Tailwind classes throughout the project.
The theme flow demonstrates how CSS variables in the UI package propagate to the Tailwind configuration.
Sources: packages/ui/src/styles/globals.css:9-40, packages/ui/src/styles/globals.css:42-66
Typography and Fonts
The application integrates multiple font families via next/font to distinguish between headings, body text, and technical data.
- Headings:
Space_Grotesk - Sans-serif (UI):
Geist,Outfit - Serif (Editorial):
Newsreader - Monospace:
JetBrains_Mono
Sources: apps/web/src/app/layout.tsx:4-31
Extending UI Blocks
There are two primary ways to extend the UI system: adding new shared primitives or creating complex application-specific blocks.
Adding Shared Primitives
To add new foundational components (e.g., Accordion, Dialog), the shadcn CLI should be targeted at the shared UI package.
npx shadcn@latest add [component-name] -c packages/ui
Sources: README.md:85-87
Creating Application Blocks
Complex blocks that are highly coupled to specific domain logic (like ArticleCard or DatasetPreviewCard) are implemented directly within the application. These blocks "extend" the UI by composing shared primitives.
Example: ArticleCard Composition
The ArticleCard uses the shared Badge primitive to display dataset metadata.
import { Badge } from "@Poneglyph/ui/components/badge";
export function ArticleCard({ article }) {
return (
<div className="rounded-md border border-grey-3">
{article.datasetIds.map((id) => (
<Badge key={id} variant="secondary">{id}</Badge>
))}
</div>
);
}
Sources: apps/web/src/app/dashboard/components/article-card.tsx:1-36
Data-Driven UI Components
The UI is built to handle complex states, such as file uploads and dynamic previews. The DatasetUploadPage demonstrates how UI blocks respond to local state (e.g., isDragging, uploadStatus).
| State | UI Response | Component Used |
|---|---|---|
| Idle | Display dropzone or file input | UploadCloud, Input |
| Uploading | Display progress spinner | AlertCircle (Spinning) |
| Success | Display success banner and check icon | CheckCircle |
| Sources: apps/web/src/app/datasets/upload/page.tsx:112-140, apps/web/src/app/datasets/upload/page.tsx:287-320 |
Summary
The Poneglyph UI system is a robust, monorepo-aware framework that balances the need for shared consistency with application-specific flexibility. By centralizing design tokens in packages/ui and utilizing a standard set of primitives, developers can predictably extend the interface while maintaining the project's professional, data-centric aesthetic.
Sources: README.md:73-81, packages/ui/src/styles/globals.css:127-136