Copy Guidelines

These guidelines ensure consistent brand voice and messaging across all platforms. Adhering to them strengthens brand recognition and builds trust with our audience.

Capitalization

• Use sentence case for all product UI, including buttons, field names, labels, descriptions, headings, empty states, dialogs, menus, table headers, filter names, toast messages, tooltips, and helper text.
  • Examples: "Create deal", "Company type", "Add status", "No companies found", "Select an email to view", "Use light mode", "Toggle columns"
  • Sentence case does not mean all lowercase. Standalone copy still starts with a capital letter: "Recent terms access is currently limited", not "recent terms access is currently limited".
  • Lowercase the first word only when the copy is an inline continuation or fragment inside a larger sentence.
• Use Title Case only for proper nouns and canonical names. This includes:
  • Product, app, service, and feature names: "Lev", "Lev Agent", "Lev Agents", "Deal Assist", "Import Hub", "Support Center", "Memo", "Memo Editor", "Vault", "Vault Checklist", "Lev Memo", "Lev Vault"
  • Memo and Vault stay capitalized when used as product nouns, including plurals and named Vault surfaces: "Recent Memos", "Recent Vaults", "Untitled Memo", "Create new Vault", "Deal Room Vault", "Private Vault", "Intake Vault"
  • Modifiers before product names follow sentence case unless they are part of a canonical name or start the sentence: "Search shared Vaults", "No shared Vaults found", "Shared Vault"
  • Company, contact, deal, Vault, pipeline, Memo, and other user-entered names: preserve source casing
  • Do not apply product-name capitalization to code identifiers, API values, GraphQL enum values, URLs, route paths, data attributes, or file extensions (e.g. type="memo", /vaults, .memo)
  • Formal roles, job titles, personas, and relationship types when used as named types: "Insurance Broker", "Debt Broker", "Investment Sales Broker", "Admin", "Editor"
  • CRE taxonomy values and controlled CRE, loan, request, document, and report type names: "Office Condo", "General Multifamily", "First Mortgage Loan", "Preferred Equity", "Bridge", "Construction", "Permanent"
  • Controlled loan request/type abbreviations and combinations: "Perm - Refi - 1st", "Perm - Acq - 1st", "Bridge - 1st", "Mezz", "Pref", "Subr"
  • Document, template, and report names when they are canonical types: "Rent Roll", "Operating Statement", "Offering Memorandum", "Term Sheet", "Tear Sheet", "Marketing Status Report"
  • Generic finance phrases that are not canonical names use sentence case: "sources and uses", not "Sources and Uses"
  • Named plans, packages, permissions, and legal/policy documents: "Pro", "Enterprise", "Lev Pro", "Pay As You Go", "Legacy Plan", "Full Access", "View Only", "Invite Only", "Limited Access", "Read-Only", "Privacy Policy", "Terms of Service"
  • When a named permission is part of a longer phrase, use sentence case around it unless the full phrase is the canonical name: "Full access to Lev CRM", not "Full Access to Lev CRM"
  • Geographic proper nouns: "New York", "San Francisco", "United States", "Los Angeles County"
• Preserve established acronyms and initialisms (e.g. API, HQ, NOI, DSCR, LTV, PSA, LOI, AUM, CRM)
• Use sentence case for statuses by default, unless the status is a user-defined value or a canonical pipeline stage/type name.

CTA Words

Use these standard action words consistently across the product:

• New: Creates a new item from scratch (e.g. New deal, New slide, New message)
• Add: Includes an existing item in a given context (e.g. "Add a placement to a deal")
• Save: Commits unsaved changes
  • Use Update when the distinction between saving and updating matters
• Delete: Permanently removes something
  • Remove: Removes item from the collection but does not destroy it
• View: To look at something (e.g. View contacts)
  • Open: "View", specifically for documents, modals, and files
• Cancel: Exits without saving changes
• Dismiss: Closes a notification or message without taking action

Commas

Always use Oxford commas (serial commas) in lists of three or more items.

✓ "deals, placements, and messages"

✗ "deals, placements and messages"

Punctuation Standards

• No periods in headlines, buttons, or labels unless they contain multiple sentences or they are used for effect
• Use em dashes (—) for breaks in thought, not hyphens or double dashes
• Use double quotes ("") for primary quotations and quoted speech
• Use single quotes ('') for quotes within quotes
• Semicolons (;) only when joining related independent clauses; prefer periods or separate sentences

Numbers and Metrics

General Number Formatting

• Spell out one (1) through nine (9) in body text
• Use numerals for 10 and above
• Exception: Always use numerals with units (5 days, 3 deals)
• Large numbers: Use commas for thousands (10,000+)

Currency

• Format: $1,234,567 (with commas for thousands)
• Decimals: Show cents only when necessary ($50 not $50.00)
• Large numbers: Use K, M, B notation when space is limited
  • $1.2M (not $1,200,000)
  • $850K (not $850,000)

Percentages

• Format: 15.5% (no space between number and %)
• Decimals: One decimal place for precision, whole numbers when possible
• Ranges: 10%–15% (use en dash, no spaces)

Units of Measure

Area

• Square feet: 1,200 sq ft
• Square miles: 5.2 sq mi
• Acres: 2.5 acres (spelled out)

Distance

• Miles: 15 miles, 2.3 mi (spell out in body text, abbreviate in tight spaces)
• Feet: 500 feet, 500 ft
• Kilometers: 10 kilometers, 10 km (when relevant)

