# Clicki Design System

> Machine-readable brand & design reference for the Clicki product family
> (Clicki Referrals, Bravo, Denaro AI, Clover by Clicki).
> Canonical URL: https://joinclicki.com/design.md
> Human-facing brand kit: https://joinclicki.com/brand

---

## 1. Brand

- **Company**: Clicki
- **Domain**: joinclicki.com
- **Tagline**: The simplest way to automate referral programs for service businesses.
- **Voice & tone**: Friendly, confident, service-business native. Lead with outcomes. Avoid jargon.
- **Address**: 109 Michigan St NW, Suite 411, Grand Rapids, MI 49503
- **Phone**: 616-227-4873 (call/text)
- **Brand contact**: brand@joinclicki.com

### Product family
| Product | URL | Purpose |
|---|---|---|
| Clicki Referrals | https://joinclicki.com | Customer / partner / influencer referral automation |
| Bravo | https://launchbravo.com | Google Reviews, NPS, tipping, technician leads |
| Denaro AI | https://denaroai.com | AI collections & automated AR |
| Clover by Clicki | https://clover.joinclicki.com | Digital door knocking & neighborhood enrichment |

---

## 2. Color tokens (HSL — production source of truth)

All colors are HSL (hue saturation% lightness%) and exposed as CSS custom properties on `:root` in `src/index.css`. Tailwind classes wrap them via `hsl(var(--token))`.

### Light theme
```
--background:           60 20% 98%      /* near-white warm canvas */
--foreground:          160 30% 15%      /* deep service-green ink */
--card:                  0 0% 100%
--card-foreground:     160 30% 15%
--primary:             160 35% 22%      /* deep green */
--primary-foreground:   60 100% 97%
--secondary:            75 70% 50%      /* lime */
--secondary-foreground:160 35% 15%
--muted:                60 10% 92%
--muted-foreground:    160 15% 40%
--accent:               75 65% 88%      /* soft lime tint */
--accent-foreground:   160 35% 22%
--cta:                  78 100% 83%     /* signature lime CTA  ≈ #E9FFA6 */
--cta-foreground:      160 35% 15%
--destructive:           0 72% 50%
--border:               60 10% 88%
--input:                60 10% 88%
--ring:                 75 70% 50%
--radius:               0.75rem
```

### Dark theme (`.dark`)
```
--background:          160 20% 8%
--foreground:           60 20% 98%
--primary:              75 70% 50%      /* lime becomes primary on dark */
--accent:               75 50% 20%
```

### Usage rules
- **Lime CTA (`--cta` ≈ `#E9FFA6`)** is reserved for the single most important action on a screen.
- Never hard-code hex/rgb in components. Always reference tokens via Tailwind: `bg-primary`, `text-foreground`, `border-border`, etc.
- All new colors must be added as HSL CSS variables AND mapped in `tailwind.config.ts`.

---

## 3. Typography

Fonts are loaded in `index.html` for performance and exposed as CSS variables + Tailwind families.

| Role | Family | Tailwind | CSS var |
|---|---|---|---|
| Headlines / editorial | **Lora** (serif) | `font-serif` | `--font-serif` |
| UI / body / buttons | **Work Sans** (sans) | `font-sans` | `--font-sans` |
| Code / IDs / data labels | **Inconsolata** (mono) | `font-mono` | `--font-mono` |

### Scale (Tailwind defaults, used consistently)
- Hero H1: `text-5xl md:text-6xl font-serif font-medium`
- Section H2: `text-3xl md:text-4xl font-serif`
- Body: `text-base text-muted-foreground` for supporting copy, `text-foreground` for primary

---

## 4. Spacing, radius, shadow

- **Radius**: `--radius: 0.75rem` (12px). Tailwind: `rounded-lg`. Smaller variants `rounded-md` / `rounded-sm` derive from it.
- **Container rhythm**: `container mx-auto px-4 py-16` (or `py-20` for hero) is the default section frame across the homepage.
- **Shadows**: `shadow-sm` → `shadow-2xl` are mapped to `--shadow-*` HSL-based tokens. Prefer `shadow-sm`/`shadow-md` for cards.
- **Borders**: 1px `border-border`, frequently used to separate full-width sections rather than heavy dividers.

