From c9a9479598b3328077d71e876377c7f4c9607eac Mon Sep 17 00:00:00 2001 From: Usman Baig Date: Fri, 6 Feb 2026 12:44:13 +0100 Subject: [PATCH] TIER 3 - POLISH --- app/sites/[id]/realtime/page.tsx | 2 +- app/sites/[id]/settings/page.tsx | 10 +- components/dashboard/ContentStats.tsx | 4 +- components/dashboard/Locations.tsx | 4 +- components/dashboard/TechSpecs.tsx | 4 +- components/settings/OrganizationSettings.tsx | 10 +- docs/DESIGN_SYSTEM.md | 1042 ++++++++++++++++++ 7 files changed, 1070 insertions(+), 6 deletions(-) create mode 100644 docs/DESIGN_SYSTEM.md diff --git a/app/sites/[id]/realtime/page.tsx b/app/sites/[id]/realtime/page.tsx index 2cab9ac..f3be638 100644 --- a/app/sites/[id]/realtime/page.tsx +++ b/app/sites/[id]/realtime/page.tsx @@ -108,7 +108,7 @@ export default function RealtimePage() { - + {visitors.length} active now diff --git a/app/sites/[id]/settings/page.tsx b/app/sites/[id]/settings/page.tsx index e8b9c39..8ea491f 100644 --- a/app/sites/[id]/settings/page.tsx +++ b/app/sites/[id]/settings/page.tsx @@ -314,9 +314,11 @@ export default function SiteSettingsPage() {
{/* Sidebar Navigation */} -
-
+
{(['top_pages', 'entry_pages', 'exit_pages'] as Tab[]).map((tab) => ( )}
-
+
{(['map', 'countries', 'regions', 'cities'] as Tab[]).map((tab) => ( )}
-
+
{(['browsers', 'os', 'devices', 'screens'] as Tab[]).map((tab) => ( +// Orange background, white text, shadow on hover +``` + +**Secondary (Neutral Action):** +```tsx + +// White background, border, neutral text +``` + +**Danger (Destructive Action):** +```tsx + +// Red background, white text (for critical actions) +``` + +--- + +### Empty States + +**Pattern:** +```tsx +
+
+ +
+

+ No data yet +

+

+ Data will appear here once visitors arrive +

+
+``` + +**Usage:** Dashboard widgets with no data, empty site lists, etc. + +--- + +### Loading States + +**Full Page Loading:** +```tsx + +``` + +**Inline Loading:** +```tsx + +``` + +**Skeleton Loading:** +```tsx +
+``` + +--- + +### Success/Error States + +**Success Toast:** +```tsx +toast.success('Site created successfully') +// Green toast with checkmark +``` + +**Error Toast:** +```tsx +toast.error('Failed to load data') +// Red toast with X icon +``` + +**Error Display:** +```tsx +
+ {error} +
+``` + +--- + +## 🎬 Animations + +### Framer Motion Patterns + +#### Page Entrance +```tsx + + {content} + +``` + +#### Stagger Animation +```tsx +{items.map((item, i) => ( + + {item} + +))} +``` + +#### Hover Scale +```tsx + + {content} + +``` + +#### List Item Entry/Exit +```tsx + + {items.map(item => ( + + {item} + + ))} + +``` + +--- + +### CSS Transitions + +**Duration Standards:** +- **Fast (200ms):** Input focus, button clicks, immediate feedback +- **Medium (300ms):** Hover effects, color changes, icon transforms +- **Slow (500ms):** Page entrances, large movements + +**Easing:** +- Default: `ease-out` (feels snappy) +- Alternative: `ease-in-out` (smooth both ways) + +```tsx +// Standard hover +className="transition-colors duration-200 hover:text-brand-orange" + +// Card hover +className="transition-all duration-300 hover:-translate-y-1 hover:shadow-xl" +``` + +--- + +## 📱 Responsive Breakpoints + +Using Tailwind defaults: + +| Breakpoint | Size | Usage | +|------------|------|-------| +| `sm:` | 640px | Small tablets, large phones | +| `md:` | 768px | Tablets, small laptops | +| `lg:` | 1024px | Laptops, desktops | +| `xl:` | 1280px | Large desktops | + +### Common Patterns + +**Grid Layouts:** +```tsx +// 1 col mobile, 2 col tablet, 3 col desktop +className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6" +``` + +**Typography:** +```tsx +// Smaller on mobile, larger on desktop +className="text-4xl md:text-5xl" +``` + +**Padding:** +```tsx +// Less padding on mobile +className="px-4 sm:px-6" +``` + +--- + +## 🔘 Buttons + +### Variant Usage + +**Primary (Orange):** +- Main CTAs ("Get Started", "Create Site", "Save Changes") +- Positive actions +- One per screen section max + +**Secondary (Neutral):** +- Cancel, Back, alternative actions +- Can have multiple per section + +**Ghost (Minimal):** +- Tertiary actions, "View All" links +- Inline actions that shouldn't be prominent + +**Danger (Red):** +- Delete, Reset Data, irreversible actions +- Always confirm before action + +### Size Variants + +```tsx +// Default + + +// Large (CTAs) + + +// Small (compact UI) + +``` + +--- + +## 📦 Cards + +### Standard Card + +```tsx +
+ {content} +
+``` + +### Glass Card (Premium Feel) + +```tsx +
+ {content} +
+``` + +**When to use Glass:** Marketing pages, feature showcases, hero sections + +### Hover Effects + +```tsx +// Subtle lift +className="hover:-translate-y-1 hover:shadow-md transition-all" + +// Scale +className="hover:scale-105 transition-transform" +``` + +--- + +## 🏷️ Badges + +### Primary Badge +```tsx + + + Privacy-First Analytics + +``` + +### Status Badges + +**Active/Live:** +```tsx +
+ + + + + Active +
+``` + +--- + +## 🎨 Special Effects + +### Background Glow (Atmosphere) + +```tsx +
+
+
+
+``` + +### Grid Pattern Background + +```tsx +
+``` + +### SVG Underline (Accent) + +```tsx + + + +``` + +--- + +## ♿ Accessibility + +### Focus Indicators + +**ALL interactive elements** must have visible focus states. See "Focus States" section above. + +### Semantic HTML + +- Use proper heading hierarchy (H1 → H2 → H3, no skipping) +- Use ` +
+ + {/* Content */} +
+ {hasData ? ( + + ) : ( + + )} +
+
+``` + +### Tab Toggles (Inside Widgets) + +```tsx +
+ {tabs.map(tab => ( + + ))} +
+``` + +--- + +## 📋 Forms + +### Input Styling + +```tsx + +// Uses @ciphera-net/ui Input component +// Automatically includes focus states, dark mode +``` + +### Label Pattern + +```tsx + +``` + +### Help Text + +```tsx +

+ Additional information about this field. +

+``` + +### Error Display + +```tsx +{error && ( +
+ {error} +
+)} +``` + +--- + +## 🎭 Code Blocks (Integration Pages) + +### VS Code-Style Syntax Highlighting + +```tsx +
+ {/* Header bar */} +
+
+
+
+
+
+ filename.tsx +
+ + {/* Code content */} +
+ + {/* Syntax-highlighted code */} + +
+
+``` + +**Colors for syntax:** +- Blue `#61AFEF`: Keywords, tags +- Orange `#D19A66`: Strings +- Purple `#C678DD`: Functions +- Green `#98C379`: Comments +- White `#ABB2BF`: Text + +--- + +## 🌍 Internationalization (Future) + +**Currently:** English only +**When implementing i18n:** +- Use `next-intl` or similar +- Extract all strings to translation files +- Maintain "Swiss infrastructure" messaging +- Support: EN, DE, FR, IT (Swiss languages) + +--- + +## 📐 Layout Patterns + +### Page Container + +```tsx +// App pages +
+ {content} +
+ +// Marketing pages +
+ {content} +
+``` + +### Two-Column Settings Layout + +```tsx +
+ {/* Sidebar */} + + + {/* Content */} +
+ {content} +
+
+``` + +--- + +## 🔌 Integration with @ciphera-net/ui + +### Current Usage + +```tsx +import { + Button, + Input, + Select, + Modal, + LoadingOverlay, + DatePicker, + Captcha, + // Icons + CheckCircleIcon, + SettingsIcon, + // etc. +} from '@ciphera-net/ui' +``` + +**Version:** `^0.0.45` + +### Preset + +Pulse uses the Ciphera UI Tailwind preset: +```ts +// tailwind.config.ts +presets: [ + require('@ciphera-net/ui/dist/tailwind-preset').default, +] +``` + +**Provides:** +- Brand colors (brand-orange) +- Background gradients (bg-ciphera-gradient) +- Neutral scale extension + +--- + +## 🎯 Design Principles + +### 1. Privacy-First Visual Language +- Clean, minimal design +- No tracking pixels, no external fonts from CDNs +- Swiss aesthetic (precision, trust, neutrality) + +### 2. Accessibility First +- WCAG 2.1 Level AA compliance +- Keyboard navigation throughout +- Clear focus indicators +- Readable text contrast + +### 3. Performance +- Lightweight animations (opacity, translate only) +- Optimized images +- Code splitting by route +- Fast transitions (200-500ms max) + +### 4. Brand Consistency +- Orange used sparingly (accents only) +- Neutral-heavy palette +- Glass effects for premium feel +- Consistent with other Ciphera products + +--- + +## 🛠️ Component Library + +### Available from @ciphera-net/ui + +**Buttons:** Primary, Secondary, Danger variants +**Forms:** Input, Select, Checkbox, DatePicker +**Feedback:** Toast (Sonner), LoadingOverlay +**Security:** Captcha component +**Icons:** Full icon set from Lucide +**Layout:** Modal component + +### Custom to Pulse + +**Dashboard:** Chart, TopPages, TopReferrers, Locations, TechSpecs, Campaigns, Goals, Performance +**Settings:** OrganizationSettings, ProfileSettings +**Sites:** SiteList, VerificationModal +**Tools:** UtmBuilder + +--- + +## 📏 Checklist for New Components + +When creating new components, ensure: + +- [ ] Uses standard color tokens (no hardcoded hex values) +- [ ] Follows typography scale (no custom text sizes) +- [ ] Has dark mode support (`dark:` variants) +- [ ] Includes focus states on interactive elements +- [ ] Uses spacing system (no arbitrary padding values) +- [ ] Follows border radius standards +- [ ] Has empty state if displays lists +- [ ] Has loading state if async +- [ ] Has error state if can fail +- [ ] Responsive on mobile (<768px) +- [ ] Accessible (semantic HTML, ARIA where needed) +- [ ] Consistent with existing components + +--- + +## 🔍 Testing Checklist + +Before deploying changes: + +### Visual +- [ ] Light mode looks correct +- [ ] Dark mode looks correct +- [ ] Focus rings visible on all interactive elements +- [ ] Typography hierarchy is clear +- [ ] Spacing feels consistent + +### Responsive +- [ ] Works on mobile (375px) +- [ ] Works on tablet (768px) +- [ ] Works on desktop (1280px+) + +### Accessibility +- [ ] Can navigate with keyboard only +- [ ] Focus visible at all times +- [ ] Screen reader friendly (test with VoiceOver/NVDA) +- [ ] Color contrast passes WCAG AA + +### Cross-Browser +- [ ] Chrome/Edge (Chromium) +- [ ] Firefox +- [ ] Safari (macOS/iOS) + +--- + +## 📚 References + +- **Tailwind CSS:** https://tailwindcss.com/docs +- **Framer Motion:** https://www.framer.com/motion/ +- **WCAG Guidelines:** https://www.w3.org/WAI/WCAG21/quickref/ +- **Ciphera Brand:** (internal brand guidelines) + +--- + +## 🔄 Changelog + +### v1.0 (2026-02-06) +- Initial design system documentation +- Documented Tier 1 + Tier 2 standardization results +- Defined all component patterns +- Established accessibility standards + +--- + +**This is a living document.** Update as the design system evolves.