From 851783fdfb8451ea4103295a566fff5e22530ccf Mon Sep 17 00:00:00 2001 From: apsinghdev Date: Wed, 19 Nov 2025 13:17:30 +0530 Subject: [PATCH 1/4] chore: ui consistency --- BRAND_CONSISTENCY_REPORT.md | 478 ++++++++++++++++ apps/web/docs/DESIGN_SYSTEM.md | 526 ++++++++++++++++++ apps/web/src/app/globals.css | 9 +- apps/web/src/app/layout.tsx | 27 +- .../components/landing-sections/Brands.tsx | 14 +- .../src/components/landing-sections/Hero.tsx | 8 +- .../components/landing-sections/navbar.tsx | 2 +- apps/web/src/components/ui/ActiveTag.tsx | 4 +- apps/web/src/components/ui/custom-button.tsx | 10 +- apps/web/src/components/ui/header.tsx | 16 +- apps/web/src/lib/design-tokens.ts | 171 ++++++ apps/web/tailwind.config.ts | 79 ++- 12 files changed, 1294 insertions(+), 50 deletions(-) create mode 100644 BRAND_CONSISTENCY_REPORT.md create mode 100644 apps/web/docs/DESIGN_SYSTEM.md create mode 100644 apps/web/src/lib/design-tokens.ts diff --git a/BRAND_CONSISTENCY_REPORT.md b/BRAND_CONSISTENCY_REPORT.md new file mode 100644 index 00000000..02f84b01 --- /dev/null +++ b/BRAND_CONSISTENCY_REPORT.md @@ -0,0 +1,478 @@ +# Brand Consistency Analysis Report for Opensox + +## Executive Summary +After analyzing your codebase, I've identified several brand consistency issues across colors, typography, and design tokens. You have **130+ instances of hardcoded hex colors** across 35 files, inconsistent purple variants, and mixed font usage patterns. + +--- + +## 🎨 COLOR ISSUES + +### Critical Problems + +#### 1. **Purple Brand Color Inconsistency** +You have **MULTIPLE purple variants** scattered across the codebase: + +**In `tailwind.config.ts`:** +- `ox-purple: #9455f4` +- `ox-purple-2: #7A45C3` + +**Hardcoded in components:** +- `#9159E2` (Brands.tsx - gradient start) +- `#341e7b` (Brands.tsx - gradient end) +- `#321D76` (Brands.tsx - pseudo element) +- `#5728f4` (custom-button.tsx - gradient start) +- `#5100FF` (custom-button.tsx - gradient end) +- `#6348fc` (custom-button.tsx - border) +- `#2c04b1` (custom-button.tsx - box shadow) +- `#3F1FBC` (header.tsx - flickering grid) +- `purple-400`, `purple-600` (Tailwind utilities) + +**Impact:** Your brand's primary color (purple) is inconsistent across the application, creating a disjointed visual identity. + +#### 2. **Background Color Inconsistency** +Multiple black/dark backgrounds: +- `background: #101010` (tailwind config) +- `#0E0E10` (ox-black-1) +- `#15161A` (ox-black-2) +- `#141414` (ox-sidebar) +- `#1E1E1E` (ox-profile-card) +- `#1A1A1A` (ox-content) +- `#363636` (ox-header) +- `#111111` (card-stack.tsx) +- `#0d1117`, `#161b22`, `#30363d` (navbar.tsx - GitHub button styles) + +**Impact:** Inconsistent surface colors make the UI feel unpolished and reduce hierarchy clarity. + +#### 3. **Border Color Inconsistency** +- `border-primary: #252525` (tailwind config) +- `border-[#252525]` (used 20+ times across components) +- `#292929` (card-stack.tsx) +- `#30363d` (navbar.tsx) +- `border: hsl(var(--border))` (defined but underutilized) + +#### 4. **Success/Active Color** +- `ActiveTag.tsx` uses custom green: `bg-[#002d21]` and `text-[#00bd7c]` +- Not defined in design system at all + +#### 5. **Hardcoded Colors Instead of Design Tokens** +Found **130 instances** of hardcoded hex colors like: +```tsx +// Bad - scattered throughout components +className="bg-[#101010] border-[#252525]" +from-[#9159E2] to-[#341e7b] +``` + +Instead of using: +```tsx +// Good - using design tokens +className="bg-background border-border-primary" +from-ox-purple to-ox-purple-2 +``` + +--- + +## 📝 TYPOGRAPHY ISSUES + +### Font Configuration Problems + +#### 1. **Inconsistent Font Declarations** +**In `layout.tsx`:** +```tsx +const dmReg = localFont({ src: "./fonts/DMMono-Regular.ttf", variable: "--font-dm-mono-req" }) +const dmMed = localFont({ src: "./fonts/DMMono-Medium.ttf", variable: "--font-dm-mono-med" }) +// But also imports: +import { GeistSans } from "geist/font/sans"; +``` + +**In `tailwind.config.ts`:** +```ts +fontFamily: { + DMfont: ["var(--font-dm-mono-med)", "var(--font-dm-mono-req)"], + MonaSans: ["var(--font-mona-sans-med)", "var(--font-mona-sans-req)"] +} +``` + +**In `globals.css`:** +```css +body { + @apply bg-background text-foreground font-MonaSans; +} +``` + +**Problems:** +1. **Mona Sans is referenced** but NEVER loaded in `layout.tsx` +2. GeistSans is used in body but MonaSans is applied globally via CSS +3. Font variables for Mona Sans are defined but fonts aren't loaded +4. `font-mono` is used extensively (30+ times) but no clarity on which mono font + +#### 2. **Font Usage Patterns** +Components use different font approaches: +- `font-mono` (30+ instances) - unclear if this refers to DMfont or system default +- `font-sans` (5+ instances) - unclear which sans-serif +- `font-DMfont` - rarely used directly +- `font-MonaSans` - defined but fonts not loaded + +--- + +## 📊 IMPACT ANALYSIS + +### Brand Consistency Score: **3.5/10** 🔴 + +**Breakdown:** +- **Color Consistency:** 2/10 - Multiple purple variants, 130+ hardcoded colors +- **Typography Consistency:** 4/10 - Font loading issues, unclear hierarchy +- **Design Token Usage:** 3/10 - Tokens defined but underutilized +- **Maintainability:** 5/10 - Too many magic values make updates difficult + +--- + +## ✅ RECOMMENDATIONS + +### Priority 1: Consolidate Color System + +#### Step 1: Create a Unified Design Token File +Create `/apps/web/src/lib/design-tokens.ts`: + +```typescript +export const colors = { + // Brand Colors + brand: { + purple: { + DEFAULT: '#9455f4', // Primary brand purple + light: '#a675f5', // Lighter variant + dark: '#7A45C3', // Darker variant + gradient: { + from: '#9455f4', + to: '#7A45C3', + } + } + }, + + // Backgrounds + background: { + primary: '#101010', // Main background + secondary: '#141414', // Sidebar, cards + tertiary: '#1A1A1A', // Content areas + elevated: '#1E1E1E', // Elevated cards + }, + + // Borders + border: { + DEFAULT: '#252525', // Primary border + light: '#363636', // Lighter borders + focus: '#9455f4', // Focus states + }, + + // Status Colors + status: { + success: { + bg: '#002d21', + text: '#00bd7c', + border: '#00bd7c', + }, + // Add error, warning, info as needed + } +} as const; + +export const gradients = { + purple: 'linear-gradient(to bottom, #9455f4, #7A45C3)', + purpleText: 'linear-gradient(to bottom, #9455f4, #341e7b)', + background: 'radial-gradient(circle at center, #101010 30%, transparent 100%)', +} as const; +``` + +#### Step 2: Update `tailwind.config.ts` +```typescript +import { colors } from './src/lib/design-tokens'; + +const config: Config = { + theme: { + extend: { + colors: { + background: colors.background.primary, + foreground: "#ffffff", + + // Brand colors + brand: { + purple: { + DEFAULT: colors.brand.purple.DEFAULT, + light: colors.brand.purple.light, + dark: colors.brand.purple.dark, + } + }, + + // Surface colors + surface: { + primary: colors.background.primary, + secondary: colors.background.secondary, + tertiary: colors.background.tertiary, + elevated: colors.background.elevated, + }, + + // Border colors + border: { + DEFAULT: colors.border.DEFAULT, + light: colors.border.light, + focus: colors.border.focus, + }, + + // Status colors + success: colors.status.success, + + // Keep shadcn/ui tokens + card: { + DEFAULT: "hsl(var(--card))", + foreground: "hsl(var(--card-foreground))", + }, + // ... rest of shadcn tokens + }, + } + } +}; +``` + +#### Step 3: Replace Hardcoded Colors + +**Before:** +```tsx +
+ +``` + +**After:** +```tsx +
+ +``` + +### Priority 2: Fix Typography System + +#### Step 1: Fix Font Loading in `layout.tsx` + +```typescript +import localFont from "next/font/local"; +import { GeistSans } from "geist/font/sans"; + +// DM Mono for code/terminal elements +const dmMono = localFont({ + src: [ + { path: "./fonts/DMMono-Regular.ttf", weight: "400", style: "normal" }, + { path: "./fonts/DMMono-Medium.ttf", weight: "500", style: "normal" }, + ], + variable: "--font-dm-mono", + display: "swap", +}); + +// Use GeistSans as primary sans-serif (REMOVE Mona Sans references or add it) +// Option 1: Stick with Geist Sans +const geistSans = GeistSans; + +// Option 2: IF you have Mona Sans fonts, load them: +// const monaSans = localFont({ +// src: [ +// { path: "./fonts/MonaSans-Regular.woff2", weight: "400", style: "normal" }, +// { path: "./fonts/MonaSans-Medium.woff2", weight: "500", style: "normal" }, +// ], +// variable: "--font-mona-sans", +// display: "swap", +// }); + +export default function RootLayout({ children }: { children: React.ReactNode }) { + return ( + + + {children} + + + ); +} +``` + +#### Step 2: Update `tailwind.config.ts` + +```typescript +fontFamily: { + sans: ["var(--font-geist-sans)", "system-ui", "sans-serif"], + mono: ["var(--font-dm-mono)", "monospace"], +} +``` + +#### Step 3: Update `globals.css` + +```css +@layer base { + body { + @apply bg-background text-foreground font-sans; + } + + code, pre, kbd { + @apply font-mono; + } +} +``` + +### Priority 3: Component Migration Strategy + +#### Create a migration checklist: + +**Phase 1: Core Components (Week 1)** +- [ ] `custom-button.tsx` - Use `brand-purple` tokens +- [ ] `header.tsx` - Use `surface-*` and `border` tokens +- [ ] `navbar.tsx` - Consolidate GitHub button colors +- [ ] `ActiveTag.tsx` - Use `success` tokens + +**Phase 2: Landing Page (Week 2)** +- [ ] `Hero.tsx` - Replace hardcoded colors +- [ ] `Brands.tsx` - Use brand gradient tokens +- [ ] `Bento.tsx` - Use surface tokens +- [ ] `CTA.tsx` - Use brand tokens + +**Phase 3: Dashboard (Week 3)** +- [ ] `ProjectsContainer.tsx` - Keep language colors (they're semantic) +- [ ] `Sidebar.tsx` - Use surface tokens +- [ ] All card components - Use surface tokens + +### Priority 4: Create Theme Documentation + +Create `/apps/web/docs/DESIGN_SYSTEM.md`: + +```markdown +# Opensox Design System + +## Colors + +### Brand Colors +- Primary: `brand-purple` (#9455f4) - CTAs, links, highlights +- Gradient: `from-brand-purple to-brand-purple-dark` + +### Surfaces +- `surface-primary` (#101010) - Main background +- `surface-secondary` (#141414) - Sidebars, navigation +- `surface-tertiary` (#1A1A1A) - Content containers +- `surface-elevated` (#1E1E1E) - Cards, modals + +### Borders +- `border` (#252525) - Default borders +- `border-light` (#363636) - Lighter borders for nested elements +- `border-focus` (brand-purple) - Focus states + +## Typography + +### Font Families +- **Sans-serif (Primary):** Geist Sans - Body text, headings +- **Monospace:** DM Mono - Code, terminal output, tech content + +### Usage +```tsx +// Body text +

