IndieStack Frontend Design

Use this skill for ANY visual or UI work on IndieStack — new pages, redesigns, component updates, or polish passes. This enforces the exact aesthetic, tokens, and constraints so nothing drifts.

Aesthetic Target

Linear.app meets Stripe Docs. Clean, precise, confident. Dark mode that looks intentional, not inverted. Warm personality without gratuitous decoration.

References to study: Linear (spatial hierarchy, dark mode confidence, typography weight), Stripe Docs (spacing, code blocks, information density), Vercel (motion, transitions, compositional balance).

Anti-references (NEVER do these):

• Purple gradients on white backgrounds
• Gradient blobs / mesh backgrounds on content pages
• Stock photos or placeholder illustrations
• Over-rounded everything (16px+ radius on small elements)
• Parallax, scroll-jacking, or animations that delay content
• Generic SaaS template layouts (three-column feature grids with emoji icons)

Architecture Constraint

Pure Python f-string HTML. No React, no Jinja2, no build step. All pages are FastAPI route functions returning HTMLResponse(page_shell(...)). CSS lives in components.py design tokens or inline styles.

File structure:

• src/indiestack/routes/components.py — design tokens (:root), nav, footer, shared components
• src/indiestack/routes/<page>.py — page-specific routes with inline HTML
• New CSS classes go in components.py design_tokens() function
• Reusable components go in components.py as Python functions

Design Tokens (Enforced)

Colors — USE THESE EXACT VARIABLES

/* Primary */             --terracotta: #1A2D4A;     /* Navy — legacy name, DO NOT rename */
/* Primary light */       --terracotta-light: #2B4A6E;
/* Primary dark */        --terracotta-dark: #0F1D30;
/* Accent */              --accent / --slate: #00D4F5; /* Cyan */
/* Highlight */           --gold: #E2B764;
/* Surfaces */            --cream: #F7F9FC;  --cream-dark: #EDF1F7;  --card-bg: white;
/* Text */                --ink: #1A1A2E;  --ink-light: #475569;  --ink-muted: #64748B;
/* Border */              --border: #E2E8F0;

Rules:

• NEVER use hardcoded hex colors — always var(--token-name)
• NEVER use rgba() with magic numbers — define as a token if needed
• Accent cyan (--accent) for interactive elements and emphasis only — not backgrounds
• Gold for verified/premium indicators only
• Navy (--terracotta) for primary actions and strong emphasis

Typography

--font-display: 'DM Serif Display', serif;   /* Headings ONLY */
--font-body: 'DM Sans', sans-serif;           /* Everything else */
--font-mono: 'JetBrains Mono', monospace;     /* Code, tags, technical */

Hierarchy (use these exact sizes):

Rules:

