omnidesign 1.0.0

package/tokens/typography/FONT_GUIDE.md

@@ -0,0 +1,381 @@
+# Font Usage Guide
+
+Complete guide for using the frontend-arsenal font collection.
+
+## Installation Methods
+
+### Method 1: Google Fonts CDN (Easiest)
+
+```html
+<!-- In your HTML head -->
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+
+<!-- Inter + JetBrains Mono -->
+<link href="https://fonts.googleapis.com/css2?family=Inter:wght@100..900&family=JetBrains+Mono:wght@100..800&display=swap" rel="stylesheet">
+
+<!-- Geist (Vercel's font) -->
+<link href="https://fonts.googleapis.com/css2?family=Geist:wght@100..900&family=Geist+Mono:wght@100..900&display=swap" rel="stylesheet">
+```
+
+### Method 2: Fontsource NPM (Best for bundlers)
+
+```bash
+# Install fonts
+npm install @fontsource/inter @fontsource/jetbrains-mono @fontsource/space-grotesk
+
+# Or all at once
+npm install @fontsource/inter @fontsource/plus-jakarta-sans @fontsource/geist-sans @fontsource/geist-mono @fontsource/merriweather @fontsource/jetbrains-mono @fontsource/space-grotesk
+```
+
+```typescript
+// In your entry file (main.tsx, layout.tsx, etc.)
+import '@fontsource/inter/400.css';
+import '@fontsource/inter/500.css';
+import '@fontsource/inter/600.css';
+import '@fontsource/inter/700.css';
+
+import '@fontsource/jetbrains-mono/400.css';
+import '@fontsource/jetbrains-mono/500.css';
+
+import '@fontsource/space-grotesk/500.css';
+import '@fontsource/space-grotesk/700.css';
+```
+
+### Method 3: Nerd Fonts (For terminal/coding)
+
+```bash
+# macOS with Homebrew
+brew tap homebrew/cask-fonts
+brew install --cask font-jetbrains-mono-nerd-font
+brew install --cask font-fira-code-nerd-font
+brew install --cask font-hack-nerd-font
+
+# Windows (Chocolatey)
+choco install nerd-fonts-hack
+choco install nerd-fonts-firacode
+
+# Arch Linux
+yay -S nerd-fonts-jetbrains-mono nerd-fonts-fira-code
+```
+
+## Font Pairings by Use Case
+
+### 1. Enterprise Dashboard
+```css
+:root {
+  --font-sans: 'Inter', system-ui, -apple-system, sans-serif;
+  --font-mono: 'JetBrains Mono', 'SF Mono', monospace;
+  --font-display: 'Space Grotesk', sans-serif;
+}
+
+body { font-family: var(--font-sans); }
+h1, h2 { font-family: var(--font-display); }
+code { font-family: var(--font-mono); }
+```
+
+### 2. Developer Tools / IDE
+```css
+:root {
+  --font-ui: 'Plus Jakarta Sans', system-ui, sans-serif;
+  --font-code: 'JetBrainsMono Nerd Font', 'JetBrains Mono', monospace;
+  --font-terminal: 'FiraCode Nerd Font', 'Fira Code', monospace;
+}
+
+/* UI Elements */
+.sidebar, .toolbar { font-family: var(--font-ui); }
+
+/* Code Editor */
+.editor { 
+  font-family: var(--font-code);
+  font-feature-settings: 'liga' 1, 'calt' 1; /* Enable ligatures */
+}
+
+/* Terminal */
+.terminal { font-family: var(--font-terminal); }
+```
+
+### 3. Creative Portfolio
+```css
+:root {
+  --font-body: 'Geist Sans', system-ui, sans-serif;
+  --font-headings: 'Clash Display', sans-serif;
+  --font-accent: 'Syne', sans-serif;
+  --font-mono: 'Geist Mono', monospace;
+}
+
+.hero-title { 
+  font-family: var(--font-headings);
+  font-weight: 700;
+  letter-spacing: -0.02em;
+}
+
+.nav-links { font-family: var(--font-accent); }
+```
+
+### 4. Editorial / Blog
+```css
+:root {
+  --font-serif: 'Merriweather', Georgia, serif;
+  --font-sans: 'Inter', system-ui, sans-serif;
+  --font-mono: 'IBM Plex Mono', monospace;
+  --font-display: 'DM Serif Display', Georgia, serif;
+}
+
+article p { font-family: var(--font-serif); }
+article h1 { font-family: var(--font-display); }
+figcaption { font-family: var(--font-sans); }
+```
+
+### 5. SaaS Marketing Site
+```css
+:root {
+  --font-primary: 'Poppins', system-ui, sans-serif;
+  --font-secondary: 'Manrope', sans-serif;
+  --font-mono: 'Geist Mono', monospace;
+}
+
+/* Headlines use Poppins for personality */
+h1, h2, .cta-button { font-family: var(--font-primary); }
+
+/* Body uses Manrope for readability */
+body { font-family: var(--font-secondary); }
+```
+
+## Nerd Fonts: Icons in Code
+
+Nerd Fonts combine regular fonts with thousands of icons from:
+- Devicons (development tools)
+- Font Awesome (general icons)
+- Material Design (Google icons)
+- Weather Icons
+- Octicons (GitHub)
+- Powerline symbols
+
+### Common Glyphs
+
+```html
+<!-- File type icons -->
+<span>󰉋</span> <!-- folder -->
+<span>󰈙</span> <!-- file text -->
+<span>󰌠</span> <!-- git -->
+<span>󰘧</span> <!-- code -->
+
+<!-- Status icons -->
+<span>󰄬</span> <!-- check -->
+<span>󰅙</span> <!-- error -->
+<span>󰌵</span> <!-- warning -->
+<span>󰋽</span> <!-- info -->
+
+<!-- Tool icons -->
+<span>󰨞</span> <!-- docker -->
+<span>󱃾</span> <!-- kubernetes -->
+<span>󰛓</span> <!-- react -->
+<span>󰛦</span> <!-- typescript -->
+```
+
+### Using with CSS
+
+```css
+.nerd-icon {
+  font-family: 'JetBrainsMono Nerd Font', monospace;
+  font-size: 1.2em;
+}
+
+/* File tree styling */
+.file-tree .folder::before {
+  content: '󰉋';
+  font-family: 'JetBrainsMono Nerd Font';
+  margin-right: 0.5em;
+}
+
+.file-tree .file-js::before {
+  content: '󰌠';
+  font-family: 'JetBrainsMono Nerd Font';
+  color: #f7df1e; /* JS yellow */
+}
+```
+
+## Performance Optimization
+
+### 1. Preconnect to Font CDNs
+```html
+<head>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <!-- Font links -->
+</head>
+```
+
+### 2. Use Variable Fonts (when available)
+```html
+<!-- Inter as variable font (one file, all weights) -->
+<link href="https://fonts.googleapis.com/css2?family=Inter:wght@100..900&display=swap" rel="stylesheet">
+```
+
+### 3. Font Display Strategy
+```css
+@font-face {
+  font-family: 'CustomFont';
+  src: url('font.woff2') format('woff2');
+  font-display: swap; /* Show fallback until loaded */
+}
+```
+
+### 4. Preload Critical Fonts
+```html
+<link rel="preload" href="/fonts/GeistSans.woff2" as="font" type="font/woff2" crossorigin>
+```
+
+### 5. Subset Fonts (Advanced)
+```bash
+# Using glyphhanger to subset fonts
+npx glyphhanger --subset=*.woff2 --formats=woff2 --css
+```
+
+## Framework Integration
+
+### React / Next.js
+
+```tsx
+// layout.tsx
+import { Inter, JetBrains_Mono } from 'next/font/google';
+
+const inter = Inter({ 
+  subsets: ['latin'],
+  variable: '--font-sans',
+});
+
+const jetbrainsMono = JetBrains_Mono({ 
+  subsets: ['latin'],
+  variable: '--font-mono',
+});
+
+export default function RootLayout({ children }) {
+  return (
+    <html className={`${inter.variable} ${jetbrainsMono.variable}`}>
+      <body className="font-sans">{children}</body>
+    </html>
+  );
+}
+```
+
+```css
+/* globals.css */
+@layer base {
+  body {
+    font-family: var(--font-sans), system-ui, sans-serif;
+  }
+  
+  code, pre {
+    font-family: var(--font-mono), monospace;
+  }
+}
+```
+
+### Tailwind CSS
+
+```javascript
+// tailwind.config.js
+module.exports = {
+  theme: {
+    extend: {
+      fontFamily: {
+        sans: ['var(--font-sans)', 'system-ui', 'sans-serif'],
+        mono: ['var(--font-mono)', 'monospace'],
+        display: ['var(--font-display)', 'sans-serif'],
+      },
+    },
+  },
+};
+```
+
+```html
+<!-- Usage -->
+<p class="font-sans text-base">Body text</p>
+<code class="font-mono text-sm">Code snippet</code>
+<h1 class="font-display text-4xl">Headline</h1>
+```
+
+## Accessibility
+
+### Minimum Requirements
+- Body text: minimum 16px (1rem)
+- Line height: 1.5 minimum for body
+- Contrast: 4.5:1 for normal text, 3:1 for large text
+
+### Dyslexia Considerations
+```css
+@media (prefers-reduced-data: no-preference) {
+  /* Offer OpenDyslexic as an option */
+  body.dyslexia-mode {
+    font-family: 'OpenDyslexic', sans-serif;
+    line-height: 1.8;
+    word-spacing: 0.16em;
+  }
+}
+```
+
+### Motion Preferences
+```css
+@media (prefers-reduced-motion: reduce) {
+  /* Disable font transitions */
+  * {
+    transition: none !important;
+  }
+}
+```
+
+## Troubleshooting
+
+### FOUT/FOIT Prevention
+```css
+/* Flash of Unstyled Text strategy */
+@font-face {
+  font-family: 'Inter';
+  src: url('inter.woff2') format('woff2');
+  font-display: swap; /* Recommended */
+  /* or font-display: optional; for faster but may not load */
+}
+```
+
+### Font Weight Mismatch
+```css
+/* If 500 looks too bold, use numeric values */
+.medium-text {
+  font-weight: 450; /* Some variable fonts support this */
+}
+```
+
+### Nerd Font Glyphs Not Showing
+```css
+/* Ensure fallback fonts have the glyphs */
+.nerd-font {
+  font-family: 'JetBrainsMono Nerd Font', 'JetBrains Mono', monospace;
+  /* The second fallback won't have icons but maintains monospace */
+}
+```
+
+## Complete Token Reference
+
+All fonts are available as design tokens in `font-collection.json`:
+
+```typescript
+import { tokens } from '@frontend-arsenal/tokens';
+
+// Font families
+const sansFont = tokens.typography.families.sans.inter.$value;
+const monoFont = tokens.typography.families.mono['jetbrains-mono'].$value;
+const nerdFont = tokens.typography.families.nerd['nerd-mono'].$value;
+
+// Font sizes
+const baseSize = tokens.typography.sizes.base.$value; // "1rem"
+const heroSize = tokens.typography.sizes['7xl'].$value; // "4.5rem"
+
+// Font weights
+const normal = tokens.typography.weights.normal.$value; // 400
+const bold = tokens.typography.weights.bold.$value; // 700
+
+// Line heights
+const bodyLeading = tokens.typography.lineHeights.relaxed.$value; // 1.625
+```

