# TekDek CSS Specification Guide

**For:** Icarus (CSS/Design)  
**Project:** Documentation Website Styling  
**Date:** 2026-04-12

---

## QUICK REFERENCE: COLOR PALETTE

```
Primary Background:   #0d0d0f (near black)
Text (primary):       #e0e0e0 (light gray)
Text (secondary):     #7B8794 (steel blue)
Accent (primary):     #C4A24E (gold)
Accent (secondary):   #E07A2F (amber/orange)
Border Color:         #2a2a2d (dark gray)
```

**CSS Variables Template:**
```css
:root {
    --color-bg: #0d0d0f;
    --color-fg: #e0e0e0;
    --color-gold: #C4A24E;
    --color-steel: #7B8794;
    --color-amber: #E07A2F;
    --color-border: #2a2a2d;
}
```

---

## TYPOGRAPHY STACK

| Element | Font | Size | Weight | Line Height |
|---------|------|------|--------|------------|
| h1 | Cinzel | 3rem | 600 | 1.2 |
| h2 | Cinzel | 2.25rem | 600 | 1.2 |
| h3 | Cinzel | 1.75rem | 600 | 1.2 |
| h4 | Cinzel | 1.5rem | 600 | 1.2 |
| h5 | Cinzel | 1.25rem | 600 | 1.2 |
| h6 | Cinzel | 1.1rem | 600 | 1.2 |
| Body | Inter | 1rem (16px) | 400 | 1.6 |
| Body (bold) | Inter | 1rem | 600 | 1.6 |
| Code | JetBrains Mono | 0.95rem | 400 | 1.5 |
| Code (bold) | JetBrains Mono | 0.95rem | 500 | 1.5 |

**Font Import:**
```css
@import url('https://fonts.googleapis.com/css2?family=Cinzel:wght@400;600;700&family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap');
```

---

## SPACING SCALE

```css
--spacing-xs:   0.5rem   (8px)
--spacing-sm:   1rem     (16px)
--spacing-md:   1.5rem   (24px)
--spacing-lg:   2rem     (32px)
--spacing-xl:   3rem     (48px)
--spacing-2xl:  4rem     (64px)
```

### Where to Use

- **xs:** Tight spacing within components (badges, inline labels)
- **sm:** Standard padding for buttons, form fields
- **md:** Section spacing, margin between elements
- **lg:** Space between major layout sections
- **xl:** Page-level spacing, large gaps
- **2xl:** Full-screen padding, hero sections

---

## COMPONENT SPECIFICATIONS

### Buttons

**Primary Button**
```css
.btn-primary {
    background: #C4A24E;        /* Gold */
    color: #0d0d0f;             /* Dark background */
    padding: 1rem 1.5rem;
    border-radius: 6px;
    font-weight: 600;
    font-family: 'Cinzel', serif;
    transition: all 0.2s ease;
    border: none;
    cursor: pointer;
}

.btn-primary:hover {
    background: #E07A2F;        /* Amber */
    transform: translateY(-2px);
    box-shadow: 0 4px 12px rgba(196, 162, 78, 0.3);
}

.btn-primary:active {
    transform: translateY(0);
}
```

**Secondary Button**
```css
.btn-secondary {
    background: transparent;
    color: #C4A24E;             /* Gold text */
    border: 2px solid #C4A24E;
    padding: 0.875rem 1.375rem; /* Account for border */
    border-radius: 6px;
    font-weight: 600;
    font-family: 'Cinzel', serif;
    transition: all 0.2s ease;
    cursor: pointer;
}

.btn-secondary:hover {
    background: #C4A24E;        /* Gold fill */
    color: #0d0d0f;
}
```

**Specs:**
- Minimum height: 44px (touch-friendly)
- Minimum width: 80px
- Padding: 1rem 1.5rem
- Border radius: 6px
- Font size: inherit or 1rem
- Cursor: pointer

---

### Cards

