# Design Hacker · Design System Spec

> Full design system reference for Design Hacker.
> Hosted at: https://brandidentitykit.com/designhacker/design.md
> Schema v1.5 · last updated 2026-05-24

---

## Architecture: The 5-Layer Stack

Design Hacker's design system is built on a 5-layer cascade. Each layer reads from the layer below. Brand swaps happen at L2, components stay clean.

1. **L1 · Token Architecture** · Raw design tokens (colors, type, spacing, radii)
2. **L2 · Brand Pack** · Brand-specific overrides (paper, ink, primary, voice)
3. **L3 · Blog System** · Article templates, blog index, category pages
4. **L4 · Components** · Buttons, cards, heroes, callouts, footers
5. **L5 · Marketing** · Landing pages, brand homes, AEO content

Brand.css ships L1 + L2 + the slim L4 inline. L3 and L5 templates live downstream.

## Tier 1: Brand backbone tokens

These are the SOURCE tokens. Everything else resolves from these. Brand pack writes ONLY these source tokens, never the resolved tier-2 tokens (hard rule).

```
--paper:           #EEE4E8   /* light surface */
--tone:            #F5EDF0   /* tinted light surface */
--ink:             #010001   /* near-black text on light */
--deep:            #45123B   /* dark plum, secondary fill */
--color-primary:   #A5205B   /* magenta-plum, brand anchor */
--color-secondary: #45123B   /* dark plum */
--color-accent:    #EB5E55   /* coral red, accent */
--color-pop:       #EB5E55   /* emphasis color */
```

**Primary color scale (50–900):**

```
50:  #FBEAF1   200: #E89BB9   500: #A5205B   800: #480C28
100: #F4CDDE   300: #DA6794   600: #871848   900: #2A0717
                400: #C53D74   700: #671238
```

**Surface-aware fill variants (brand color as background):**

```
--color-primary-fill: oklch(from #A5205B clamp(0.45, l, 0.65) c h)
```

Lightness clamped 0.45 floor (dark scheme legibility) and 0.65 ceiling (light scheme).

**Text variants (brand color as foreground):**

```
--color-primary-text: oklch(from #A5205B clamp(0.25, l, 0.55) max(c, 0.06) h)
```

## Typography

**Font family:** Poppins (exclusive). System fallbacks: system-ui, -apple-system, sans-serif.

**Weights used:**

- Display: 700
- Heading: 600
- Body: 400
- Caption: 500

**Letter spacing:**

- Display: -0.02em
- Heading: -0.01em
- Body: 0
- Eyebrow: 0.08em (uppercase)

**Type scale (comfortable):**

```
--t-display:  clamp(2.5rem, 5vw + 1rem, 5rem)
--t-title:    clamp(1.75rem, 2.5vw + 1rem, 3.25rem)
--t-subtitle: clamp(1.25rem, 1vw + 1rem, 1.75rem)
--t-h1:       2.5rem
--t-h2:       2rem
--t-h3:       1.5rem
--t-h4:       1.25rem
--t-body:     1rem
--t-small:    0.875rem
--t-caption:  0.75rem
--t-eyebrow:  0.75rem
```

**Line heights:**

- Display: 1.05
- Heading: 1.15
- Body: 1.6

## Spacing scale (8pt base)

```
--space-1:  4px       --space-6:  32px
--space-2:  8px       --space-7:  48px
--space-3:  12px      --space-8:  64px
--space-4:  16px      --space-9:  96px
--space-5:  24px      --space-10: 128px
```

## Border radius (role tokens)

Components consume ROLE tokens, never base radius values:

```
--card-radius:   16px
--block-radius:  12px
--pill-radius:   999px
--btn-radius:    10px
--input-radius:  10px
--imagery-radius: 10px
```

## Motion

```
--motion-scale:       1            /* hover transition speed multiplier */
--alive-dur-mult:     1            /* ambient animation duration multiplier */
--transition-speed:   200ms
--transition-easing:  cubic-bezier(0.2, 0.8, 0.2, 1)
```

