diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index ad887ec8d4..13bf7f8d7b 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -9,6 +9,7 @@ on: branches: [main] paths: - "docs/**" + - "DOCS_GUIDELINES.md" concurrency: group: docs-${{ github.ref }} diff --git a/DESIGN.md b/DESIGN.md new file mode 100644 index 0000000000..6c13bbd281 --- /dev/null +++ b/DESIGN.md @@ -0,0 +1,301 @@ +# HyperFrames Design System & Style Guide + +Use this guide to configure Mintlify docs or any other platform to match the HyperFrames brand. + +--- + +## Color Palette + +### Light Mode + +| Token | Hex | Usage | +| ------------------ | --------- | ------------------------------------------------ | +| `--bg` | `#f6f5f1` | Page background | +| `--surface` | `#ffffff` | Cards, panels, elevated surfaces | +| `--surface2` | `#eeedea` | Secondary surfaces, timeline, subtle backgrounds | +| `--border` | `#e0dfdb` | Default borders | +| `--border-light` | `#d0cfcb` | Hover/active borders | +| `--text` | `#1a1a1a` | Primary body text | +| `--text-secondary` | `#6b6b6b` | Secondary/muted text | +| `--text-tertiary` | `#999999` | Tertiary/placeholder text | +| `--heading` | `#0a0a0a` | Headings, nav brand, buttons | +| `--code-bg` | `#ffffff` | Code block backgrounds | + +#### Accent Colors (Light) + +| Token | Hex | Usage | +| ------------------------ | ----------------------- | ---------------------------- | +| `--accent-green` | `#1a7a0a` | Success, recommended badges | +| `--accent-green-light` | `rgba(26,122,10,0.07)` | Green badge backgrounds | +| `--accent-green-border` | `rgba(26,122,10,0.25)` | Green badge borders | +| `--accent-blue` | `#2563eb` | Links, info badges | +| `--accent-blue-light` | `rgba(37,99,235,0.06)` | Blue badge backgrounds | +| `--accent-blue-border` | `rgba(37,99,235,0.2)` | Blue badge borders | +| `--accent-purple` | `#7c3aed` | Highlights, special elements | +| `--accent-purple-light` | `rgba(124,58,237,0.06)` | Purple badge backgrounds | +| `--accent-purple-border` | `rgba(124,58,237,0.2)` | Purple badge borders | + +#### Syntax Highlighting (Light) + +| Token | Hex | Usage | +| ---------------------- | --------- | ------------------------------- | +| `--syntax-keyword` | `#9333ea` | Keywords (const, let, function) | +| `--syntax-function` | `#0891b2` | Function names | +| `--syntax-string` | `#16a34a` | Strings, values | +| `--syntax-number` | `#d97706` | Numbers | +| `--syntax-property` | `#6366f1` | Object properties | +| `--syntax-punctuation` | `#aaaaaa` | Brackets, semicolons | +| `--syntax-tag` | `#b45309` | HTML/JSX tags | +| `--syntax-attribute` | `#555555` | HTML attributes | +| `--syntax-comment` | `#bbbbbb` | Comments | + +--- + +### Dark Mode + +| Token | Hex | Usage | +| ------------------ | --------- | -------------------------------- | +| `--bg` | `#0a0a0a` | Page background | +| `--surface` | `#141414` | Cards, panels, elevated surfaces | +| `--surface2` | `#1a1a1a` | Secondary surfaces | +| `--border` | `#2a2a2a` | Default borders | +| `--border-light` | `#3a3a3a` | Hover/active borders | +| `--text` | `#e5e5e5` | Primary body text | +| `--text-secondary` | `#a0a0a0` | Secondary/muted text | +| `--text-tertiary` | `#666666` | Tertiary/placeholder text | +| `--heading` | `#f5f5f5` | Headings | +| `--code-bg` | `#141414` | Code block backgrounds | + +#### Accent Colors (Dark) + +| Token | Hex | Usage | +| ------------------------ | ----------------------- | ---------------------------- | +| `--accent-green` | `#22c55e` | Success, recommended badges | +| `--accent-green-light` | `rgba(34,197,94,0.1)` | Green badge backgrounds | +| `--accent-green-border` | `rgba(34,197,94,0.3)` | Green badge borders | +| `--accent-blue` | `#3b82f6` | Links, info badges | +| `--accent-blue-light` | `rgba(59,130,246,0.1)` | Blue badge backgrounds | +| `--accent-blue-border` | `rgba(59,130,246,0.3)` | Blue badge borders | +| `--accent-purple` | `#a78bfa` | Highlights, special elements | +| `--accent-purple-light` | `rgba(167,139,250,0.1)` | Purple badge backgrounds | +| `--accent-purple-border` | `rgba(167,139,250,0.3)` | Purple badge borders | + +#### Syntax Highlighting (Dark) + +| Token | Hex | Usage | +| ---------------------- | --------- | -------------------- | +| `--syntax-keyword` | `#c084fc` | Keywords | +| `--syntax-function` | `#22d3ee` | Function names | +| `--syntax-string` | `#4ade80` | Strings, values | +| `--syntax-number` | `#fbbf24` | Numbers | +| `--syntax-property` | `#818cf8` | Object properties | +| `--syntax-punctuation` | `#666666` | Brackets, semicolons | +| `--syntax-tag` | `#fb923c` | HTML/JSX tags | +| `--syntax-attribute` | `#a0a0a0` | HTML attributes | +| `--syntax-comment` | `#555555` | Comments | + +--- + +## Typography + +### Font Families + +| Token | Stack | Usage | +| ---------------- | ----------------------------------------------------------------------------- | ---------------------- | +| `--font-display` | `'ABC Solar Display', 'Inter', -apple-system, BlinkMacSystemFont, sans-serif` | Headlines, nav brand | +| `--font-body` | `'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif` | Body text, UI elements | +| `--font-mono` | `'IBM Plex Mono', 'SF Mono', 'Fira Code', monospace` | Code, terminals | + +### Google Fonts Import + +```css +@import url("https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500;600&family=Inter:wght@300;400;500;600;700&display=swap"); +``` + +### Type Scale + +| Element | Size | Weight | Letter Spacing | Line Height | +| ---------- | ------------------------------ | ------ | -------------- | ----------- | +| H1 | `clamp(2.6rem, 6vw, 4.5rem)` | 400 | `-0.02em` | 1.0 | +| H2 | `clamp(1.6rem, 3.5vw, 2.2rem)` | 400 | `-0.02em` | 1.2 | +| H3 | `1rem` | 600 | `-0.01em` | 1.4 | +| Body | `1rem` | 400 | `normal` | 1.6 | +| Body Small | `0.95rem` | 400 | `normal` | 1.7 | +| Caption | `0.82rem` | 400 | `normal` | 1.6 | +| Code | `0.75rem` | 400 | `normal` | 1.9 | +| Mono Small | `0.65rem` | 500 | `normal` | 1.6 | + +--- + +## Spacing + +| Token | Value | Usage | +| ----- | --------------- | ------------------- | +| `xs` | `0.25rem` (4px) | Tight gaps | +| `sm` | `0.5rem` (8px) | Small gaps | +| `md` | `1rem` (16px) | Default gaps | +| `lg` | `1.5rem` (24px) | Section gaps | +| `xl` | `2rem` (32px) | Large spacing | +| `2xl` | `4rem` (64px) | Section padding | +| `3xl` | `8rem` (128px) | Hero/footer padding | + +--- + +## Border Radius + +| Token | Value | Usage | +| ----- | --------------- | ---------------------- | +| `sm` | `4px` | Badges, small elements | +| `md` | `6px` | Buttons, inputs | +| `lg` | `8px` | Cards, panels | +| `xl` | `10px` - `12px` | Large cards | + +--- + +## Shadows & Effects + +- **No heavy shadows** — HyperFrames uses a flat, minimal aesthetic +- **Borders over shadows** — Use `1px solid var(--border)` instead of box-shadows +- **Backdrop blur** for nav: `backdrop-filter: blur(12px)` +- **Selection color**: `rgba(128,128,128,0.2)` (light) / `rgba(255,255,255,0.15)` (dark) + +--- + +## Mintlify Configuration + +The docs site at `docs/docs.json` implements this design system. Key settings: + +```json +{ + "theme": "maple", + "colors": { + "primary": "#0a0a0a", + "light": "#f6f5f1", + "dark": "#0a0a0a" + }, + "background": { + "color": { + "light": "#f6f5f1", + "dark": "#0a0a0a" + } + }, + "fonts": { + "family": "Inter", + "heading": { "family": "Inter" } + }, + "appearance": { + "default": "light" + } +} +``` + +Additional overrides (code font, CSS variables, heading tracking) live in `docs/custom.css`. + +--- + +## Component Patterns + +### Cards + +```css +.card { + background: var(--surface); + border: 1px solid var(--border); + border-radius: 12px; + overflow: hidden; + transition: border-color 0.2s; +} + +.card:hover { + border-color: var(--border-light); +} +``` + +### Buttons + +```css +.btn-primary { + font-size: 0.8rem; + padding: 0.4rem 1rem; + border-radius: 6px; + background: var(--heading); + color: #fff; + font-weight: 500; +} + +[data-theme="dark"] .btn-primary { + background: var(--heading); + color: #0a0a0a; +} +``` + +### Code Blocks / Terminals + +```css +.terminal { + background: var(--code-bg); + border: 1px solid var(--border); + border-radius: 8px; + overflow: hidden; +} + +.terminal-bar { + display: flex; + gap: 5px; + padding: 10px 14px; + border-bottom: 1px solid var(--border); +} + +.terminal-dot { + width: 8px; + height: 8px; + border-radius: 50%; + background: var(--border-light); +} + +.terminal-body { + padding: 0.85rem 1.1rem; + font-family: var(--font-mono); + font-size: 0.8rem; + line-height: 1.9; +} +``` + +### Badges + +```css +.badge-green { + color: var(--accent-green); + background: var(--accent-green-light); + border: 1px solid var(--accent-green-border); +} + +.badge-blue { + color: var(--accent-blue); + background: var(--accent-blue-light); + border: 1px solid var(--accent-blue-border); +} + +.badge-purple { + color: var(--accent-purple); + background: var(--accent-purple-light); + border: 1px solid var(--accent-purple-border); +} +``` + +--- + +## Animation Guidelines + +- **Duration**: 0.15s - 0.2s for micro-interactions, 0.5s for reveals +- **Easing**: `ease` or `ease-out` for most transitions +- **Hover states**: Use `opacity: 0.85` or border color changes +- **Scroll reveals**: `translateY(20px)` with opacity fade + +--- + +## Brand Assets + +- **Logo**: "HyperFrames" in `--font-display` at 600 weight +- **Primary color**: `#0a0a0a` (near-black) +- **Warm neutral palette**: Beige/cream tones, not pure grays diff --git a/docs/custom.css b/docs/custom.css new file mode 100644 index 0000000000..4daf5c9877 --- /dev/null +++ b/docs/custom.css @@ -0,0 +1,141 @@ +/* HyperFrames Design System — Mintlify Theme Overrides */ + +@import url('https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500;600&display=swap'); + +/* ── TT Norms Pro (matches hyperframes.heygen.com) ── */ + +@font-face { + font-family: 'TT Norms Pro'; + src: url('https://www-static-assets.heygen.com/fonts/tt-norms/TT_Norms_Pro_Normal.woff2') format('woff2'); + font-weight: 400; + font-style: normal; + font-display: swap; +} + +@font-face { + font-family: 'TT Norms Pro'; + src: url('https://www-static-assets.heygen.com/fonts/tt-norms/TT_Norms_Pro_Medium.woff2') format('woff2'); + font-weight: 500; + font-style: normal; + font-display: swap; +} + +@font-face { + font-family: 'TT Norms Pro'; + src: url('https://www-static-assets.heygen.com/fonts/tt-norms/TT_Norms_Pro_DemiBold.woff2') format('woff2'); + font-weight: 600; + font-style: normal; + font-display: swap; +} + +@font-face { + font-family: 'TT Norms Pro'; + src: url('https://www-static-assets.heygen.com/fonts/tt-norms/TT_Norms_Pro_Bold.woff2') format('woff2'); + font-weight: 700; + font-style: normal; + font-display: swap; +} + +/* ── Light mode (default) ── */ + +:root { + --background: #f6f5f1; + --background-light: #ffffff; + --surface2: #eeedea; + --border-color: #e0dfdb; + --border-color-light: #d0cfcb; + --text: #1a1a1a; + --text-secondary: #6b6b6b; + --text-tertiary: #999999; + --heading: #0a0a0a; + --code-bg: #ffffff; + + --accent-green: #1a7a0a; + --accent-green-light: rgba(26, 122, 10, 0.07); + --accent-green-border: rgba(26, 122, 10, 0.25); + --accent-blue: #2563eb; + --accent-blue-light: rgba(37, 99, 235, 0.06); + --accent-blue-border: rgba(37, 99, 235, 0.2); + --accent-purple: #7c3aed; + --accent-purple-light: rgba(124, 58, 237, 0.06); + --accent-purple-border: rgba(124, 58, 237, 0.2); + + --selection-bg: rgba(128, 128, 128, 0.2); +} + +/* ── Dark mode ── */ + +.dark, +[data-theme="dark"] { + --background: #0a0a0a; + --background-light: #141414; + --surface2: #1a1a1a; + --border-color: #2a2a2a; + --border-color-light: #3a3a3a; + --text: #e5e5e5; + --text-secondary: #a0a0a0; + --text-tertiary: #666666; + --heading: #f5f5f5; + --code-bg: #141414; + + --accent-green: #22c55e; + --accent-green-light: rgba(34, 197, 94, 0.1); + --accent-green-border: rgba(34, 197, 94, 0.3); + --accent-blue: #3b82f6; + --accent-blue-light: rgba(59, 130, 246, 0.1); + --accent-blue-border: rgba(59, 130, 246, 0.3); + --accent-purple: #a78bfa; + --accent-purple-light: rgba(167, 139, 250, 0.1); + --accent-purple-border: rgba(167, 139, 250, 0.3); + + --selection-bg: rgba(255, 255, 255, 0.15); +} + +/* ── Typography ── */ + +body { + font-family: 'TT Norms Pro', 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; +} + +h1, h2, h3, h4, h5, h6 { + font-family: 'TT Norms Pro', 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; +} + +h1, h2 { + letter-spacing: -0.02em; +} + +h3 { + letter-spacing: -0.01em; +} + +/* Code font — IBM Plex Mono (loaded via Google Fonts above) */ +code, pre, pre code, kbd, +[class*="code"], +[class*="Code"] { + font-family: 'IBM Plex Mono', 'SF Mono', 'Fira Code', monospace; +} + +/* ── Code blocks ── */ + +pre { + background: var(--code-bg) !important; + border: 1px solid var(--border-color) !important; + border-radius: 8px !important; +} + +/* ── Selection ── */ + +::selection { + background: var(--selection-bg); +} + +/* ── Links ── */ + +a:not([class]) { + color: var(--accent-blue); +} + +a:not([class]):hover { + opacity: 0.85; +} diff --git a/docs/docs.json b/docs/docs.json index adf90ff280..2df12e6863 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -1,11 +1,26 @@ { "$schema": "https://mintlify.com/docs.json", - "name": "Hyperframes", - "theme": "mint", + "name": "HyperFrames", + "theme": "maple", "colors": { - "primary": "#00C4FF", - "light": "#00C4FF", - "dark": "#00A8E1" + "primary": "#0a0a0a", + "light": "#f6f5f1", + "dark": "#0a0a0a" + }, + "background": { + "color": { + "light": "#f6f5f1", + "dark": "#0a0a0a" + } + }, + "fonts": { + "family": "Inter", + "heading": { + "family": "Inter" + } + }, + "appearance": { + "default": "light" }, "logo": { "light": "/logo/light.svg", diff --git a/docs/logo/dark.svg b/docs/logo/dark.svg index 5d9cf54465..2e9ba8c581 100644 --- a/docs/logo/dark.svg +++ b/docs/logo/dark.svg @@ -1,311 +1,15 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/logo/light.svg b/docs/logo/light.svg index dc7fa020d1..061fdbd55b 100644 --- a/docs/logo/light.svg +++ b/docs/logo/light.svg @@ -1,307 +1,15 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/template-gallery.css b/docs/template-gallery.css index 82727b1104..f2ab2f6468 100644 --- a/docs/template-gallery.css +++ b/docs/template-gallery.css @@ -11,7 +11,7 @@ .tpl-card:hover { transform: translateY(-2px); - box-shadow: 0 8px 24px rgba(0,0,0,0.25); + border-color: var(--border-color-light, #d0cfcb); } .tpl-label { diff --git a/lefthook.yml b/lefthook.yml index 9807101e05..5df24cbd0d 100644 --- a/lefthook.yml +++ b/lefthook.yml @@ -5,7 +5,7 @@ pre-commit: glob: "*.{js,jsx,ts,tsx}" run: bunx oxlint {staged_files} format: - glob: "*.{js,jsx,ts,tsx,json,css,md,yaml,yml}" + glob: "*.{js,jsx,ts,tsx,json,md,yaml,yml}" run: bunx oxfmt --check {staged_files} typecheck: glob: "*.{ts,tsx}"