# EKA Brand Design System — AI Context Document

> **Auto-generated** from `src/app/globals.css` + component source on 2026-07-13T10:10:14.473Z
> **Version:** 1.0.0
> **Live endpoints:** https://ekabalance.com/brand/

This document gives an AI assistant complete context to generate on-brand components, layouts, and styles for the EKA design system. Feed this file as system context when using Claude, GPT, Gemini, or any other LLM to build EKA-branded UI.

---

## Quick Reference Card

| Concern | Value |
|---|---|
| Primary color | `#0071e3` (Apple-like blue) |
| Gold accent | `#ffb405` (premium, use sparingly) |
| Background | `oklch(1 0 0)` = white |
| Body font | MiSans Latin, weight **300** |
| Heading font | MiSans Latin, weight **500** |
| Card radius | `2rem` (`--radius-apple`, `rounded-apple`) |
| Shadows | **None** — all `0 0 #0000` |
| Borders | `1px` (0.5px on hi-DPI, `var(--border-hairline)`) |
| Frosted glass | `backdrop-blur-2xl` + `bg-background/55` |
| Button shape | Always `rounded-full` |
| Nav frosted | `app-chrome-surface` utility |
| Card surface | `app-card-surface` utility |
| Section badge | `app-kicker` utility (place above headings) |

---

## 1. Brand Identity

**Name:** EKA
**Philosophy:** Minimalist, Apple-inspired flat design. Clean surfaces, generous whitespace, and light typography. No box-shadows — depth is expressed through hairline borders, transparency layers, and backdrop-blur.

### Core Principles

1. **Flat design** — all `box-shadow` values are `0 0 #0000`. Never add drop shadows.
2. **Light type** — body is font-weight 300 (light). Headings are 500 (medium). Never bold body text.
3. **Hairline borders** — 1px on standard displays, 0.5px on 2×+ DPI (`var(--border-hairline)`).
4. **Apple radius** — `2rem` (`--radius-apple`) is the canonical card/container radius. Degrades to `1.5rem` on mobile.
5. **OKLch palette** — all colors use the OKLch color space for perceptual uniformity.
6. **Frosted glass nav** — `backdrop-blur-2xl` + `bg-background/55` + subtle border. Never opaque nav bars.
7. **Primary blue** `#0071e3` — high-trust, action-oriented. Use for CTAs, links, focus rings.
8. **Rating amber** `#ffb405` — premium feel. Use sparingly for star ratings, highlights, special emphasis.
9. **Round everything** — buttons are `rounded-full`, cards are `rounded-apple`.

---

## 2. Design Tokens

> Live JSON: https://ekabalance.com/brand/tokens.json
> Live CSS: https://ekabalance.com/brand/tokens.css

### 2.1 Color Palette

All colors are CSS custom properties available via `var(--color-*)`.

| Token | Value |
|---|---|
| `--color-rating-light` | `#fde68a` |
| `--color-rating` | `#ffb405` |
| `--color-rating-dark` | `#b45309` |
| `--color-sidebar` | `oklch(0.985 0 0)` |
| `--color-sidebar-foreground` | `oklch(0.145 0 0)` |
| `--color-sidebar-primary` | `oklch(0.546 0.245 262.881)` |
| `--color-sidebar-primary-foreground` | `oklch(0.97 0.014 254.604)` |
| `--color-sidebar-accent` | `oklch(0.97 0 0)` |
| `--color-sidebar-accent-foreground` | `oklch(0.205 0 0)` |
| `--color-sidebar-border` | `oklch(0.922 0 0)` |
| `--color-sidebar-ring` | `oklch(0.708 0 0)` |
| `--color-chart-1` | `oklch(0.87 0 0)` |
| `--color-chart-2` | `oklch(0.556 0 0)` |
| `--color-chart-3` | `oklch(0.439 0 0)` |
| `--color-chart-4` | `oklch(0.371 0 0)` |
| `--color-chart-5` | `oklch(0.269 0 0)` |