package/tokens/typography/README.md

@@ -0,0 +1,37 @@
+# Typography
+
+Type scale definitions (font families, sizes, weights, line heights). These establish the typographic hierarchy for the system.
+
+## 📦 Font Collection
+
+Complete typography system with 40+ font families including Nerd Fonts.
+
+See [font-collection.json](./font-collection.json) for all available fonts.
+
+### Font Categories
+- **Sans-Serif (7 families)** - Geist Sans, Inter, Satoshi, Manrope, Outfit, Poppins, Plus Jakarta Sans
+- **Serif (5 families)** - Merriweather, DM Serif Display, Lora, Source Serif 4, Literata
+- **Monospace (6 families)** - Geist Mono, JetBrains Mono, Fira Code, Cascadia Code, SF Mono, IBM Plex Mono
+- **Nerd Fonts (5 patched)** - JetBrainsMono Nerd Font, FiraCode Nerd Font, Hack Nerd Font, CaskaydiaCove Nerd Font, Symbols Nerd Font
+- **Display (5 families)** - Clash Display, Space Grotesk, Bungee, Archivo Black, Syne
+
+### Quick Setup
+
+```html
+<!-- Google Fonts CDN -->
+<link href="https://fonts.googleapis.com/css2?family=Inter:wght@100..900&family=JetBrains+Mono:wght@100..800&family=Space+Grotesk:wght@300..700&display=swap" rel="stylesheet">
+```
+
+```bash
+# Or via npm (Fontsource)
+npm install @fontsource/inter @fontsource/jetbrains-mono @fontsource/space-grotesk
+```
+
+### Recommended Pairings
+
+**Professional:** Inter + JetBrains Mono + Space Grotesk
+**Modern:** Geist Sans + Geist Mono + Clash Display  
+**Editorial:** Merriweather + Inter + IBM Plex Mono
+**Developer:** Plus Jakarta Sans + JetBrainsMono Nerd Font
+
+Full documentation in [FONT_GUIDE.md](./FONT_GUIDE.md) (create with complete usage examples).