---

## 5. Components (shadcn/ui + custom variants)

All primitives live in `src/components/ui/`. Always import from there — never re-implement.

### Button (`@/components/ui/button`)
Variants: `default`, `secondary`, `outline`, `ghost`, `link`, `destructive`, **`cta`** (lime — primary action).
Sizes: `default`, `sm`, `lg`, `icon`.

```tsx
<Button variant="cta" size="lg">Get started</Button>
```

### Card (`@/components/ui/card`)
`Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter`. Default: `rounded-lg border bg-card text-card-foreground shadow-sm`.

### Badge (`@/components/ui/badge`)
Variants: `default`, `secondary`, `outline`, `destructive`. Use for tags, "Do/Don't" labels, status chips.

### Other primitives
Dialog, Sheet, Tooltip, Tabs, Accordion, Form, Input, Select, Toast (sonner) — all standard shadcn, themed via the tokens above.

---

## 6. Motion

Defined in `tailwind.config.ts` keyframes/animations:

- `animate-fade-up` — 30px translateY + opacity, 0.7s ease-out
- `animate-fade-left` / `animate-fade-right` — 30px translateX + opacity, 0.7s ease-out
- `animate-scroll-left` / `animate-scroll-right` — 30s infinite marquee (logo strips)
- `animate-accordion-down` / `animate-accordion-up` — 0.2s ease-out

Reach for fade-up on scroll-in section reveals. Avoid stacking >1 motion per element.

---

## 7. Stack & architecture

- **Framework**: React 18 + Vite 5 + TypeScript 5
- **Styling**: Tailwind CSS v3 (no inline hex; tokens only)
- **Routing**: react-router-dom (see `src/App.tsx`)
- **Backend**: Lovable Cloud (managed Supabase) — auth, edge functions, storage
- **AI**: Lovable AI Gateway (Gemini & GPT models, no external keys required)
- **Email**: Resend for transactional, Gmail OAuth for proposal sends
- **Payments**: Stripe SetupIntents (save card, no immediate charge)
- **Analytics**: Meta Pixel, Google Ads, PostHog, LinkedIn, Apollo visitor tracking

---

## 8. SEO & AEO essentials

- Single H1 per page; semantic HTML throughout.
- `<title>` < 60 chars, `<meta name="description">` < 160 chars, canonical link on every page.
- JSON-LD `Organization` schema with logo + sameAs links to product domains.
- `public/sitemap.xml` lists every public route. `public/robots.txt` allows AI crawlers (GPTBot, ClaudeBot, PerplexityBot, etc.).
- "Ask AI" footer block deep-links to ChatGPT, Claude, Perplexity, Gemini, and Grok with a pre-filled brand prompt.

---

## 9. Source-of-truth files

If you're an LLM building or auditing on this codebase, read these directly:

- Design tokens: `src/index.css`
- Tailwind theme: `tailwind.config.ts`
- Homepage composition: `src/pages/Index.tsx`
- Hero pattern: `src/components/HeroSection.tsx`
- Card / CTA pattern: `src/components/PricingSection.tsx`
- Button primitive: `src/components/ui/button.tsx`
- Public brand kit page: `src/pages/Brand.tsx`

---

## 10. Logos

Available on the brand kit page (https://joinclicki.com/brand) with light + dark previews:
- `clicki-logo.png` — Clicki Referrals primary mark
- `bravo-logo.png` / `bravo-logo-full.png` — Bravo icon + wordmark
- `denaro-logo.png` — Denaro AI
- `clover-logo.svg` / `clover-logo.png` — Clover by Clicki

Maintain clear space equal to the height of the mark. Do not recolor; use the dark/light tile that matches the surface.

---

_Last updated: 2026-04-23_