Regular text

+ +// Code/Terminal +Terminal output +``` + +## Usage Guidelines + +### DO ✅ +- Use design tokens: `bg-surface-primary border-border` +- Use brand purple for CTAs and highlights +- Use semantic color names + +### DON'T ❌ +- Hardcode hex colors: `bg-[#101010]` +- Use random purple variants +- Mix different surface colors arbitrarily +``` + +--- + +## 🛠️ IMPLEMENTATION CHECKLIST + +### Immediate Actions (This Week) +- [ ] Create `design-tokens.ts` with all color constants +- [ ] Update `tailwind.config.ts` with new color system +- [ ] Fix font loading in `layout.tsx` (add Mona Sans OR remove references) +- [ ] Create `DESIGN_SYSTEM.md` documentation + +### Short-term (Next 2 Weeks) +- [ ] Migrate core components (buttons, headers, navbars) +- [ ] Replace all `#9159E2`, `#341e7b` purple variants with tokens +- [ ] Replace all `#252525` border colors with `border` token +- [ ] Update all background colors to use `surface-*` tokens + +### Medium-term (Next Month) +- [ ] Audit and migrate all 35 files with hardcoded colors +- [ ] Create Storybook/component library documentation +- [ ] Add ESLint rule to prevent hardcoded colors +- [ ] Set up design token tests + +--- + +## 📈 EXPECTED IMPROVEMENTS + +After implementing these recommendations: + +1. **Consistency:** Brand will look cohesive across all pages +2. **Maintainability:** Update colors in one place, change everywhere +3. **Performance:** Reduced CSS bundle size (no duplicate color definitions) +4. **Developer Experience:** Clear guidelines, easier onboarding +5. **Scalability:** Easy to add dark/light mode, themes, or rebrand + +**New Brand Consistency Score Target: 9/10** 🟢 + +--- + +## 🔍 ADDITIONAL NOTES + +### Language Colors Exception +The `languageColors` object in `ProjectsContainer.tsx` is FINE as-is: +```tsx +const languageColors: Record = { + javascript: "bg-yellow-500/15 text-yellow-500", + typescript: "bg-blue-500/15 text-blue-500", + // ... +}; +``` +These are semantic colors representing programming languages (industry standard). + +### Gradients +Consider creating reusable gradient classes: +```css +.gradient-purple { + @apply bg-gradient-to-b from-brand-purple to-brand-purple-dark; +} + +.gradient-text-purple { + @apply bg-gradient-to-b from-brand-purple to-brand-purple-dark bg-clip-text text-transparent; +} +``` + +--- + +## 🎯 PRIORITY SUMMARY + +**🔴 CRITICAL:** +1. Consolidate purple brand colors (you have 8+ variants!) +2. Fix font loading (Mona Sans is referenced but not loaded) + +**🟡 HIGH:** +3. Create `design-tokens.ts` file +4. Update `tailwind.config.ts` with new tokens +5. Document design system + +**🟢 MEDIUM:** +6. Migrate components phase by phase +7. Add ESLint rules for hardcoded colors + +--- + +## Questions? + +If you need help implementing any of these recommendations, let me know and I can: +- Create the design tokens file +- Update specific components +- Set up ESLint rules +- Create migration scripts + +Would you like me to start implementing these fixes? + diff --git a/apps/web/docs/DESIGN_SYSTEM.md b/apps/web/docs/DESIGN_SYSTEM.md new file mode 100644 index 00000000..5d5e2c0b --- /dev/null +++ b/apps/web/docs/DESIGN_SYSTEM.md @@ -0,0 +1,526 @@ +# Opensox Design System + +## Overview + +This document outlines the design system for Opensox, including colors, typography, spacing, and component guidelines. All design tokens are centralized in `/src/lib/design-tokens.ts` to ensure consistency across the application. + +--- + +## 🎨 Colors + +### Brand Colors + +Our primary brand color is purple, used for CTAs, highlights, and key brand elements. + +#### Purple + +```tsx +// Usage in Tailwind +className="bg-brand-purple" +className="text-brand-purple" +className="border-brand-purple" + +// Available variants +brand-purple // #9455f4 - Primary brand purple +brand-purple-light // #a675f5 - Lighter variant for hover states +brand-purple-dark // #7A45C3 - Darker variant for depth +``` + +**When to use:** +- Primary CTAs and action buttons +- Links and interactive elements +- Brand highlights and accents +- Focus states + +**Examples:** +```tsx +// Button + +``` + +### Cards + +```tsx +
+