Weight

• Pounds: 150 pounds, 150 lbs
• Tons: 2.5 tons (spell out)

Volume

• Gallons: 500 gallons, 500 gal
• Cubic feet: 1,000 cu ft

Date and Time

Date Formats

• Default format: Aug 27, 2025 (abbreviated month, no leading zeros)
• Short format: 8/27/25 (when space is very limited)
• ISO format: 2025-08-27 (for technical contexts only)
• Ranges: Aug 27–30, 2025 (en dash, no spaces)

Time Formats

• 12-hour format: 2:30 PM (no leading zeros, space before AM/PM)
• Time ranges: 2:30–4:00 PM (en dash, repeat AM/PM only when crossing)
• Duration: 1h 30m (no spaces around units)

Relative Time

• Recent: "2 minutes ago", "1 hour ago", "yesterday"
• Future: "in 5 minutes", "tomorrow", "next week"
• Always spell out time units in relative formats

Days of the Week

• Full names: Monday, Tuesday, Wednesday (in body text and formal contexts)
• Abbreviations: Mon, Tue, Wed, Thu, Fri, Sat, Sun (in calendars, tables, tight spaces)
• Ranges: Monday–Friday (en dash, no spaces), Mon–Fri (abbreviated)
• Today/Tomorrow: Use "today" and "tomorrow" instead of day names when referring to current/next day
• Capitalization: Always capitalize day names and abbreviations

Airy Design System Rules

These rules apply to consuming applications using the Airy design system. They cover registry-managed files, app-owned extension points, component usage, forms, accessibility, and implementation patterns.

For copy, labels, button text, errors, empty states, and product wording, also read copy.md.

App Policy Wins

Airy rules provide defaults for consuming apps. If an app has stricter or more specific guidance in AGENTS.md, local Cursor rules, or established code patterns, follow the app's guidance first.

Do not introduce a second framework, form stack, styling system, routing pattern, or validation library into a consuming app without an explicit migration plan.

For visual design language, token roles, presentation guidance, and iconography, use the Airy guidelines if they are installed: ../airy-guidelines/design.md and ../airy-guidelines/visual-design.md.

If those files are missing, install them with:

npx shadcn@latest add @airy/airy-guidelines

Protected Airy Installs

Do not edit Airy-installed directories or files in consuming apps.

Protected consuming-app paths depend on the app's install layout. Common protected paths include:

• components/ui/ or src/components/ui/
• components/airy-blocks/ or src/components/airy-blocks/
• styles/airy-theme/ or src/styles/airy-theme/
• components/lev-assets/ or src/components/lev-assets/
• airy-rules/

If a protected file appears to need changes:

1. Stop and diagnose the underlying need.
2. Prefer an app-owned wrapper, shared component, className, variant, CSS variable, descendant selector, or data-slot override.
3. If the change belongs in Airy itself, propose an upstream Airy registry change instead of editing the consuming app's installed copy.
4. Do not patch the consuming app's installed copy as a local customization.

These files are installed from the Airy registry. Local edits can be overwritten on updates and can break upgrade paths.

Where Custom Work Goes

Use app-owned code for application-specific changes:

• Create wrappers or composed components outside protected Airy install folders.
• Prefer app-specific folders such as components/<feature>/, src/components/<feature>/, app/_components/, or src/app/_components/.
• Use Airy primitives and blocks through composition rather than editing their source.
• Document any app-specific customizations near the wrapper or feature code.

If a change truly belongs in a protected Airy component or theme file, propose an upstream Airy registry change. Do not patch the consuming app's installed copy as a local customization.

Component Usage

• Use the app's configured Airy import aliases, commonly @/components/ui/* and @/components/airy-blocks/*.
• Do not recreate primitives such as Button, Card, Dialog, Sidebar, Input, or Form.
• Prefer component variants and size props before adding custom classes.
• Add custom classes only for layout, spacing, or a clearly app-owned wrapper.
• Use descendant selectors or data-slot attributes from an app-owned wrapper when a child primitive needs styling.

Example:

import { Button } from '@/components/ui/button'
;<Button variant="default" size="lg">
  Continue
</Button>

Do not modify components/ui/button.tsx or other installed primitive files to change one app's behavior.

Select Composition

When using Select, wrap menu options in SelectGroup inside SelectContent. This follows the shadcn composition and preserves the menu gutter.

SelectGroup provides optional grouping semantics. It does not change the single-value behavior of Select.

<SelectContent>
  <SelectGroup>
    <SelectItem value="one">One</SelectItem>
  </SelectGroup>
</SelectContent>

Component Classification

Airy has two installed component families:

• Primitives (components/ui/) - shadcn components installed from the registry. These are protected low-level building blocks.
• Blocks (components/airy-blocks/) - composed Airy components built on primitives. These are also protected registry-managed assets.

If it is not an installed primitive or block, treat it as app-owned code and keep it outside protected Airy folders.

Brand Assets