**Semantic color usage:**
- `--color-primary` → CTAs, links, focus rings, interactive states, icon tile backgrounds
- `--color-rating` → premium highlights, star ratings — use sparingly
- `--color-success / warning / destructive` → status feedback
- `--color-muted-foreground` → body text, descriptions, secondary info
- `--color-foreground` → primary text, headings
- `--color-background` → page background, card fills
- `--color-whatsapp` (#25D366) → WhatsApp CTAs only

### 2.2 Typography

| Token | Value |
|---|---|


**Font: MiSans Latin** (Xiaomi open-source, self-hosted WOFF2)
Available weights: 100 (Thin), 200 (ExtraLight), **300 (Light — body default)**, 350 (Normal), 400 (Regular), **500 (Medium — headings)**, 600 (Demibold), 650 (Semibold), 700 (Bold), 900 (Heavy).

Typography scale:
| Class | Size | Weight | Use |
|---|---|---|---|
| `apple-headline` / `heading-1` | 2xl → 6xl | 300 light | Hero/display text |
| `apple-title` / `heading-2` | xl → 3xl | 500 medium | Card/section headings |
| `apple-subtitle` / `heading-3` | base → xl | 400 normal | Subheadings, muted |
| `text-body-lg` | base → lg | 300 light | Comfortable body |

### 2.3 Border Radius

| Token | Value |
|---|---|


Use `rounded-apple` (= `--radius-apple` = 2rem) on all major surfaces. On mobile (<768px) the global CSS automatically reduces `rounded-apple` to 1.5rem.

### 2.4 Easing Functions

| Token | Cubic-bezier |
|---|---|


Prefer `--ease-out-quint` or `--ease-out-expo` for entrance animations.

### 2.5 Animations

| Token | Value |
|---|---|


Available keyframes: `fadeIn`, `slideUp`, `scaleIn`, `subtlePulse`, `gentleFloat`, `float`.

### 2.6 Z-index Scale

| Token | Value |
|---|---|


Never exceed these values. Stacking context in order: dropdown → modal → tooltip → toast.

### 2.7 Surfaces & Borders (CSS variables)




---

## 3. Tailwind Utility Classes

> These are `@utility` definitions in `globals.css`. Use them directly as class names.

### Layout
- **`section-container`** — `max-w-7xl mx-auto px-4 sm:px-6 lg:px-8` — wraps page section content

### Surface Utilities
| Class | Description |
|---|---|
| `app-card-surface` | Canonical card: `rounded-apple`, hairline border, `bg-card` |
| `apple-card` | Interactive card: adds `hover:border-primary/30` transition |
| `app-muted-card` | Secondary card: `bg-muted/35`, softer border |
| `app-chrome-surface` | Frosted nav bar: `rounded-full`, `backdrop-blur-2xl`, `bg-background/55` |
| `app-dropdown-surface` | Dropdown/popover: `rounded-apple`, heavy frosted glass |
| `app-muted-section` | Page section tint: `bg-muted/35` |
| `glass-panel` | Light frosted panel: `bg-background/80`, `backdrop-blur-xl` |
| `glass-panel-strong` | Heavy frosted panel: `bg-background/95`, `backdrop-blur-xl` |
| `app-soft-tile` | Neutral tile: `rounded-apple`, `bg-background` |
| `app-icon-tile` | Icon container: `rounded-apple`, `bg-primary/10`, `text-primary` |

### Label & Badge Utilities
| Class | Description |
|---|---|
| `app-kicker` | Category badge: `rounded-full`, `border-primary/20`, `bg-primary/5`, `text-[10px] uppercase text-primary`. Place above section headings. |
| `app-eyebrow` | Small section label: `text-xs font-medium uppercase text-muted-foreground` |

### Navigation Utilities
| Class | Description |
|---|---|
| `app-nav-pill` | Base nav pill button shape |
| `app-nav-pill-active` | Active state: blue tint |
| `app-nav-pill-idle` | Idle state: muted text, hover bg |

### Typography Utilities
| Class | Description |
|---|---|
| `apple-headline` / `heading-1` | Large display text, font-light |
| `apple-title` / `heading-2` | Section heading, font-medium |
| `apple-subtitle` / `heading-3` | Subheading, muted, font-normal |
| `text-body-lg` | Body text, font-light, muted, relaxed leading |

---

## 4. Component Library

> Full source: https://ekabalance.com/brand/components.json
> Source directory: `src/components/`

### All Components

- **Container** (`src/components/layout/Container.tsx`) — Max-width wrapper. max-w-6xl, responsive horizontal padding.
- **Section** (`src/components/layout/Section.tsx`) — Page section with tone (default|muted|inverted) and spacing (tight|default|loose) props. Wraps Container unless bleed=true.
- **PageHero** (`src/components/layout/PageHero.tsx`) — Page header component. Props: eyebrow, title, subtitle, actions, align. Responsive h1 from 3xl to 7xl.
- **CTABlock** (`src/components/layout/CTABlock.tsx`) — Call-to-action panel. Tones: soft (muted bg) | bold (primary bg). rounded-apple, centered text.
- **FeatureGrid** (`src/components/layout/FeatureGrid.tsx`) — Grid of icon+title+description feature cards. columns: 2|3|4. Cards use apple-card with hover effect.
- **FAQSection** (`src/components/layout/FAQSection.tsx`) — Animated FAQ with native details elements and Framer Motion height animation.
- **Accordion** (`src/components/Accordion.tsx`) — Context-based accordion with single or multiple open items. Framer Motion animation.
- **AnimateIn** (`src/components/AnimateIn.tsx`) — Scroll-triggered entrance animation wrapper.
- **AppleHero** (`src/components/AppleHero.tsx`) — Full-bleed hero section with Apple-style large typography.
- **CTASection** (`src/components/CTASection.tsx`) — Full-bleed CTA with parallax background image and dark overlay.
- **ServiceCard** (`src/components/ServiceCard.tsx`) — Service listing card with image, price badge, benefits list, booking button.
- **MainLayout** (`src/components/MainLayout.tsx`) — Root layout with fixed frosted-glass nav, footer, cookie banner, toast container.
- **CoreServiceTemplate** (`src/components/templates/CoreServiceTemplate.tsx`) — Full page template for service pages. Sections: hero, features, stats, bento grid, FAQ, pricing, testimonials.
- **FunnelHero** (`src/components/templates/FunnelHero.tsx`) — Conversion-focused hero with problem selector and adaptive copy.

---

## 5. Key Component Source Code

### Container

**File:** `src/components/layout/Container.tsx`

Max-width wrapper. max-w-6xl, responsive horizontal padding.

```tsx
export { Container } from "@eka/blocks/container";

```

---

### Section

**File:** `src/components/layout/Section.tsx`

Page section with tone (default|muted|inverted) and spacing (tight|default|loose) props. Wraps Container unless bleed=true.

```tsx
export { Section } from "@eka/blocks/section";
export type { SectionProps } from "@eka/blocks/section";

```

---

### PageHero

**File:** `src/components/layout/PageHero.tsx`

Page header component. Props: eyebrow, title, subtitle, actions, align. Responsive h1 from 3xl to 7xl.

```tsx
export { PageHero } from "@eka/blocks/page-hero";
export type { PageHeroProps } from "@eka/blocks/page-hero";

```

---

### CTABlock

**File:** `src/components/layout/CTABlock.tsx`

Call-to-action panel. Tones: soft (muted bg) | bold (primary bg). rounded-apple, centered text.

```tsx
export { CTABlock } from "@eka/blocks/cta-block";
export type { CTABlockProps } from "@eka/blocks/cta-block";

```

---

### FeatureGrid

**File:** `src/components/layout/FeatureGrid.tsx`

Grid of icon+title+description feature cards. columns: 2|3|4. Cards use apple-card with hover effect.

```tsx
export { FeatureGrid } from "@eka/blocks/feature-grid";
export type { Feature, FeatureGridProps } from "@eka/blocks/feature-grid";

```

---

## 6. Common UI Patterns

Copy-paste patterns that match the EKA design system. All use standard Tailwind + the custom utilities above.

### 6.1 Page Section with Header

```tsx
<Section tone="default" spacing="default">
  <div className="flex flex-col items-center gap-4 text-center mb-12">
    <span className="app-kicker">Category Label</span>
    <h2 className="apple-headline max-w-3xl">Section Headline Goes Here</h2>
    <p className="apple-subtitle max-w-2xl">
      Supporting description that explains the section purpose briefly.
    </p>
  </div>
  {/* section content */}
</Section>
```

### 6.2 Feature Card Grid

```tsx
<FeatureGrid
  columns={3}
  features={[
    {
      icon: <SomeIcon className="size-6" />,
      title: "Feature Title",
      description: "Short description of this feature and its benefit.",
    },
    // ...
  ]}
/>
```

### 6.3 Standard Card

```tsx
<div className="app-card-surface p-6 flex flex-col gap-4">
  <div className="app-icon-tile w-12 h-12">
    <SomeIcon className="size-5" />
  </div>
  <div>
    <h3 className="apple-title">Card Title</h3>
    <p className="text-body-lg mt-1">Card description text here.</p>
  </div>
</div>
```

### 6.4 Interactive Hover Card

```tsx
<div className="apple-card p-6 flex flex-col gap-4">
  <h3 className="apple-title">Card Title</h3>
  <p className="text-body-lg">Description text.</p>
  <Button variant="outline" size="sm">Learn More</Button>
</div>
```

### 6.5 Primary CTA Block

```tsx
<CTABlock
  tone="bold"
  eyebrow="Get Started"
  title="Ready to grow your business?"
  subtitle="Join hundreds of clients who have transformed their online presence."
  actions={
    <>
      <Button size="lg">Book a Session</Button>
      <Button variant="inverse" size="lg">Learn More</Button>
    </>
  }
/>
```

### 6.6 Frosted Nav Pill

```tsx
<nav className="app-chrome-surface px-2 py-2 flex items-center gap-1">
  <a href="/services" className="app-nav-pill app-nav-pill-active px-4 py-2">
    Services
  </a>
  <a href="/about" className="app-nav-pill app-nav-pill-idle px-4 py-2">
    About
  </a>
</nav>
```

### 6.7 Icon Feature Row

```tsx
<div className="flex items-start gap-4">
  <div className="app-icon-tile w-12 h-12 shrink-0">
    <CheckmarkIcon className="size-5" />
  </div>
  <div>
    <h4 className="apple-title text-lg">Feature Name</h4>
    <p className="text-body-lg text-sm mt-0.5">Brief explanation of this feature.</p>
  </div>
</div>
```

### 6.8 Badge + Heading Combo (Section Header Pattern)

```tsx
<div className="flex flex-col gap-3">
  <span className="app-kicker">Our Services</span>
  <h2 className="apple-headline">What We Offer</h2>
  <p className="apple-subtitle max-w-xl">
    Explore our full range of SEO and web services designed for growth.
  </p>
</div>
```

### 6.9 Bento Grid

```tsx
<div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4">
  <BentoCard href="/service/seo" delay={0}>
    <div className="p-6 flex flex-col gap-3 h-full">
      <div className="app-icon-tile w-10 h-10">
        <SearchIcon className="size-4" />
      </div>
      <h3 className="apple-title text-lg">SEO Optimization</h3>
      <p className="text-body-lg text-sm">Grow organic traffic.</p>
    </div>
  </BentoCard>
  {/* more cards */}
</div>
```

### 6.10 Form Input Group

```tsx
<div className="flex flex-col gap-4">
  <div className="flex flex-col gap-1.5">
    <Label htmlFor="name">Full Name</Label>
    <Input id="name" placeholder="Your name" type="text" />
  </div>
  <div className="flex flex-col gap-1.5">
    <Label htmlFor="email">Email</Label>
    <Input id="email" placeholder="you@example.com" type="email" />
  </div>
  <div className="flex flex-col gap-1.5">
    <Label htmlFor="message">Message</Label>
    <Textarea id="message" placeholder="How can we help?" />
  </div>
  <Button type="submit" size="lg" className="w-full">Send Message</Button>
</div>
```

### 6.11 Muted Section (Alternating Background)

```tsx
<Section tone="muted" spacing="default">
  <Container>
    {/* content on subtle muted background */}
  </Container>
</Section>
```

### 6.12 Page Hero

```tsx
<PageHero
  eyebrow={<Badge variant="secondary">SEO Services</Badge>}
  title={<>Grow Your Organic<br />Traffic with EKA</>}
  subtitle="Data-driven SEO strategy that delivers measurable results for your business."
  align="center"
  actions={
    <>
      <Button size="xl">Book Free Consultation</Button>
      <Button variant="outline" size="xl">View Case Studies</Button>
    </>
  }
/>
```

---

## 7. Animation Patterns

### Entrance Animation (CSS)
```css
.my-element {
  animation: slideUp 0.5s var(--ease-out-quint) forwards;
}

/* or */
.my-element {
  animation: fadeIn 0.3s ease-out forwards;
}
```

### Entrance Animation (Framer Motion)
```tsx
import { motion } from 'framer-motion';

<motion.div
  initial={{ opacity: 0, y: 20 }}
  animate={{ opacity: 1, y: 0 }}
  transition={{ duration: 0.5, ease: [0.23, 1, 0.32, 1] }} // ease-out-quint
>
  Content
</motion.div>
```

### Staggered List
```tsx
<motion.ul>
  {items.map((item, i) => (
    <motion.li
      key={item.id}
      initial={{ opacity: 0, y: 16 }}
      animate={{ opacity: 1, y: 0 }}
      transition={{ delay: i * 0.08, duration: 0.4, ease: [0.23, 1, 0.32, 1] }}
    >
      {item.label}
    </motion.li>
  ))}
</motion.ul>
```

---

## 8. Integration Guide

### 8.1 Import CSS tokens in any project

```css
/* @import in your global CSS */
@import url('https://ekabalance.com/brand/tokens.css');

/* Now use CSS custom properties */
.my-button {
  background: var(--color-primary);
  color: var(--color-primary-foreground);
  border-radius: var(--radius-apple);
}
```

### 8.2 Fetch tokens at build time (no runtime dependency)

```bash
# In package.json "prebuild" script:
curl https://ekabalance.com/brand/tokens.json -o src/brand-tokens.json
curl https://ekabalance.com/brand/tokens.css  -o src/styles/brand.css
```

### 8.3 Tailwind v3 preset

```js
// tailwind.config.js
const brandPreset = require('./brand-tokens.json'); // fetched at build time

module.exports = {
  presets: [{ theme: brandPreset.theme }],
  // your config
};
```

### 8.4 Tailwind v4 with token CSS

```css
/* In your globals.css */
@import 'https://ekabalance.com/brand/tokens.css';
@import 'tailwindcss';

/* --color-primary etc. are now available as Tailwind theme values */
```

### 8.5 Inject as AI context

```bash
# Download and feed to an LLM:
curl https://ekabalance.com/brand/ai-context.md > brand-context.md

# Claude API example:
# Include brand-context.md content in your system prompt, then ask:
# "Generate an on-brand pricing section component using the EKA design system."

```

---

## 9. AI Generation Checklist

When generating UI components for the EKA brand, verify each of these:

- [ ] No box-shadows anywhere (all should be `0 0 #0000` or omitted)
- [ ] Cards use `rounded-apple` (2rem) or `app-card-surface` utility
- [ ] Buttons are `rounded-full`
- [ ] Body text is `font-light` (weight 300)
- [ ] Headings are `font-medium` (weight 500) or lighter
- [ ] Interactive elements use `--color-primary` (#0071e3)
- [ ] Section headings have an `app-kicker` badge above them
- [ ] Frosted glass uses `backdrop-blur-xl` or `backdrop-blur-2xl` (not opaque)
- [ ] Borders use `var(--border-hairline)` width (1px / 0.5px)
- [ ] Easing uses `--ease-out-quint` or `--ease-out-expo` for entrances
- [ ] Colors are sourced from the token palette (CSS custom properties)
- [ ] No inline `z-index` values outside the defined z-index scale

---

## 10. Design Dos and Don'ts

### ✅ Do
- Use `var(--color-primary)` / `#0071e3` for all CTAs and interactive elements
- Use `rounded-apple` (2rem) for card containers
- Apply `border-width: var(--border-hairline)` on cards
- Use `backdrop-blur-2xl` for overlay and nav surfaces
- Keep font-weight 300 for body, 500 for headings
- Use `--ease-out-quint` for entrance animations
- Prefix custom utilities with `app-`
- Add `app-kicker` badges above section headings
- Use `text-muted-foreground` for body/description text
- Use OKLch values when adding new colors

### ❌ Don't
- Add `box-shadow` — the brand is flat
- Use `font-weight > 500` on body or paragraph text
- Use colors outside the token palette
- Use `border-radius` below `1.5rem` on major surfaces
- Make square or barely-rounded buttons
- Exceed the z-index scale (100/200/300/400)
- Mix `--color-rating` and `--color-primary` in the same component
- Use `border-width` greater than 1px

---

*Generated by `scripts/generate-brand.mjs` · Source: `src/app/globals.css` · https://ekabalance.com/brand/*