Card Title

+

Card content goes here.

+
+``` + +**Card Variants:** +- `surface-elevated` - Standard cards +- `surface-card` - Alternative card background +- Add `hover:bg-surface-hover` for interactive cards + +### Tags/Badges + +```tsx +// Success tag + + +// Custom badge + + Pro + +``` + +### Forms + +```tsx + +``` + +--- + +## 🚫 What NOT to Do + +### ❌ DON'T: Use Hardcoded Colors + +```tsx +// BAD +
+ +// GOOD +
+``` + +### ❌ DON'T: Mix Different Purple Variants + +```tsx +// BAD +
+
+
+ +// GOOD - Use consistent brand colors +
+``` + +### ❌ DON'T: Use Inconsistent Fonts + +```tsx +// BAD +

+ +// GOOD +

+``` + +### ❌ DON'T: Create Custom Spacing + +```tsx +// BAD +

+ +// GOOD - Use Tailwind spacing scale +
// 0.75rem (12px) +``` + +--- + +## ✅ Best Practices + +### 1. Always Use Design Tokens + +```tsx +// Import when needed +import { colors } from '@/lib/design-tokens'; + +// Use in inline styles (when necessary) +style={{ color: colors.brand.purple.DEFAULT }} +``` + +### 2. Maintain Color Hierarchy + +```tsx +// Layer surfaces properly +
{/* Base */} + +
+``` + +### 3. Use Semantic Naming + +```tsx +// GOOD - Describes purpose +
+ +// BAD - Describes appearance +
+``` + +### 4. Leverage Tailwind Utilities + +```tsx +// Combine utilities for complex styles +