**Base Card**
```css
.card {
    background: rgba(255, 255, 255, 0.03);
    border: 1px solid #2a2a2d;
    border-radius: 8px;
    padding: 2rem;
    transition: all 0.2s ease;
}

.card:hover {
    background: rgba(255, 255, 255, 0.05);
    border-color: #C4A24E;
    transform: translateY(-2px);
    box-shadow: 0 8px 24px rgba(0, 0, 0, 0.4);
}
```

**Quick Link Card**
```css
.quick-link-card {
    background: rgba(255, 255, 255, 0.03);
    border: 1px solid #2a2a2d;
    border-radius: 8px;
    padding: 2rem;
    transition: all 0.2s ease;
}

.quick-link-card:hover {
    background: rgba(255, 255, 255, 0.05);
    border-color: #C4A24E;
    transform: translateY(-4px);  /* Lift higher on hover */
}

.quick-link-card h3 a {
    color: #C4A24E;
}

.quick-link-card p {
    color: #7B8794;             /* Steel */
}
```

---

### Header & Navigation

**Header Style**
```css
.site-header {
    background: linear-gradient(135deg, #0d0d0f 0%, rgba(0, 0, 0, 0.5) 100%);
    border-bottom: 1px solid #2a2a2d;
    height: 80px;
    display: flex;
    align-items: center;
    position: sticky;
    top: 0;
    z-index: 1;
}

.logo-text {
    font-family: 'Cinzel', serif;
    font-size: 1.8rem;
    font-weight: 700;
    color: #C4A24E;
    transition: color 0.2s ease;
}

.logo a:hover .logo-text {
    color: #E07A2F;
}
```

**Navigation Menu**
```css
.menu {
    display: flex;
    list-style: none;
    gap: 2rem;
    margin: 0;
    padding: 0;
}

.menu-link {
    color: #e0e0e0;
    padding: 0.5rem 1rem;
    transition: color 0.2s ease;
    text-decoration: none;
    border-bottom: 2px solid transparent;
}

.menu-link:hover {
    color: #C4A24E;
}

.menu-link.active {
    color: #C4A24E;
    border-bottom-color: #C4A24E;
}
```

**Dropdown Menu**
```css
.menu-level-1 {
    display: none;
    position: absolute;
    top: 100%;
    left: 0;
    background: rgba(13, 13, 15, 0.95);
    border: 1px solid #2a2a2d;
    border-radius: 6px;
    padding: 1rem 0;
    min-width: 200px;
    z-index: 100;
    box-shadow: 0 8px 24px rgba(0, 0, 0, 0.5);
}

.menu-item.has-submenu:hover .menu-level-1 {
    display: block;
}

.menu-level-1 .menu-link {
    display: block;
    padding: 1rem 1.5rem;
    border: none;
}
```

---

### Hero Section

**Hero Container**
```css
.hero-section {
    padding: 4rem 0;
    text-align: center;
    background: linear-gradient(135deg, rgba(196, 162, 78, 0.05) 0%, rgba(224, 122, 47, 0.05) 100%);
    border-radius: 12px;
    margin-bottom: 4rem;
}

.hero-title {
    font-size: 4rem;
    font-weight: 700;
    margin-bottom: 1.5rem;
    background: linear-gradient(135deg, #C4A24E, #E07A2F);
    -webkit-background-clip: text;
    -webkit-text-fill-color: transparent;
    background-clip: text;
}

.hero-subtitle {
    font-size: 1.5rem;
    color: #7B8794;
    margin-bottom: 1.5rem;
}

.hero-desc {
    font-size: 1.1rem;
    color: #e0e0e0;
    margin-bottom: 3rem;
    line-height: 1.8;
    max-width: 600px;
    margin-left: auto;
    margin-right: auto;
}
```

---

### Footer

**Footer Style**
```css
.site-footer {
    background: rgba(0, 0, 0, 0.3);
    border-top: 1px solid #2a2a2d;
    padding: 4rem 1.5rem;
    margin-top: 4rem;
}

.footer-container {
    max-width: 1200px;
    margin: 0 auto;
    display: flex;
    justify-content: space-between;
    align-items: center;
    gap: 2rem;
}

.footer-content p {
    margin-bottom: 0.5rem;
    color: #e0e0e0;
}

.footer-tagline {
    color: #7B8794;
    font-size: 0.9rem;
}

.footer-link {
    color: #7B8794;
    transition: color 0.2s ease;
}

.footer-link:hover {
    color: #C4A24E;
}
```

