From fe9cd301ec7c35f458f68e4f9958649c4d3531c9 Mon Sep 17 00:00:00 2001 From: James Russo Date: Tue, 7 Apr 2026 20:24:35 -0700 Subject: [PATCH] docs: apply HyperFrames design system to Mintlify theme (#225) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs: apply HyperFrames design system to Mintlify theme Update docs config and add custom CSS to match the HyperFrames brand: - Switch theme from mint to maple, replace cyan palette with warm neutrals - Add Inter (body/headings) and IBM Plex Mono (code) fonts - Add custom.css with full light/dark mode CSS variables - Default to light mode appearance - Replace box-shadow hover effects with border-color (flat aesthetic) - Add DESIGN.md to repo root as design system reference - Fix docs CI to also trigger on DOCS_GUIDELINES.md pushes to main Co-Authored-By: Claude Opus 4.6 (1M context) * docs: replace HeyGen logo with HyperFrames text wordmark Replace 41KB HeyGen SVG logos with lightweight (~400B) text-based SVGs rendering "HyperFrames" in Inter semibold with tight tracking, matching the wordmark style on hyperframes.heygen.com. Co-Authored-By: Claude Opus 4.6 (1M context) * docs: use ABC Solar Display font for logo wordmark Match the exact font rendering from hyperframes.heygen.com: - Load ABC Solar Display Bold from HeyGen static assets CDN - SVGs use 15.2px/600w/-0.15 letter-spacing (matches computed styles) - Dark mode fill matches rgb(240,240,240) from the website - Add @font-face in custom.css for site-wide availability - Fix lefthook: remove css from oxfmt glob (oxfmt doesn't support CSS) Co-Authored-By: Claude Opus 4.6 (1M context) * docs: convert logo SVGs to outlined paths SVG elements don't render custom fonts when loaded as (browser security restriction). Convert the ABC Solar Display glyphs to SVG paths extracted from the font outlines — renders identically everywhere with zero font dependency. Remove @font-face for the display font from custom.css since it's no longer needed. Co-Authored-By: Claude Opus 4.6 (1M context) * docs: constrain logo height to match website sizing Co-Authored-By: Claude Opus 4.6 (1M context) * Revert "docs: constrain logo height to match website sizing" This reverts commit 89e9cb598e00874d87e501128b2dd689192329bd. * docs: switch body font from Inter to TT Norms Pro Use TT Norms Pro (from HeyGen static assets CDN) to match hyperframes.heygen.com. Loads weights 400-700 via @font-face with Inter as fallback. Co-Authored-By: Claude Opus 4.6 (1M context) --------- Co-authored-by: Claude Opus 4.6 (1M context) --- .github/workflows/docs.yml | 1 + DESIGN.md | 301 ++++++++++++++++++++++++++++++++++ docs/custom.css | 141 ++++++++++++++++ docs/docs.json | 25 ++- docs/logo/dark.svg | 322 ++----------------------------------- docs/logo/light.svg | 318 ++---------------------------------- docs/template-gallery.css | 2 +- lefthook.yml | 2 +- 8 files changed, 491 insertions(+), 621 deletions(-) create mode 100644 DESIGN.md create mode 100644 docs/custom.css diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index ad887ec8d..13bf7f8d7 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 000000000..6c13bbd28 --- /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 000000000..4daf5c987 --- /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 adf90ff28..2df12e686 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 5d9cf5446..2e9ba8c58 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 dc7fa020d..061fdbd55 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 82727b110..f2ab2f646 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 9807101e0..5df24cbd0 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}"