Refined design skill for AI agents

Overview

Refined is an elegant, serif-forward design system skill file that tells AI coding assistants to generate interfaces with the sophistication of editorial design. Where most UI systems default to geometric sans-serifs, Refined leads with Playfair Display — a high-contrast transitional serif that brings the typographic confidence of luxury magazines and publishing to digital products.

This skill is built for products that need to communicate quality, authority, and taste: portfolio sites, editorial platforms, luxury e-commerce, premium SaaS, creative agencies, and any interface where the typography itself is part of the brand experience.

Design Tokens

Color Palette

Refined uses the same trusted blue-and-violet palette found in professional-grade design systems, but here the colors play a supporting role — the typography carries the personality:

The palette is intentionally understated. In Refined, color accents are used sparingly so the eye is drawn to the typography first. The primary blue marks interactive elements clearly without competing with the visual weight of the serif headings.

Typography

Typography is the defining feature of the Refined system:

• Primary and display font: Playfair Display — a transitional serif with high stroke contrast, elegant ball terminals, and distinctive italics. Its design references the European Enlightenment era of type, giving headings and display text a sense of heritage and authority. At body sizes it remains legible while retaining its refined character
• Monospace font: JetBrains Mono — a clean developer font for code blocks and technical content, providing a modern counterpoint to the classical serif

The type scale follows: 12 / 14 / 16 / 20 / 24 / 32px, with weights from 100 through 900. The serif typeface shines at the upper end of the scale — 24px and 32px headings in Playfair Display carry the editorial weight that defines this system's personality. At smaller sizes (12–14px), the high stroke contrast remains readable but benefits from slightly increased line height.

Spacing

All spacing follows a 4px base unit with a scale of 4 / 8 / 12 / 16 / 24 / 32px. Generous whitespace is essential to the Refined aesthetic — serif typography needs room to breathe. Tight spacing that might work with a compact sans-serif will crowd Playfair Display's character shapes and undermine the elegance the font provides.

The skill file emphasizes comfortable vertical rhythm, particularly around headings and between sections, to create the measured pace of a well-typeset page.

Component Coverage

Refined includes guidance for over 40 component families, each designed to carry the editorial aesthetic while remaining fully functional:

• Inputs and forms — buttons, text inputs, selects, checkboxes, radios, switches, textareas, date/time pickers, file uploaders
• Data display — cards, tables, data lists, data grids, charts, stats/metrics, badges, avatars
• Navigation — breadcrumbs, pagination, steppers, sidebars, top bars, tabs, command palette
• Overlays and feedback — modals, drawers, tooltips, popovers, alerts, toasts, notifications, progress indicators, skeletons
• Page-level patterns — search, empty states, onboarding, authentication screens, settings pages, documentation layouts, pricing blocks

Each component defines required states (default, hover, focus-visible, active, disabled, loading, error), interaction behavior for keyboard, pointer, and touch, and explicit token usage for spacing, typography, and color. The serif personality comes through in heading treatments, button labels, and card titles — not by overriding the component structure, but by elevating its typographic quality.

The Serif Difference

Using a serif typeface as the primary UI font is a deliberate choice that changes how AI-generated interfaces feel:

• Headings carry authority — Playfair Display at 24–32px creates a sense of editorial weight that geometric sans-serifs cannot replicate
• Content feels curated — body text in a transitional serif reads as intentionally crafted, like a published article rather than a software interface
• Visual hierarchy is typographic — instead of relying on color, weight, or size alone, the inherent contrast between serif strokes creates hierarchy within the letterforms themselves
• The interface has voice — a serif font carries cultural associations of quality, tradition, and care that influence how users perceive the product

The skill file balances this editorial personality with practical UI requirements — interactive elements remain clearly identifiable, data-dense views stay readable, and the serif treatment enhances rather than obscures functionality.

Accessibility

Refined enforces WCAG 2.2 AA compliance as a baseline:

• Keyboard-first interaction patterns with visible focus states on every interactive element
• Sufficient color contrast between the white surface (#FFFFFF) and text (#111827)
• Semantic HTML structure and proper ARIA attributes throughout
• Testable acceptance criteria for every accessibility requirement
• Attention to line height and letter spacing at smaller sizes, where the high stroke contrast of Playfair Display requires slightly more generous vertical spacing for comfortable reading

When the refined serif aesthetic conflicts with accessibility — for example, if small serif text at 12px becomes difficult to read — the skill file prioritizes readability and provides specific guidance on minimum sizes and line heights for the serif typeface.

How to Use with AI Tools

Cursor and Claude

1. Pull the skill file into your project:

npx typeui.sh pull refined

2. The skill file saves as a SKILL.md in your project. Cursor automatically detects skill files and uses them as context during code generation.

3. Start prompting — ask Cursor to build landing pages, portfolios, or editorial layouts, and the output will follow the Refined system's serif typography, restrained color palette, and generous spacing.

Claude (Anthropic)

Use Refined directly with Claude by adding the skill file as context:

1. Copy or download the skill file from the design skill page
2. Paste it at the start of a Claude conversation, or add it to a Claude Project as project knowledge
3. Prompt Claude to generate UI code — it will produce elegant, serif-driven interfaces following the Refined tokens, typographic rules, and accessibility requirements

Other AI Tools

The skill file is standard markdown compatible with any AI assistant that accepts context or system instructions:

• ChatGPT — paste into Custom Instructions or at the start of a conversation
• Windsurf / Codeium — place the file in your project directory
• GitHub Copilot — add to your repository's context or instruction files
• v0 by Vercel — paste the design tokens and typography rules as prompt context

Design Philosophy

Refined is built on the principle that typography is the interface. The skill file follows three rules:

1. Type first, everything else second — the serif typeface is the primary design element. Color, spacing, and component structure exist to support and showcase the typography
2. Restraint signals quality — fewer colors, less decoration, and more whitespace communicate confidence. The interface doesn't need to shout when the typography speaks with authority
3. Editorial standards for digital products — the same care that goes into typesetting a printed page should go into every screen. Line heights, spacing rhythms, and font pairings are treated with the precision of book design