---

### Content Layout

**Article Container**
```css
.content-article {
    background: rgba(255, 255, 255, 0.02);
    border: 1px solid #2a2a2d;
    padding: 3rem;
    border-radius: 8px;
}

.content-body h2 {
    margin-top: 3rem;
    margin-bottom: 1.5rem;
}

.content-body ul,
.content-body ol {
    margin-left: 2rem;
    margin-bottom: 1.5rem;
}

.content-body li {
    margin-bottom: 0.5rem;
}
```

**Sidebar**
```css
.content-sidebar {
    position: sticky;
    top: calc(80px + 1.5rem);
    height: fit-content;
}

.sidebar-section {
    background: rgba(255, 255, 255, 0.02);
    border: 1px solid #2a2a2d;
    padding: 1.5rem;
    border-radius: 8px;
    margin-bottom: 1.5rem;
}

.section-link {
    display: block;
    color: #7B8794;
    padding: 0.5rem 1rem;
    border-left: 3px solid transparent;
    transition: all 0.2s ease;
}

.section-link:hover {
    color: #C4A24E;
    border-left-color: #C4A24E;
}

.section-link.active {
    color: #C4A24E;
    border-left-color: #C4A24E;
}
```

---

## RESPONSIVE BREAKPOINTS

```css
/* Default: Desktop (1200px+) */
body { font-size: 16px; }

/* Tablet (768px and below) */
@media (max-width: 768px) {
    body { font-size: 15px; }
    
    .menu-toggle { display: flex; }
    .site-nav { /* Mobile menu styles */ }
    .content-container { grid-template-columns: 1fr; }
    .footer-container { flex-direction: column; }
    
    h1 { font-size: 2rem; }
    h2 { font-size: 1.75rem; }
    h3 { font-size: 1.5rem; }
    
    .hero-title { font-size: 2.5rem; }
    .quick-links-grid { grid-template-columns: 1fr; }
}

/* Mobile (480px and below) */
@media (max-width: 480px) {
    body { font-size: 14px; }
    
    h1 { font-size: 1.5rem; }
    h2 { font-size: 1.25rem; }
    h3 { font-size: 1.1rem; }
    
    .hero-title { font-size: 1.75rem; }
    .btn { padding: 0.5rem 1rem; }
    .site-main { padding: 1.5rem 0.5rem; }
}
```

---

## ACCESSIBILITY REQUIREMENTS

### Color Contrast

**Must meet WCAG AA (4.5:1 for normal text, 3:1 for large text)**