Use installed Lev assets from @/components/lev-assets/* for Lev brand marks. Do not recreate, approximate, or edit the logo assets without explicit confirmation.

Install if needed:

bunx shadcn@latest add @airy/lev-logo -y -o

Import:

import { LevLogo } from '@/components/lev-assets/lev-logo'

Variants:

• icon - mark only.
• logo - wordmark only.
• lockup - wordmark and icon.

LevLogo uses currentColor, so it inherits text color automatically.

Theming

• Use semantic tokens such as background, foreground, primary, muted, card, and border.
• Never use raw hex or RGB values such as #ff0000 or rgb(255,0,0).
• Never use raw Tailwind colors such as bg-orange-500; use semantic tokens.
• Do not apply alpha modifiers to semantic color variables, such as text-foreground/60 or border-border/50, unless the user explicitly asks for that treatment.
• Respect the dual theme structure:
  • App: :root and .dark.
  • Marketing: .theme-marketing and .theme-marketing.dark.

The installed Airy theme directory, commonly styles/airy-theme/ or src/styles/airy-theme/, is protected. Ask before modifying any file in that directory.

Surface Treatments

Use .surface-glass for translucent, blurred surfaces such as floating panels, popovers, command palettes, and similar elevated UI.

Glass owns background, backdrop-filter, border, and box-shadow. Pair it with Tailwind utilities for radius, padding, sizing, layout, and typography.

<div className="surface-glass rounded-2xl p-6">...</div>
<NavigationMenuViewport className="surface-glass" />

Per-instance overrides use CSS variable hooks:

• --glass-tint - background color.
• --glass-blur - backdrop blur radius.
• --glass-saturation - backdrop saturation boost.

Avoid glass-on-glass nesting. For full guidance, see ../airy-guidelines/visual-design.md.

Forms

• Use the app's established form stack.
• If the app does not have an established form stack, prefer Airy Form components with react-hook-form.
• Do not introduce a second form stack into a consuming app without an explicit migration plan.
• When using Airy Form components, use Form, FormField, FormItem, FormLabel, and FormMessage.
• Validate with the app's established schema library, or use Zod when no schema standard exists.
• Keep labels, descriptions, and error messages accessible.

Before generating form code, inspect the consuming app's existing forms and follow that pattern.

Accessibility

• Every input must have a label.
• All interactive elements must be keyboard accessible.
• Preserve focus rings and aria-* attributes.
• Use sr-only for visual hiding, not display: none.
• Keep error messages associated with their controls.

Naming Conventions

• Component names: PascalCase.
• Props: camelCase.
• Variants: kebab-case or semantic words such as default, secondary, and ghost.

Feedback And Errors

• Use sonner for toasts when a top-level action succeeds or fails.
• Use FormMessage for inline form errors.
• Explain errors and empty states plainly.
• For product wording, read copy.md before writing or revising UI text.

Consuming App File Structure

components/ or src/components/
├── ui/           # Protected Airy primitives, do not modify without confirmation
├── airy-blocks/  # Protected Airy blocks, do not modify without confirmation
├── lev-assets/   # Protected Lev assets, do not modify without confirmation
└── ...           # App-owned components and wrappers

styles/airy-theme/ or src/styles/airy-theme/
└── ...           # Protected Airy theme files, do not modify without confirmation

airy-rules/
└── ...           # Protected Airy rule docs, do not modify without confirmation

Airy / Lev Design Language

Airy is Lev's design system for product software, documents, presentations, and brand collateral. Use this guide when an AI needs to create something that should feel like Lev, not just use Lev tokens.

This file is intentionally written as design context for AI agents. It should be returned alongside the correct token data for the target surface.

Style Thesis

Airy is a calm, confident, gallery-quiet interface language. It feels like a well-lit architecture studio: precise, warm, high-trust, and operational. The system should look designed by someone who understands complex commercial real estate work and refuses to decorate around it.

Hierarchy comes from semantic color roles, type weight, spacing, and disciplined composition. Avoid spectacle. Avoid generic AI gloss. Every visual move should have a job.

Use these words as the north star:

• Calm
• Precise
• Warm
• Operational
• High-trust
• Architectural
• Dense but readable
• Confidently restrained

How AI Should Use This Guide

Airy adapts by surface.

| Surface | Primary format | What the AI should do | | -------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------- | | Web app | Production code | Use Airy/shadcn components, semantic Tailwind classes, and airy.css tokens. | | Static HTML | HTML/CSS | Use semantic CSS variables and HTML/CSS references. | | PDF / print | Print-oriented HTML or document spec | Use resolved theme values, print-safe spacing, and document patterns. | | Presentation | Native slide-object spec | Build editable slide objects: text boxes, shapes, lines, images, charts. Use HTML/CSS previews only as reference. | | Figma | Design-tool spec | Use frames, text styles, fills, effects, and component-like layout guidance. | | Image / social | Single-frame spec | Use resolved values, composition patterns, and brand asset rules. | | Email | Email-safe HTML | Use resolved values, table-safe layout constraints, and conservative typography. |

For PowerPoint and presentation tools, do not treat React components or HTML snippets as the final object. Use them as visual references. The final deck should be built from native slide primitives: text boxes, rectangles, rounded rectangles, lines, pictures, charts, and groups.

Surface Rules

Web App / Production Code

Use semantic classes and installed Airy components:

• Ground: bg-background
• Text: text-foreground
• Secondary text: text-muted-foreground
• Borders: border-border
• Primary actions: bg-primary text-primary-foreground
• Cards: bg-card text-card-foreground border-border

Do not resolve colors to hex for normal web app implementation. The CSS variables are the design contract.

Presentation / Native PPTX

Use semantic roles plus resolved values from Airy theme context.

The AI should translate Airy into native slide objects:

• Backgrounds become full-slide rectangles using the background role.
• Cards become rounded rectangles using the card role, border stroke, and Airy radius values.
• Buttons become rounded rectangles plus centered text boxes.
• Headings, body copy, and captions become text boxes with resolved font families, sizes, weights, and colors.
• Lev logos become SVG/PNG picture objects, never recreated with text.
• Component HTML/CSS previews are reference material only unless the workflow explicitly uses an HTML-to-PPTX exporter.

HTML Intermediate / Reference

Claude Design-style HTML exports use the browser as the design-system interpreter:

1. HTML and copied CSS build the slide or component reference.
2. CSS variables resolve in the browser.
3. An exporter reads computed styles.
4. DOM nodes map to PowerPoint primitives or screenshots.

This is useful context, but it is not the default Airy presentation path. For direct PPTX generation, return native slide-object specs first and HTML previews second.

Theme Selection

Airy has distinct theme contexts. Choose the theme before choosing components.

| Theme | Selector / mode | Use for | | --------------- | ---------------------------------- | ------------------------------------------------------------------------------------ | | App light | :root, .app, .memo | Default signed-in product UI, dashboards, forms, tables, operational workflows. | | App dark | .dark, .app.dark, .dark .app | Product dark mode and app-like dark surfaces. | | Marketing light | .theme-marketing | Public surfaces that need warmth and lightness. Use sparingly. | | Marketing dark | .theme-marketing.dark | Canonical brand-forward marketing, presentation, and high-impact collateral surface. | | Memo | .memo | Document/note surfaces that need quiet neutral canvas behavior. |

Do not mix themes inside one screen or slide unless explicitly showing a product screenshot/mockup inside a marketing surface.

Token Roles

Use token roles by meaning. The MCP or consuming tool should provide the right token form for the surface: classes for web apps, resolved values for decks/images/PDFs, or CSS variables for HTML.

| Role | Meaning | Web app expression | Presentation / static expression | | ---------------------- | --------------------------------------------- | ------------------------------------ | ----------------------------------------- | | background | Page, slide, or document ground | bg-background | Resolved fill for full-canvas shape | | foreground | Primary text | text-foreground | Resolved text color | | muted-foreground | Captions, metadata, helper text | text-muted-foreground | Resolved secondary text color | | card | Raised or grouped content surface | bg-card | Resolved card fill on shape | | card-foreground | Text on cards | text-card-foreground | Resolved card text color | | border | Dividers, frames, strokes | border-border | 1px stroke color | | primary | Primary CTA, active state, key emphasis | bg-primary, text-primary | CTA fill, accent line, metric highlight | | primary-foreground | Text on primary | text-primary-foreground | Text color on primary-filled shapes | | secondary | Secondary surface | bg-secondary | Low-emphasis panel fill | | accent | Hover/active affordance, small emphasis | bg-accent | Small accent fill or interaction state | | muted | Quiet background, hover area, table alternate | bg-muted | Low-emphasis shape fill | | destructive | Irreversible/danger actions | text-destructive, bg-destructive | Error callout/accent only | | ring | Focus state | ring-ring | Rarely used in static output | | chart-1 to chart-5 | Ordered data palette | Chart config | Chart series colors | | levender-* | Special Lev brand moments | Semantic callouts | Reserved tint/accent for branded emphasis |

Theme Color Guidance

Airy uses OKLCH primitives and semantic tokens. Do not invent raw colors.

App Light

• Primary ground: white / neutral light canvas.
• Primary ink: neutral 900.
• Primary action: deep, low-saturation Lev green.
• Sidebar/chrome: warm mud/off-white.
• Best for: product apps, admin surfaces, forms, dashboards, tables.

App Dark

• Primary ground: terra deep neutral.
• Cards/chrome: stepped terra surfaces.
• Primary action: inverted light neutral.
• Best for: product dark mode, app-like demos, dense workspaces.

Marketing Dark

• Primary ground: abyss deep teal-black, never pure black.
• Primary ink: neutral light.
• Accent: brightened Lev green.
• Best for: pitch decks, hero moments, public marketing, executive collateral.

Marketing Light

• Primary ground: warm mud/off-white.
• Cards: white or subtle warm surfaces.
• Accent: Lev green.
• Best for: lighter editorial pages or collateral where dark backgrounds feel too heavy.

Typography

Airy uses IBM Plex Sans as its main voice: humanist, precise, and warm. IBM Plex Mono handles code, metadata, tables, and technical labels. Caveat is reserved for rare handwritten annotations.

| Role | Size guidance | Weight | Use for | | --------------- | ------------: | ------: | -------------------------------------------------------- | | Micro label | 9-10px | 500-600 | Table labels, small metadata, uppercase technical labels | | Caption | 12px | 400-500 | Captions, helper text, chart labels | | Body small | 14px | 400 | Dense product UI and compact explanations | | Body | 16px | 400 | Default prose, slide supporting copy | | Emphasized body | 18-20px | 500 | Pullouts, short supporting statements | | Section heading | 24-32px | 600-700 | Product page titles, card group headings | | Display | 44-64px | 600-700 | Presentation and marketing headlines | | Hero display | 64-80px range | 700 | Rare full-bleed marketing moments |

Rules:

• Use IBM Plex Sans for display and body.
• Use IBM Plex Mono for numbers in dense data layouts.
• Use Caveat only for editorial annotations or human callouts.
• Do not use Inter. It reads as the AI default and dilutes the system.
• Do not use generic serifs.
• Use sentence case for headings, buttons, labels, and slide titles.
• Use solid foreground color for major headlines. No gradient text.

Spacing, Radius, And Elevation

Airy uses a 4px spacing foundation. Surfaces should breathe without becoming empty.

| Role | Guidance | | --------------------- | ---------------------------------------------- | | Element gap | 8-12px | | Card internal padding | 16-24px app, 24-32px marketing/collateral | | Slide safe margin | 48-72px from edges | | Section gap | 64-96px in documents/slides, responsive in web | | Radius default | 10px (var(--radius)) | | Radius small | 6-8px for compact controls | | Radius large | 14-18px for modals or large panels | | Radius full | Pill buttons, tags, avatars |

Elevation is subtle. Prefer borders, tonal steps, and low shadows over dramatic depth.

• Routine cards: 1px border plus subtle shadow.
• Floating panels: .surface-glass for command palettes, popovers, and menus.
• Avoid outer glows, neon blooms, and stacked translucent glass.

Components As Design References

For production web apps, use Airy components directly. For presentations, PDFs, images, and prototypes, use components as visual references and translate them into the target medium.

Button

Web app

• Use Airy Button variants.
• Primary: bg-primary text-primary-foreground.
• Outline: transparent/ground fill, border.
• Ghost: transparent until hover.
• Destructive: destructive role only for irreversible actions.

Presentation native spec

Use for app-like slide UI, product mockups, and CTA moments.

• Object: rounded rectangle plus centered text.
• Height: 36-40px equivalent.
• Width: content-fit; minimum 96px; typical 120-180px.
• Corner radius: 10px for app-like buttons; full pill only for intentional marketing CTA style.
• Fill: primary for primary, background or transparent for outline/ghost.
• Text: primary-foreground on primary, foreground otherwise.
• Stroke: none for primary; 1px border for outline.
• Font: IBM Plex Sans, 14-16px, 500-600.
• Padding: 10-16px horizontal.
• Usage: one primary action per visual cluster.

HTML reference

Use button preview/spec HTML only to understand proportions, states, and CSS behavior. Do not embed HTML in a native PPTX unless the workflow explicitly renders HTML to an image.

Card

Presentation native spec

• Object: rounded rectangle.
• Fill: card.
• Stroke: 1px border.
• Radius: 10-16px depending on scale.
• Padding: 20-32px.
• Shadow: subtle only, or none if the card is already separated by color/stroke.
• Text: foreground for title, muted-foreground for secondary.
• Use cards when grouping is meaningful. Do not card every piece of content.

Input / Form Field

Presentation native spec

• Object: rounded rectangle or underline-like frame depending on context.
• Height: 36-40px equivalent.
• Fill: background or card.
• Stroke: 1px input or border.
• Radius: 8-10px.
• Label: above field, 12-14px medium, foreground.
• Helper/error text: 12px, muted-foreground or destructive.

Table

Presentation native spec

• Use table-like shapes only when the slide is about operational detail.
• Header row: muted or card fill, medium text.
• Body rows: background/card fill, 1px border dividers.
• Numbers: IBM Plex Mono.
• Keep 4-6 rows visible. For more, show a cropped product screenshot or summary instead.

Badge / Tag

Presentation native spec

• Object: pill or small rounded rectangle.
• Height: 22-28px.
• Fill: muted, secondary, or semantic status background.
• Text: 11-13px, medium.
• Radius: full pill for status chips, 6-8px for dense tags.

Brand Assets

Use official Lev assets. Never recreate the mark or approximate it with text.

| Asset | Use for | Notes | | ---------------- | ------------------------------------------------------- | -------------------------------------------------------------------- | | LevLogo icon | Favicons, compact marks, small brand moments | Inherits current color in code. In slides, use the official SVG/PNG. | | LevLogo logo | Wordmark-only placements | Good for understated footer/chrome usage. | | LevLogo lockup | Title slides, closing slides, formal collateral | Preferred for decks and presentation open/close. | | LevToken | Brand motif, AI/credit/token concept, decorative accent | Use sparingly. It supports, never replaces, the logo. |

Presentation placement:

• Title slide: lockup in lower-left, lower-right, or top-left depending on composition.
• Section divider: small icon or wordmark with lots of negative space.
• Footer: small wordmark only when needed; do not brand every slide aggressively.
• Closing slide: lockup plus URL/contact.

Layout Principles

• Use clean spatial zones. No overlaps.
• Prefer asymmetric compositions over centered defaults for marketing/collateral.
• Use cards and panels only when they create hierarchy.
• Avoid generic 3-column equal feature grids.
• Use one dominant idea per slide or section.
• Use whitespace as structure, not as emptiness.
• In product UI, favor sidebar + main canvas, clear headers, filters, tables, and cards.
• In collateral, favor thesis-led layouts, controlled negative space, and restrained visual punctuation.

Presentation Guidance

Presentation output should default to native slide objects, not HTML. Use this guide to create editable decks.

Slide Defaults

• Canvas: 16:9 widescreen.
• Safe margins: 48-72px.
• Primary background: background.
• Primary text: foreground.
• Secondary text: muted-foreground.
• Accent: primary, used once per slide unless showing a chart.
• Logo: official SVG/PNG asset.
• Body text: 18-24px depending on density.
• Slide headline: 44-64px for title slides, 32-44px for content slides.
• Footer/caption: 10-12px.

Presentation Do

• Use one main idea per slide.
• Write headlines as claims, not labels.
• Keep body copy short and operational.
• Use large numbers only when data is real or explicitly marked as placeholder.
• Use primary to focus attention, not decorate the page.
• Build charts with the chart token order.
• Use product UI previews as framed evidence, not wallpaper.

Presentation Don't

• Do not recreate web hover/focus states in slides.
• Do not use React/source/dependency details in a deck.
• Do not use HTML snippets as final slide content unless the workflow renders HTML to an image.
• Do not invent metrics.
• Do not add AI gradients, neon glows, emoji, or generic SaaS blobs.
• Do not make every slide a card grid.

Presentation Patterns

Use these as recipes. Adapt copy and scale to the deck.

Title Slide

Purpose: Open with a clear thesis and a restrained brand moment.

Objects:

• Full-slide background rectangle using background.
• Large headline text box using foreground.
• Short supporting text box using muted-foreground.
• Optional small LevLogo lockup or wordmark.
• Optional primary CTA or date/contact line.

Layout:

• Left-aligned or asymmetric.
• Keep the headline to 1-3 lines.
• Use 60/40 space distribution: content on one side, quiet negative space or subtle product visual on the other.

Multi-Line Thesis Slide

Purpose: Make one strategic point feel memorable.

Objects:

• Large text box with 2-4 short lines.
• Optional inline LevToken or product screenshot crop as visual punctuation.
• Small caption or source note.

Rules:

• Use display type.
• Avoid bullets.
• Use one accent highlight maximum.

Three-Part Explainer

Purpose: Explain three related ideas without dense bullets.

Objects:

• Slide title.
• Three content groups.
• Each group has a short label, one-sentence description, and optional icon.

Style:

• Labels: foreground, medium weight.
• Descriptions: muted-foreground.
• Group frames: none or subtle border.
• Accent: primary for one key item only.

Four-Item Overview

Purpose: Show a complete set of steps, options, or categories.

Objects:

• Title.
• 2x2 grid or vertical list of four items.
• Small numeric markers or mono labels.

Rules:

• Avoid equal-card sameness when possible. Make one item slightly larger if there is a priority.
• Keep each item to 1-2 lines.

Visual + Caption

Purpose: Let a product screenshot, chart, map, or diagram carry the slide.

Objects:

• Main visual frame.
• Caption below or beside the visual.
• Optional label or source.

Style:

• Visual frame: card fill, border stroke, subtle radius.
• Caption: muted-foreground, 14-18px.
• Do not over-annotate. One or two callouts maximum.

Header / Body Narrative

Purpose: Explain context with more prose than a normal slide.

Objects:

• Small eyebrow or subtitle.
• Main header.
• Body text block.
• Optional sidebar note or callout.

Rules:

• Body max width: 55-70 characters.
• Use paragraph rhythm, not dense bullets.
• Good for setup, methodology, or executive explanation.

Quote / Testimonial

Purpose: Add human proof or executive emphasis.

Objects:

• Large quote text.
• Attribution line.
• Optional logo or small headshot.

Style:

• Quote: foreground, 28-40px.
• Attribution: muted-foreground, 14-16px.
• Avoid oversized quotation marks unless they are extremely subtle.

Labeled Visual

Purpose: Explain parts of an image, product UI, or system diagram.

Objects:

• Main visual frame.
• 3-5 labels connected with thin lines.
• Optional legend.

Style:

• Lines: border role.
• Labels: card or background fill with border.
• Keep labels concise.

Numbered Process

Purpose: Show a sequence, workflow, or phased approach.

Objects:

• Title.
• 3-5 numbered steps.
• Optional timeline line or vertical stack.

Style:

• Numbers: IBM Plex Mono, primary or muted-foreground.
• Step title: foreground.
• Description: muted-foreground.

Rules:

• Avoid more than five steps on one slide.
• Use a continuation slide for detailed processes.

Technical / Code Slide

Purpose: Show implementation detail, API shape, or technical proof.

Objects:

• Title.
• Code block or structured pseudo-code.
• Optional notes column.

Style:

• Code: IBM Plex Mono.
• Code surface: card or secondary fill.
• Border: border role.
• Use syntax color sparingly; never rainbow.

Closing / Contact Slide

Purpose: End with a clear next step.

Objects:

• Short closing headline.
• Contact or URL line.
• LevLogo lockup.
• Optional primary CTA.

Style:

• Keep it quiet.
• Use generous whitespace.
• Do not cram legal, contact, and CTA content into one corner.

PDF / Print Guidance

• Use resolved theme values, not CSS variables, unless generating HTML first.
• Keep backgrounds print-safe; avoid large low-contrast gradients.
• Use 0.5-1px strokes for borders.
• Avoid tiny captions below 9pt.
• Ensure every chart remains legible in grayscale.
• Prefer document patterns: title, executive summary, key facts, detail sections, appendix.

Static HTML Guidance

• Load Airy token CSS first.
• Use semantic variables.
• Use component preview HTML/CSS as a reference library.
• If exporting to PDF/PPTX through a renderer, the browser's computed styles become the source of truth.
• Do not assume HTML remains editable after export.

Image / Social Guidance

• Use one statement, one visual gesture, one brand mark.
• Use resolved values.
• Use generous safe margins.
• Avoid dense UI unless showing a product proof.
• Prefer dark marketing for high-impact pieces and light marketing for editorial/announcement pieces.

App UI Guidance

• Use real Airy components.
• Use registry/ui primitives only as installed/protected components.
• Compose higher-level UI in blocks or app-specific wrappers.
• Use semantic tokens. Never hardcode raw colors.
• Prefer tables, cards, filters, sidebars, breadcrumbs, and command/menu patterns that reflect actual Lev product workflows.

Anti-Patterns

These patterns are forbidden in Airy output:

• Emojis as icons or visual decoration.
• Inter as primary font.
• Generic serifs.
• Pure black for Airy surfaces unless explicitly required by an external format.
• Purple/blue AI gradients.
• Neon glows or outer glows.
• Gradient text.
• Custom cursors.
• Overlapping elements.
• Generic 3-column equal feature rows.
• Centered marketing hero compositions by default.
• Fake metrics, fake uptime, fake user counts, fake benchmarks.
• "SYSTEM // 2026" or similar pseudo-technical label typography.
• Generic AI marketing words: "elevate", "seamless", "unleash", "next-gen", "cutting-edge", "revolutionary", "game-changer".
• Placeholder names like "John Doe", "Acme Inc.", "Nexus", or "Lorem Industries".
• Raw Tailwind colors or raw hex values in web code.
• Alpha modifiers on semantic tokens unless specifically approved.
• Glass-on-glass nesting.
• h-screen; use min-h-[100dvh].
• Animating layout properties.
• Mixing App and Marketing themes without an embedded-product reason.

Copy Voice

Airy copy is plainspoken, factual, and operational. Lev sells to commercial real estate professionals; the voice should be clear and useful, not playful.

• Sentence case for headlines, labels, and buttons.
• Verb-first buttons: "Create deal", "Save changes", "Delete", "Continue".
• No periods in headlines, buttons, or labels unless there are multiple sentences.
• Use Oxford commas.
• Avoid hype language.
• Use real metrics or marked placeholders.
• Explain errors and empty states plainly.

For full rules, see copy.md.

Agent Prompt Guide

Build A Presentation Title Slide

Create a 16:9 title slide using Airy marketing dark. Use the background role for the full-slide ground, foreground for a large left-aligned thesis headline, muted-foreground for one supporting sentence, and the LevLogo lockup as a small picture object in the lower corner. Keep one primary accent moment only.

Build A Product Evidence Slide

Create a slide with a large product UI screenshot or mockup framed as a card. Use card fill, border stroke, and subtle radius. Add one short headline above and one caption below. Do not add more than two callouts.

Build A Three-Part Explainer

Create a slide with a clear title and three content groups. Each group has a short label and one sentence. Use foreground for labels, muted-foreground for descriptions, and border only if grouping needs structure.

Build A Native PPTX Button

Create a primary Airy button as a rounded rectangle. Use primary fill, primary-foreground text, IBM Plex Sans 14-16px medium/semibold, 36-40px height, 10-16px horizontal padding, and 10px corner radius unless a pill CTA is specifically requested.

Build A Web App Settings Screen

Use Airy App light. Compose with real Airy components, semantic classes, and app layout patterns. Use card surfaces only where grouping is meaningful. Use labels above fields, helper text below, and one primary action.

Generation Checklist

Before finalizing an Airy output, verify:

• The target surface is clear.
• The target output format is clear: production code, native PPTX, HTML reference, print HTML, image spec, or design spec.
• The theme is declared.
• Semantic roles are used.
• Resolved values are used for non-web surfaces.
• design.md, copy.md, and visual-design.md guidance have been considered.
• Brand marks use official assets.
• Presentation outputs are editable native objects unless explicitly screenshot/image-based.
• HTML previews are treated as reference unless an HTML export pipeline is explicitly in use.
• No banned AI-design tells are present.

Visual Design Rules

This guide documents the visual system behind Airy.

Theme Architecture

Airy supports two themes with light and dark variants:

• App theme: :root and .dark
• Marketing theme: .theme-marketing and .theme-marketing.dark

All tokens currently use identical defaults so you can customize later without changing component code.

Color System

Use semantic tokens, not raw hex values:

• --background, --foreground
• --primary, --secondary, --accent
• --muted, --destructive, --border
• --card, --popover, --ring

Charts and sidebar tokens exist for dashboards and admin surfaces.

Typography

Use the tokenized scale in airy.css:

• --text-xs through --text-3xl
• --line-height-tight, --line-height-normal, --line-height-relaxed
• --font-weight-regular, --font-weight-medium, --font-weight-semibold, --font-weight-bold

Font families:

• --font-sans: "IBM Plex Sans", ui-sans-serif, system-ui, sans-serif
• --font-mono: "IBM Plex Mono", ui-monospace, monospace
• --font-handwriting: "Caveat", cursive

Font roles:

• Body and interface text: font-sans
• Code and tabular text: font-mono
• Accent/handwritten treatments: font-handwriting

Spacing

Use the spacing tokens:

• --space-0 through --space-24

Prefer layout utilities for spacing. Use tokens when defining new CSS rules.

Radius

Use --radius and derived tokens (--radius-md, --radius-lg, etc).

Surface Treatments

Glass

.surface-glass is a translucent, blurred surface treatment for floating panels, popovers, command palettes, and similar elevated UI. Inspired by Apple's "Liquid Glass" material.

<div className="surface-glass rounded-2xl p-6">…</div>

Behavior:

• Owns: background, backdrop-filter, border, box-shadow.
• Does NOT own: border-radius, padding, sizing, layout, typography.
• Lives in the airy-glass cascade layer (declared after utilities), so it auto-overrides Tailwind utilities like bg-popover, border, shadow-*. No bg-transparent border-0 shadow-none boilerplate needed.
• Falls back to a solid background in browsers without backdrop-filter.
• Supports both light and dark mode via the .dark parent selector.

Per-instance overrides via CSS variable hooks (preferred over ! overrides):

| Variable | Default (light) | Purpose | | -------------------- | ------------------------------------------- | ------------------------- | | --glass-tint | oklch(var(--primitive-neutral-50) / 0.82) | Background color | | --glass-blur | 32px | Backdrop blur radius | | --glass-saturation | 190% | Backdrop saturation boost |

<div className="surface-glass [--glass-tint:oklch(0.85_0.12_140/0.55)]">
  Brand-tinted glass surface
</div>

<div className="surface-glass [--glass-blur:8px]">
  Subtler frost (e.g. for nested glass surfaces)
</div>

For one-off property overrides outside the hook set, use Tailwind's ! prefix (e.g. !bg-red-500/20). Inline style is the right tool for dynamic values driven from JavaScript.

Composing onto a primitive that already sets a background — no need to neutralize it with bg-transparent:

<NavigationMenuViewport className="surface-glass" />
<DialogContent className="surface-glass rounded-2xl" />

When NOT to use:

• Inside another glass surface — glass-on-glass produces visual noise. Use a plain bg-card panel inside a glass dialog, or tune the inner surface to a much lighter blur ([--glass-blur:6px]).
• On large flat-color backgrounds — glass needs varied content behind it (images, gradients, busy UI) to read as glass.
• On dozens of elements simultaneously — backdrop-filter is GPU-expensive.

Brand

• Use the lev-logo registry component for all logo placements
• Three variants: icon, logo (wordmark), lockup (wordmark + icon)
• The logo uses currentColor — set text color on the parent to control it
• Never recreate the logo as raw SVG or an image tag

Iconography

Airy uses the Lucide icon set. Browse the full library at lucide.dev.

Sizing and alignment

• Icons are drawn on a 24x24 grid but can be scaled up or down as needed
• Icon size should be roughly 2px larger than the accompanying text size
• Maintain 16-24px clear padding from surrounding UI elements
• Align icons optically to the text's x-height for visual balance
• Single-line text: center-align the icon vertically
• Multiline text: align the icon to the top edge of the text
• Never use emojis as icon substitutes

If you need an icon not in the Lucide standard set, contact Product Design before introducing a new one.

Code implementation

In React, import from lucide-react:

import { Mail, Search, Settings } from "lucide-react"

Size pairings (icon should be ~2px larger than the text):

• text-xs with size-3.5
• text-sm with size-4
• text-base with size-5
• text-lg or text-xl with size-6

Use text-muted-foreground for secondary/decorative icons and text-foreground for primary action icons.

Example:

<Button><Mail className="size-4" /> Send email</Button>

When lucide-react cannot be imported (static HTML, emails, sandboxed environments): use inline SVGs from lucide.dev. Never use emojis or image tags as substitutes.

Reserved icons

These icons are reserved to ensure consistency across Lev products. They represent core actions and concepts that should not be replaced, restyled, or repurposed. Always reference the reserved set first and only introduce new icons when a concept is not already represented.

Status and feedback:

• Info — info
• CircleAlert — warning
• TriangleAlert — error
• CircleCheck — success

Universal system actions:

• CircleHelp — help
• Search — search
• Share2 — share
• Settings — settings
• MoreHorizontal — more
• RefreshCw — refresh

File manipulations:

• Save — save
• Trash2 — delete
• Upload — upload
• Download — download
• Copy — copy / duplicate

Editing:

• Pencil — edit
• Link — link
• Undo2 — undo
• Redo2 — redo

Dark Mode

• Maintain contrast ratios for all text and controls.
• Avoid hard-coded colors in components.
• Verify hover, focus, and disabled states in both themes.

Marketing Assets

Marketing materials — brochures, one-pagers, landing pages, pitch decks — use the marketing dark theme (.theme-marketing.dark). All colors must come from the semantic tokens defined in that theme context, not from primitives or hardcoded values.

The marketing dark theme provides a dark background with green accent palette. Use the same semantic token names as the app theme (--background, --foreground, --card, --primary, --border, etc.) — they resolve to the correct marketing values automatically.

When generating output that cannot reference CSS variables (PDFs, static HTML, emails, sandboxed artifacts), use the resolved theme values returned in Airy route or part payloads. Those values are generated from registry/airy-theme/*.css and preserve semantic role names. Never extract colors from Figma mockups or approximate values.

Resolved Theme Decision Rule

Use this rule before requesting resolved theme values:

1. Will CSS custom properties be available at render time?
2. If yes, use semantic tokens/classes directly (do not resolve).
3. If no or unknown, request route or part context that includes resolved values.

Common examples:

• Use resolved values: PDFs, emails, static exports, sandboxed outputs, native presentations, and image specs.
• Do not use resolved values: normal web app components with airy.css loaded, runtime light/dark switching, or token discovery tasks.

For non-web deliverables, pair theme resolution with Airy context:

• request context for the target surface and deliverable type
• search covered parts, brand assets, guidelines, and theme roles as needed
• fetch exact part or token payloads when precision matters
• use resolved theme token payloads when CSS variables are unavailable
• preserve semantic token role names in specs so implementation can trace every resolved color back to Airy

Anti-pattern: claiming exact Airy component fidelity for non-web output without using the relevant Airy source files, assets, and resolved theme tokens.