---
version: "1.0"
name: HandbookHub
description: HandbookHub design tokens and UI guidelines. Light theme only.
colors:
  background: "oklch(1 0 0)"
  foreground: "oklch(0.145 0 0)"
  primary: "oklch(0.205 0 0)"
  primary-foreground: "oklch(0.985 0 0)"
  secondary: "oklch(0.97 0 0)"
  secondary-foreground: "oklch(0.205 0 0)"
  muted: "oklch(0.97 0 0)"
  muted-foreground: "oklch(0.556 0 0)"
  accent: "oklch(0.97 0 0)"
  destructive: "oklch(0.577 0.245 27.325)"
  border: "oklch(0.922 0 0)"
  brand-accent: "#0891b2"
typography:
  font-sans: IBM Plex Sans
  font-mono: ui-monospace, SFMono-Regular, Consolas, Liberation Mono, Menlo, monospace
  heading-hero: 48px / 600 / tight tracking
  heading-page: 32px / 600
  body-large: 20px / 400
  body: 16px / 400
  body-small: 14px / 400
  label: 14px / 500
spacing:
  base: 4px
  scale: [4, 8, 12, 16, 24, 32, 40, 64]
rounded:
  sm: 6px
  md: 8px
  lg: 10px
  xl: 14px
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.primary-foreground}"
    height: 36px
  button-large:
    height: 48px
    typography: 18px / 500
  button-outline:
    backgroundColor: "{colors.background}"
    borderColor: "{colors.border}"
---

# HandbookHub Design

## Overview

HandbookHub is an AI employee handbook builder. The UI is clean and professional: neutral surfaces, IBM Plex Sans typography, and a cyan accent on the word "Hub" in the logo. Prioritize clarity and trust — HR and ops teams use this daily.

The product uses [shadcn/ui](https://ui.shadcn.com) components on Tailwind CSS v4. Semantic color tokens in `frontend/src/styles/globals.css` are the source of truth.

## Brand

- **Name:** Handbook**Hub** — "Hub" uses brand accent `#0891b2` (Tailwind `cyan-600`).
- **Logo:** Owl mark at `/images/hh_owl_logo.png`.
- **Tone:** Direct, helpful, no hype. Speak to busy people managing handbooks, not developers.

## Colors

Use semantic tokens, not raw grays:

| Token | Role |
| ----- | ---- |
| `background` | Page and card surfaces |
| `foreground` | Primary text |
| `primary` | Primary buttons, key actions |
| `secondary` | Secondary buttons, subtle fills |
| `muted` / `muted-foreground` | Helper text, placeholders |
| `destructive` | Delete, irreversible actions |
| `border` | Dividers, input borders |
| `brand-accent` | Logo accent, sparing highlights |

HandbookHub is light theme only — do not design for dark mode.

## Typography

- **UI and marketing:** IBM Plex Sans (`font-sans`).
- **Code and data:** System monospace stack (`font-mono`).
- **Headings:** Semibold (`font-semibold`), tight tracking on large headlines.
- **Body:** Regular weight; use `text-muted-foreground` for secondary copy.
- **Prose:** Tailwind Typography (`prose`) for handbook page content in the editor.

## Layout

- Spacing follows a 4px base: 8px inside groups, 16–24px between groups, 32–64px between sections.
- Marketing content is centered in a max-width container (~1200px) with responsive side padding.
- Cards use subtle borders and light shadows (`shadow-xs`), not heavy elevation.

## Components

Built on shadcn/ui `Button` with these variants:

- **default** — solid primary fill; main CTA on a view (`bg-primary text-primary-foreground`).
- **secondary** — low-emphasis filled button.
- **outline** — bordered, transparent fill; secondary actions.
- **ghost** — text-only with hover tint.
- **destructive** — red fill for delete/confirm-destructive flows.
- **link** — underlined text link.

Default button height is 36px (`h-9`). Large CTAs use `size="xl"` (48px). Focus states use a visible ring — never remove outlines without a replacement.

## Voice & Content

- Use sentence case for body copy; title case for nav labels and primary buttons.
- Name actions clearly: `Start Free Trial`, `Create Handbook`, not `Submit` or `OK`.
- Errors state what happened and what to do next.
- Empty states suggest the first action: `No pages yet. Add your first page to get started.`
- In-progress states use an ellipsis: `Generating…`, `Saving…`.
- Avoid "successfully", "please", and marketing superlatives on product UI.

## Related Agent Resources

- [Pricing](https://handbookhub.com/pricing.md)
- [Changelog](https://handbookhub.com/changelog.md)