package/tokens/typography/font-collection.json

@@ -0,0 +1,221 @@
+{
+  "families": {
+    "sans": {
+      "geist": {
+        "$type": "fontFamily",
+        "$value": "'Geist Sans', system-ui, sans-serif",
+        "$description": "Vercel's Geist Sans - modern geometric sans-serif, clean and technical"
+      },
+      "inter": {
+        "$type": "fontFamily",
+        "$value": "'Inter', system-ui, sans-serif",
+        "$description": "Inter - highly legible, great for UI and data"
+      },
+      "satoshi": {
+        "$type": "fontFamily",
+        "$value": "'Satoshi', 'Inter', sans-serif",
+        "$description": "Satoshi - contemporary geometric sans, modern alternative"
+      },
+      "manrope": {
+        "$type": "fontFamily",
+        "$value": "'Manrope', sans-serif",
+        "$description": "Manrope - versatile geometric with personality"
+      },
+      "outfit": {
+        "$type": "fontFamily",
+        "$value": "'Outfit', sans-serif",
+        "$description": "Outfit - geometric with slight quirk, great for headlines"
+      },
+      "poppins": {
+        "$type": "fontFamily",
+        "$value": "'Poppins', sans-serif",
+        "$description": "Poppins - geometric, excellent for modern web apps"
+      },
+      "plus-jakarta-sans": {
+        "$type": "fontFamily",
+        "$value": "'Plus Jakarta Sans', sans-serif",
+        "$description": "Plus Jakarta Sans - humanist geometric, warm yet modern"
+      }
+    },
+    "serif": {
+      "merriweather": {
+        "$type": "fontFamily",
+        "$value": "'Merriweather', Georgia, serif",
+        "$description": "Merriweather - readable serif, great for long-form text"
+      },
+      "dm-serif-display": {
+        "$type": "fontFamily",
+        "$value": "'DM Serif Display', Georgia, serif",
+        "$description": "DM Serif Display - elegant display serif for headings"
+      },
+      "lora": {
+        "$type": "fontFamily",
+        "$value": "'Lora', Georgia, serif",
+        "$description": "Lora - modern calligraphic serif for body text"
+      },
+      "source-serif": {
+        "$type": "fontFamily",
+        "$value": "'Source Serif 4', Georgia, serif",
+        "$description": "Source Serif 4 - optimized for screen reading"
+      },
+      "literata": {
+        "$type": "fontFamily",
+        "$value": "'Literata', Georgia, serif",
+        "$description": "Literata - distinctive serif, great for editorial"
+      }
+    },
+    "mono": {
+      "geist-mono": {
+        "$type": "fontFamily",
+        "$value": "'Geist Mono', 'SF Mono', Monaco, monospace",
+        "$description": "Vercel's Geist Mono - clean technical monospace"
+      },
+      "jetbrains-mono": {
+        "$type": "fontFamily",
+        "$value": "'JetBrains Mono', 'Fira Code', monospace",
+        "$description": "JetBrains Mono - developer-focused with ligatures"
+      },
+      "fira-code": {
+        "$type": "fontFamily",
+        "$value": "'Fira Code', 'Fira Mono', monospace",
+        "$description": "Fira Code - popular coding font with ligatures"
+      },
+      "cascadia-code": {
+        "$type": "fontFamily",
+        "$value": "'Cascadia Code', 'Consolas', monospace",
+        "$description": "Cascadia Code - Microsoft's modern coding font"
+      },
+      "sf-mono": {
+        "$type": "fontFamily",
+        "$value": "'SF Mono', 'Monaco', 'Menlo', monospace",
+        "$description": "SF Mono - Apple's system monospace font"
+      },
+      "ibm-plex-mono": {
+        "$type": "fontFamily",
+        "$value": "'IBM Plex Mono', 'Courier New', monospace",
+        "$description": "IBM Plex Mono - classic technical monospace"
+      }
+    },
+    "nerd": {
+      "nerd-symbols": {
+        "$type": "fontFamily",
+        "$value": "'Symbols Nerd Font', monospace",
+        "$description": "Nerd Font symbols - thousands of icons and glyphs"
+      },
+      "nerd-mono": {
+        "$type": "fontFamily",
+        "$value": "'JetBrainsMono Nerd Font', 'JetBrains Mono', monospace",
+        "$description": "JetBrains Mono with Nerd Font glyphs"
+      },
+      "nerd-fira": {
+        "$type": "fontFamily",
+        "$value": "'FiraCode Nerd Font', 'Fira Code', monospace",
+        "$description": "Fira Code with Nerd Font glyphs"
+      },
+      "nerd-hack": {
+        "$type": "fontFamily",
+        "$value": "'Hack Nerd Font', 'Hack', monospace",
+        "$description": "Hack font with Nerd Font glyphs"
+      },
+      "nerd-cascadia": {
+        "$type": "fontFamily",
+        "$value": "'CaskaydiaCove Nerd Font', 'Cascadia Code', monospace",
+        "$description": "Cascadia Code with Nerd Font glyphs (CaskaydiaCove)"
+      }
+    },
+    "display": {
+      "clash-display": {
+        "$type": "fontFamily",
+        "$value": "'Clash Display', sans-serif",
+        "$description": "Clash Display - bold geometric display font"
+      },
+      "space-grotesk": {
+        "$type": "fontFamily",
+        "$value": "'Space Grotesk', sans-serif",
+        "$description": "Space Grotesk - quirky geometric with personality"
+      },
+      "bungee": {
+        "$type": "fontFamily",
+        "$value": "'Bungee', sans-serif",
+        "$description": "Bungee - bold, attention-grabbing display font"
+      },
+      "archivo-black": {
+        "$type": "fontFamily",
+        "$value": "'Archivo Black', sans-serif",
+        "$description": "Archivo Black - heavy sans for headlines"
+      },
+      "syne": {
+        "$type": "fontFamily",
+        "$value": "'Syne', sans-serif",
+        "$description": "Syne - experimental sans, great for creative sites"
+      }
+    }
+  },
+  "sizes": {
+    "2xs": {
+      "$type": "fontSize",
+      "$value": "0.625rem",
+      "$description": "10px - smallest text, timestamps"
+    },
+    "xs": { "$type": "fontSize", "$value": "0.75rem", "$description": "12px - captions, badges" },
+    "sm": {
+      "$type": "fontSize",
+      "$value": "0.875rem",
+      "$description": "14px - small body, buttons"
+    },
+    "base": { "$type": "fontSize", "$value": "1rem", "$description": "16px - default body text" },
+    "lg": { "$type": "fontSize", "$value": "1.125rem", "$description": "18px - lead paragraphs" },
+    "xl": { "$type": "fontSize", "$value": "1.25rem", "$description": "20px - small headings" },
+    "2xl": { "$type": "fontSize", "$value": "1.5rem", "$description": "24px - H4" },
+    "3xl": { "$type": "fontSize", "$value": "1.875rem", "$description": "30px - H3" },
+    "4xl": { "$type": "fontSize", "$value": "2.25rem", "$description": "36px - H2" },
+    "5xl": { "$type": "fontSize", "$value": "3rem", "$description": "48px - H1" },
+    "6xl": { "$type": "fontSize", "$value": "3.75rem", "$description": "60px - display headings" },
+    "7xl": { "$type": "fontSize", "$value": "4.5rem", "$description": "72px - hero headings" },
+    "8xl": { "$type": "fontSize", "$value": "6rem", "$description": "96px - mega headings" },
+    "9xl": { "$type": "fontSize", "$value": "8rem", "$description": "128px - extreme display" }
+  },
+  "weights": {
+    "thin": { "$type": "fontWeight", "$value": 100, "$description": "Ultra light - display only" },
+    "extralight": { "$type": "fontWeight", "$value": 200, "$description": "Extra light" },
+    "light": { "$type": "fontWeight", "$value": 300, "$description": "Light weight" },
+    "normal": { "$type": "fontWeight", "$value": 400, "$description": "Normal/regular weight" },
+    "medium": {
+      "$type": "fontWeight",
+      "$value": 500,
+      "$description": "Medium weight - UI emphasis"
+    },
+    "semibold": { "$type": "fontWeight", "$value": 600, "$description": "Semi-bold - headings" },
+    "bold": { "$type": "fontWeight", "$value": 700, "$description": "Bold - strong emphasis" },
+    "extrabold": { "$type": "fontWeight", "$value": 800, "$description": "Extra bold - display" },
+    "black": { "$type": "fontWeight", "$value": 900, "$description": "Black - maximum weight" }
+  },
+  "lineHeights": {
+    "none": { "$type": "lineHeight", "$value": 1, "$description": "No leading - headings" },
+    "tight": { "$type": "lineHeight", "$value": 1.25, "$description": "Tight - display text" },
+    "snug": { "$type": "lineHeight", "$value": 1.375, "$description": "Snug - small text" },
+    "normal": { "$type": "lineHeight", "$value": 1.5, "$description": "Normal - body text" },
+    "relaxed": {
+      "$type": "lineHeight",
+      "$value": 1.625,
+      "$description": "Relaxed - comfortable reading"
+    },
+    "loose": { "$type": "lineHeight", "$value": 2, "$description": "Loose - editorial" }
+  },
+  "letterSpacing": {
+    "tighter": {
+      "$type": "letterSpacing",
+      "$value": "-0.05em",
+      "$description": "Extra tight - large headings"
+    },
+    "tight": { "$type": "letterSpacing", "$value": "-0.025em", "$description": "Tight - headings" },
+    "normal": { "$type": "letterSpacing", "$value": "0", "$description": "No tracking" },
+    "wide": { "$type": "letterSpacing", "$value": "0.025em", "$description": "Slight tracking" },
+    "wider": { "$type": "letterSpacing", "$value": "0.05em", "$description": "Medium tracking" },
+    "widest": {
+      "$type": "letterSpacing",
+      "$value": "0.1em",
+      "$description": "Wide tracking - labels"
+    }
+  }
+}