| Combination | Ratio | Status |
|------------|-------|--------|
| Gold (#C4A24E) on Dark (#0d0d0f) | ~5.2:1 | ✅ |
| Steel (#7B8794) on Dark (#0d0d0f) | ~4.5:1 | ✅ |
| Amber (#E07A2F) on Dark (#0d0d0f) | ~6.8:1 | ✅ |
| Light Text (#e0e0e0) on Dark (#0d0d0f) | ~16:1 | ✅ |

### Focus States

All interactive elements must have visible focus states:
```css
a:focus,
button:focus,
input:focus {
    outline: 2px solid #C4A24E;
    outline-offset: 2px;
}
```

### Touch Targets

- Minimum 44px × 44px for buttons, links
- Mobile links need generous padding
- Hover states clear on touch

---

## TRANSITION & ANIMATION GUIDELINES

**Standard Transitions**
```css
/* Quick feedback (UI elements) */
transition: all 0.2s ease;

/* Smoother, more natural (larger movements) */
transition: all 0.3s ease;
```

**Common Effects**
```css
/* Hover lift */
transform: translateY(-2px);

/* Card expand on hover */
transform: translateY(-4px);
box-shadow: 0 8px 24px rgba(0, 0, 0, 0.4);

/* Smooth color change */
color: #C4A24E;
transition: color 0.2s ease;
```

**Performance Notes**
- Use `transform` and `opacity` for smooth 60fps animations
- Avoid animating width/height (causes layout reflow)
- Keep animations under 300ms for snappiness
- Test on mobile devices for smooth performance

---

## GRADIENT USAGE

**Hero Title Gradient**
```css
background: linear-gradient(135deg, #C4A24E, #E07A2F);
-webkit-background-clip: text;
-webkit-text-fill-color: transparent;
background-clip: text;
```

**Header Background**
```css
background: linear-gradient(135deg, #0d0d0f 0%, rgba(0, 0, 0, 0.5) 100%);
```

**Hero Section Background**
```css
background: linear-gradient(135deg, rgba(196, 162, 78, 0.05) 0%, rgba(224, 122, 47, 0.05) 100%);
```

---

## TRANSPARENCY SCALE

Use rgba with consistent alpha values for hierarchy:

```css
/* Very subtle */
rgba(255, 255, 255, 0.02);    /* Cards, subtle bg */

/* Subtle */
rgba(255, 255, 255, 0.03);    /* Card containers */

/* Noticeable */
rgba(255, 255, 255, 0.05);    /* Card hover, slight emphasis */

/* Strong */
rgba(255, 255, 255, 0.08);    /* Form inputs, secondary bg */

/* Dark overlays */
rgba(0, 0, 0, 0.3);            /* Footer bg */
rgba(0, 0, 0, 0.5);            /* Header gradient end */
```

---

## BORDER RADIUS

```css
--radius-sm: 3px;      /* Code blocks, small elements */
--radius-md: 6px;      /* Buttons, inputs, cards */
--radius-lg: 8px;      /* Card containers, larger components */
--radius-xl: 12px;     /* Hero sections, large containers */
```

---

## BOX SHADOWS

```css
/* Subtle */
box-shadow: 0 2px 4px rgba(0, 0, 0, 0.2);

/* Medium (hover states) */
box-shadow: 0 4px 12px rgba(196, 162, 78, 0.3);

/* Strong (dropdown, modal) */
box-shadow: 0 8px 24px rgba(0, 0, 0, 0.5);
```

---

## TESTING CHECKLIST FOR ICARUS

### Visual Testing
- [ ] Colors render correctly on multiple monitors
- [ ] Dark theme looks consistent
- [ ] Gold/amber contrast is clear and not too bright
- [ ] Text is readable at all sizes
- [ ] Code blocks have proper contrast

### Responsive Testing
- [ ] Desktop layout (1200px+): All 3 columns work
- [ ] Tablet (768px): Navigation collapses, content reflows
- [ ] Mobile (480px): Single column, touch-friendly
- [ ] Hero section scales appropriately
- [ ] Buttons are always 44px+ height

### Interaction Testing
- [ ] Hover states are clear on all interactive elements
- [ ] Focus states are visible (keyboard navigation)
- [ ] Transitions are smooth (no jank)
- [ ] Mobile menu toggle works
- [ ] Dropdown menus display correctly

### Cross-Browser Testing
- [ ] Chrome (latest)
- [ ] Firefox (latest)
- [ ] Safari (if available)
- [ ] Mobile Chrome
- [ ] Mobile Safari

### Accessibility Testing
- [ ] No text is color-only (icons + text or patterns)
- [ ] Color contrast meets WCAG AA
- [ ] Focus indicators visible
- [ ] Button sizes adequate
- [ ] Form inputs keyboard accessible

### Performance Testing
- [ ] CSS files minify to < 50KB combined
- [ ] Fonts load without FOIT (flash of invisible text)
- [ ] Animations are smooth 60fps
- [ ] No excessive repaints/reflows
- [ ] Page Insights score > 80

---

## DELIVERABLES FOR TALOS

1. **`/css/base.css`** - ~500 lines
   - Variables, reset, typography, layout

2. **`/css/components.css`** - ~600 lines
   - All UI components (buttons, cards, hero, etc.)

3. **`/css/responsive.css`** - ~400 lines
   - Media queries for tablet and mobile

**Total CSS:** ~1500 lines (unminified)

---

**Specification Created:** 2026-04-12  
**Status:** Ready for Implementation  
**Next:** Icarus builds the three CSS files