• DM Serif Display is NEVER bold (it's a display face — weight 400 only)
• Line-height: 1.2 for headings, 1.6 for body, 1.4 for labels
• Letter-spacing: 0.5px on uppercase labels, 0 elsewhere

Spacing — 8px Base Grid

ONLY use these values: 4, 8, 12, 16, 20, 24, 32, 40, 48, 64, 80px

NEVER use: 10px, 15px, 18px, 22px, 28px, 36px, 50px, 60px or any value not on the scale.

Elevation — Layered Shadows

/* Light mode */
--shadow-sm: 0 1px 3px rgba(26,45,74,0.06);
--shadow-md: 0 4px 12px rgba(26,45,74,0.08);
--shadow-lg: 0 12px 40px rgba(26,45,74,0.10);

/* Use shadow layering for depth */
/* Resting card:    shadow-sm */
/* Hover card:      shadow-md + translateY(-2px) */
/* Floating:        shadow-lg */
/* Modal/dropdown:  shadow-lg + border */

Rules:

• Cards at rest: box-shadow: var(--shadow-sm) with border: 1px solid var(--border)
• Cards on hover: box-shadow: var(--shadow-md); transform: translateY(-2px) — NOT -3px (too jumpy)
• Dropdowns/modals: var(--shadow-lg) with border
• NEVER use box-shadow: none on interactive cards

Radius

• Cards, modals: 12px (--radius)
• Inputs, dropdowns: 8px (--radius-sm)
• Buttons, pills, badges: 999px (full round)
• NEVER use 4px, 6px, or 16px radius

Transitions

/* Standard */   transition: all 0.15s ease;
/* Emphasis */   transition: all 0.2s cubic-bezier(0.4, 0, 0.2, 1);
/* Page enter */  animation: fadeUp 0.4s ease-out;

Rules:

• Every interactive element MUST have a transition
• Hover scale: transform: scale(1.02) max — never 1.05+
• Active/pressed: transform: scale(0.98) for tactile feedback
• Stagger animations with animation-delay in 50ms increments

Component Patterns

Cards

f'''<div class="card" style="padding:24px;">
    <div style="font-family:var(--font-display);font-size:17px;color:var(--ink);margin-bottom:8px;">{title}</div>
    <div style="font-size:13px;color:var(--ink-muted);line-height:1.6;">{description}</div>
</div>'''

Buttons

Always use .btn class. Never inline-style a button from scratch.

f'<a href="{url}" class="btn btn-primary">Label</a>'
f'<button class="btn btn-secondary">Label</button>'

Pills / Filter Buttons

Use the .pill-filter class (add to components.py if missing):

.pill-filter {
    display: inline-flex; align-items: center; gap: 4px;
    padding: 8px 16px; border-radius: 999px;
    font-size: 13px; font-weight: 600;
    border: 1px solid var(--border);
    background: var(--card-bg); color: var(--ink-light);
    cursor: pointer; transition: all 0.15s ease;
    min-height: 36px;
}
.pill-filter:hover { border-color: var(--ink-muted); color: var(--ink); }
.pill-filter.active { background: var(--terracotta); color: white; border-color: var(--terracotta); }

Section Layout

f'''<section style="padding:64px 24px;">
    <div class="container" style="max-width:700px;">
        <h2 style="font-family:var(--font-display);font-size:22px;color:var(--ink);margin-bottom:24px;">
            Section Title
        </h2>
        <!-- content -->
    </div>
</section>'''

Badges

Always use .badge class with variant: .badge-success, .badge-info, .badge-warning, .badge-gold, .badge-muted.

Modern Touches to Apply

1. Layered borders — Use border-left: 3px solid var(--accent) for emphasis, not just uniform 1px borders
2. Subtle gradients — background: linear-gradient(180deg, var(--cream) 0%, var(--card-bg) 100%) for section transitions
3. Backdrop blur — backdrop-filter: blur(12px); background: rgba(247,249,252,0.85) on nav (light) / rgba(15,20,32,0.85) (dark)
4. Custom selects — Replace <select> with styled <details> dropdowns
5. Keyboard hints — Show / shortcut on search, Esc on modals
6. Skeleton loading — For async content, use background: linear-gradient(90deg, var(--cream-dark) 25%, var(--cream) 50%, var(--cream-dark) 75%); background-size: 200% 100%; animation: shimmer 1.5s infinite;
7. Focus rings — outline: 2px solid var(--accent); outline-offset: 2px; on all focusable elements
8. Scroll-triggered reveals — .reveal class with IntersectionObserver (already in landing.py, extend to all pages)

Dark Mode Rules

• Landing page: dark by default (forced via script)
• All other pages: respect user preference
• NEVER hardcode colors — always use var(--token)
• Test both modes for every change
• Dark mode nav: backdrop-filter: blur(12px); background: rgba(15,20,32,0.85);

Screenshot Feedback Protocol

When doing visual work:

1. Make the change
2. User takes a screenshot and pastes it
3. Compare against Linear/Stripe reference aesthetic
4. Identify: spacing inconsistencies, color misuse, typography hierarchy breaks, missing hover states
5. Iterate until it feels "expensive"

Checklist — Before Finishing Any Visual Change

• [ ] All colors use CSS variables (no hardcoded hex/rgba)
• [ ] All spacing values are on the 8px grid scale
• [ ] Typography follows the hierarchy table exactly
• [ ] Interactive elements have hover + focus + active states
• [ ] Dark mode tested (both themes look intentional)
• [ ] Mobile responsive at 768px, 600px, 480px breakpoints
• [ ] Touch targets >= 44px
• [ ] No browser-default form elements visible (style or replace)
• [ ] Transitions on all state changes (0.15s ease minimum)
• [ ] python3 -c "import ast; ast.parse(open('file.py').read())" passes