Hover transitions scale with `--motion-scale`. Ambient (idle loops) scale with `--alive-dur-mult`. Never mix these in one calc.

## Shadows

```
--shadow-sm:    0 1px 2px rgba(1, 0, 1, 0.06)
--shadow-md:    0 4px 12px rgba(1, 0, 1, 0.08)
--shadow-lg:    0 12px 32px rgba(1, 0, 1, 0.12)
--shadow-brand: 0 8px 24px color-mix(in srgb, var(--color-primary) 25%, transparent)
```

## Surface attribute pattern

Sections that override surface use `data-surface` for /system/ cascade to trigger correctly:

```html
<section data-surface="ink">...</section>     <!-- dark ink bg, paper text -->
<section data-surface="paper">...</section>   <!-- light paper bg, ink text -->
<section data-surface="tone">...</section>    <!-- tinted light bg -->
<section data-surface="brand">...</section>   <!-- brand-fill bg, paper text -->
<section data-surface="deep">...</section>    <!-- deep plum bg, paper text -->
```

## Component inventory

Components are documented and rendered in `components.html`. The Brand Kit ships with this canonical set:

- **Hero** · Marketing hero with eyebrow + display title + body + dual CTA + photo
- **Pricing card** · Tier card with title, price, feature list, CTA
- **Feature grid** · 3-column grid of icon + title + body
- **Testimonial** · Quote-first, photo at bottom
- **Call-to-action block** · Full-width band with display headline + button
- **Article callout** · Inline content block for blog posts (rounded card with eyebrow + headline + body)
- **Footer** · Multi-column with brand mark, nav links, social links, legal

## Imagery rules

- Filter default: `none` (true color)
- Treatment: editorial magazine, not SaaS stock
- Avoid AI-generated faces, "diverse team collaborating" stock photos
- Warm natural lighting preferred
- Photos should feel candid, not staged

## Anti-slop discipline

Every component CSS follows the 13-rule cascade rigor checklist:

1. `var()` everywhere, no hardcoded color hex
2. `--color-X-fill` variants for brand backgrounds
3. Role tokens (`--card-radius` etc) for all radii
4. `var(--border-style, solid)` for borders (never just "solid")
5. `--imagery-filter: none` default for photos
6. No hardcoded patterns or magic numbers
7. No `transition: all`
8. No gradient text on headings
9. No emoji as bullet point styling
10. No left-border accent stripes on cards
11. Photos default true-color, no monochrome filter
12. SVG icons have aria-label or aria-hidden
13. Components consume role tokens, never base radius

## Variant dials (v1.5)

The Brand Kit ships with 12 variant dials that cascade through every component:

```
borderStyle:        solid | dashed | dotted
iconStroke:         hairline | normal | bold
imageryRadius:      sharp | soft | rounded | pill
imageryFilter:      none | monochrome | warm | cool
focusStyle:         ring | underline | block
buttonHoverEffect:  lift | pop | ripple | shine | none
buttonEffect:       none | glow | pulse
buttonTextCase:     default | sentence | lower | upper
buttonFontWeight:   default | normal | bold
buttonFillStyle:    solid | outline | ghost | gradient
buttonOutlineWidth: thin | medium | thick
headingDrama:       subtle | moderate | bold
```

## Brand Kit files

The Brand Kit at `brandidentitykit.com/designhacker/`:

| File | Role | Format |
|---|---|---|
| `brand.json` | Canonical Brand Kit data | JSON |
| `brand.css` | Executable design system | CSS |
| `context.md` | Voice + audience + archetype | Markdown |
| `prompt.md` | AI builder drop-in instructions | Markdown |
| `design.md` | This spec | Markdown |
| `components.html` | Reference components rendered | HTML |
| `index.html` | Public Brand Home | HTML |

---

**Live preview:** https://brandidentitykit.com/designhacker
**Canonical brand:** https://designhacker.com
**Founder:** Andrew Lane